effect 4.0.6 → 4.0.7

package/src/http-api/HttpApiEndpoint.ts

@@ -9,6 +9,62 @@
  * constructors, payload and response schema helpers, and type utilities used by
  * builders and generated clients.
  *
+ * **Request variants**
+ *
+ * A server needs a distinct method and path per endpoint.
+ * `HttpApiBuilder.layer` rejects two endpoints that share them, even when their
+ * query, headers or payload differ. Declare the variants of one operation as a
+ * single endpoint instead:
+ *
+ * - discriminate with a `query` or `headers` field, such as `stream: Schema.Boolean`
+ * - list several `payload` schemas, chosen by the request `Content-Type`
+ * - list several `success` schemas with distinct content types or statuses. One
+ *   of them can be a stream. The server encodes whichever value the handler
+ *   returns, and the client decodes by the response `Content-Type`
+ *
+ * The handler branches on the decoded request, and OpenAPI documents one
+ * operation with every alternative. The generated client returns the union of
+ * the success types. Wrap the client method to narrow the result per variant
+ * when callers need it.
+ *
+ * **Example** (Buffered and streaming variants of one operation)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Schema, Stream } from "effect"
+ * import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api"
+ *
+ * const Stats = Schema.Struct({ cpu: Schema.Number })
+ *
+ * const Api = HttpApi.make("Docker").add(
+ *   HttpApiGroup.make("containers").add(
+ *     // GET /stats?stream=false returns JSON, ?stream=true returns NDJSON
+ *     HttpApiEndpoint.get("stats", "/stats", {
+ *       query: { stream: Schema.Boolean },
+ *       success: [Stats, HttpApiSchema.StreamNdjson({ schema: Stats })]
+ *     }),
+ *     // POST /images accepts a JSON pull request or a tar archive
+ *     HttpApiEndpoint.post("createImage", "/images", {
+ *       payload: [
+ *         Schema.Struct({ fromImage: Schema.String }),
+ *         HttpApiSchema.StreamUint8Array({ contentType: "application/x-tar" })
+ *       ],
+ *       success: Schema.String
+ *     })
+ *   )
+ * )
+ *
+ * const ContainersLive = HttpApiBuilder.group(Api, "containers", (handlers) =>
+ *   handlers
+ *     .handle("stats", ({ query }) =>
+ *       Effect.succeed(query.stream ? Stream.make({ cpu: 1 }, { cpu: 2 }) : { cpu: 1 })
+ *     )
+ *     .handle("createImage", ({ payload }) =>
+ *       Stream.isStream(payload)
+ *         ? Effect.as(Stream.runDrain(payload), "imported")
+ *         : Effect.succeed(`pulled ${payload.fromImage}`)
+ *     ))
+ * ```
+ *
  * @stability unstable
  * @since 4.0.0
  */
@@ -36,6 +92,7 @@ import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import type * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
 import * as MediaType from "./internal/mediaType.ts"
+import { toCodecHttpProperties } from "./internal/toCodecHttpProperties.ts"
 
 const TypeId = "~effect/http-api/HttpApiEndpoint"
 
@@ -71,6 +128,7 @@ type SuccessEncodingServices<S> = S extends HttpApiSchema.StreamSse<
 > ? _Events["EncodingServices"] | _Error["EncodingServices"]
   : S extends HttpApiSchema.StreamUint8Array ? never
   : S extends HttpApiSchema.StreamNdjson<infer _S> ? _S["EncodingServices"]
+  : S extends HttpApiSchema.Upgrade<infer _Headers> ? _Headers["EncodingServices"]
   : S extends Schema.Constraint ? S["EncodingServices"]
   : never
 
@@ -81,6 +139,7 @@ type SuccessDecodingServices<S> = S extends HttpApiSchema.StreamSse<
 > ? _Events["DecodingServices"] | _Error["DecodingServices"]
   : S extends HttpApiSchema.StreamUint8Array ? never
   : S extends HttpApiSchema.StreamNdjson<infer _S> ? _S["DecodingServices"]
+  : S extends HttpApiSchema.Upgrade<infer _Headers> ? _Headers["DecodingServices"]
   : S extends Schema.Constraint ? S["DecodingServices"]
   : never
 
@@ -95,10 +154,19 @@ type ExtractStreamSuccess<S extends SuccessConstraint> = UnwrapReadonlyArray<S>
   Success extends HttpApiSchema.StreamSchema ? Success : never
   : never
 
-type ExtractUpgradeSuccess<S extends SuccessConstraint> = Extract<UnwrapReadonlyArray<S>, HttpApiSchema.Upgrade>
+type ExtractUpgradeSuccess<S extends SuccessConstraint> = UnwrapReadonlyArray<S> extends infer Success ?
+  Success extends HttpApiSchema.Upgrade<infer _Headers> ?
+    [_Headers] extends [never] ? Success : HttpApiSchema.Upgrade<Schema.toCodecStringTree<_Headers>>
+  : never
+  : never
+
+type UpgradeRequest<Success> = [Extract<Success, HttpApiSchema.Upgrade>] extends [never] ? {}
+  : { readonly upgrade: UpgradeFunction<Extract<Success, HttpApiSchema.Upgrade>> }
 
-type UpgradeSocket<Success> = [Extract<Success, HttpApiSchema.Upgrade>] extends [never] ? {}
-  : { readonly socket: Socket.Socket }
+type UpgradeFunction<S> = S extends HttpApiSchema.Upgrade<infer _Headers> ?
+  [_Headers] extends [never] ? () => Effect<Socket.Socket>
+  : (options: { readonly headers: _Headers["Type"] }) => Effect<Socket.Socket>
+  : never
 
 type ExtractWithHeadersSuccess<S extends SuccessConstraint> = UnwrapReadonlyArray<S> extends infer Success ?
   Success extends HttpApiSchema.WithHeaders<infer _Inner, infer _Headers> ? HttpApiSchema.WithHeaders<
@@ -148,7 +216,7 @@ type PayloadError<Payload> = Payload extends HttpApiSchema.StreamUint8Array ? Ht
   : never
 
 type RequestFromParts<Endpoint, ParamsType, QueryType, Payload, HeadersType, Success> =
-  & UpgradeSocket<Success>
+  & UpgradeRequest<Success>
   & ([ParamsType] extends [never] ? {} : { readonly params: Simplify<ParamsType> })
   & ([QueryType] extends [never] ? {} : { readonly query: Simplify<QueryType> })
   & ([Payload] extends [never] ? {} : { readonly payload: RequestPayload<Payload> })
@@ -160,7 +228,7 @@ type RequestFromParts<Endpoint, ParamsType, QueryType, Payload, HeadersType, Suc
   }
 
 type RequestRawFromParts<Endpoint, ParamsType, QueryType, HeadersType, Success> =
-  & UpgradeSocket<Success>
+  & UpgradeRequest<Success>
   & ([ParamsType] extends [never] ? {} : { readonly params: Simplify<ParamsType> })
   & ([QueryType] extends [never] ? {} : { readonly query: Simplify<QueryType> })
   & ([HeadersType] extends [never] ? {} : { readonly headers: Simplify<HeadersType> })
@@ -1111,6 +1179,16 @@ type ErrorNoStream<S extends ErrorConstraint> = [
  * and response schemas, applying automatic JSON or string-tree codecs unless
  * `disableCodecs` is enabled.
  *
+ * **Gotchas**
+ *
+ * URL parameters are flat on the server: each `query` field, each field of a
+ * no-body `payload` and each field of a form-urlencoded `payload` should encode
+ * to a string or an array of strings. A field that encodes to a nested object
+ * is sent as bracket keys (`meta[k]=v`) that the server does not read back, so
+ * it is dropped, or reported missing when required. Send structured values with
+ * an explicit codec such as `Schema.fromJsonString(...)`, or declare bracket
+ * keys literally, for example `"page[size]": Schema.String`.
+ *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
@@ -1217,16 +1295,17 @@ export const make = <Method extends HttpMethod>(method: Method): {
   Error extends ReadonlyArray<Schema.Constraint> ? Error[number] : Error
 > => {
   const disableCodecs = options?.disableCodecs ?? false
-  const transformStringTree = disableCodecs ? identity : Schema.toCodecStringTree
+  const transformProperties = disableCodecs ? identity : toCodecHttpProperties
+  const payload = getPayload(options?.payload, method, disableCodecs)
   return makeProto({
     identifier,
     path,
     method,
-    params: ensureStruct(options?.params, transformStringTree),
-    query: ensureStruct(options?.query, transformStringTree),
-    headers: ensureStruct(options?.headers, transformStringTree),
-    payload: getPayload(options?.payload, method, disableCodecs),
-    success: getSuccessResponse(options?.success, method, options?.payload !== undefined, disableCodecs),
+    params: ensureStruct(options?.params, transformProperties),
+    query: ensureStruct(options?.query, transformProperties),
+    headers: ensureStruct(options?.headers, transformProperties),
+    payload,
+    success: getSuccessResponse(options?.success, method, payload, disableCodecs),
     error: getErrorResponse(options?.error, disableCodecs),
     annotations: Context.empty(),
     middlewares: new Set(),
@@ -1281,11 +1360,13 @@ function getPayload(
         throw new Error("Multiple streaming payloads are not supported")
       }
       hasStream = true
-      const contentType = MediaType.normalize(schema.contentType)
-      if (result.has(contentType)) {
-        throw new Error(`Cannot combine buffered and streaming payloads for content-type: ${schema.contentType}`)
+      for (const declared of schema.contentTypes) {
+        const contentType = MediaType.normalize(declared)
+        if (result.has(contentType)) {
+          throw new Error(`Cannot combine buffered and streaming payloads for content-type: ${declared}`)
+        }
+        result.set(contentType, { encoding: { _tag: "Stream", contentType: declared }, schemas: [schema] })
       }
-      result.set(contentType, { encoding: { _tag: "Stream", contentType: schema.contentType }, schemas: [schema] })
       continue
     }
     const encoding = HttpApiSchema.getPayloadEncoding(schema.ast, method)
@@ -1314,22 +1395,27 @@ const reservedStreamFailureEvent = "effect/http-api/stream/failure"
 function getSuccessResponse(
   success: Schema.Top | ReadonlyArray<Schema.Top> | undefined,
   method: HttpMethod,
-  hasPayload: boolean,
+  payload: PayloadMap,
   disableCodecs: boolean
 ): Set<Schema.Top> {
   if (success === undefined) return new Set()
   const schemas = Arr.ensure(success)
-  validateSuccessResponse(schemas, method, hasPayload)
+  validateSuccessResponse(schemas, method, payload)
   return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
 }
 
 const transformResponseSchema = memoize((schema: Schema.Top): Schema.Top => {
-  if (HttpApiSchema.isStreamSchema(schema) || HttpApiSchema.isUpgrade(schema)) return schema
+  if (HttpApiSchema.isStreamSchema(schema)) return schema
+  if (HttpApiSchema.isUpgrade(schema)) {
+    return schema.headers === undefined
+      ? schema
+      : HttpApiSchema.rebuildUpgrade(schema.protocol, toCodecHttpProperties(schema.headers))
+  }
   if (HttpApiSchema.isWithHeaders(schema)) {
     const inner = HttpApiSchema.isStreamSchema(schema.schema)
       ? schema.schema
       : applyResponseEncoding(schema.schema, HttpApiSchema.getResponseEncodingSchema(schema))
-    return HttpApiSchema.rebuildWithHeaders(schema, inner, Schema.toCodecStringTree(schema.headers))
+    return HttpApiSchema.rebuildWithHeaders(schema, inner, toCodecHttpProperties(schema.headers))
   }
   return transformResponse(schema)
 })
@@ -1353,7 +1439,7 @@ function getErrorResponse(
   return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
 }
 
-function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, method: HttpMethod, hasPayload: boolean) {
+function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, method: HttpMethod, payload: PayloadMap) {
   if (schemas.some(HttpApiSchema.isUpgrade)) {
     if (schemas.length > 1) {
       throw new Error("Cannot combine an upgrade with other success responses")
@@ -1361,8 +1447,11 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
     if (method === "HEAD") {
       throw new Error("HEAD endpoints cannot declare an upgrade")
     }
-    if (hasPayload) {
-      throw new Error("Upgrade endpoints cannot declare a payload")
+    // The 101 can only follow the end of the request, so the body is read before the upgrade.
+    for (const { encoding } of payload.values()) {
+      if (encoding._tag === "Stream" || (encoding._tag === "Multipart" && encoding.mode === "stream")) {
+        throw new Error("Upgrade endpoints cannot declare a streaming payload")
+      }
     }
     return
   }
@@ -1386,10 +1475,12 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
       if (entry.noContent) {
         throw new Error(`Cannot combine no-content and streaming success responses for status: ${status}`)
       }
-      if (entry.bufferedContentTypes.has(MediaType.normalize(inner.contentType))) {
-        throw new Error(
-          `Cannot combine buffered and streaming success responses for status ${status} and content-type: ${inner.contentType}`
-        )
+      for (const declared of inner.contentTypes) {
+        if (entry.bufferedContentTypes.has(MediaType.normalize(declared))) {
+          throw new Error(
+            `Cannot combine buffered and streaming success responses for status ${status} and content-type: ${declared}`
+          )
+        }
       }
       statuses.set(status, { ...entry, stream: inner })
     } else {
@@ -1400,9 +1491,8 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
           throw new Error(`Cannot combine no-content and streaming success responses for status: ${status}`)
         }
         const encoding = HttpApiSchema.getResponseEncodingSchema(schema)
-        if (
-          MediaType.normalize(encoding.contentType) === MediaType.normalize(entry.stream.contentType)
-        ) {
+        const contentType = MediaType.normalize(encoding.contentType)
+        if (entry.stream.contentTypes.some((declared) => MediaType.normalize(declared) === contentType)) {
           throw new Error(
             `Cannot combine buffered and streaming success responses for status ${status} and content-type: ${encoding.contentType}`
           )
@@ -1535,7 +1625,7 @@ function transformResponse(schema: Schema.Top): Schema.Top {
     "~httpApiWithHeaders": {
       ...withHeaders,
       bodyCodec: applyResponseEncoding(withHeaders.body, encoding),
-      headersCodec: Schema.toCodecStringTree(withHeaders.headers)
+      headersCodec: toCodecHttpProperties(withHeaders.headers)
     }
   })
 }
@@ -1553,6 +1643,7 @@ function applyResponseEncoding(schema: Schema.Top, encoding: HttpApiSchema.Respo
 }
 
 function transformPayload(schema: Schema.Top, method: HttpMethod): Schema.Top {
+  if (!hasBody(method)) return toCodecHttpProperties(schema)
   const encoding = HttpApiSchema.getPayloadEncoding(schema.ast, method)
   switch (encoding._tag) {
     case "Json":

package/src/http-api/HttpApiSchema.ts

@@ -10,6 +10,7 @@
  * @stability unstable
  * @since 4.0.0
  */
+import * as Arr from "../Array.ts"
 import * as ByteSize from "../ByteSize.ts"
 import * as Sse from "../encoding/Sse.ts"
 import { constVoid, type LazyArg } from "../Function.ts"
@@ -22,6 +23,7 @@ import * as SchemaAST from "../SchemaAST.ts"
 import * as SchemaTransformation from "../SchemaTransformation.ts"
 import * as Socket from "../socket/Socket.ts"
 import * as Stream from "../Stream.ts"
+import * as MediaType from "./internal/mediaType.ts"
 
 declare module "../Schema.ts" {
   namespace Annotations {
@@ -122,13 +124,15 @@ export type StatusLiteral = HttpStatus.Literal
  *
  * **Details**
  *
- * The status is stored with `.annotateKey({ httpApiStatus: code })`, so a named
- * schema reused with different statuses still emits a single OpenAPI component.
- * If the schema has checks or already has an `httpApiStatus` annotation, it is
- * stored with `.annotate({ httpApiStatus: code })` instead. A later
- * `.annotate({ httpApiStatus })` takes precedence, and a later check drops the
- * status. You can pass either a numeric status code (for example, `201`) or a
- * common literal name (for example, `"Created"`).
+ * Stores the status with `.annotateKey({ httpApiStatus: code })` unless the
+ * schema or any of its checks already has an ordinary `httpApiStatus`
+ * annotation, including an explicit `undefined`. In that case, uses
+ * `.annotate({ httpApiStatus: code })` instead.
+ *
+ * Ordinary status annotations take precedence over key annotations. Checks
+ * without a status annotation preserve the existing status. You can pass
+ * either a numeric code (for example, `201`) or a common literal name
+ * (for example, `"Created"`).
  *
  * @stability unstable
  * @category schemas
@@ -149,9 +153,9 @@ export function status(code: StatusLiteral): {
 export function status(code: number | StatusLiteral) {
   const statusCode = typeof code === "string" ? HttpStatus.fromLiteral(code) : code
   return <S extends Schema.Top>(self: S): S["Rebuild"] =>
-    self.ast.checks !== undefined || hasStatusAnnotation(self.ast)
-      ? self.annotate({ httpApiStatus: statusCode })
-      : self.annotateKey({ httpApiStatus: statusCode })
+    findHttpApiStatusAnnotation(self.ast) === undefined
+      ? self.annotateKey({ httpApiStatus: statusCode })
+      : self.annotate({ httpApiStatus: statusCode })
 }
 
 /**
@@ -321,6 +325,7 @@ export interface StreamSse<
   readonly mode: "sse"
   readonly sseMode: StreamSseMode
   readonly contentType: string
+  readonly contentTypes: Arr.NonEmptyReadonlyArray<string>
   readonly events: Events
   readonly error: Error
   readonly "~Value"?: Value | undefined
@@ -379,6 +384,7 @@ export interface StreamUint8Array extends
   readonly _tag: "StreamUint8Array"
   readonly mode: "uint8array"
   readonly contentType: string
+  readonly contentTypes: Arr.NonEmptyReadonlyArray<string>
   readonly maxBytes: ByteSize.ByteSize | undefined
 }
 
@@ -430,6 +436,7 @@ export interface StreamNdjson<S extends Schema.Constraint> extends
   readonly _tag: "StreamNdjson"
   readonly mode: "ndjson"
   readonly contentType: string
+  readonly contentTypes: Arr.NonEmptyReadonlyArray<string>
   readonly schema: S
   readonly maxBytes: ByteSize.ByteSize | undefined
   readonly maxElementBytes: ByteSize.ByteSize
@@ -523,7 +530,7 @@ export const StreamSse: {
     _tag: "StreamSse",
     mode: "sse",
     sseMode: options.events === undefined ? "data" : "events",
-    contentType: options.contentType ?? defaultStreamContentType("sse"),
+    ...streamContentTypes(options.contentType, "sse"),
     events,
     error: options.error ?? Schema.Never
   })
@@ -534,22 +541,24 @@ export const StreamSse: {
  *
  * **Details**
  *
- * `contentType` defaults to `application/octet-stream`. `maxBytes` only applies
- * to request payloads and has no default.
+ * `contentType` defaults to `application/octet-stream`. Pass a list when the
+ * same stream is sent under several media types. The first entry is the
+ * default response type, and payloads are accepted under every entry.
+ * `maxBytes` only applies to request payloads and has no default.
  *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
 export const StreamUint8Array = (options?: {
-  readonly contentType?: string | undefined
+  readonly contentType?: string | ReadonlyArray<string> | undefined
   readonly maxBytes?: ByteSize.Input | undefined
 }): StreamUint8Array =>
   Schema.make<StreamUint8Array>(streamSchema.ast, {
     [StreamSchemaTypeId]: StreamSchemaTypeId,
     _tag: "StreamUint8Array",
     mode: "uint8array",
-    contentType: options?.contentType ?? defaultStreamContentType("uint8array"),
+    ...streamContentTypes(options?.contentType, "uint8array"),
     maxBytes: options?.maxBytes === undefined ? undefined : ByteSize.fromInputUnsafe(options.maxBytes)
   })
 
@@ -559,7 +568,8 @@ export const StreamUint8Array = (options?: {
  * **Details**
  *
  * `contentType` defaults to `application/x-ndjson` and `maxElementBytes` to 1
- * MiB. `maxBytes` has no default.
+ * MiB. `maxBytes` has no default. Pass a list of content types to accept
+ * aliases such as `application/jsonl`. The first entry is the default.
  *
  * **Example** (Declaring an NDJSON request payload)
  *
@@ -587,7 +597,7 @@ export const StreamUint8Array = (options?: {
  */
 export const StreamNdjson = <S extends Schema.Constraint>(options: {
   readonly schema: S
-  readonly contentType?: string | undefined
+  readonly contentType?: string | ReadonlyArray<string> | undefined
   readonly maxBytes?: ByteSize.Input | undefined
   readonly maxElementBytes?: ByteSize.Input | undefined
 }): StreamNdjson<S> =>
@@ -595,7 +605,7 @@ export const StreamNdjson = <S extends Schema.Constraint>(options: {
     [StreamSchemaTypeId]: StreamSchemaTypeId,
     _tag: "StreamNdjson",
     mode: "ndjson",
-    contentType: options.contentType ?? defaultStreamContentType("ndjson"),
+    ...streamContentTypes(options.contentType, "ndjson"),
     schema: options.schema,
     maxBytes: options.maxBytes === undefined ? undefined : ByteSize.fromInputUnsafe(options.maxBytes),
     maxElementBytes: options.maxElementBytes === undefined
@@ -637,24 +647,27 @@ const UpgradeTypeId = "~effect/http-api/HttpApiSchema/Upgrade"
  *
  * Created with {@link Upgrade}. The response is `101 Switching Protocols`, and
  * the connection then carries raw bytes in both directions as a `Socket`.
+ * `Headers` is the schema of the custom `101` headers, or `never` when the
+ * upgrade declares none.
  *
  * @stability unstable
  * @category models
  * @since 4.0.6
  */
-export interface Upgrade extends
+export interface Upgrade<Headers extends Schema.Top = Schema.Top> extends
   Schema.Bottom<
     Socket.Socket,
     Socket.Socket,
     never,
     never,
     SchemaAST.Declaration,
-    Upgrade
+    Upgrade<Headers>
   >
 {
-  readonly "Rebuild": Upgrade
+  readonly "Rebuild": Upgrade<Headers>
   readonly [UpgradeTypeId]: typeof UpgradeTypeId
   readonly protocol: string
+  readonly headers: Headers | undefined
 }
 
 const upgradeSchema = Schema.declare(Socket.isSocket).pipe(status(101))
@@ -672,26 +685,41 @@ const upgradeSchema = Schema.declare(Socket.isSocket).pipe(status(101))
  *
  * **Details**
  *
- * The handler receives the connection as `socket`. The `101` response is
- * sent when the handler acquires the socket's reader, so a handler can still
- * fail with a declared error before then. Requests that do not ask for
- * `protocol` get `426 Upgrade Required`.
+ * The handler receives an `upgrade` function that returns the connection.
+ * The `101` response is sent when the handler acquires the socket's reader,
+ * so a handler can still fail with a declared error before then. Requests
+ * that do not ask for `protocol` get `426 Upgrade Required`.
  *
- * The client sends `Connection: Upgrade` and `Upgrade: protocol`, and returns
- * the response headers with the connection. Other responses are decoded as
- * the endpoint's errors.
+ * `headers` declares custom `101` response headers, encoded like
+ * `WithHeaders` headers. The handler passes them to `upgrade`, so they can
+ * depend on the decoded request. `Connection`, `Upgrade`, `Content-Length`
+ * and `Transfer-Encoding` cannot be set.
+ *
+ * The endpoint may declare a buffered payload, which is decoded before the
+ * handler runs. Streaming payloads are rejected.
  *
- * The endpoint cannot declare a payload or other success schemas.
+ * The client sends `Connection: Upgrade` and `Upgrade: protocol`, and returns
+ * the response headers with the connection, decoded with `headers` when
+ * declared. Other responses are decoded as the endpoint's errors.
  *
- * **Example** (Declaring an attach endpoint)
+ * **Example** (Declaring an exec start endpoint)
  *
  * ```ts
  * import { Schema } from "effect"
  * import { HttpApiEndpoint, HttpApiSchema } from "effect/http-api"
  *
