typespec-hono 0.22.0 → 0.24.0

package/src/runtime.ts

@@ -1,5 +1,5 @@
 import type { Context, Env, Input, MiddlewareHandler } from "hono";
-import type { ZodType } from "zod";
+import type { output, ZodError, ZodType } from "zod";
 
 /**
  * One arm of an operation's declared response set, as the document publishes it.
@@ -14,36 +14,14 @@ export interface ResponseArm {
 	readonly status: number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
 	readonly schema: ZodType | undefined;
 	/**
-	 * The media types this response offers, where the document names MORE than one.
-	 *
-	 * Absent where it names one, which is what an application already assumes, so "one type" and
-	 * "not carried" are the same state rather than two to tell apart. Present, it is the set to
-	 * negotiate against: `selectContentType` takes the caller's `Accept` and these.
+	 * Every media type this response offers, including a single one. Absent where there is no body.
 	 */
 	readonly contentTypes?: readonly string[];
 	/**
-	 * The headers this response declares, as the document publishes them.
-	 *
-	 * **Two names, because two different things need them.** `name` is the WIRE name, which is what
-	 * the response sets; `property` is the name on the value the handler returned, which is where the
-	 * value is read from. `@header("x-correlation-id") correlationId: string` is `x-correlation-id`
-	 * on the wire and `correlationId` in the result, and they differ for any header with a hyphen.
-	 *
-	 * Absent where the response declares none.
+	 * The headers this response declares, by the WIRE name the response sets. `optional` is the
+	 * document's `required: false`. Absent where the response declares none.
 	 */
-	readonly headers?: readonly { readonly name: string; readonly property: string }[];
-	readonly when?: {
-		readonly property: string;
-		/**
-		 * **A number too, because a `@statusCode` union selects by the status itself.**
-		 *
-		 * `model Created { @statusCode statusCode: 200 | 201 }` names the property that chooses, and
-		 * its values are the statuses. The discriminator case carries a boolean or string literal off
-		 * the body instead; both are the same question - which arm did the handler mean - so both use
-		 * this one field.
-		 */
-		readonly value: boolean | number | string;
-	};
+	readonly headers?: readonly { readonly name: string; readonly optional: boolean }[];
 }
 
 /**
@@ -85,32 +63,39 @@ export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
  * assertion invented to put the guarantee back.
  *
  * What is left for the app to supply is genuinely app-specific: how a request becomes a caller's
- * context, and how a result becomes a response. Everything else, routing, validation, which
- * validator applies to which target, what status each arm answers, is generated.
+ * context, and what a refusal looks like. Everything else, routing, validation, which validator
+ * applies to which target, which statuses an operation may answer with and how each one is served,
+ * is generated.
  */
 
 /**
- * How an operation's return value is wrapped.
+ * The Hono environment the generated server mounts on.
  *
- * Identity by default, so an operation may simply return its value. An app with a result envelope
- * points `runtime-module` at its own module and re-declares this as, say, `ServiceResult<T>`, which
- * is what keeps the generated `Operations` interface concretely typed end to end instead of falling
- * back to `unknown` and reintroducing the cast this whole change exists to delete.
- */
-export type Result<T> = T;
-
-/**
- * The Hono environment the generated server mounts on, and the caller context its operations take.
+ * **An interface, so an application AUGMENTS it rather than replacing this module.**
+ *
+ * ```ts
+ * declare module "./generated/runtime.gen.js" {
+ * 	interface AppEnv {
+ * 		Bindings: { BACKEND: Service<Backend> };
+ * 		Variables: { principal: Principal };
+ * 	}
+ * }
+ * ```
  *
- * **Concrete on purpose.** Making `registerRoutes` generic over the environment does not work:
- * Hono narrows `Context` per route and its conditional types cannot reduce
- * `IfAnyThenEmptyObject<E extends Env ? ...>` while `E` is an unbound parameter, so nothing the app
- * supplies is ever assignable and every call site needs a cast. Naming the types here instead, an
- * app points `runtime-module` at its own module and re-declares them, keeps every generated call
- * site concrete and cast-free. Identity defaults, so an app with neither can ignore both.
+ * That is the idiom Hono itself uses for `ContextVariableMap`, and it is what lets this module be
+ * emitted beside the generated code on every compile instead of being copied into an application and
+ * aged there. A copy was the only other way to name an environment: a gateway ran a runtime from
+ * `0.10.1` while the emitter reached `0.21.0`, carrying a content-negotiation defect fixed eleven
+ * releases earlier.
+ *
+ * **Concrete rather than a type parameter of `registerRoutes`, and that was measured twice.** Hono
+ * narrows `Context` per route, and its conditional types cannot reduce
+ * `IfAnyThenEmptyObject<E extends Env ? ...>` while `E` is an unbound parameter, so nothing an
+ * application supplies is ever assignable and every call site needs a cast. Confirmed again on hono
+ * 4.13.1 with TypeScript 7.0.2: three `TS2345`s on a three-route probe.
  */
