effect 4.0.5 → 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
  */
@@ -18,7 +74,7 @@ import * as Context from "../Context.ts"
 import type { Effect } from "../Effect.ts"
 import type * as Sse from "../encoding/Sse.ts"
 import { identity, memoize } from "../Function.ts"
-import type { HttpMethod } from "../http/HttpMethod.ts"
+import { hasBody, type HttpMethod } from "../http/HttpMethod.ts"
 import * as HttpRouter from "../http/HttpRouter.ts"
 import type { HttpServerRequest } from "../http/HttpServerRequest.ts"
 import type { HttpServerResponse } from "../http/HttpServerResponse.ts"
@@ -27,13 +83,16 @@ import { type Pipeable, pipeArguments } from "../Pipeable.ts"
 import * as Predicate from "../Predicate.ts"
 import * as Schema from "../Schema.ts"
 import * as AST from "../SchemaAST.ts"
+import type * as Socket from "../socket/Socket.ts"
 import type * as Stream from "../Stream.ts"
 import type { Simplify } from "../Struct.ts"
 import type * as Types from "../Types.ts"
+import type * as HttpApiError from "./HttpApiError.ts"
 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"
 
@@ -57,6 +116,8 @@ type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
     infer _Value
   > ? Stream.Stream<_Value, _Error["Type"], never>
   : S extends HttpApiSchema.StreamUint8Array ? Stream.Stream<Uint8Array, unknown, never>
+  : S extends HttpApiSchema.StreamNdjson<infer _S> ? Stream.Stream<_S["Type"], unknown, never>
+  : S extends HttpApiSchema.Upgrade ? void
   : S extends Schema.Constraint ? S["Type"]
   : never
 
@@ -66,6 +127,8 @@ type SuccessEncodingServices<S> = S extends HttpApiSchema.StreamSse<
   infer _Value
 > ? _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
 
@@ -75,6 +138,8 @@ type SuccessDecodingServices<S> = S extends HttpApiSchema.StreamSse<
   infer _Value
 > ? _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
 
@@ -82,13 +147,27 @@ type UnwrapReadonlyArray<S> = S extends ReadonlyArray<infer A> ? A : S
 
 type ExtractBufferedSuccess<S extends SuccessConstraint> = Exclude<
   Extract<UnwrapReadonlyArray<S>, Schema.Top>,
-  HttpApiSchema.StreamSchema | HttpApiSchema.WithHeaders<Schema.Top, Schema.Top>
+  HttpApiSchema.StreamSchema | HttpApiSchema.Upgrade | HttpApiSchema.WithHeaders<Schema.Top, Schema.Top>
 >
 
 type ExtractStreamSuccess<S extends SuccessConstraint> = UnwrapReadonlyArray<S> extends infer Success ?
   Success extends HttpApiSchema.StreamSchema ? Success : never
   : never
 
+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 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<
       _Inner extends HttpApiSchema.StreamSchema ? _Inner : Schema.toCodecJson<_Inner>,
@@ -98,8 +177,12 @@ type ExtractWithHeadersSuccess<S extends SuccessConstraint> = UnwrapReadonlyArra
   : never
 
 type ToSuccessCodec<S extends SuccessConstraint> = [ExtractBufferedSuccess<S>] extends [never] ?
-  ExtractStreamSuccess<S> | ExtractWithHeadersSuccess<S>
-  : Schema.toCodecJson<ExtractBufferedSuccess<S>> | ExtractStreamSuccess<S> | ExtractWithHeadersSuccess<S>
+  ExtractStreamSuccess<S> | ExtractUpgradeSuccess<S> | ExtractWithHeadersSuccess<S>
+  :
+    | Schema.toCodecJson<ExtractBufferedSuccess<S>>
+    | ExtractStreamSuccess<S>
+    | ExtractUpgradeSuccess<S>
+    | ExtractWithHeadersSuccess<S>
 
 type ToJsonCodec<S> = [S] extends [never] ? never
   : [S] extends [Schema.Constraint] ? Schema.toCodecJson<S>
