Docs/Analog adapter

Packages

Analog adapter

Registers Strata controllers in an Analog and Nitro application.

Experimental Analog 2 adapter for Strata: registers @strata-sc/core controllers on the Nitro router from a Nitro server plugin. It does not depend on h3, nitropack or @analogjs/*, and its declarations do not expose H3/Nitro types.

pnpm add @strata-sc/core@next @strata-sc/analog@next
// src/server/strata/posts.controller.ts
import { Controller, Delete, Get, Post } from "@strata-sc/core";
import type { StrataAnalogRequest } from "@strata-sc/analog";
import { z } from "zod";

const productParams = z.object({ id: z.string().transform(Number) });
const createProduct = z.object({ name: z.string().min(1) });

@Controller("/api/posts")
export class PostsController {
  @Get("/:id")
  async findOne(request: StrataAnalogRequest) {
    const { id } = await request.validateParams(productParams);
    return { id };
  }

  @Post()
  async create(request: StrataAnalogRequest) {
    return request.readValidatedJson(createProduct);
  }

  @Delete("/:id")
  remove(request: StrataAnalogRequest) {
    return { deleted: request.params["id"] };
  }
}
// src/server/plugins/strata.ts
import { registerControllers } from "@strata-sc/analog";
import type { StrataAnalogGuard, StrataAnalogInterceptor } from "@strata-sc/analog";
import { defineNitroPlugin } from "nitropack/runtime";

import { PostsController } from "../strata/posts.controller";

const requireAuth: StrataAnalogGuard = ({ request, route, onCleanup }) => {
  // Verify credentials with application-owned code. Never trust an identity
  // copied from a query parameter or arbitrary header.
  const token = request.headers.get("authorization");
  onCleanup(() => releaseRequestResources());
  if (!verifyToken(token)) return { allow: false, status: 401 };
  if (route.method === "DELETE" && !canDelete(token, request.params["id"])) {
    return { allow: false, status: 403 };
  }
  return { allow: true };
};

const timingInterceptor: StrataAnalogInterceptor = async (context, next) => {
  const started = performance.now();
  try {
    return await next();
  } finally {
    recordDuration(context.route, performance.now() - started);
  }
};

const loggingInterceptor: StrataAnalogInterceptor = async ({ route }, next) => {
  try {
    return await next();
  } catch (error) {
    // Record only stable route metadata. Do not log credentials or request data.
    recordSanitizedFailure(route.method, route.path);
    throw error;
  }
};

export default defineNitroPlugin((nitroApp) => {
  registerControllers(nitroApp.router, [PostsController], {
    guards: [requireAuth],
    interceptors: [timingInterceptor, loggingInterceptor],
  });
});

Guards are opt-in and run sequentially before a controller is constructed. Each receives the current request, immutable route metadata (method, final registered path, controller name and handler name), and the same request-local onCleanup used by the controller factory. Return exactly { allow: true } or { allow: false, status: 401 | 403 }. Denials use generic JSON and Cache-Control: no-store; malformed decisions and thrown/rejected guards are application failures. Authentication and authorization remain consumer-owned: Strata does not verify credentials, manage sessions or provide RBAC/ABAC. Guards do not supply CSRF policy or production tenant-isolation certification. Interceptors may optionally wrap controller execution. Guards always run first; interceptors then enter in registration order and unwind in reverse order. Each normally completing interceptor must call and await next() exactly once. An interceptor can inspect, transform or rethrow downstream results and errors. It cannot short-circuit execution. Interceptors are consumer policy, not an authentication or general middleware system; real application adoption and Strata 1.0 remain unqualified.

The interceptor context contains the immutable route information, request and the existing request cleanup hook. Results flow directly to Nitro. Plain data can be transformed; a native Response passed through unchanged retains its headers, status, body and streaming behavior. Interceptors should not read a response body just to log it. Errors propagate to Nitro unless consumer code deliberately catches and replaces one. Such replacement is consumer policy. Cleanup runs after interceptor unwinding and preserves the existing LIFO and AggregateError rules. Do not log credentials, request bodies or private validation issues. Production tracing and client-disconnect cancellation are not qualified. A response body outlives the invocation only through streamResponse(); an ordinary Response does not.

Every @strata-sc/core HTTP decorator (Get, Post, Put, Patch, Delete) is registered for its own method on the Nitro router, and all of them run through the same request-scoped invocation. Handlers receive a StrataAnalogRequest with method, params, query, headers and lazy body readers (readJson(), readText(), readBody()).

Validation is opt-in through validateParams(schema), validateQuery(schema), validateHeaders(schema), readValidatedJson(schema) and readValidatedForm(schema). These accept Standard Schema v1 schemas and return the schema's inferred output type, including transformations. Validators may run synchronously or asynchronously. Zod, Valibot and other conforming libraries work; Analog has no runtime dependency on a schema library.

validateParams sees matched route params as strings, preserving Nitro routing and URL decoding. validateQuery keeps a single value as a string and repeated values as arrays; it performs no implicit coercion. Empty query objects are valid inputs. A schema may transform or coerce values explicitly.

validateHeaders hands the schema a frozen, request-local snapshot typed StrataAnalogHeaders (Readonly<Record<string, string>>): lowercase names, string values, own properties only, no coercion. request.headers is unchanged. The native Headers API has already normalized the names and combined repeated fields with ", "; nothing is split, because a comma can be part of a value. Include transport headers (host, accept, user-agent) in a strict schema or use one that selects only its declared fields (Zod's z.object strips unknown keys by default). Optional headers are z.string().optional().

const metadata = await request.validateHeaders(
  z.object({
    "x-request-id": z.string().min(1).max(128),
    "x-client-version": z.string().regex(/^\d+$/).transform(Number),
  }),
);
// { "x-request-id": string; "x-client-version": number }

This is input validation, not authentication: Strata verifies no credential, and does not trust forwarded or x-forwarded-*. A schema that reads authorization or cookie only checks its shape; verifying it stays with the application, which can still read the native request.headers.

readValidatedJson accepts application/json and application/*+json, with UTF-8 (or no declared charset). readValidatedForm accepts only application/x-www-form-urlencoded; multipart uploads are not supported. Both validated body methods default to a 1 MiB maximum measured from consumed bytes, not Content-Length or JavaScript string length. On Node (Nitro node-server, Analog dev) the rest of an oversized body is drained and discarded rather than buffered, so the 413 leaves the keep-alive connection usable for the next request. Form input accepts no charset declaration or one UTF-8 declaration (utf-8 / utf8, case-insensitive, optionally quoted); unsupported, malformed or duplicate charset declarations answer 415. Empty JSON validates as undefined; an empty form validates as an empty record.

Form schemas receive Readonly<Record<string, string | readonly string[]>>, with the same repeated-value convention as query validation: one occurrence is a string, repeated occurrences are an ordered array, and a missing key is absent. + and %20 decode to space, %2B to a literal plus, and encoded delimiters such as %26 and %3D remain inside their key or value. The first literal = separates a key from a value. Empty keys and values are retained; empty segments from consecutive & characters are ignored. UTF-8, including encoded NUL, is decoded without numeric or boolean coercion. Bracket and dotted names remain literal keys. Malformed percent escapes, invalid percent-encoded UTF-8, and invalid raw UTF-8 answer 400. A validated form is limited to 10,000 non-empty fields; exceeding that limit answers 413 to bound parser amplification.

Call either validated body method before any raw body reader so Analog can enforce the bound on the original body. A raw reader first makes a later validated read a configuration error. After a successful validated read, raw readers reuse its bounded text. Repeated and concurrent calls to the same validated method share one request-local read; JSON and form validation cannot reinterpret one another's body. The raw readers themselves remain unchanged and unbounded.

Expected input failures return safe JSON with Cache-Control: no-store:

Status Error Trigger
400 invalid_request malformed JSON/form encoding or schema issues
413 payload_too_large body exceeds 1 MiB or form exceeds 10,000 fields
415 unsupported_media_type unsupported JSON/form media type or charset

Responses include a stable source (params, query, headers or body) and never include schema issue messages or request values. A validator that throws or rejects is an application failure, not a 400. A malformed Standard Schema contract is a configuration error. Validation failures still run cleanup; cleanup failures retain precedence and are not converted to input responses.

readJson<T>() remains unchecked. Validation is opt-in and does not validate unrelated routes. It does not provide authentication, authorization or CSRF protection. State-changing form endpoints need a consumer-owned CSRF or origin policy that fits the application's authentication model; never trust a form field such as userId, tenant, role or principal as authenticated identity. Unexpected SSR failures are outside this input contract. M3 and Strata 1.0 remain unqualified.

Controllers are request-scoped. An optional controllerFactory (sync or async) creates each request's controller and can register onCleanup callbacks that run after the invocation settles. A handler that returns streamResponse() keeps them open until its body ends.

Application HTTP contract

Controllers and interceptors can throw an expected application error with a conservative status and stable machine-readable code:

import { StrataAnalogHttpError } from "@strata-sc/analog";

throw new StrataAnalogHttpError(404, "not_found", "Product 42 is absent");

Recognized statuses are 400, 404, 409, 422, 429 and 503. Codes must match ^[a-z][a-z0-9_]{0,63}$. The constructor rejects unsupported statuses and malformed codes. The optional message and ErrorOptions (including cause) stay available to server-side diagnostics. The public response uses only { "error": "not_found" }, application/json; charset=utf-8 and Cache-Control: no-store; it never serializes a message, cause, stack, custom details or schema issues. Unexpected exceptions keep Nitro's existing error behavior. Guard-owned 401/403 and validated-input 400/413/415 responses keep their existing contracts.

Errors are translated only after the request's one CleanupScope completes successfully. A cleanup failure, including an AggregateError, remains a server failure and is not hidden behind an application status or guard denial. Interceptors may observe and rethrow application errors; their order, next() rules and reverse unwind behavior are unchanged.

Use the native Web Response API for explicit response statuses and headers:

import { jsonResponse, noContent } from "@strata-sc/analog";

return jsonResponse({ id: product.id }, { status: 201 });
return noContent({ headers: { "x-deleted-product": product.id } });

jsonResponse(value, init?) defaults to 200, serializes once, keeps supplied headers (including multiple Set-Cookie values), and supplies application/json; charset=utf-8 only when no content type was supplied. It uses native Response validation for body/status combinations, so JSON with 204/205/304 and unsupported serialization throw. noContent(init?) always returns an empty 204 and does not add a content type. Both preserve caller headers such as Cache-Control. Plain return values and native Response objects remain supported; Nitro routes do not pass through this adapter.

Complete consumer example

This example is also typechecked from the packed consumer fixture at http-contract-example.ts. The token table and in-memory map are fixture-sized examples; real applications own credential verification and storage.

import { Controller, Delete, Get, Patch, Post } from "@strata-sc/core";
import {
  StrataAnalogHttpError,
  jsonResponse,
  noContent,
  registerControllers,
} from "@strata-sc/analog";
import type {
  StrataAnalogGuard,
  StrataAnalogInterceptor,
  StrataAnalogRequest,
} from "@strata-sc/analog";
import { defineNitroPlugin } from "nitropack/runtime";
import { z } from "zod";

const products = new Map<number, { id: number; name: string; status: "active" | "archived" }>([
  [1, { id: 1, name: "Keyboard", status: "active" }],
]);
const owners = new Map<number, string>([[1, "ada"]]);
const tokens = new Map<string, string>([["fixture-token", "ada"]]);
const durations: number[] = [];
const paramsSchema = z.object({ id: z.coerce.number().int().positive() });
const querySchema = z.object({
  includeArchived: z
    .enum(["true", "false"])
    .transform((value) => value === "true")
    .optional(),
});
const createSchema = z.object({ name: z.string().trim().min(1) });
const patchSchema = z.object({ name: z.string().trim().min(1) });
let nextId = 2;

@Controller("/api/products")
class ProductsController {
  @Get("/:id")
  async get(request: StrataAnalogRequest) {
    const { id } = await request.validateParams(paramsSchema);
    const { includeArchived } = await request.validateQuery(querySchema);
    const product = products.get(id);
    if (!product || (product.status === "archived" && !includeArchived)) {
      throw new StrataAnalogHttpError(404, "not_found");
    }
    return jsonResponse(product);
  }

  @Post()
  async post(request: StrataAnalogRequest) {
    const input = await request.readValidatedJson(createSchema);
    const duplicate = [...products.values()].some((product) => product.name === input.name);
    if (duplicate) throw new StrataAnalogHttpError(409, "conflict");
    const product = { id: nextId++, name: input.name, status: "active" as const };
    products.set(product.id, product);
    owners.set(product.id, "ada");
    return jsonResponse(product, { status: 201, headers: { "cache-control": "no-store" } });
  }

  @Patch("/:id")
  async patch(request: StrataAnalogRequest) {
    const { id } = await request.validateParams(paramsSchema);
    const input = await request.readValidatedJson(patchSchema);
    const product = products.get(id);
    if (!product) throw new StrataAnalogHttpError(404, "not_found");
    if (product.status !== "active") {
      throw new StrataAnalogHttpError(422, "invalid_product_state");
    }
    const updated = { ...product, name: input.name };
    products.set(id, updated);
    return jsonResponse(updated);
  }

  @Delete("/:id")
  async delete(request: StrataAnalogRequest) {
    const { id } = await request.validateParams(paramsSchema);
    if (!products.delete(id)) throw new StrataAnalogHttpError(404, "not_found");
    owners.delete(id);
    return noContent();
  }
}

const requireOwner: StrataAnalogGuard = ({ request, route }) => {
  const token = request.headers.get("authorization")?.replace(/^Bearer /, "") ?? "";
  const principal = tokens.get(token);
  if (!principal) return { allow: false, status: 401 };
  const rawId = request.params["id"];
  const owner = rawId === undefined ? undefined : owners.get(Number(rawId));
  if (owner !== undefined && owner !== principal) return { allow: false, status: 403 };
  return { allow: true };
};

const timing: StrataAnalogInterceptor = async (_context, next) => {
  const started = performance.now();
  try {
    return await next();
  } finally {
    durations.push(performance.now() - started);
  }
};

export default defineNitroPlugin((nitroApp) => {
  registerControllers(nitroApp.router, [ProductsController], {
    guards: [requireOwner],
    interceptors: [timing],
  });
});

The complete consumer fixture checks the public declarations and exercises these APIs from package tarballs installed outside the pnpm workspace. See the HTTP contract qualification for runtime and release evidence.

Streaming responses

Cleanup callbacks normally run when the handler settles, which is too early for a response body that is still being read: an ordinary Response over a ReadableStream finds its request-scoped resources already closed. Return streamResponse() to keep them open for the life of the body:

import { Controller, Get } from "@strata-sc/core";
import { streamResponse } from "@strata-sc/analog";
import type { StrataAnalogControllerFactory } from "@strata-sc/analog";

class OrderCursor {
  async *rows(): AsyncGenerator<string> {
    /* reads from a connection that must stay open */
  }
  close(): void {}
}