-export type AppEnv = Env;
-export type Ctx = unknown;
+// oxlint-disable-next-line typescript/no-empty-interface -- augmented by the application.
+export interface AppEnv extends Env {}
 
 /** Anything an operation may hand back: the value, or a promise of it. */
 export type Awaitable<T> = T | Promise<T>;
@@ -140,7 +125,7 @@ export type Awaitable<T> = T | Promise<T>;
  * **Specificity was implemented as a tie-break and that was wrong three ways at once**, all of them
  * live in a published runtime until `test/negotiation.test.ts` was written. Scoring every matching
  * range and keeping the best `(q, specificity)` pair lets a permissive wildcard out-vote the precise
- * rule a caller wrote about that exact type - so `Accept: *​/*, application/json;q=0` was served
+ * rule a caller wrote about that exact type - so an `Accept` of any type at all followed by `application/json;q=0` was served
  * JSON, which is the one outcome an explicit refusal must never produce. The prose above stated the
  * right rules the whole time; nothing compared it to the code.
  *
@@ -214,20 +199,169 @@ export const headOnly: MiddlewareHandler = async (c, next) =>
 	c.req.method === "HEAD" ? next() : c.notFound();
 
 /**
- * **The request-body middleware used to live here, and it moved into `app.gen.ts`.**
+ * **A route whose template writes a query string, `/items?fixed=true{&param}`, is only that route when
+ * the request carries it.** A router matches paths, so the pairs are checked here, and a request
+ * without them gets the 404 any unrouted request gets, through whatever `app.notFound()` the
+ * application has set. In the runtime for the same reason as {@link headOnly}.
+ */
+export const literalQuery =
+	(pairs: readonly (readonly [string, string])[]): MiddlewareHandler =>
+	async (c, next) =>
+		pairs.every(([name, value]) => c.req.query(name) === value) ? next() : c.notFound();
+
+/**
+ * A response body that does not match the schema the document publishes for its status.
+ *
+ * **Thrown, so an application decides what a contract failure answers with in `app.onError`**,
+ * which is where Hono puts that decision. Before this existed every consumer made the same check in
+ * its own `respond` and answered differently - a 500, a 502, a 502 with the issues in the body, a 502
+ * with them redacted - and only one of them checked failure bodies at all.
+ *
+ * `issues` are Zod's, so they carry paths and codes. They also carry the offending VALUES; an
+ * application that logs them should decide whether its responses may contain anything it would not
+ * log.
+ */
+export class ResponseContractError extends Error {
+	constructor(
+		readonly operationId: string,
+		readonly status: number,
+		readonly issues: ZodError["issues"],
+		/**
+		 * Which half of the response broke its contract. **Defaulted, so the three-argument form an
+		 * application may already construct or match on keeps working.**
+		 */
+		readonly part: "body" | "headers" = "body",
+	) {
+		super(
+			`${operationId} answered ${status} with ${part === "body" ? "a body" : "headers"} its document does not permit`,
+		);
+		this.name = "ResponseContractError";
+	}
+}
+
+/**
+ * A handler answered with a status its operation does not declare.
+ *
+ * **Unreachable from a typed handler.** The generated `Operations` interface types every result as
+ * the union of the declared statuses, so a literal outside it does not compile. This is what a CAST
+ * produces, or a result that crossed a boundary the type system cannot see into, such as untyped
+ * data from a service binding. Thrown rather than served, because serving it would publish a status
+ * the contract does not state.
+ */
+export class UndeclaredStatusError extends Error {
+	constructor(
+		readonly operationId: string,
+		readonly result: unknown,
+	) {
+		const status =
+			typeof result === "object" && result !== null && "status" in result
+				? String(result.status)
+				: "no status";
+		super(`${operationId} answered ${status}, which its document does not declare`);
+		this.name = "UndeclaredStatusError";
+	}
+}
+
+/**
+ * The body a response SERVES: what the handler returned, parsed against the schema the document
+ * publishes for that status.
  *
- * `byContentType` and `optionalBody` were exported from this module and imported by the generated
- * server, which made them part of a SECOND contract this package has: what an application that
- * points `runtime-module` at a module of its own must export. That contract is easy to break without
- * noticing, and it was the reason a required single-media-type body kept `zValidator` - whose
- * `HTTPException` on an unreadable body is a `text/plain` 400 raised before `deps.invalid`, escaping
- * the app's error envelope. Routing those through `byContentType` closed the gap in one line and
- * made that export mandatory for every substituting app: measured, 15 arms red.
+ * **What is served is the PARSED value, not the one the handler returned.** A schema that strips
+ * undeclared keys therefore strips them from the wire too, which is how an internal field such as a
+ * tenant id is kept out of a response the document does not publish it in. Seven of the nine
+ * consumer surfaces surveyed relied on exactly that, each in its own hand-written `respond`.
  *
- * Emitting the middleware instead closes the gap and SHRINKS the runtime contract by these two
- * names. Nothing generated imports them, so keeping them here would leave a second implementation of
- * body reading that nothing exercises - which is how two copies of one rule drift apart.
+ * Synchronous, because nothing this emitter writes is asynchronous - `test/sync.test.ts` asserts it
+ * over the whole corpus - and the asynchronous path costs 2.6x per parse.
  */