- * const attach = HttpApiEndpoint.post("attach", "/containers/:id/attach", {
+ * const start = HttpApiEndpoint.post("start", "/exec/:id/start", {
  *   params: { id: Schema.String },
- *   success: HttpApiSchema.Upgrade({ protocol: "tcp" })
+ *   payload: Schema.Struct({ Detach: Schema.Boolean, Tty: Schema.Boolean }),
+ *   success: HttpApiSchema.Upgrade({
+ *     protocol: "tcp",
+ *     headers: {
+ *       "content-type": Schema.Literals([
+ *         "application/vnd.docker.raw-stream",
+ *         "application/vnd.docker.multiplexed-stream"
+ *       ])
+ *     }
+ *   })
  * })
  * ```
  *
@@ -699,23 +727,72 @@ const upgradeSchema = Schema.declare(Socket.isSocket).pipe(status(101))
  * @category constructors
  * @since 4.0.6
  */
-export const Upgrade = (options: {
+export function Upgrade(options: { readonly protocol: string }): Upgrade<never>
+/**
+ * @stability unstable
+ */
+export function Upgrade<H extends Schema.Struct.Fields>(options: {
+  readonly protocol: string
+  readonly headers: H
+}): Upgrade<Schema.Struct<H>>
+/**
+ * @stability unstable
+ */
+export function Upgrade<H extends Schema.Top>(options: {
   readonly protocol: string
-}): Upgrade => {
+  readonly headers: H
+}): Upgrade<H>
+/**
+ * @stability unstable
+ */
+export function Upgrade(options: {
+  readonly protocol: string
+  readonly headers?: Schema.Top | Schema.Struct.Fields | undefined
+}): Upgrade {
   if (options.protocol.toLowerCase() === "websocket") {
     throw new Error("Upgrade does not support WebSocket")
   }
-  return Schema.make<Upgrade>(upgradeSchema.ast, {
+  const headers = options.headers === undefined || Schema.isSchema(options.headers)
+    ? options.headers
+    : Schema.Struct(options.headers)
+  return rebuildUpgrade(options.protocol, headers)
+}
+
+/**
+ * @internal
+ */
+export const rebuildUpgrade = (protocol: string, headers: Schema.Top | undefined): Upgrade =>
+  Schema.make<Upgrade>(upgradeSchema.ast, {
     [UpgradeTypeId]: UpgradeTypeId,
-    protocol: options.protocol
+    protocol,
+    headers
   })
-}
 
 /**
  * @internal
  */
 export const isUpgrade = (u: unknown): u is Upgrade => Schema.isSchema(u) && Predicate.hasProperty(u, UpgradeTypeId)
 
+function streamContentTypes(
+  contentType: string | ReadonlyArray<string> | undefined,
+  mode: StreamMode
+): { readonly contentType: string; readonly contentTypes: Arr.NonEmptyReadonlyArray<string> } {
+  if (contentType === undefined) contentType = defaultStreamContentType(mode)
+  if (typeof contentType === "string") return { contentType, contentTypes: [contentType] }
+  if (!Arr.isReadonlyArrayNonEmpty(contentType)) {
+    throw new Error("Stream schemas require at least one content type")
+  }
+  const seen = new Set<string>()
+  for (const entry of contentType) {
+    const normalized = MediaType.normalize(entry)
+    if (seen.has(normalized)) {
+      throw new Error(`Duplicate stream content type: ${entry}`)
+    }
+    seen.add(normalized)
+  }
+  return { contentType: contentType[0], contentTypes: contentType }
+}
+
 function defaultStreamContentType(mode: StreamMode): string {
   switch (mode) {
     case "sse":
@@ -779,8 +856,8 @@ export type WithHeadersValueTypeId = typeof WithHeadersValueTypeId
  *   `StreamSse` and `StreamUint8Array`; error responses remain non-streaming.
  *   Nesting `WithHeaders` is rejected at construction.
  * - `headers` is any schema; endpoint construction applies
- *   `Schema.toCodecStringTree` unless codecs are disabled, so leaves become
- *   `string | undefined` on the wire and `undefined` leaves are omitted from the response.
+ *   a StringTree codec unless codecs are disabled. Optional headers that encode
+ *   to `undefined` are omitted from the response.
  * - Status and response-encoding annotations are resolved from the wrapper
  *   first, falling through to the inner schema.
  * - A header-carrying response cannot share its status and content type with
@@ -1224,6 +1301,12 @@ export function asJson(options?: {
  *
  * The schema's encoded side must be a record of strings.
  *
+ * **Gotchas**
+ *
+ * Fields are flat on the server. A field that encodes to a nested object is
+ * sent as bracket keys that the server does not read back; use an explicit
+ * codec such as `Schema.fromJsonString(...)` for structured values.
+ *
  * @stability unstable
  * @category encoding
  * @since 4.0.0
@@ -1299,18 +1382,28 @@ const resolveHttpApiEncoding = SchemaAST.resolveAt<Encoding>("~httpApiEncoding")
  */
 export const getWithHeadersAnnotation = SchemaAST.resolveAt<WithHeadersAnnotation>("~httpApiWithHeaders")
 
-const resolveHttpApiStatusAnnotation = SchemaAST.resolveAt<number>("httpApiStatus")
-
-function hasStatusAnnotation(ast: SchemaAST.AST): boolean {
-  const annotations = SchemaAST.resolve(ast)
-  return annotations !== undefined && "httpApiStatus" in annotations
+function findHttpApiStatusAnnotation(
+  ast: SchemaAST.AST | SchemaAST.FilterGroup<any>
+): Schema.Annotations.Annotations | undefined {
+  if (ast.checks) {
+    for (let i = ast.checks.length - 1; i >= 0; i--) {
+      const check = ast.checks[i]
+      if (check.annotations && "httpApiStatus" in check.annotations) return check.annotations
+      if (check._tag === "FilterGroup") {
+        const annotations = findHttpApiStatusAnnotation(check)
+        if (annotations !== undefined) return annotations
+      }
+    }
+  }
+  const annotations = ast.annotations
+  return annotations && "httpApiStatus" in annotations ? annotations : undefined
 }
 
-// An `httpApiStatus` annotation, even `undefined`, overrides the key context set by
-// `status`, which a later check drops, matching annotations
 function resolveHttpApiStatus(ast: SchemaAST.AST): number | undefined {
-  if (hasStatusAnnotation(ast)) return resolveHttpApiStatusAnnotation(ast)
-  return ast.checks === undefined ? ast.context?.annotations?.httpApiStatus : undefined
+  const annotations = findHttpApiStatusAnnotation(ast)
+  // An explicit undefined clears the status instead of falling back to key context.
+  if (annotations !== undefined) return annotations.httpApiStatus as number | undefined
+  return ast.context?.annotations?.httpApiStatus
 }
 
 const defaultJsonEncoding: Encoding = {

package/src/http-api/HttpApiTest.ts

@@ -25,7 +25,7 @@ import * as Layer from "../Layer.ts"
 import type { Path } from "../Path.ts"
 import * as Scope from "../Scope.ts"
 import type * as HttpApi from "./HttpApi.ts"
-import type { HandlerRuntime } from "./HttpApiBuilder.ts"
+import type { GroupService, HandlerRuntime } from "./HttpApiBuilder.ts"
 import * as HttpApiBuilder from "./HttpApiBuilder.ts"
 import * as HttpApiClient from "./HttpApiClient.ts"
 import type * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
@@ -98,7 +98,8 @@ export const groups = Effect.fnUntraced(function*<
       handlers.set(endpointIdentifier, handler)
       routes.push(HttpApiBuilder.handlerToRoute(api, group as any, handler, context))
     }
-    context = Context.add(context, group as any, { handlers, routes })
+    const service: GroupService = { handlers, routes }
+    context = Context.add(context, group as any, service)
   }
 
   const layer: Layer.Layer<