Middleware Without Mystery: Hooks, Ordering, and Response Transformation

// @daloyjs/core — the entire Hooks interface, no surprises.
export interface Hooks {
  onRequest?:    (req: Request)                        => void | Promise<void>;
  beforeHandle?: (ctx: BaseContext)                    => void | Response | Promise<void | Response>;
  afterHandle?:  (ctx: BaseContext, result: unknown)   => void | unknown | Promise<void | unknown>;
  onSend?:       (res: Response, ctx?: BaseContext)    => void | Response | Promise<void | Response>;
  onResponse?:   (res: Response)                       => void | Promise<void>;
  onError?:      (err: unknown, ctx?: BaseContext)     => void | Response | Promise<void | Response>;
}
//
// Successful request order:
//   onRequest → beforeHandle → handler → afterHandle → onSend → onResponse
// Error path:
//   onRequest → (anywhere it throws) → onError → onSend → onResponse

time ─────────────────────────────────────────────────────────────────▶

   ┌──────────┐   ┌──────────────┐   ┌─────────┐   ┌─────────────┐
   │onRequest │ → │ beforeHandle │ → │ handler │ → │ afterHandle │ → …
   └──────────┘   └──────────────┘   └─────────┘   └─────────────┘
        ▲              │ may return                    │ may return
        │              ▼ a Response (short-circuit)    ▼ a new value
        │
   raw Request                                              ┌────────┐
        │                  ┌────────────┐   ┌────────────┐  │ socket │
        │              … → │   onSend   │ → │ onResponse │→ │ closes │
        │                  └────────────┘   └────────────┘  └────────┘
        │                      │ may                fire-and-forget
        │                      ▼ replace             observer
        │
        └──[ anywhere throws ]──▶  onError  ─▶  Response  ─▶  onSend  ─▶  onResponse

// Three scopes. Composed in this order. No magic.
const app = new App({
  hooks: { /* (1) GLOBAL — runs first, every request, every route */ },
});

app.use({  /* (2) GROUP  — runs after global, on routes registered AFTER this */ });

app.route({
  method: "GET",
  path: "/admin",
  handler: ...,
  hooks: { /* (3) ROUTE — runs last, only on THIS route */ },
});

// Each hook *kind* (onRequest, beforeHandle, etc.) composes pipeline-style:
// global onSend, then every group onSend in registration order, then route onSend.
// First one to return a new Response wins the next stage's input.

// Watch the order. The console output is the easiest way to internalize it.
const app = new App({
  hooks: {
    onRequest:    () => console.log("[1] global  onRequest"),
    beforeHandle: () => console.log("[2] global  beforeHandle"),
    afterHandle:  () => console.log("[6] global  afterHandle"),
    onSend:       () => console.log("[8] global  onSend"),
    onResponse:   () => console.log("[10] global onResponse"),
  },
});

app.use({
  beforeHandle: () => console.log("[3] group   beforeHandle"),
  afterHandle:  () => console.log("[7] group   afterHandle"),
  onSend:       () => console.log("[9] group   onSend"),
});

app.route({
  method: "GET",
  path: "/x",
  handler: async () => {
    console.log("[5] handler runs");
    return { status: 200, body: { ok: true } };
  },
  hooks: {
    beforeHandle: () => console.log("[4] route   beforeHandle"),
  },
});

// $ curl http://localhost:3000/x
// [1] global  onRequest
// [2] global  beforeHandle
// [3] group   beforeHandle
// [4] route   beforeHandle
// [5] handler runs
// [6] global  afterHandle
// [7] group   afterHandle
// [8] global  onSend
// [9] group   onSend
// [10] global onResponse

// src/middleware/maintenance.ts — short-circuit BEFORE the handler runs.
import type { Hooks } from "@daloyjs/core";

export function maintenanceMode(opts: { enabled: () => boolean }): Hooks {
  return {
    beforeHandle(ctx) {
      if (!opts.enabled()) return;            // ← void: continue the pipeline
      if (ctx.route?.path === "/healthz") return; // ← let liveness through
      return new Response(
        JSON.stringify({
          type:   "https://daloyjs.dev/errors/service-unavailable",
          title:  "Maintenance in progress",
          status: 503,
          detail: "Back in roughly 5 minutes. Thank you for your patience.",
        }),
        {
          status: 503,
          headers: {
            "content-type": "application/problem+json",
            "retry-after": "300",
          },
        },
      );
    },
  };
}

// Globally:
app.use(maintenanceMode({ enabled: () => process.env.MAINTENANCE === "1" }));

// src/middleware/require-role.ts — a per-route auth gate.
// beforeHandle is where authentication and authorization live, because
// short-circuiting here means the handler never runs, never queries the DB,
// never consumes the body, never burns its rate-limit slot.

export function requireRole(role: string): Hooks {
  return {
    beforeHandle(ctx) {
      const user = ctx.state.session?.user;
      if (!user)               throw new UnauthorizedError("Sign in first");
      if (!user.roles?.includes(role))
                               throw new ForbiddenError(`Need role: ${role}`);
    },
  };
}

app.route({
  method: "DELETE",
  path: "/admin/users/:id",
  handler: deleteUser,
  hooks: { ...requireRole("admin") },   // ← scoped to THIS route only
});

// onSend — the right place to stamp response headers on EVERY response,
// including the ones produced by error paths and OPTIONS preflights.

