ArctonArcton
Middleware

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

FormaAplica 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.

En esta página