ArctonArcton
Middleware

Execution Order

Cómo decide Arcton qué middleware corre una ruta, por qué importa el orden de registro, y el único caso en el que no importa.

Dos reglas explican cada pregunta de orden en Arcton:

  1. Una ruta corre el middleware y los providers registrados antes que ella.
  2. Dentro de ese conjunto, el orden es global → validation → route middleware → handler.

El snapshot de registro

Cuando registras una ruta, Arcton toma el middleware y los providers que existen en ese momento y guarda la cadena ya terminada junto con la ruta. Las llamadas hechas después no la alcanzan.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/before', () => ({ timed: false }))

app.use(async (ctx, next) => {
  const start = performance.now()
  await next()
  ctx.response.headers.set('X-Time', `${performance.now() - start}ms`)
})

app.get('/after', () => ({ timed: true }))

app.listen()

/after recibe el header X-Time. /before no — se registró cuando ese middleware todavía no existía.

Por eso el archivo se lee tal como se comporta: mover una llamada a use() hacia arriba o hacia abajo cambia exactamente las rutas debajo de ella.

La regla práctica: registra el middleware global y los providers al principio del archivo, antes de cualquier ruta. Así cada ruta los ve a todos.

El orden adentro de un request

Para una ruta matcheada:

       request
          │
          ▼
   ┌─ match path + method ───────────────┐
   │                                     │
   ▼                                     │
global middleware      (en orden de registro, la más exterior primero)
   │                                     │
   ▼                                     │
validation             (params → query → body)
   │                                     │
   ▼                                     │
route middleware       (en el orden escrito, la más interior)
   │                                     │
   ▼                                     │
handler                                  │
   │                                     │
   └─ vuelta: route mw → global mw ──────┘
          │
          ▼
   response mapping

Visto en código:

import { Arcton } from '@arcton/core'
import * as v from 'valibot'

const app = Arcton()

app.use(async (ctx, next) => {
  console.log('1 global in')
  await next()
  console.log('6 global out')
})

app.get('/users/:id', {
  params: v.object({
    id: v.pipe(v.string(), v.transform(Number), v.number())
  }),
  middleware: [
    async (ctx, next) => {
      console.log('3 route in')
      await next()
      console.log('5 route out')
    }
  ],
  handler: ctx => {
    console.log('4 handler')
    return { id: ctx.params.id }
  }
})

app.listen()

GET /users/42 loguea 1 global in, después corre la validation (paso 2, en silencio), después 3 route in, 4 handler, 5 route out, 6 global out.

Como la validation queda entre medio, el middleware global ve el string crudo ctx.params.id, mientras que el middleware de ruta y el handler ven el número.

Los providers siguen la misma regla

provide() comparte la secuencia con use(), así que aplica el mismo snapshot:

import { Arcton } from '@arcton/core'

const app = Arcton()

app
  .provide(() => ({ startedAt: Date.now() }))
  .get('/uptime', ctx => ({ uptime: Date.now() - ctx.startedAt }))

app.listen()

Registrar la ruta antes que el provider sería un error de compilación, porque ctx.startedAt todavía no sería parte del tipo del context. El sistema de tipos y el runtime están de acuerdo aquí: leen la misma lista, en el mismo orden.

Middleware con scope

Un scope se aplica encima del snapshot: cuando una ruta se registra, Arcton conserva el middleware con scope cuyo path contiene a esa ruta, y descarta el resto.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.use(async (ctx, next) => {
  console.log('global')
  await next()
})

app.use('/admin', async (ctx, next) => {
  console.log('admin only')
  await next()
})

app.get('/admin/stats', () => ({ users: 42 }))  // both
app.get('/health', () => ({ status: 'ok' }))    // global only

app.listen()

La decisión ocurre una sola vez, al registrarse. Nada se vuelve a verificar por request.

La excepción: 404 y 405

Las respuestas que Arcton genera porque nada matcheó se comportan distinto: el middleware global corre sobre ellas sin importar el orden de registro.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/', () => ({ ok: true }))

app.use(async (ctx, next) => {
  await next()
  ctx.response.headers.set('Access-Control-Allow-Origin', '*')
})

app.listen()

GET /missing responde 404 con el header de CORS, aunque el middleware se registró después de todas las rutas.

La razón es que la regla del snapshot es sobre una ruta: "antes" y "después" solo significan algo en relación al propio registro de una ruta. Un 404 no tiene ninguna ruta, así que no hay nada respecto de lo cual estar antes o después — y las cosas que pertenecen a esas respuestas (CORS, logging, request ids) son exactamente las que deben cubrir cada respuesta. Arcton junta el middleware use() sin scope una sola vez cuando se llama a listen(), y lo aplica ahí.

Qué no corre en 404/405:

Ruta matcheada404 / 405
use(middleware)solo antessiempre
use(scope, middleware)solo antes, bajo el scopeno
middleware de rutasíno
provide()solo antesno
validationsíno

Módulos

Montar un módulo sigue la misma regla desde el lado del padre: el middleware global y los providers del padre registrados antes de app.use(module) envuelven cada ruta que trae el módulo, y cualquier cosa registrada después no lo hace.

import { Arcton } from '@arcton/core'

const users = Arcton({ prefix: '/users' })
users.get('/:id', ctx => ({ id: ctx.params.id }))

const app = Arcton()

app.use(async (ctx, next) => {
  ctx.response.headers.set('X-Before', 'yes')
  await next()
})

app.use(users)

app.use(async (ctx, next) => {
  ctx.response.headers.set('X-After', 'no')
  await next()
})

app.listen()

GET /users/1 lleva X-Before y no X-After.

El propio middleware del módulo sigue funcionando después de montarlo, y corre adentro del middleware del padre.

Por qué funciona así

Resolver la cadena una sola vez, al registrarse, hace que un request nunca tenga que preguntar "¿qué middleware aplica aquí?" — la respuesta ya se calculó cuando se creó la ruta. También hace honesto al sistema de tipos: ctx se tipa a partir de los providers registrados antes del handler, que es exactamente el conjunto que va a correr.

Ver Pipeline para cómo se construye la cadena.

En esta página