@Controller("/api/orders")
class OrdersController {
  constructor(private readonly cursor: OrderCursor) {}

  @Get("/export")
  export() {
    return streamResponse(this.cursor.rows(), {
      headers: { "content-type": "application/x-ndjson" },
    });
  }
}

const controllerFactory: StrataAnalogControllerFactory = (_Controller, { onCleanup }) => {
  const cursor = new OrderCursor();
  onCleanup(() => cursor.close());
  return new OrdersController(cursor);
};

streamResponse(body, init?) takes an async iterable of strings (UTF-8 encoded) or Uint8Array and returns a native Response. It is opt-in: Strata never infers ownership from a response's shape, because every buffered Response also has a ReadableStream body.

Lifetime. After the handler and all interceptors settle, the adapter binds the invocation's cleanup scope to the response. It stays open until the first of:

  • the body completes;
  • the body iterable throws;
  • the consumer cancels the body (response.body.cancel(), or a transport cancelling its reader).

Then the cleanups run once, last registered first and awaited, exactly as for an ordinary request. The body is pulled lazily, one chunk per read, never ahead of the consumer. A cleanup registered while the stream runs (through the factory's onCleanup) is still accepted.

Errors. Status and headers are committed when the first chunk is written, so nothing after that can change the HTTP status. A body that throws errors the stream with that error, after the cleanups have run; if cleanups also fail the stream errors with an AggregateError of the body error followed by every cleanup error. A cleanup that fails after a complete body errors the stream instead of ending it cleanly. No message or stack is ever written to the response body by Strata; what the client observes of an errored stream is up to the transport (see below). Before the first chunk, guards, validation and handler errors behave as for any request: a denied or invalid request never starts a stream.

Interceptors. Passing the same Response through, and reading its headers or status, keeps the stream owned. Replacing it with another response (including new Response(original.body, …)) hands ownership to nobody: the scope closes at once as for an ordinary request, and the abandoned body fails with a StrataAnalogConfigurationError if anything reads it. Reading the body before the adapter owns it fails the invocation the same way; so does returning one streamResponse() object from two invocations.

HEAD. A derived HEAD request cancels the body, which releases the resources.

What the transport decides. Release depends on the transport reading the body to its end or cancelling it. Qualified on the pinned tuple (Analog 2.7.2, Nitro 2.13.4, H3 1.15.11), see the evidence:

Behavior Node (node-server, Vite dev) Cloudflare Pages (local workerd)
Chunks delivered incrementally yes no: the body is buffered
Resources released once after the body yes yes
Client disconnect releases the resources no: when the body ends no: when the body ends
Body error after the first chunk connection left open, no end empty 200, indistinguishable

Client disconnect is not propagated to the body on either runtime, so a body must be finite: an unbounded producer is not released when its client goes away. Strata adds no timers and no abort signal for this. Do not stream where the transport buffers if you need incremental delivery: the body is still delivered, complete, and released, just not early.

Observing requests: onRequestSettled

Opt-in, request-local facts about how each Strata controller invocation ended. Strata does not log, export or store anything: the application decides what to do with them. Without the option nothing is allocated and nothing changes.

import { registerControllers } from "@strata-sc/analog";
import type { StrataAnalogRequestObservation } from "@strata-sc/analog";
import { defineNitroPlugin } from "nitropack/runtime";

function record(o: StrataAnalogRequestObservation): void {
  console.log(
    JSON.stringify({
      event: "strata.request",
      method: o.route.method,
      route: o.route.path, // the registered template, e.g. /users/:id
      outcome: o.outcome,
      status: o.status ?? null, // known only where Strata produced it
      streaming: o.streaming,
      cleanup: o.cleanup,
      invocationMs: o.invocationMs,
      elapsedMs: o.elapsedMs,
    }),
  );
}

export default defineNitroPlugin((nitroApp) => {
  registerControllers(nitroApp.router, [UsersController], { onRequestSettled: record });
});

The observation is a frozen object with route (method, path as registered, controller, handler), outcome, status, phase, streaming, cleanup and two durations.

outcome Meaning status
completed the controller returned and every cleanup succeeded undefined
guard-denied a guard answered 401/403; no controller was constructed 401 / 403
input-rejected validated params, query or body were rejected 400 / 413 / 415
application-error a StrataAnalogHttpError was thrown its status
failed anything else was thrown; it still propagates to Nitro undefined
cleanup-failed a cleanup callback failed (takes precedence over every other outcome) undefined
stream-completed an owned streamResponse() body ended undefined
stream-failed an owned body threw undefined
stream-cancelled an owned body was cancelled (including by a derived HEAD) undefined

status is never inferred: when Nitro owns the final status (a returned value or Response, an unexpected failure) it is undefined, not 200 or 500. phase is guards, execution, cleanup or stream.

When it fires. Exactly once per invocation, after its cleanups ran (last registered first). A handler that returned is not a finished request: a successful handler whose cleanup fails is cleanup-failed. For an owned streamResponse() it fires when the body completes, fails or is cancelled and its cleanups have settled, before the stream's own end is delivered, not when the handler returns. An interceptor that replaces the stream yields a normal completed. A stream the transport never reads or cancels is never reported: Strata does not observe client disconnects and adds no timeout to pretend it did.

Durations use performance.now(). invocationMs covers guards, interceptors and the handler, before cleanup (for a stream: until it was returned). elapsedMs runs until the observation, after cleanup (for a stream: the full body lifetime). On Cloudflare Workers the clock only advances across I/O, so CPU-only work can read 0.

Failure policy. The callback is synchronous. Its return value is ignored and never awaited, and whatever it throws or rejects with is discarded, so it cannot change the response, the original error or a cleanup AggregateError. Do asynchronous work from it only through a lifetime your runtime provides (for example waitUntil); Strata provides none and keeps no queue.

What it never contains. No URL, query or route parameter values, headers, cookies, bodies, error objects, messages, causes, stacks, validation issues or response content. The route is the registered template. A callback can of course log secrets it obtains elsewhere.

Scope. Only Strata-owned controller invocations. Native Nitro routes, Analog server functions and the API boundary's own 404/405/OPTIONS answers are not observed (observing boundary decisions would need its own contract).

Correlating a request: requestCorrelation

Opt-in (default false). When enabled, Strata generates one random identifier (globalThis.crypto.randomUUID()) for each matched Strata controller invocation and carries it on the explicit request object, so it survives await without AsyncLocalStorage or any global registry:

  • request.correlationId is set before the first guard runs, and is the same value in guards, interceptors, the controller factory and the handler;
  • the onRequestSettled observation has the identical correlationId.
registerControllers(nitroApp.router, [UsersController], {
  requestCorrelation: true,
  guards: [({ request }) => (log(request.correlationId, "guard"), { allow: true })],
  onRequestSettled(o) {
    console.log(JSON.stringify({ id: o.correlationId, route: o.route.path, outcome: o.outcome }));
  },
});

The identifier is random: it is never taken from a header, cookie, query value or body (a client-sent x-request-id is ignored), and holds no user, tenant, route parameter, credential or timestamp. Disabled, nothing is generated and neither request.correlationId nor the observation field exists, so the observation keeps its previous exact shape. Status, error handling, cleanup order, AggregateError precedence and stream ownership are unchanged: for an owned streamResponse() the id stays on the observation until the body completes, fails or is cancelled.

It is for operational correlation only, not a session, tenant, CSRF or authorization value, and Strata does not set any response header or add it to a body. Exposing it is your policy, for example:

interceptors: [
  async ({ request }, next) => {
    const result = await next();
    return result instanceof Response && request.correlationId
      ? new Response(result.body, {
          status: result.status,
          headers: { ...Object.fromEntries(result.headers), "x-request-id": request.correlationId },
        })
      : result;
  },
],

It does not provide distributed tracing or propagation across services.

API boundary: 404, 405, HEAD and OPTIONS

By default registerControllers() only adds routes to Nitro's router, so a request that matches none of them falls through to Analog's HTML renderer: GET /api/unknown answers 200 text/html, and so does an unsupported method on a known path. The opt-in apiBoundary option makes selected path prefixes an explicit API namespace with deterministic, safe answers:

import { registerControllers } from "@strata-sc/analog";
import { defineNitroPlugin } from "nitropack/runtime";

export default defineNitroPlugin((nitroApp) => {
  registerControllers(nitroApp.router, [OrdersController], {
    apiBoundary: {
      prefixes: ["/api"],
      // Native Nitro routes under the prefix, declared for accurate 405 + Allow.
      nativeRoutes: [{ path: "/api/health", methods: ["GET"] }],
      head: "derive", // default
      options: "allow", // default: "off"
    },
  });
  // Later calls only add routes; the shared boundary already covers them.
  registerControllers(nitroApp.router, [ProductsController], { guards: [requireToken] });
});

A complete, compile-checked version (two controllers, a protected one, a native route and the boundary) is api-boundary-example.ts.

Request Answer
Matches a Strata route and method The route runs: guards, interceptors, factory, handler, cleanup
Matches a native Nitro route that handles the method Nitro serves it, untouched
Below an owned prefix, matches nothing 404, {"error":"not_found"}, application/json; charset=utf-8, Cache-Control: no-store
Matches a Strata (or declared native) path, method not handled 405, {"error":"method_not_allowed"}, same headers plus Allow
Outside every owned prefix (pages, assets, /_analog/fn/*) Unchanged: Analog and Nitro decide

Ownership. The boundary owns only the prefixes you list. A prefix is one or more static segments (/api, /internal/v1); /, wildcards, parameters, repeated separators and overlapping prefixes are configuration errors, so the website itself can never be owned by accident. Internally it registers a fallback for every method on /<prefix> and /<prefix>/**; Nitro's router always prefers a more specific route that handles the request's method, so native routes, Strata routes and Analog's own endpoints are never shadowed.

404 versus an application 404. The boundary's 404 means no route matched. A matched handler that throws StrataAnalogHttpError(404, "not_found") produces the same public body, but it did run its guards, interceptors and factory. A path parameter is never treated as an unknown route: GET /api/products/not-a-route reaches the /:id handler, which decides.

Allow. Derived only from registered route metadata (plus declared native routes), in a stable order: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS. If several patterns match the path (a static route next to a /:id route) the set is their union, which is also how Nitro falls through between them. Undeclared native routes are unknown to the boundary: their wrong-method request answers 404, not 405 (declare them with nativeRoutes to get an accurate 405). A declared native route that already handles the method is always served by Nitro.

HEAD (head: "derive", default). HEAD on a path with a Strata GET route runs that route's whole pipeline exactly once (guards, interceptors, factory, handler, one cleanup) and returns its status and headers without a body. A Response result's body is released without being read, so streams are not consumed; a streamResponse() body is cancelled, which releases its resources. A denied GET is a denied HEAD. Handlers see request.method === "HEAD". Plain returned values get the content type H3 would give them (JSON, text); no Content-Length is synthesized. HEAD never maps to a mutating route. It is not derived for native routes. head: "off" answers it like any other unsupported method.

OPTIONS (options: "allow", default "off"). A plain OPTIONS on a known path returns 204 with Allow (including OPTIONS) and no body. A CORS preflight (Origin plus Access-Control-Request-Method) is never answered by Strata: it gets the 405 above without any Access-Control-* header, so the browser blocks the cross-origin request. CORS, authentication and CSRF are not part of routing: keep your CORS middleware, which runs before the router and handles preflights itself. This also means an OPTIONS answer discloses the supported methods of an owned path without authentication, exactly like a 405; leave options off if that matters.

Guards and interceptors do not apply to framework answers. A 404, a 405 and an OPTIONS answer are produced before any route matched, so no guard, interceptor or controller factory runs. Put request-wide policy (authentication for the whole namespace, rate limiting) in Nitro middleware; a route-specific guard is never pretended to apply to a route that did not match.

Registration checks (all before the router is touched): invalid or overlapping prefixes, unknown option keys, invalid nativeRoutes, a policy change for an already owned prefix, and every Strata route below an owned prefix must use static and :param segments only, with unique parameter names and no two routes of one method that differ only in parameter names (Nitro would serve them from one entry). Routes outside owned prefixes keep every existing behavior. The metadata is scoped to the router, so independent Nitro apps and server lifetimes never share it.

Known limits. A native method-less catch-all that Nitro registers for exactly /<prefix>/** is replaced by the fallback (use a method-specific file such as [...].get.ts, which keeps priority). Path matching follows what the router already decoded (%34%32 is 42, %2F stays encoded, one trailing / is ignored, // never matches). Nitro's router does not backtrack out of a static branch (/a/new/x against /a/new/y and /a/:id/x); the boundary then serves the matching Strata route instead of contradicting its own route table. Declaring Analog's own /_analog prefix is unsupported.

Registration

  • registerControllers() validates the whole batch (controllers, handlers, controllerFactory, route keys) before touching the router. If any check fails, it throws a StrataAnalogConfigurationError and registers nothing.
  • Two Strata routes with the same HTTP method and final path (for example GET /api/users) on one router are a configuration error, whether they come from one controller, two controllers or two calls.
  • Static and named-parameter routes are compared by their normalized final path shape. Same-method routes such as GET /products/:id and GET /products/:slug fail preflight. Nitro/H3 v1 also shares parameter-name metadata across methods, so different templates with the same shape fail even across methods. The exact same template remains valid for multiple methods; static routes such as /products/new remain distinct from /products/:id.
  • Shape checks cover only static segments and whole named-parameter segments, matching the API boundary grammar. Outside an apiBoundary, unsupported Nitro patterns retain Nitro behavior and only exact method/path duplicates are checked. Native Nitro routes remain outside Strata's ownership; declare native routes in apiBoundary.nativeRoutes for boundary validation.
  • Repeated calls on one router are supported for non-overlapping routes, and the same controllers can be registered on different routers.
  • Duplicate detection covers Strata registrations on the same router only; it does not see native Analog/Nitro routes (declare them in apiBoundary.nativeRoutes when you want accurate 405 answers).
  • Registration is atomic with respect to Strata configuration validation. It is not transactional against failures thrown by the external router while committing routes: that error propagates, and routes the router already accepted cannot be rolled back.

Pre-1.0 and experimental. 0.x releases may contain breaking changes in any minor. Release candidates are published on the next dist-tag. ESM only, Node.js >= 22.

See the repository README for documentation. License: MIT.

EARLY, OPEN, AND DELIBERATE

Build the next layer with us.

Strata is experimental today. Server Components and controllers ship as 0.x packages on npm, and Server Components are dogfooded on this site. The design work is public and contributions are welcome.