Middleware

Middleware in Routa is part of the route contract. Auth, permissions, tenant loading, and request enrichment should not disappear into invisible side effects.

Context

Middleware declares what context it requires and what context it provides. Route handlers receive typed ctx from the middleware chain.

export default defineRoute({
  get: createRoute({
    middleware: [requireAuth()],
    responses: {
      success: {
        status: 200,
        schema: UserSchema,
      },
    },
    run: async ({ ctx }) => {
      return users.getCurrentUser(ctx.state.auth.principal.id);
    },
  }),
});

Early Responses

Middleware can also produce early HTTP responses, such as authentication failures or permission denials. Those responses should remain visible to the route contract and generated OpenAPI.

Where Middleware Lives

Routa reads middleware from route files and folder middleware files. This lets context grow as routing becomes more specific.

Directorysrc/routes/
- middleware.ts
- Directoryadmin/
  - middleware.ts
  - Directoryaudit-events/
    route.ts
- Directorytenants/
  - Directory$tenantId/
    middleware.ts
    Directoryprojects/
    route.ts

Generated route metadata tracks middleware order, required context keys, provided context keys, reject outcomes, groups, and route segments.

v0 Scope

Routa v0 includes a minimal typed middleware surface. Broader security integrations and operational features are deferred beyond v0.