+export function servedBody<S extends ZodType>(
+	schema: S,
+	value: unknown,
+	operationId: string,
+	status: number,
+): output<S> {
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) throw new ResponseContractError(operationId, status, parsed.error.issues);
+	return parsed.data;
+}
+
+/**
+ * Declared response headers, as the strings a response carries.
+ *
+ * An optional header the handler did not supply is omitted rather than sent as `"undefined"`, and a
+ * typed value - a `retry-after` declared `int32` - is written as its text. Hono's `HeaderRecord`
+ * refuses `undefined`, so dropping it here is also what keeps the generated call sites free of a
+ * conditional per header.
+ */
+export function headersOf(declared: Readonly<Record<string, unknown>>): Record<string, string> {
+	const headers: Record<string, string> = {};
+	for (const [name, value] of Object.entries(declared)) {
+		if (value !== undefined) headers[name] = String(value);
+	}
+	return headers;
+}
+
+/**
+ * Declared response headers, CHECKED against the schemas the document publishes for them.
+ *
+ * **The body beside them was always checked and these never were.** `servedBody` parses every
+ * response body against its status's schema and throws `ResponseContractError`; a declared header
+ * went through `headersOf`, which is `String(value)` and nothing else. Measured on a generated
+ * server: a header the document constrains to `^[A-Za-z0-9-]+$` was served as
+ * `not a valid id"; injected=1` with a 200, while a body breaking its own schema on the same route
+ * threw. That asymmetry is the whole of what this removes.
+ *
+ * **Not a response-splitting hole, and worth saying so.** `new Response` refuses a header value
+ * containing CR or LF with a `TypeError` on both `workerd` and undici, so the runtime already stops
+ * the injection. What it does not stop is a response that disagrees with its own document, which a
+ * client generated from that document is entitled to rely on.
+ *
+ * **Undefined values are dropped BEFORE the check, not after.** An optional header the handler did
+ * not supply is absent rather than explicitly `undefined`, which is what the emitted schema's
+ * `.exactOptional()` means, and it is also what Hono's `HeaderRecord` requires. The check then runs
+ * on the values as the handler produced them - a `retry-after` declared `int32` is still a number
+ * here - because checking the text would check a different thing than the document describes.
+ *
+ * **What is returned is every header, including ones the schema does not mention.** A response
+ * carries headers the document does not declare, the `Content-Type` this emitter sets among them,
+ * and those are not a contract violation. The schema is a plain object schema, so it ignores them.
+ */
+export function servedHeaders(
+	schema: ZodType,
+	declared: Readonly<Record<string, unknown>>,
+	operationId: string,
+	status: number,
+): Record<string, string> {
+	const present: Record<string, unknown> = {};
+	for (const [name, value] of Object.entries(declared)) {
+		if (value !== undefined) present[name] = value;
+	}
+	const parsed = schema.safeParse(present);
+	if (!parsed.success) {
+		throw new ResponseContractError(operationId, status, parsed.error.issues, "headers");
+	}
+	return headersOf(present);
+}
+
+/** RFC 9110 `token`, less `*`, which names a range rather than a type. */
+const MEDIA_TOKEN = "[!#$%&'+.^_`|~0-9A-Za-z-]+";
+const SERVED_MEDIA_TYPE = new RegExp(`^(${MEDIA_TOKEN})/${MEDIA_TOKEN}\\s*(;.*)?$`);
+
+/**
+ * Whether a media type a handler answers with lies inside a range the document offers.
+ *
+ * **A range is not a type a response can be sent as**, so where a status offers `image/*` the handler
+ * names the concrete type, and its result type already refuses one outside the range. This is what a
+ * CAST reaches, or data from a service binding: `text/html` under `image/*`, or `image/*` itself,
+ * would otherwise be served with a `Content-Type` the document does not permit. Type names compare
+ * case-insensitively (RFC 9110 section 8.3.1), and parameters such as `charset` are allowed.
+ */
+export function mediaTypeWithin(served: string, range: string): boolean {
+	const type = SERVED_MEDIA_TYPE.exec(served)?.[1];
+	if (type === undefined) return false;
+	if (range === "*/*") return true;
+	return range.endsWith("/*") && type.toLowerCase() === range.slice(0, -2).toLowerCase();
+}
 
 /**
  * What the app provides. One object, passed once, rather than a module the generated file imports by
@@ -239,26 +373,25 @@ export const headOnly: MiddlewareHandler = async (c, next) =>
  * so a hook typed against a single `Context<E>` is not assignable at any real call site. Making the
  * hooks generic lets the app write functions that ignore both, without a cast anywhere.
  *
- * **`E` and `C` are PARAMETERS, and they have to be.** The defaults keep the bare `RouteDeps` the
- * generated server writes working for an app that substitutes nothing. An app that substitutes
- * anything binds them once, `export type RouteDeps = BaseRouteDeps<AppEnv, Ctx>` in the module it
- * points `runtime-module` at, and every hook is then typed against its own environment and its own
- * caller context.
+ * **`C` is the caller context, and `registerRoutes` INFERS it from `context`.** An application that
+ * returns a `Caller` from `context` has handlers typed `(ctx: Caller, input)`, with nothing to
+ * declare. It used to be a type an application re-declared in a substituted copy of this module.
  *
- * Re-exporting this interface unparameterised instead does not work, and the reason is not obvious:
- * **Hono's `Context` is INVARIANT in its environment**, because `Context.set` takes `E` as an
- * argument. So `Context<AppEnv, ...>` is not assignable to `Context<Env, ...>` however plain the
- * substituted environment is, and every generated `deps.*` call site fails. Separately, `context`
- * would keep returning the identity `Ctx` (`unknown`) which the app's own handlers then reject.
- * Measured before this was parameterised: **19 errors on a four-operation service.**
+ * **Nothing here renders a successful response, and that is the point.** Which statuses an operation
+ * may answer with, which body each one carries and how it is serialised are all things the document
+ * states, so the generated route does them. A `respond` hook used to be handed every arm and the
+ * handler's result, and every application re-implemented the choice by hand: five status-mapping
+ * tables across the consumers surveyed, none consulting the arms, one sending a declared 404 as 400.
+ * What remains are the refusals that happen before a handler runs, whose envelope only the
+ * application knows.
  */
