ArctonArcton
Middleware

Middleware Overview

What a middleware is in Arcton, the onion model, and the three ways to attach one.

A middleware is a function that runs around your handlers. It receives the context and a next function, and it decides what happens before and after the rest of the chain:

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()

Everything before await next() runs on the way in. Everything after runs on the way out, once the handler and every inner middleware have finished.

The onion

Middleware nests. With two registered, the flow through a request is:

   ┌── middleware A ─────────────────────────┐
   │   ┌── middleware B ──────────────────┐  │
   │   │   ┌── handler ───────────────┐   │  │
   │   │   │  returns a value         │   │  │
   │   │   └──────────────────────────┘   │  │
   │   │   code after await next()        │  │
   │   └──────────────────────────────────┘  │
   │   code after 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()

A request to / logs A: in, B: in, handler, B: out, A: out.

Three ways to attach one

FormApplies to
app.use(middleware)every route registered after the call, plus 404/405 responses
app.use('/admin', middleware)routes under that path, registered after the call
app.get(path, middleware, handler)that route only
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()

Each form has its own page: Global, Scoped and Route level.

Which middleware a route runs is decided when the route is registered, from the calls made before it. Execution order is the page to read once the basics are clear.

Short-circuiting

A middleware that returns a value without calling next() answers the request on its own. The handler and everything inside never run:

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()

The returned value goes through the same response mapping as a handler's, so returning an object produces JSON and returning a Response passes it through.

Typing a middleware

Middleware is exported from @arcton/contracts. Declaring the type gives a standalone middleware its parameter types:

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()
}

That is a fragment — import it into a file that builds an app to run it.

Reusable middleware

A middleware that takes options is just a function that returns one:

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()
  }
}

That is the same shape @arcton/cors uses.

On this page