Define Fetch application and request context contracts

[Romakita]

Parent Epic: #3436

Goal

Define the public contracts that make a Ts.ED application a native Fetch application while keeping the HTTP core independent from Node.js and framework-specific abstractions.

Scope

• Define the TsEDFetchApp / Fetch handler contract.
• Define an optional runtime context for capabilities not represented by Request.
• Revisit PlatformContext for a Fetch-native HTTP model.
• Use standard Web primitives (Request, Response, URL, Headers, FormData, ReadableStream, AbortSignal).
• Define request-scoped DI lifecycle around a Fetch request.
• Ensure the public contract does not expose IncomingMessage, ServerResponse, Koa context, Express request/response, or equivalent wrappers.

Candidate API

interface TsEDFetchApp {
  fetch(request: Request, context?: RuntimeContext): Response | Promise<Response>;
}

interface RuntimeContext<Env = unknown, Platform = unknown> {
  env?: Env;
  platform?: Platform;
  waitUntil?(promise: Promise<unknown>): void;
}

The exact API is part of this story and may evolve during implementation.

Acceptance criteria

• A stable Fetch handler contract is defined and exported by @tsed/platform-fetch.
• Request-scoped Ts.ED context can be created from a standard Request.
• Runtime-specific information can be supplied without mutating or wrapping Request.
• No node:http types leak into the public Fetch contracts.
• The contracts can represent Bun/Workers/Vike/Hono-style execution without framework-specific types.
• Unit tests validate the contracts using Web API objects only.

[Romakita]

Contract update from the current router work:

• The portable boundary remains Web Fetch: a router exposes fetch(request: Request): Response | Promise<Response>.
• FetchRouter is currently a consumer-facing interface, not a premature runtime implementation. It exposes standard HTTP helpers, use() composition, and fetch().
• The method union is deliberately limited to GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS. The exploratory QUERY, HEADR, and OPTION names are not part of the public Fetch contract.
• Endpoint handlers receive a FetchContext with the original Request, decoded params/query/headers/body, and generic host-owned state. This avoids importing DI, Node, Express, Koa, or Fastify types into the router package.
• Schemas are opaque adapter-owned metadata. The contract accepts Ts.ED schemas today without depending on @tsed/schema; adapters remain free to add validation, mapping, and OpenAPI generation.
• Output metadata is a status-code map (200, 400, ...) containing description, optional contentType, headers, and schema.
• A handler may return a native Response, a serializable value, or void. The future platform owns conversion to the final Response.

The implementation deliberately does not introduce a runtime-specific RuntimeContext yet; the generic state slot keeps that decision open without leaking host APIs.

[Romakita]

Follow-up decision: the initial state extension point has been removed from FetchContext. The base contract now contains only Request, decoded params, query, headers, and body. Runtime-specific data will be designed later as a separate RuntimeContext concern, rather than being exposed prematurely to every endpoint handler.

[Romakita]

DX update: FetchRouter is now instantiable so consumers can build a route declaration tree directly. Contract tests cover the concise (path, handler) and object declaration forms of get, all standard verb helpers, fluent chaining, and use(router) / use(path, router). These methods are intentionally declaration-only at this stage; route storage, matching, and dispatch remain work for #3438.

[Romakita]

API composition refinement: defineEndpoint(options) now returns a single-route FetchRouter, rather than a detached options object. This preserves router.get({path, input, output, handler}) for local composition while allowing endpoint modules to be exported and mounted directly: router.use('/api', defineEndpoint({method: 'GET', ...})). The relation between the two public APIs is therefore explicit and no separate registration method is needed.

[Romakita]

OpenAPI customization decision: FetchEndpointOptions now extends Omit<OS3Operation, 'parameters' | 'requestBody' | 'responses'>. Consumers can set standard operation metadata (operationId, summary, description, tags, security, etc.) directly alongside path, input, output, and handler. The omitted fields remain derived from the router contract, preventing competing sources of truth. Because the exported declaration references OS3Operation, @tsed/router now declares @tsed/openspec as a public dependency.

[Romakita]

Response metadata refinement: FetchResponseOptions now combines a shallow OS3MediaType surface (example, examples, encoding) with the response-level links and headers fields. output[status] accepts one option or an array, enabling multiple content types for the same status without exposing the full nested OpenAPI content structure.

[Romakita]

Further contract decisions: response description remains optional and the OpenAPI mapper emits "" when absent; encoding remains available in the simplified media contract; operationId is optional and defaults to a value generated from HTTP method plus path. When a handler returns a value rather than a native Response, the response metadata is selected from the smallest numeric status in output. Schema-owned metadata (description, examples, validation constraints) is preserved when an input is a Ts.ED class; transport-owned metadata remains a per-endpoint concern.

[Romakita]

Request-body contract refinement: input.body supports either a bare schema/class (the conventional JSON case) or exported FetchBodyOptions. The latter combines OS3RequestBody metadata (required, description, examples) with a flat {schema, contentType} representation, so the mapper can produce OpenAPI requestBody.content without consumers constructing its nested shape. Type coverage includes a Ts.ED-style class as the body schema.

[Romakita]

Type-inference refinement: FetchSchema<T> is now Type<T> | JsonSchema<T>. FetchEndpointInputFromSchemas derives the decoded handler input from input.params/query/headers/body, including FetchBodyOptions.schema. As a result, router.get({input: {params: s.object({id: s.string().required()})}, handler}) exposes context.params.id as string without a user-supplied input generic. The context and endpoint option types are exported from the package entrypoint.

[Romakita]

Inference fix: FetchBodyOptions is now generic over its schema. FetchEndpointInputFromSchemas extracts that schema type, so an explicit body form such as {schema: CreatePath, contentType: 'application/json', ...} preserves the class/interface type in context.body just like a bare body schema does.

[Romakita]

Mise à jour du contrat FetchContext : il devient une classe FetchContext<Input> qui étend DIContext. Il expose le Request natif ainsi que les valeurs déjà décodées (params, query, headers, body) avec les types issus de l’endpoint. Le scope DI (logger, cache, providers request-scoped et destroy()) reste donc disponible aux handlers. Nous ne lui ajoutons ni Response, ni State, ni parsing/validation : ces responsabilités restent dans l’adapter/runtime. Un test couvre l’héritage DI, les valeurs typées et le cache.

[Romakita]

Correction de typage : le passage de FetchContext en classe avait fait perdre l’inférence avec tsc -b (params, query et body devenaient unknown). FetchContextOptions porte désormais directement l’input générique (DIContextOptions & Input), ce qui permet à TypeScript d’inférer les valeurs à la construction. Pour les routes, FetchEndpointOptions accepte soit un input décodé explicite, soit les FetchEndpointSchemas, et résout le type transmis au handler. Les cas router.get({ input: { params: UserParams, query: UserQuery, body: CreateUser }, handler }) sont validés par yarn tsc -b.