Middleware

The @talosjs/middleware component is a pipeline framework for intercepting requests. Each middleware implements the IMiddleware interface (or ISocketMiddleware for WebSockets), receives the request context, and returns it, modified or unchanged, to the next stage. Register a class with @decorator.middleware() and the container resolves it; the app runs registered middleware in order before the controller handles the request.

The pipeline model

Every HTTP middleware implements IMiddleware with a single handler(context) method, which keeps them predictable to write, read, and test. The same context object flows through every stage, carrying the request, response, and headers, and you read and mutate it in place. Write a response (context.response.json(...) or context.response.exception(...)) to halt the pipeline before the controller, which is how auth checks and rate limits short-circuit. WebSocket interception works the same way: ISocketMiddleware mirrors the HTTP shape against the socket context for connection-time checks. Because every middleware is decorated and resolved through dependency injection, you can constructor-inject env, loggers, or services.

How it works

The app holds an ordered list of middleware. For each incoming request it builds a context and passes it through every registered middleware in sequence, then to the matched controller. Each handler returns the context to continue the chain.

Stage	What happens
Before the controller	Each middleware’s `handler` runs in registration order, reading and mutating the shared `context`.
Short-circuit	If a middleware writes a response (e.g. `context.response.exception(...)` or `context.response.json(...)`), the pipeline can resolve early without reaching the controller.
At the controller	The fully processed `context` (with any state a middleware attached, like a resolved user) reaches the route handler.

A middleware runs “before” by doing its work at the top of handler and then returning context. Since the same context object carries the response, middleware can also shape the outgoing response (set headers, status) before returning. The contract comes down to one rule: always return the context so the chain continues.

public async handler(context: ContextType): Promise<ContextType> {
  // Pre-processing: inspect/modify request, attach state, set response headers
  return context; // hand off to the next middleware or the controller
}

Decorator and usage

`@decorator.middleware()`

Registers a class as middleware with the dependency injection container. It accepts an optional scope (defaults to singleton). The class must implement IMiddleware (HTTP) or ISocketMiddleware (WebSocket).

interface IMiddleware<T extends ContextConfigType = ContextConfigType> {
  handler: (context: ContextType<T>) => Promise<ContextType<T>> | ContextType<T>;
}

A real HTTP middleware reads the context, optionally writes to the response to short-circuit, and returns the context:

import type { ContextType } from "@talosjs/controller";
import { decorator, type IMiddleware } from "@talosjs/middleware";

@decorator.middleware()
export class AuthMiddleware implements IMiddleware {
  public async handler(context: ContextType): Promise<ContextType> {
    const authHeader = context.header.get("Authorization");

    if (!authHeader?.startsWith("Bearer ")) {
      // Short-circuit: write a response and the controller is skipped
      context.response.exception("Missing authorization header", { status: 401 });
      return context;
    }

    // Continue to the next middleware / controller
    return context;
  }
}

Inject dependencies through the constructor; the container provides them when it resolves the middleware:

import { AppEnv } from "@talosjs/app-env";
import { inject } from "@talosjs/container";
import type { ContextType } from "@talosjs/controller";
import { decorator, type IMiddleware } from "@talosjs/middleware";

@decorator.middleware()
export class VersionMiddleware implements IMiddleware {
  constructor(@inject(AppEnv) private readonly env: AppEnv) {}

  public async handler(context: ContextType): Promise<ContextType> {
    context.response.header.set("X-App-Version", this.env.APP_VERSION ?? "unknown");
    return context;
  }
}

WebSocket middleware uses the same decorator and shape against the socket context via ISocketMiddleware:

import type { ContextType } from "@talosjs/socket";
import { decorator, type ISocketMiddleware } from "@talosjs/middleware";

@decorator.middleware()
export class SocketAuthMiddleware implements ISocketMiddleware {
  public async handler(context: ContextType): Promise<ContextType> {
    return context;
  }
}

Writing solid middleware

The chain continues only when handler returns the context object, so always return it and never return a new object in its place. Read from and write to the shared context in place, attaching resolved state (like a user) for downstream middleware and the controller to use. Write a response only when you actually mean to stop the pipeline, as on auth failures or rate limits; otherwise fall through. Keep each middleware to one concern (auth, logging, rate limiting) so the registration order reads as a clear pipeline. Order matters: middleware runs in registration order, so put cross-cutting concerns like logging and headers ahead of guards that may short-circuit. And pull env, loggers, and services through the constructor with @inject rather than constructing them inside handler.

CLI command

Scaffold a middleware class and its test file with the generator. It writes the class under modules/<module>/src/middlewares/<Name>Middleware.ts, adds a matching test, and installs @talosjs/middleware if it is missing.

# Interactive: prompts for the name and whether it is a socket middleware
talos middleware:create

# Provide the name
talos middleware:create --name=Auth

# Socket middleware in a specific module, overwriting an existing file
talos middleware:create --name=Auth --module=auth --is-socket=true --override

Option	Description	Default
`--name`	Middleware class name. The `Middleware` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--is-socket`	Generate a WebSocket middleware against the socket context.	Prompted if omitted
`--override`	Overwrite an existing class without prompting.	`false`

The generated class is a ready-to-implement IMiddleware stub:

import type { ContextType } from "@talosjs/controller";
import { decorator, type IMiddleware } from "@talosjs/middleware";

@decorator.middleware()
export class AuthMiddleware implements IMiddleware {
  public async handler(context: ContextType): Promise<ContextType> {
    // Example: Add custom header
    // context.response.header("X-Custom-Header", "value");

    return context
  }
}

A socket middleware stub is identical except it imports ContextType from @talosjs/socket. After generating, register the class in the middlewares array of your module. See middleware:create for the full command reference.

Use with Claude and Codex

The generator ships a matching middleware:create skill. It runs the scaffold, then guides your AI agent through completing the middleware: implementing handler with real logic (auth checks, logging, header injection), wiring dependencies through the constructor, and registering the class in its module. Initialize the skills once for your agent.

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a middleware that logs every incoming request.

talos agent:skills:create

Then ask Codex in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a middleware that logs every incoming request.

For example, the prompt above maps to middleware:create --name=Logging, then implements handler to log the request method and path before returning the context.

Getting Started

AI

Framework

Command Line

The pipeline model

How it works

Decorator and usage

`@decorator.middleware()`

Writing solid middleware

CLI command

Use with Claude and Codex

​The pipeline model

​How it works

​Decorator and usage

​@decorator.middleware()

​Writing solid middleware

​CLI command

​Use with Claude and Codex

The pipeline model

How it works

Decorator and usage

`@decorator.middleware()`

Writing solid middleware

CLI command

Use with Claude and Codex