ArctonArcton
Middleware

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.

On this page