Scoped Middleware
Applying middleware to the routes under a path with app.use(scope, middleware).
Passing a path before the middleware limits it to the routes under that path:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.use('/admin', async (ctx, next) => {
if (ctx.request.headers.get('x-admin-key') !== 'secret') {
return new Response('Unauthorized', { status: 401 })
}
await next()
})
app.get('/admin/stats', () => ({ users: 42 }))
app.get('/health', () => ({ status: 'ok' }))
app.listen()/admin/stats is protected. /health is not.
What "under a path" means
A scope matches the path itself and anything below it, compared segment by segment — not as a string prefix:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.use('/api', async (ctx, next) => {
ctx.response.headers.set('X-Scoped', 'yes')
await next()
})
app.get('/api', () => ({ root: true })) // matches the scope itself
app.get('/api/users', () => ({ users: [] })) // matches, nested
app.get('/apidocs', () => ({ docs: true })) // does NOT match
app.listen()/apidocs starts with the same letters as /api, but it is not under it.
A scope is a static path
Scopes are plain paths — :param and *wildcard segments are not part of this
form:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.use('/users', async (ctx, next) => {
ctx.response.headers.set('X-Section', 'users')
await next()
})
app.get('/users/:id', ctx => ({ id: ctx.params.id }))
app.listen()The scope '/users' covers /users/:id because that route lives under it. See
Registration errors for the error a
non-static scope produces.
Order still applies
Like global middleware, a scope only reaches routes registered after it:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.get('/admin/early', () => ({ guarded: false }))
app.use('/admin', async (ctx, next) => {
if (ctx.request.headers.get('x-admin-key') !== 'secret') {
return new Response('Unauthorized', { status: 401 })
}
await next()
})
app.get('/admin/late', () => ({ guarded: true }))
app.listen()Only /admin/late is guarded. Register the scope before the routes it
protects — see Execution order.
Scoped middleware and matched routes
Scoped middleware runs only for routes that matched. It does not run on the
404 and 405 responses Arcton generates, since those have no route to belong
to. When a concern has to reach every response, register it
globally instead.
Scopes inside modules
A module can scope its own middleware, and the scope is compared against the path as written inside the module — not the mounted path:
import { Arcton } from '@arcton/core'
const api = Arcton({ prefix: '/api' })
api.use('/admin', async (ctx, next) => {
if (ctx.request.headers.get('x-admin-key') !== 'secret') {
return new Response('Unauthorized', { status: 401 })
}
await next()
})
api.get('/admin/stats', () => ({ users: 42 }))
const app = Arcton()
app.use(api)
app.listen()The route is served at /api/admin/stats and the scope is written '/admin',
matching how the route was written inside the module.
A scope belongs to the instance it is registered on. A parent's scoped middleware does not reach the routes of a mounted module — put the scoped middleware in the module that owns those routes.