Namespace Olve.TypeSpec

ApiOperation: One contract operation as the generated code describes it: its id, its success statuses (usually one; e.g. 201, 202 for a create that may queue) and the error statuses it declares. Attached to each generated endpoint as metadata, so middleware can answer in the contract's terms (see BindingFailureMiddleware).

BindingFailureMiddleware: Answers request-binding failures (a BadHttpRequestException: a malformed or incomplete JSON body, limit=abc, a missing required parameter) through the API's IApiErrorWriter, with the matched ApiOperation so the writer can answer in the contract's terms. Requires RouteHandlerOptions.ThrowOnBadRequest (AddTypeSpecApi(IServiceCollection, JsonSerializerContext) sets it) so the failures reach the middleware. A bare 400 that the endpoint set without writing anything is answered the same way: the request delegate generator (on under Native AOT) answers a failed parse of an optional parameter that way instead of throwing.

JsonResponse<T>: Writes a generated response variant's body as JSON with the given status, through the app's JsonOptions (so the generated source-gen context serializes it). Resolving the type info there, rather than through TypedResults.Json, keeps the generated code free of reflection warnings under Native AOT.

OperationHandlerAttribute: Marks a class as the handler of the operations whose generated handler interfaces it implements. The generated services.AddOperationHandlers() registers exactly the marked classes, transient; a class that only implements the interface (a decorator, a test double) is not registered.

RequestValidation: Runs a generated request-body validator (from the spec's @maxLength etc.) before the handler; a failure is a 400 written by the API's IApiErrorWriter, like a binding failure.

ResponseHeaders: Sets a generated response variant's declared headers (its @header properties), then writes the variant's body. The body is registered for disposal first, so a header value the server refuses can't leak its stream. A null value (an optional header left unset) is not sent.

ServerSentEventsResult<T>: Writes a handler's events as text/event-stream: each event's name is its EventType, its id the item's, and its data the JSON of the event serialized as the union (so the type discriminator is always written). The stream ends quietly when the client disconnects or the app stops, so open streams never hold up shutdown.

StreamResponse: Writes a generated response variant's binary body (bytes with a non-JSON content type) by copying content to the response as it is read, so large files are never buffered. The stream is disposed once written, or when the response is if writing never starts. A declared Content-Length header sets the length.

TextResponse: Writes a generated response variant's text body (a string with a text/* content type) as UTF-8, as is: not as a JSON string.

TypeSpecApiExtensions: Wires a generated API surface into the app. The generated code calls these from its own Add…Api / Use…Api, passing what only it knows: its JSON context and handler types.

ServerSentEvent<T>: One event an SSE operation's handler yields: its data and its SSE id (null sends it without one, e.g. heartbeats, so clients' Last-Event-ID never points at it).

IApiErrorWriter: Writes the errors the runtime itself answers with, before a handler runs: a request-binding failure (malformed JSON, limit=abc, a missing required parameter) or a failed request validation. The service registers one implementation, so every API keeps its own error body; a typical implementation answers the body only when the matched operation declares the status (Declares(int)) and the bare status otherwise.

IOperationHandler<TRequest, TResponse>: Implements one contract operation: takes its generated request record and returns one of the responses the contract declares for it (the generated per-operation response union), so an undeclared status can't compile. Expected failures are declared responses, not exceptions.

IOperationResponse: One declared response of an operation: a variant of the generated per-operation response union (WidgetsUpdateResponse.Conflict, …) that knows its status and how to write itself.

IServerSentEvent: An event of a generated SSE event union (an @events union in the contract). The event name on the wire is its EventType, which is also the type of its data.