Http.Contract

Http.Contract states the request and response shape of one HTTP operation. It contributes an HttpContract extension node, linked to its operation by ExtensionOf. It attaches to an operation that has an HTTP verb annotation. It is explicit on every HTTP operation, even when a group supplies root and group.

// decorator
@Http.Contract({ group: "users", params: Params, success: User.Public, metadata: { operationId: "users.get" } })

// builder
.http.contract({ group: "users", params: Params, success: User.Public, metadata: { operationId: "users.get" } })

Spec 0005 defines the contract; spec 0013 lets a group fill root, group, success, middleware and metadata.annotator (HTTP).

HttpContractOptionsCopy Anchor Link

Source: packages/runtime/src/Annotation.ts (HttpContractOptions); IR defaults and requirements in packages/compiler/src/extensions/http-contract.ts; semantics in docs/specs/0005-http-contract-extension.md §"Source syntax and lowering".

metadataCopy Anchor Link

HttpOperationMetadata, the argument to annotator:

Absent fields are omitted, not emitted as undefined. HttpOperationAnnotator is (metadata: HttpOperationMetadata) => Context.Context<never>.

ExportedFunctionSymbol is (request: never) => CommandIdentityValue:

The application owns key issuance, the original request and precondition, and retry. effx never mints a key, holds an identity in hidden state or retries (spec 0007 §"Stable command identity").

Source: packages/runtime/src/Annotation.ts (HttpOperationMetadata, HttpOperationAnnotator, CommandIdentityValue, ExportedFunctionSymbol); docs/specs/0010-target-profiles-and-emit-modes.md.

Query over POST: payloadIsQueryCopy Anchor Link

A @Query may use POST only when its contract sets payloadIsQuery: true and declares a payload. The flag exists for read inputs that must not appear in a URL, such as an exact email address. The body stays in the request body, not in the URL or query channel.

Illustrative snippet (the names are invented; the options are the real ones):

@Query({ name: "Org.LookupCandidate", input: LookupInput, success: Candidate })
@Http.Post("/api/lookup")
@Http.Contract({ group: "org", payload: LookupInput, payloadIsQuery: true, success: Candidate })

This is an opt-in declaration of intent. It is not permission to write, not an authorization decision, and not a purity guarantee. The handler stays responsible for read-only semantics (ADR 0010, docs/decisions/0010-query-over-post.md; ADR 0006).

Request channels and query: trueCopy Anchor Link

params, query, headers and payload are derived from the operation's input when you omit them, and an explicit channel always wins (How group defaults merge). An input wrapped by Http.headers(schema) is the headers channel. The derived channel is written into this contract before interpretation, so the IR, paramsKeys/headersKeys and generated files equal the explicit spelling.

query: true still means "the operation's declared input is the query". It is redundant for a GET whose route has no path parameters, and resolves only through a group association: it is EFFX2405 when the method or kind is wrong, input is already assigned to params or headers (or is a header schema), or a payload is declared. The IR option schema accepts a schema for query, so without an association true is not rewritten (group-defaults.ts, http-contract.ts).

Middleware and security markersCopy Anchor Link

middleware entries must be exported HttpApiMiddleware.Service marker classes. The frontend records a security flag for markers that carry the HttpApiMiddleware security type stamp. That is what satisfies EFFX2503 for a protected Http.Access. Root schema-error middleware cannot. The compiler checks presence and identity only, not that a Layer implements the marker.

DiagnosticsCopy Anchor Link

Source: packages/compiler/src/extensions/http-contract.ts (validate); EFFX2410 and EFFX2411 come from the pre-pass packages/compiler/src/request-channels.ts. A property is never silently dropped: a bad combination is a diagnostic before generation.

Generated shapeCopy Anchor Link

Per spec 0005 §"Generation and compatibility": operations group by (root, group), one group class per pair and one root class per root. Endpoint options use Effect v4 params, query, headers, payload, success and error. Status and media wrappers come from HttpApiSchema. Middleware and OpenApi.annotations attach after the endpoint is built. The handler is an ordinary Effect handler. This page does not claim the exact emitted text; inspect it with effx build.