-export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
+export interface RouteDeps<E extends Env = AppEnv, C = unknown> {
 	/**
 	 * The gate the DOCUMENT publishes, as middleware.
 	 *
 	 * **Which scopes an operation demands is a contract fact; how a token is verified is not.**
 	 * `@useAuth(OAuth2Auth<...>)` reaches OpenAPI as `security` per operation, so the requirement is
-	 * generated and this implements the check. The same split as `context` and `respond`. Emitted
+	 * generated and this implements the check. The same split as `context`. Emitted
 	 * only where the operation declares scopes, which is why an internal surface with none is
 	 * unaffected.
 	 *
@@ -280,9 +413,17 @@ export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
 	/**
 	 * The caller's context, or `null` when there is none to establish.
 	 *
-	 * `authentication` is what the DOCUMENT says, and only that: `"none"` where the operation
-	 * declares `@useAuth(NoAuth)` (`security: []` in OpenAPI) and `"required"` otherwise. Deciding
-	 * it at generation time is the point: the gate the document publishes is the gate that runs.
+	 * `authentication` is what the DOCUMENT says, and only that:
+	 *
+	 * - `"none"`: no requirement asks for anything (`@useAuth(NoAuth)`, or no authentication at all);
+	 * - `"optional"`: an anonymous alternative sits beside a real one (`NoAuth | BearerAuth`), so
+	 *   `authorize` has admitted this caller either way and a presented credential should still be
+	 *   read;
+	 * - `"required"`: every alternative asks for something.
+	 *
+	 * **`"optional"` is new, and without it the middle case was reported as `"none"`**, so a caller
+	 * with a valid token on an optional route was never established as a caller. Deciding it at
+	 * generation time is the point: the gate the document publishes is the gate that runs.
 	 *
 	 * **It used to be `"none" | "account" | "resource"`, and the last two were an invention.** They
 	 * were chosen by whether the path had parameters, which no OpenAPI keyword expresses and which
@@ -292,7 +433,7 @@ export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
 	 */
 	readonly context: <P extends string, I extends Input>(
 		c: Context<E, P, I>,
-		authentication: "none" | "required",
+		authentication: "none" | "optional" | "required",
 	) => C | null;
 	/** The response when `context` returns `null`. */
 	readonly noContext: <P extends string, I extends Input>(c: Context<E, P, I>) => Response;
@@ -318,13 +459,4 @@ export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
 		result: { readonly success: boolean },
 		c: Context<E, P, I>,
 	) => Response | undefined;