@@ -110,13 +193,33 @@ type ToStringTreeCodec<S> = [S] extends [never] ? never
   : [S] extends [Schema.Constraint] ? Schema.toCodecStringTree<S>
   : never
 
-type RequestFromParts<Endpoint, ParamsType, QueryType, PayloadType, HeadersType> =
+type ToPayloadCodec<S> = [Exclude<S, HttpApiSchema.StreamSchema>] extends [never] ?
+  Extract<S, HttpApiSchema.StreamSchema>
+  : ToJsonCodec<Exclude<S, HttpApiSchema.StreamSchema>> | Extract<S, HttpApiSchema.StreamSchema>
+
+// Stream payloads are keyed on the schema, because a stream schema's `Type`
+// describes the response direction.
+type RequestPayload<Payload> = Payload extends HttpApiSchema.StreamUint8Array ?
+  Stream.Stream<Uint8Array, HttpApiError.HttpApiPayloadTooLarge>
+  : Payload extends HttpApiSchema.StreamNdjson<infer _S> ?
+    Stream.Stream<_S["Type"], HttpApiError.HttpApiSchemaError | HttpApiError.HttpApiPayloadTooLarge>
+  : Payload extends Schema.Top ? BufferedRequestPayload<Payload["Type"]>
+  : never
+
+type BufferedRequestPayload<PayloadType> = PayloadType extends Brand<HttpApiSchema.MultipartStreamTypeId> ?
+  Stream.Stream<Multipart.Part, Multipart.MultipartError>
+  : Simplify<PayloadType>
+
+type PayloadError<Payload> = Payload extends HttpApiSchema.StreamUint8Array ? HttpApiError.HttpApiPayloadTooLarge
+  : Payload extends HttpApiSchema.StreamNdjson<infer _S> ?
+    HttpApiError.HttpApiSchemaError | HttpApiError.HttpApiPayloadTooLarge
+  : never
+
+type RequestFromParts<Endpoint, ParamsType, QueryType, Payload, HeadersType, Success> =
+  & UpgradeRequest<Success>
   & ([ParamsType] extends [never] ? {} : { readonly params: Simplify<ParamsType> })
   & ([QueryType] extends [never] ? {} : { readonly query: Simplify<QueryType> })
-  & ([PayloadType] extends [never] ? {}
-    : PayloadType extends Brand<HttpApiSchema.MultipartStreamTypeId> ?
-      { readonly payload: Stream.Stream<Multipart.Part, Multipart.MultipartError> }
-    : { readonly payload: Simplify<PayloadType> })
+  & ([Payload] extends [never] ? {} : { readonly payload: RequestPayload<Payload> })
   & ([HeadersType] extends [never] ? {} : { readonly headers: Simplify<HeadersType> })
   & {
     readonly request: HttpServerRequest
@@ -124,7 +227,8 @@ type RequestFromParts<Endpoint, ParamsType, QueryType, PayloadType, HeadersType>
     readonly group: HttpApiGroup.Top
   }
 
-type RequestRawFromParts<Endpoint, ParamsType, QueryType, HeadersType> =
+type RequestRawFromParts<Endpoint, ParamsType, QueryType, HeadersType, Success> =
+  & UpgradeRequest<Success>
   & ([ParamsType] extends [never] ? {} : { readonly params: Simplify<ParamsType> })
   & ([QueryType] extends [never] ? {} : { readonly query: Simplify<QueryType> })
   & ([HeadersType] extends [never] ? {} : { readonly headers: Simplify<HeadersType> })
@@ -138,14 +242,26 @@ type RequestRawFromParts<Endpoint, ParamsType, QueryType, HeadersType> =
  * Maps normalized media types to a payload encoding strategy and one or more
  * schemas. Each schema retains its declared content type in its encoding annotation.
  *
