Middleware Overview
Qué es un middleware en Arcton, el modelo onion, y las tres formas de agregar uno.
Un middleware es una función que corre alrededor de tus handlers. Recibe
el context y una función next, y
decide qué pasa antes y después del resto de la cadena:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.use(async (ctx, next) => {
const start = performance.now()
await next()
ctx.response.headers.set(
'X-Response-Time',
`${(performance.now() - start).toFixed(2)}ms`
)
})
app.get('/', () => ({ ok: true }))
app.listen()Todo lo que está antes de await next() corre a la entrada. Todo lo que
está después corre a la salida, una vez que el handler y cada middleware
interior terminaron.
El onion
El middleware se anida. Con dos registrados, el flujo a través de un request es:
┌── middleware A ─────────────────────────┐
│ ┌── middleware B ──────────────────┐ │
│ │ ┌── handler ───────────────┐ │ │
│ │ │ retorna un valor │ │ │
│ │ └──────────────────────────┘ │ │
│ │ después de await next() │ │
│ └──────────────────────────────────┘ │
│ después de await next() │
└─────────────────────────────────────────┘import { Arcton } from '@arcton/core'
const app = Arcton()
app.use(async (ctx, next) => {
console.log('A: in')
await next()
console.log('A: out')
})
app.use(async (ctx, next) => {
console.log('B: in')
await next()
console.log('B: out')
})
app.get('/', () => {
console.log('handler')
return { ok: true }
})
app.listen()Un request a / loguea A: in, B: in, handler, B: out, A: out.
Tres formas de agregar uno
| Forma | Aplica a |
|---|---|
app.use(middleware) | cada ruta registrada después de la llamada, más las respuestas 404/405 |
app.use('/admin', middleware) | rutas bajo ese path, registradas después de la llamada |
app.get(path, middleware, handler) | solo esa ruta |
import { Arcton } from '@arcton/core'
import type { Middleware } from '@arcton/contracts'
const requestId: Middleware = async (ctx, next) => {
ctx.response.headers.set('X-Request-Id', crypto.randomUUID())
await next()
}
const app = Arcton()
app.use(requestId) // global
app.use('/admin', requestId) // scoped
app.get('/health', requestId, () => ({ ok: true })) // route level
app.listen()Cada forma tiene su propia página: Global, Scoped y Route level.
Qué middleware corre una ruta se decide cuando la ruta se registra, a partir de las llamadas hechas antes de ella. Execution order es la página para leer una vez que lo básico está claro.
Short-circuiting
Un middleware que retorna un valor sin llamar a next() responde el
request por su cuenta. El handler y todo lo de adentro nunca corren:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.use(async (ctx, next) => {
if (ctx.request.headers.get('x-api-key') !== 'secret') {
return new Response('Unauthorized', { status: 401 })
}
await next()
})
app.get('/private', () => ({ secret: true }))
app.listen()El valor retornado pasa por el mismo
mapeo de respuestas que el de un
handler, así que retornar un objeto produce JSON y retornar un
Response lo pasa directo.
Tipar un middleware
Middleware se exporta desde @arcton/contracts. Declarar el tipo le
da a un middleware independiente sus tipos de parámetro:
import type { Middleware } from '@arcton/contracts'
export const logger: Middleware = async (ctx, next) => {
const { method, url } = ctx.request
console.log(`→ ${method} ${new URL(url).pathname}`)
await next()
}Eso es un fragmento — impórtalo en un archivo que arme una app para correrlo.
Middleware reusable
Un middleware que toma opciones es simplemente una función que retorna uno:
import type { Middleware } from '@arcton/contracts'
export function requireHeader(name: string): Middleware {
return async (ctx, next) => {
if (!ctx.request.headers.has(name)) {
return new Response(`Missing ${name}`, { status: 400 })
}
await next()
}
}Esa es la misma forma que usa @arcton/cors.