export function stampServerTiming(): Hooks {
  return {
    beforeHandle(ctx) {
      ctx.state._startedAt = performance.now();
    },
    onSend(res, ctx) {
      // Mutate in place — no need to return a new Response.
      const elapsed = performance.now() - (ctx?.state._startedAt ?? 0);
      res.headers.set("server-timing", `app;dur=${elapsed.toFixed(1)}`);
      res.headers.set("x-request-id", ctx?.requestId ?? "unknown");
    },
  };
}

app.use(stampServerTiming());

// You can also REPLACE the response by returning a new one:
//   onSend(res) {
//     if (res.status !== 401) return;
//     return new Response(res.body, {
//       status: 401,
//       headers: { ...Object.fromEntries(res.headers), "www-authenticate": "Bearer" },
//     });
//   }

// onResponse — fire-and-forget observer. Cannot change anything.
// This is your logging/metrics/audit slot. By design it cannot accidentally
// break the response because the bytes are already in flight.

export function accessLog(): Hooks {
  return {
    onResponse(res) {
      // `res` is the SAME response the client received.
      logger.info(
        {
          status: res.status,
          contentType: res.headers.get("content-type"),
          bytes: res.headers.get("content-length"),
        },
        "http",
      );
    },
  };
}

// Same place is perfect for metrics:
//   metrics.histogram("http_response_status").observe(res.status);
//   metrics.counter("http_responses_total").inc({ status: res.status });

// onError — runs on the error path before the response is serialized.
// Return a Response to take over rendering; return nothing to fall through to
// the framework's default RFC 9457 serialization (which is what you usually want).

app.use({
  onError(err, ctx) {
    // 1. Always log. The framework will not double-log.
    ctx?.log.error(
      {
        err,
        requestId: ctx.requestId,
        route: ctx.route?.operationId,
      },
      "unhandled",
    );

    // 2. Translate a specific upstream library error into a domain HttpError.
    if (err instanceof PaymentGatewayTimeout) {
      return new ServiceUnavailableError("Payments are slow right now").toResponse();
    }

    // 3. Anything else: fall through. The framework wraps unknown errors as
    //    InternalError and serializes them as problem+json with the right
    //    production redaction baked in.
  },
});

// afterHandle — transform the handler's return value before serialization.
// Use sparingly. 95% of the time you should just shape the body in the handler.
// Real use case: redact PII from a generic search response across many routes.

export function redactEmail(): Hooks {
  return {
    afterHandle(ctx, result) {
      if (!ctx.route?.path.startsWith("/v1/search")) return; // narrow scope
      // result is whatever the handler returned: { status, body, headers? }.
      // Return a new value, or undefined to leave it alone.
      const shaped = result as { status: number; body: Array<{ email?: string }> };
      return {
        ...shaped,
        body: shaped.body.map((row) =>
          row.email ? { ...row, email: row.email.replace(/(?<=.).(?=[^@]*?@)/g, "*") } : row,
        ),
      };
    },
  };
}

// src/plugins/observability.ts — encapsulated plugin.
// Routes/hooks registered inside `register` are scoped to the child app.
import type { App, Hooks } from "@daloyjs/core";

export const observability = {
  name: "observability",
  register(child: App) {
    child.use(stampServerTiming());
    child.use(accessLog());

    // You can mount routes too — they get the prefix from the parent's call.
    child.route({
      method: "GET",
      path: "/metrics",
      operationId: "metrics",
      responses: { 200: { description: "Prometheus exposition" } },
      handler: async () => ({
        status: 200,
        body: await metrics.render(),
        headers: { "content-type": "text/plain; version=0.0.4" },
      }),
    });
  },
};

// Mount it like this:
app.register(observability, {
  prefix: "/_ops",            // every route inside lives under /_ops
  hooks: { /* extra hooks just for this plugin's scope */ },
  auth: false,                // turn off global auth inside the plugin
});

# What goes where — print this out, tape it to your monitor.

onRequest      ↳ stuff that needs the raw Request (TLS termination metadata,
                 conditional request decoding). No context yet. Cannot decide.

beforeHandle   ↳ AUTH. AUTHZ. RATE LIMITING. Anything that should prevent
                 the handler from running. THIS is where short-circuiting lives.

handler        ↳ your code. Nothing else.

afterHandle    ↳ shape transformations that span MANY routes (PII redaction,
                 envelope wrapping). 95% of the time, just shape it in the handler.

onSend         ↳ response HEADERS for every response (success + error + OPTIONS).
                 Server-Timing, X-Request-Id, Strict-Transport-Security, CSP, …

onResponse     ↳ FIRE-AND-FORGET observers. Logging. Metrics. Audit events.
                 Cannot change the response. This is by design.

onError        ↳ translate framework-foreign errors into HttpError subclasses,
                 log once, fall through to the default problem+json serializer.

# Three patterns that look smart but bite you in production:

# 1) Mutating ctx.state in onResponse. Too late! The response is already gone.
#    Put state changes in beforeHandle / afterHandle. Put OBSERVATION in onResponse.

# 2) Doing auth in afterHandle. The handler already ran (and probably hit the DB,
#    and probably consumed the rate-limit budget). Auth belongs in beforeHandle.

# 3) Catching errors in beforeHandle to "swallow" them. The framework already
#    does graceful error → problem+json conversion. Trust it. If you need to
#    REWRITE the error, do it in onError. If you need to PREVENT it, do it in
#    beforeHandle with a short-circuit Response or a thrown HttpError.