+ * **Details**
+ *
+ * A streaming payload (`HttpApiSchema.StreamUint8Array` or
+ * `HttpApiSchema.StreamNdjson`) has a `Stream` encoding and is the only schema
+ * for its media type.
+ *
  * @stability unstable
  * @category models
  * @since 4.0.0
  */
-export type PayloadMap = ReadonlyMap<string, {
-  readonly encoding: HttpApiSchema.PayloadEncoding
-  readonly schemas: readonly [Schema.Top, ...Array<Schema.Top>]
-}>
+export type PayloadMap = ReadonlyMap<
+  string,
+  {
+    readonly encoding: HttpApiSchema.PayloadEncoding
+    readonly schemas: readonly [Schema.Top, ...Array<Schema.Top>]
+  } | {
+    readonly encoding: { readonly _tag: "Stream"; readonly contentType: string }
+    readonly schemas: readonly [HttpApiSchema.StreamUint8Array | HttpApiSchema.StreamNdjson<Schema.Top>]
+  }
+>
 
 /**
  * Represents an API endpoint. An API endpoint is mapped to a single route on
@@ -178,8 +294,15 @@ export interface HttpApiEndpoint<
   readonly "~Error": Error
   readonly "~Middleware": Middleware
   readonly "~MiddlewareServices": MiddlewareServices
-  readonly "~Request": RequestFromParts<this, Params["Type"], Query["Type"], Payload["Type"], Headers["Type"]>
-  readonly "~RequestRaw": RequestRawFromParts<this, Params["Type"], Query["Type"], Headers["Type"]>
+  readonly "~Request": RequestFromParts<
+    this,
+    Params["Type"],
+    Query["Type"],
+    Payload,
+    Headers["Type"],
+    Success
+  >
+  readonly "~RequestRaw": RequestRawFromParts<this, Params["Type"], Query["Type"], Headers["Type"], Success>
 
   readonly identifier: Identifier
   readonly path: Path
@@ -518,7 +641,7 @@ export type RequestRaw<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint
  * Builds the request object accepted by a generated client method, including the
  * params, query, headers, and payload required by the endpoint, plus optional
  * response mode and SSE decoding options. Multipart payloads are supplied as
- * `FormData`.
+ * `FormData`, and streaming payloads as a `Stream` that requires `PayloadR`.
  *
  * @stability unstable
  * @category utility types
@@ -529,7 +652,8 @@ export type ClientRequest<
   Query extends Schema.Constraint,
   Payload extends Schema.Constraint,
   Headers extends Schema.Constraint,
-  ResponseMode extends ClientResponseMode
+  ResponseMode extends ClientResponseMode,
+  PayloadR = never
 > = (
   & ([Params["Type"]] extends [never] ? {} : { readonly params: Params["Type"] })
   & ([Query["Type"]] extends [never] ? {} : { readonly query: Query["Type"] })
@@ -538,8 +662,8 @@ export type ClientRequest<
     : Payload["Type"] extends infer P ?
       P extends Brand<HttpApiSchema.MultipartTypeId> | Brand<HttpApiSchema.MultipartStreamTypeId>
         ? { readonly payload: FormData }
-      : { readonly payload: Payload["Type"] }
-    : { readonly payload: Payload["Type"] })
+      : { readonly payload: ClientPayload<Payload, PayloadR> }
+    : { readonly payload: ClientPayload<Payload, PayloadR> })
 ) extends infer Req ? keyof Req extends never ? (void | {
       readonly responseMode?: ResponseMode
       readonly sseOptions?: Sse.DecodeOptions | undefined
@@ -550,6 +674,11 @@ export type ClientRequest<
   } :
   void
 
+type ClientPayload<Payload extends Schema.Constraint, R> = Payload extends HttpApiSchema.StreamUint8Array
+  ? Stream.Stream<Uint8Array, unknown, R>
+  : Payload extends HttpApiSchema.StreamNdjson<infer S> ? Stream.Stream<S["Type"], unknown, R>
+  : Payload["Type"]
+
 /**
  * Controls what a generated client method returns: the decoded success value,
  * the decoded value paired with the raw response, or only the raw response.
@@ -628,7 +757,11 @@ export type ErrorServicesDecode<Endpoint> = Endpoint extends ConstraintRequest ?
  */
 export type Handler<Endpoint extends Constraint, E, R> = (
   request: Simplify<Endpoint["~Request"]>
-) => Effect<SuccessType<Endpoint["~Success"]> | HttpServerResponse, Endpoint["~Error"]["Type"] | E, R>
+) => Effect<
+  SuccessType<Endpoint["~Success"]> | HttpServerResponse,
+  Endpoint["~Error"]["Type"] | PayloadError<Payload<Endpoint>> | E,
+  R
+>
 
 /**
  * The raw server handler for an endpoint, receiving a request shape without a
@@ -981,7 +1114,9 @@ export type QueryConstraint =
  *   encode to `string | ReadonlyArray<string> | undefined` and OpenAPI can expand
  *   it into `in: query` parameters
  * - for body methods, payload may be any `Schema.Top` (or content-type keyed
- *   schemas) and OpenAPI uses `requestBody` instead of `parameters`
+ *   schemas) and OpenAPI uses `requestBody` instead of `parameters`. This
+ *   includes one `HttpApiSchema.StreamUint8Array` or `HttpApiSchema.StreamNdjson`,
+ *   but not `HttpApiSchema.StreamSse`, which is response-only
  *
  * @stability unstable
  * @category utility types
@@ -991,7 +1126,10 @@ export type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMe
     string,
     Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>
   > :
-  Schema.Top | ReadonlyArray<Schema.Top>
+  PayloadSchema | ReadonlyArray<PayloadSchema>
+
+// `StreamSse` is response-only, so it is the one stream schema excluded here.
+type PayloadSchema = Schema.Top & { readonly sseMode?: never }
 
 /**
  * Payload constraint used when automatic codecs are enabled: no-body methods
@@ -1004,7 +1142,7 @@ export type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMe
  */
 export type PayloadConstraintCodecs<Method extends HttpMethod> = Method extends HttpMethod.NoBody ?
   Record<string, Schema.Top> :