-	/**
-	 * Turn an operation's result into a response, checked against the schema the document publishes
-	 * for the arm that applies. A bodyless success is an arm whose `schema` is `undefined`.
-	 */
-	readonly respond: <P extends string, I extends Input>(
-		c: Context<E, P, I>,
-		arms: readonly ResponseArm[],
-		result: unknown,
-	) => Awaitable<Response>;
 }

package/dist/src/security.d.ts

@@ -1,29 +0,0 @@
-import { type HttpOperation } from "@typespec/http";
-import type { Program } from "@typespec/compiler";
-import type { SecurityRequirement } from "./runtime.js";
-/**
- * What the DOCUMENT says a caller must satisfy, in the shape the document says it.
- *
- * **The scheme was being thrown away, and only "is a caller needed" survived.** `@useAuth(BearerAuth)`
- * reaches OpenAPI as `security: [{ "BearerAuth": [] }]`, and this emitter reduced that to
- * `deps.context(c, "required")`. A gate was emitted ONLY when the scheme carried scopes, so for
- * bearer, api-key and basic, which is the common case, nothing carried which scheme at all. An
- * application whose `context` read a cookie would happily serve a route the document says needs a
- * bearer token, and nothing anywhere would notice.
- *
- * **Passed through, never enforced here.** Which credentials satisfy a scheme is the application's
- * business and could not be anything else; which schemes an operation ACCEPTS is a contract fact and
- * is now generated. That is the same split as `context` and `respond`, applied to the half that was
- * missing.
- */
-export type { SecurityRequirement } from "./runtime.js";
-/**
- * The requirements an operation declares. Satisfying **any one** of them authorises the caller,
- * which is what an array of `security` objects means in OpenAPI, and why this is a list of lists
- * rather than a flat set of scopes.
- *
- * Empty when the operation declares `@useAuth(NoAuth)` or no authentication at all.
- */
-export declare function securityFor(program: Program, operation: HttpOperation): SecurityRequirement[];
-/** The requirements as a TypeScript literal, for the generated call site. */
-export declare function renderSecurity(requirements: readonly SecurityRequirement[]): string;