-  Schema.Top | ReadonlyArray<Schema.Top>
+  PayloadSchema | ReadonlyArray<PayloadSchema>
 
 /**
  * Constraint for success response schemas, allowing either a single schema or a
@@ -1031,7 +1169,7 @@ type ErrorSchema<S> = S extends HttpApiSchema.WithHeaders<infer Inner, Schema.To
 type ErrorNoStream<S extends ErrorConstraint> = [
   Extract<
     ErrorSchema<S extends ReadonlyArray<Schema.Constraint> ? S[number] : S>,
-    HttpApiSchema.StreamSchema
+    HttpApiSchema.StreamSchema | HttpApiSchema.Upgrade
   >
 ] extends [never] ? S : never
 
@@ -1041,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
@@ -1073,7 +1221,7 @@ export const make = <Method extends HttpMethod>(method: Method): {
     Path,
     ToStringTreeCodec<Params>,
     ToStringTreeCodec<Query>,
-    Method extends HttpMethod.WithBody ? ToJsonCodec<ToSchema<Payload>>
+    Method extends HttpMethod.WithBody ? ToPayloadCodec<ToSchema<Payload>>
       : ToStringTreeCodec<ToSchema<Payload>>,
     ToStringTreeCodec<Headers>,
     ToSuccessCodec<Success>,
@@ -1147,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, 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(),
@@ -1185,21 +1334,48 @@ function getPayload(
 ): PayloadMap {
   const result: Map<
     string,
-    { encoding: HttpApiSchema.PayloadEncoding; schemas: [Schema.Top, ...Array<Schema.Top>] }
+    {
+      encoding: HttpApiSchema.PayloadEncoding | { readonly _tag: "Stream"; readonly contentType: string }
+      schemas: [Schema.Top, ...Array<Schema.Top>]
+    }
   > = new Map()
-  if (payload === undefined) return result
+  if (payload === undefined) return result as PayloadMap
   const schemas: Array<Schema.Top> = Array.isArray(payload)
     ? payload
     : Schema.isSchema(payload)
     ? [payload]
     : [(Schema.Struct(payload as any)).pipe(HttpApiSchema.asFormUrlEncoded())]
   const transform = disableCodecs ? identity : transformPayload
+  let hasStream = false
 
   for (const schema of schemas) {
+    if (HttpApiSchema.isStreamSchema(schema)) {
+      if (HttpApiSchema.isStreamSse(schema)) {
+        throw new Error("StreamSse is response-only and cannot be used as a payload")
+      }
+      if (!hasBody(method)) {
+        throw new Error(`${method} endpoints cannot declare a streaming payload`)
+      }
+      if (hasStream) {
+        throw new Error("Multiple streaming payloads are not supported")
+      }
+      hasStream = true
+      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] })
+      }
+      continue
+    }
     const encoding = HttpApiSchema.getPayloadEncoding(schema.ast, method)
     const contentType = MediaType.normalize(encoding.contentType)
     const existing = result.get(contentType)
     if (existing) {
+      if (existing.encoding._tag === "Stream") {
+        throw new Error(`Cannot combine buffered and streaming payloads for content-type: ${encoding.contentType}`)
+      }
       if (existing.encoding._tag !== encoding._tag) {
         throw new Error(`Multiple payload encodings for content-type: ${encoding.contentType}`)
       }
@@ -1211,7 +1387,7 @@ function getPayload(
       result.set(contentType, { encoding, schemas: [transform(schema, method)] })
     }
   }
-  return result
+  return result as PayloadMap
 }
 
 const reservedStreamFailureEvent = "effect/http-api/stream/failure"
@@ -1219,21 +1395,27 @@ const reservedStreamFailureEvent = "effect/http-api/stream/failure"
 function getSuccessResponse(
   success: Schema.Top | ReadonlyArray<Schema.Top> | undefined,
   method: HttpMethod,
+  payload: PayloadMap,
   disableCodecs: boolean
 ): Set<Schema.Top> {
   if (success === undefined) return new Set()
   const schemas = Arr.ensure(success)
-  validateSuccessResponse(schemas, method)
+  validateSuccessResponse(schemas, method, payload)
   return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
 }
 
 const transformResponseSchema = memoize((schema: Schema.Top): Schema.Top => {
   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)
 })
@@ -1249,12 +1431,30 @@ function getErrorResponse(
     if (HttpApiSchema.isStreamSchema(body)) {
       throw new Error("Streaming schemas are not supported in error responses")
     }
+    if (HttpApiSchema.isUpgrade(body)) {
+      throw new Error("Upgrade schemas are not supported in error responses")
+    }
   }
   validateResponseExclusivity(schemas, HttpApiSchema.getStatusErrorSchema)
   return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
 }
 
-function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, method: HttpMethod) {
+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")
+    }
+    if (method === "HEAD") {
+      throw new Error("HEAD endpoints cannot declare an upgrade")
+    }
+    // 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
+  }
   let hasStream = false
   const statuses = new Map<number, {
     readonly stream?: HttpApiSchema.StreamSchema | undefined
@@ -1275,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 {
@@ -1289,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}`
           )
@@ -1424,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)
     }
   })
 }
@@ -1442,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/HttpApiError.ts

@@ -10,6 +10,7 @@
  * @stability unstable
  * @since 4.0.0
  */
+import type * as ByteSize from "../ByteSize.ts"
 import * as Data from "../Data.ts"
 import * as Effect from "../Effect.ts"
 import * as ErrorReporter from "../ErrorReporter.ts"
@@ -28,6 +29,7 @@ const notAcceptableResponse = HttpServerResponse.empty({ status: 406 })
 const requestTimeoutResponse = HttpServerResponse.empty({ status: 408 })
 const conflictResponse = HttpServerResponse.empty({ status: 409 })
 const goneResponse = HttpServerResponse.empty({ status: 410 })
+const payloadTooLargeResponse = HttpServerResponse.empty({ status: 413 })
 const unprocessableEntityResponse = HttpServerResponse.empty({ status: 422 })
 const internalServerErrorResponse = HttpServerResponse.empty({ status: 500 })
 const notImplementedResponse = HttpServerResponse.empty({ status: 501 })
@@ -505,3 +507,56 @@ export class HttpApiSchemaError extends Data.TaggedClass("HttpApiSchemaError")<{
     return Effect.succeed(this[ErrorReporter.ignore] ? badRequestResponse : internalServerErrorResponse)
   }
 }
+
+/**
+ * Type-level identifier used to mark `HttpApiPayloadTooLarge` values.
+ *
+ * @stability unstable
+ * @category type IDs
+ * @since 4.0.6
+ */
+export type HttpApiPayloadTooLargeTypeId = "~effect/http-api/HttpApiError/HttpApiPayloadTooLarge"
+
+/**
+ * Runtime identifier used to mark and detect `HttpApiPayloadTooLarge` values.
+ *
+ * @stability unstable
+ * @category type IDs
+ * @since 4.0.6
+ */
+export const HttpApiPayloadTooLargeTypeId: HttpApiPayloadTooLargeTypeId =
+  "~effect/http-api/HttpApiError/HttpApiPayloadTooLarge"
+
+/**
+ * Error raised when a streaming request payload exceeds a limit declared on
+ * its `HttpApiSchema.StreamUint8Array` or `HttpApiSchema.StreamNdjson` schema.
+ * It responds with an empty `413 Payload Too Large` and is ignored by error
+ * reporters.
+ *
+ * **Details**
+ *
+ * `limit` names the option that was exceeded: `maxBytes` caps the whole body
+ * and `maxElementBytes` caps one NDJSON line. `size` is its configured value.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.6
+ */
+export class HttpApiPayloadTooLarge extends Data.TaggedClass("HttpApiPayloadTooLarge")<{
+  readonly limit: "maxBytes" | "maxElementBytes"
+  readonly size: ByteSize.ByteSize
+}> {
+  readonly [HttpApiPayloadTooLargeTypeId]: HttpApiPayloadTooLargeTypeId = HttpApiPayloadTooLargeTypeId
+  readonly [ErrorReporter.ignore] = true
+
+  static is(u: unknown): u is HttpApiPayloadTooLarge {
+    return hasProperty(u, HttpApiPayloadTooLargeTypeId)
+  }
+
+  readonly name = "HttpApiPayloadTooLarge"
+  readonly message = `Payload exceeds ${this.limit} of ${this.size} bytes`;
+
+  [HttpServerRespondable.symbol]() {
+    return Effect.succeed(payloadTooLargeResponse)
+  }
+}

package/src/http-api/HttpApiScalar.ts

@@ -17,7 +17,6 @@ import type * as Layer from "../Layer.ts"
 import type * as HttpApi from "./HttpApi.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import * as Html from "./internal/html.ts"
-import * as internal from "./internal/httpApiScalar.ts"
 import * as OpenApi from "./OpenApi.ts"
 
 /**
@@ -212,7 +211,8 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Constraint>(
  * **Details**
  *
  * The route serves the OpenAPI specification generated from the API at the
- * configured path, defaulting to `/docs`.
+ * configured path, defaulting to `/docs`. The bundled script is loaded when
+ * the layer is built, not when this module is imported.
  *
  * @stability unstable
  * @category layers
@@ -226,11 +226,12 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Constraint>
   } | undefined
 ): Layer.Layer<never, never, HttpRouter.HttpRouter> =>
   HttpRouter.use(Effect.fnUntraced(function*(router) {
+    const { javascript } = yield* Effect.promise(() => import("./internal/httpApiScalar.ts"))
     const handler = makeHandler({
       api,
       source: {
         _tag: "Inline",
-        source: internal.javascript
+        source: javascript
       },
       scalar: options?.scalar
     })