package/dist/src/security.js

@@ -1,48 +0,0 @@
-import { getAuthenticationForOperation } from "@typespec/http";
-/**
- * The requirements an operation declares. Satisfying **any one** of them authorises the caller,
- * which is what an array of `security` objects means in OpenAPI, and why this is a list of lists
- * rather than a flat set of scopes.
- *
- * Empty when the operation declares `@useAuth(NoAuth)` or no authentication at all.
- */
-export function securityFor(program, operation) {
-    const authentication = getAuthenticationForOperation(program, operation.operation);
-    const requirements = [];
-    for (const option of authentication?.options ?? []) {
-        const requirement = {};
-        let anonymous = false;
-        for (const scheme of option.schemes) {
-            /**
-             * **`NoAuth` inside an option means that option needs nothing**, which is how a spec says
-             * "authentication is optional here". It is not a scheme to demand, and emitting it as one
-             * would refuse every anonymous caller the document permits.
-             */
-            if (scheme.type === "noAuth") {
-                anonymous = true;
-                continue;
-            }
-            /**
-             * Scopes belong to the flows of an OAuth2 scheme; every other kind has none. Read from the
-             * scheme rather than assumed, and de-duplicated because two flows may name the same scope.
-             */
-            const scopes = scheme.type === "oauth2"
-                ? [...new Set(scheme.flows.flatMap((flow) => flow.scopes.map((scope) => scope.value)))]
-                : [];
-            requirement[scheme.id] = scopes;
-        }
-        if (anonymous && Object.keys(requirement).length === 0)
-            continue;
-        if (Object.keys(requirement).length > 0)
-            requirements.push(requirement);
-    }
-    return requirements;
-}
-/** The requirements as a TypeScript literal, for the generated call site. */
-export function renderSecurity(requirements) {
-    return `[${requirements
-        .map((requirement) => `{ ${Object.entries(requirement)
-        .map(([scheme, scopes]) => `${JSON.stringify(scheme)}: [${scopes.map((s) => JSON.stringify(s)).join(", ")}]`)
-        .join(", ")} }`)
-        .join(", ")}]`;
-}