effect 4.0.0-beta.99 → 4.0.0-rc.108

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -44,11 +44,15 @@ const TypeId = "~effect/httpapi/HttpApiEndpoint"
  */
 export const isHttpApiEndpoint = (u: unknown): u is Top => Predicate.hasProperty(u, TypeId)
 
-type SuccessType<S> = S extends HttpApiSchema.StreamSse<
-  infer _Events,
-  infer _Error,
-  infer _Value
-> ? Stream.Stream<_Value, _Error["Type"], never>
+type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
+  infer _Inner,
+  infer _Headers
+> ? HttpApiSchema.withHeaders<SuccessType<_Inner>, _Headers["Type"]>
+  : S extends HttpApiSchema.StreamSse<
+    infer _Events,
+    infer _Error,
+    infer _Value
+  > ? Stream.Stream<_Value, _Error["Type"], never>
   : S extends HttpApiSchema.StreamUint8Array ? Stream.Stream<Uint8Array, unknown, never>
   : S extends Schema.Constraint ? S["Type"]
   : never
@@ -75,15 +79,24 @@ type UnwrapReadonlyArray<S> = S extends ReadonlyArray<infer A> ? A : S
 
 type ExtractBufferedSuccess<S extends SuccessConstraint> = Exclude<
   Extract<UnwrapReadonlyArray<S>, Schema.Top>,
-  HttpApiSchema.StreamSchema
+  HttpApiSchema.StreamSchema | HttpApiSchema.WithHeaders<Schema.Top, Schema.Top>
 >
 
 type ExtractStreamSuccess<S extends SuccessConstraint> = UnwrapReadonlyArray<S> extends infer Success ?
   Success extends HttpApiSchema.StreamSchema ? Success : never
   : never
 
-type ToSuccessCodec<S extends SuccessConstraint> = [ExtractBufferedSuccess<S>] extends [never] ? ExtractStreamSuccess<S>
-  : Schema.toCodecJson<ExtractBufferedSuccess<S>> | ExtractStreamSuccess<S>
+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>,
+      Schema.toCodecStringTree<_Headers>
+    > :
+  never
+  : never
+
+type ToSuccessCodec<S extends SuccessConstraint> = [ExtractBufferedSuccess<S>] extends [never] ?
+  ExtractStreamSuccess<S> | ExtractWithHeadersSuccess<S>
+  : Schema.toCodecJson<ExtractBufferedSuccess<S>> | ExtractStreamSuccess<S> | ExtractWithHeadersSuccess<S>
 
 type ToJsonCodec<S> = [S] extends [never] ? never
   : [S] extends [Schema.Constraint] ? Schema.toCodecJson<S>
@@ -334,7 +347,7 @@ export interface Top extends
 /**
  * Extracts the endpoint identifier literal from an `HttpApiEndpoint`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Identifier<Endpoint> = Endpoint extends Constraint ? Endpoint["identifier"] : never
@@ -342,7 +355,7 @@ export type Identifier<Endpoint> = Endpoint extends Constraint ? Endpoint["ident
 /**
  * Extracts the success schema associated with an endpoint.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Success<Endpoint> = Endpoint extends Constraint ? Endpoint["~Success"] : never
@@ -350,7 +363,7 @@ export type Success<Endpoint> = Endpoint extends Constraint ? Endpoint["~Success
 /**
  * Extracts the error schema associated with an endpoint.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Error<Endpoint> = Endpoint extends Constraint ? Endpoint["~Error"] : never
@@ -358,7 +371,7 @@ export type Error<Endpoint> = Endpoint extends Constraint ? Endpoint["~Error"] :
 /**
  * Extracts the schema used for an endpoint's path parameters.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Params<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Params"]
@@ -367,7 +380,7 @@ export type Params<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~P
 /**
  * Extracts the schema used for an endpoint's query parameters.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Query<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Query"]
@@ -376,7 +389,7 @@ export type Query<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Qu
 /**
  * Extracts the schema used for an endpoint's request payload.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Payload<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Payload"]
@@ -385,7 +398,7 @@ export type Payload<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~
 /**
  * Extracts the schema used for an endpoint's request headers.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Headers<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Headers"]
@@ -394,7 +407,7 @@ export type Headers<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~
 /**
  * Extracts the middleware identifiers attached to an endpoint.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Middleware<Endpoint> = Endpoint extends { readonly "~Middleware": infer M } ? M
@@ -403,7 +416,7 @@ export type Middleware<Endpoint> = Endpoint extends { readonly "~Middleware": in
 /**
  * Computes the services provided by the middleware attached to an endpoint.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareProvides<Endpoint> = HttpApiMiddleware.Provides<Middleware<Endpoint>>
@@ -411,7 +424,7 @@ export type MiddlewareProvides<Endpoint> = HttpApiMiddleware.Provides<Middleware
 /**
  * Computes the client-side middleware services required by an endpoint.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareClient<Endpoint> = HttpApiMiddleware.MiddlewareClient<Middleware<Endpoint>>
@@ -420,7 +433,7 @@ export type MiddlewareClient<Endpoint> = HttpApiMiddleware.MiddlewareClient<Midd
  * Computes the error types that can be produced by the middleware attached to an
  * endpoint.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareError<Endpoint> = HttpApiMiddleware.Error<Middleware<Endpoint>>
@@ -429,7 +442,7 @@ export type MiddlewareError<Endpoint> = HttpApiMiddleware.Error<Middleware<Endpo
  * Computes the full error value union for an endpoint, including the endpoint
  * error schema's type and errors introduced by middleware.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Errors<Endpoint> = Endpoint extends ConstraintRequest ?
@@ -440,7 +453,7 @@ export type Errors<Endpoint> = Endpoint extends ConstraintRequest ?
  * Computes the services required to encode an endpoint's error responses,
  * including services required by middleware error encoders.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesEncode<Endpoint> = Endpoint extends ConstraintRequest ?
@@ -453,7 +466,7 @@ export type ErrorServicesEncode<Endpoint> = Endpoint extends ConstraintRequest ?
  * available params, query, payload, headers, the raw request, endpoint, and group.
  * Multipart stream payloads are exposed as streams of parts.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Request<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~Request"]
@@ -464,7 +477,7 @@ export type Request<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~
  * params, query, and headers plus the raw request, endpoint, and group, while
  * leaving payload handling to the raw request.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type RequestRaw<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint["~RequestRaw"]
@@ -475,7 +488,7 @@ export type RequestRaw<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint
  * the params, query, headers, payload, and response mode fields required by the
  * endpoint. Multipart payloads are supplied as `FormData`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ClientRequest<
@@ -511,7 +524,7 @@ export type ClientResponseMode = "decoded-only" | "decoded-and-response" | "resp
  * Computes the services required on the server to decode endpoint inputs and
  * encode endpoint success, error, and middleware error responses.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ServerServices<Endpoint> = Endpoint extends ConstraintRequest ?
@@ -528,7 +541,7 @@ export type ServerServices<Endpoint> = Endpoint extends ConstraintRequest ?
  * Computes the services required on the client to encode endpoint requests and
  * decode endpoint success or error responses.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ClientServices<Endpoint> = Endpoint extends ConstraintRequest ?
@@ -543,7 +556,7 @@ export type ClientServices<Endpoint> = Endpoint extends ConstraintRequest ?
 /**
  * Extracts the additional services required by middleware applied to an endpoint.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareServices<Endpoint> = Endpoint extends { readonly "~MiddlewareServices": infer R } ? R
@@ -553,7 +566,7 @@ export type MiddlewareServices<Endpoint> = Endpoint extends { readonly "~Middlew
  * Computes the services required to decode an endpoint's error responses,
  * including services required by middleware error decoders.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesDecode<Endpoint> = Endpoint extends ConstraintRequest ?
@@ -565,7 +578,7 @@ export type ErrorServicesDecode<Endpoint> = Endpoint extends ConstraintRequest ?
  * The normal server handler for an endpoint, accepting the decoded request shape
  * and returning either the endpoint success value or a custom `HttpServerResponse`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Handler<Endpoint extends Constraint, E, R> = (
@@ -576,7 +589,7 @@ export type Handler<Endpoint extends Constraint, E, R> = (
  * The raw server handler for an endpoint, receiving a request shape without a
  * decoded payload so the handler can read the raw `HttpServerRequest` directly.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type HandlerRaw<Endpoint extends Constraint, E, R> = (
@@ -586,7 +599,7 @@ export type HandlerRaw<Endpoint extends Constraint, E, R> = (
 /**
  * Selects the endpoint with the specified identifier from a union of endpoints.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type WithIdentifier<Endpoints, Identifier extends string> = Extract<
@@ -597,7 +610,7 @@ export type WithIdentifier<Endpoints, Identifier extends string> = Extract<
 /**
  * Removes endpoints with the specified identifier from a union of endpoints.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ExcludeIdentifier<Endpoints, Identifier extends string> = Exclude<
@@ -609,7 +622,7 @@ export type ExcludeIdentifier<Endpoints, Identifier extends string> = Exclude<
  * Derives the normal handler type for the endpoint with the specified identifier
  * in an endpoint union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type HandlerWithIdentifier<Endpoints extends Constraint, Identifier extends string, E, R> = Handler<
@@ -622,7 +635,7 @@ export type HandlerWithIdentifier<Endpoints extends Constraint, Identifier exten
  * Derives the raw handler type for the endpoint with the specified identifier in
  * an endpoint union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type HandlerRawWithIdentifier<Endpoints extends Constraint, Identifier extends string, E, R> = HandlerRaw<
@@ -635,7 +648,7 @@ export type HandlerRawWithIdentifier<Endpoints extends Constraint, Identifier ex
  * Extracts the decoded success value type for the endpoint with the specified
  * identifier in an endpoint union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type SuccessWithIdentifier<Endpoints extends Constraint, Identifier extends string> = Success<
@@ -646,7 +659,7 @@ export type SuccessWithIdentifier<Endpoints extends Constraint, Identifier exten
  * Computes the full error value union for the endpoint with the specified
  * identifier in an endpoint union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorsWithIdentifier<Endpoints extends Constraint, Identifier extends string> = Errors<
@@ -657,7 +670,7 @@ export type ErrorsWithIdentifier<Endpoints extends Constraint, Identifier extend
  * Computes the server-side service requirements for the endpoint with the
  * specified identifier in an endpoint union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ServerServicesWithIdentifier<Endpoints extends Constraint, Identifier extends string> = ServerServices<
@@ -668,7 +681,7 @@ export type ServerServicesWithIdentifier<Endpoints extends Constraint, Identifie
  * Extracts the middleware identifiers for the endpoint with the specified
  * identifier in an endpoint union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareWithIdentifier<Endpoints extends Constraint, Identifier extends string> = Middleware<
@@ -679,7 +692,7 @@ export type MiddlewareWithIdentifier<Endpoints extends Constraint, Identifier ex
  * Extracts the middleware service requirements for the endpoint with the
  * specified identifier in an endpoint union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareServicesWithIdentifier<Endpoints extends Constraint, Identifier extends string> =
@@ -689,7 +702,7 @@ export type MiddlewareServicesWithIdentifier<Endpoints extends Constraint, Ident
  * Removes services provided by the HTTP router and the selected endpoint's
  * middleware from a service requirement union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ExcludeProvidedWithIdentifier<Endpoints extends Constraint, Identifier extends string, R> = ExcludeProvided<
@@ -701,7 +714,7 @@ export type ExcludeProvidedWithIdentifier<Endpoints extends Constraint, Identifi
  * Removes services provided by the HTTP router and endpoint middleware from a
  * service requirement union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ExcludeProvided<Endpoint extends Constraint, R> = Exclude<
@@ -714,7 +727,7 @@ export type ExcludeProvided<Endpoint extends Constraint, R> = Exclude<
  * Returns an endpoint type with the supplied path prefix prepended while
  * preserving the endpoint's schemas, method, errors, and middleware.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type AddPrefix<Endpoint, Prefix extends HttpRouter.PathInput> = Endpoint extends HttpApiEndpoint<
@@ -748,7 +761,7 @@ export type AddPrefix<Endpoint, Prefix extends HttpRouter.PathInput> = Endpoint
  * Returns an endpoint type with additional middleware applied and the endpoint's
  * middleware service requirements updated accordingly.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type AddMiddleware<Endpoint, M extends HttpApiMiddleware.AnyId> = Endpoint extends HttpApiEndpoint<
@@ -869,7 +882,7 @@ function makeProto<
  * Constraint for path parameter schemas: each parameter must encode to
  * `string | undefined`, or the schema must encode to a record of those values.
  *
- * @category constraints
+ * @category utility types
  * @since 4.0.0
  */
 export type ParamsConstraint =
@@ -880,7 +893,7 @@ export type ParamsConstraint =
  * Constraint for header schemas: each header must encode to `string | undefined`,
  * or the schema must encode to a record of those values.
  *
- * @category constraints
+ * @category utility types
  * @since 4.0.0
  */
 export type HeadersConstraint =
@@ -891,7 +904,7 @@ export type HeadersConstraint =
  * Constraint for query schemas: each field must encode to `string`, an array of
  * strings, or `undefined`, or the schema must encode to a record of those values.
  *
- * @category constraints
+ * @category utility types
  * @since 4.0.0
  */
 export type QueryConstraint =
@@ -906,7 +919,7 @@ export type QueryConstraint =
  * - for body methods, payload may be any `Schema.Top` (or content-type keyed
  *   schemas) and OpenAPI uses `requestBody` instead of `parameters`
  *
- * @category constraints
+ * @category utility types
  * @since 4.0.0
  */
 export type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMethod.NoBody ? Record<
@@ -920,7 +933,7 @@ export type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMe
  * accept field records for query-style encoding, while body methods accept one or
  * more schemas.
  *
- * @category constraints
+ * @category utility types
  * @since 4.0.0
  */
 export type PayloadConstraintCodecs<Method extends HttpMethod> = Method extends HttpMethod.NoBody ?
@@ -931,7 +944,7 @@ export type PayloadConstraintCodecs<Method extends HttpMethod> = Method extends
  * Constraint for success response schemas, allowing either a single schema or a
  * readonly array of schemas.
  *
- * @category constraints
+ * @category utility types
  * @since 4.0.0
  */
 export type SuccessConstraint = Schema.Top | ReadonlyArray<Schema.Top>
@@ -940,14 +953,16 @@ export type SuccessConstraint = Schema.Top | ReadonlyArray<Schema.Top>
  * Constraint for error response schemas, allowing either a single schema or a
  * readonly array of schemas.
  *
- * @category constraints
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorConstraint = Schema.Top | ReadonlyArray<Schema.Top>
 
+type ErrorSchema<S> = S extends HttpApiSchema.WithHeaders<infer Inner, Schema.Top> ? Inner : S
+
 type ErrorNoStream<S extends ErrorConstraint> = [
   Extract<
-    S extends ReadonlyArray<Schema.Constraint> ? S[number] : S,
+    ErrorSchema<S extends ReadonlyArray<Schema.Constraint> ? S[number] : S>,
     HttpApiSchema.StreamSchema
   >
 ] extends [never] ? S : never
@@ -1139,11 +1154,18 @@ function getSuccessResponse(
   if (success === undefined) return new Set()
   const schemas = Arr.ensure(success)
   validateSuccessResponse(schemas, method)
-  return new Set(
-    disableCodecs ?
-      schemas :
-      schemas.map((schema) => HttpApiSchema.isStreamSchema(schema) ? schema : transformResponse(schema))
-  )
+  return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
+}
+
+function transformResponseSchema(schema: Schema.Top): Schema.Top {
+  if (HttpApiSchema.isStreamSchema(schema)) return schema
+  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 transformResponse(schema)
 }
 
 function getErrorResponse(
@@ -1153,14 +1175,17 @@ function getErrorResponse(
   if (error === undefined) return new Set()
   const schemas = Arr.ensure(error)
   for (const schema of schemas) {
-    if (HttpApiSchema.isStreamSchema(schema)) {
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    if (HttpApiSchema.isStreamSchema(body)) {
       throw new Error("Streaming schemas are not supported in error responses")
     }
   }
-  return new Set(disableCodecs ? schemas : schemas.map(transformResponse))
+  validateResponseExclusivity(schemas, HttpApiSchema.getStatusErrorSchema)
+  return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
 }
 
 function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, method: HttpMethod) {
+  let hasStream = false
   const statuses = new Map<number, {
     readonly stream?: HttpApiSchema.StreamSchema | undefined
     bufferedContentTypes: Set<string>
@@ -1168,31 +1193,32 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
   }>()
 
   for (const schema of schemas) {
-    if (HttpApiSchema.isStreamSchema(schema)) {
-      validateStreamSuccess(schema, method)
-      const status = HttpApiSchema.getStatusStream(schema)
-      const entry = getStatusEntry(statuses, status)
-      if (entry.stream !== undefined) {
-        throw new Error(`Multiple streaming success responses for status: ${status}`)
+    const inner = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    const status = HttpApiSchema.getStatusSuccessSchema(schema)
+    if (HttpApiSchema.isStreamSchema(inner)) {
+      validateStreamSuccess(inner, method)
+      if (hasStream) {
+        throw new Error("Multiple streaming success responses are not supported")
       }
+      hasStream = true
+      const entry = getStatusEntry(statuses, status)
       if (entry.noContent) {
         throw new Error(`Cannot combine no-content and streaming success responses for status: ${status}`)
       }
-      if (entry.bufferedContentTypes.has(MediaType.normalize(schema.contentType))) {
+      if (entry.bufferedContentTypes.has(MediaType.normalize(inner.contentType))) {
         throw new Error(
-          `Cannot combine buffered and streaming success responses for status ${status} and content-type: ${schema.contentType}`
+          `Cannot combine buffered and streaming success responses for status ${status} and content-type: ${inner.contentType}`
         )
       }
-      statuses.set(status, { ...entry, stream: schema })
+      statuses.set(status, { ...entry, stream: inner })
     } else {
-      const status = HttpApiSchema.getStatusSuccess(schema.ast)
       const entry = getStatusEntry(statuses, status)
-      const noContent = HttpApiSchema.isNoContent(schema.ast)
+      const noContent = HttpApiSchema.isNoContent(inner.ast)
       if (entry.stream !== undefined) {
         if (noContent) {
           throw new Error(`Cannot combine no-content and streaming success responses for status: ${status}`)
         }
-        const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
+        const encoding = HttpApiSchema.getResponseEncodingSchema(schema)
         if (
           MediaType.normalize(encoding.contentType) === MediaType.normalize(entry.stream.contentType)
         ) {
@@ -1203,12 +1229,14 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
       }
       if (!noContent) {
         entry.bufferedContentTypes.add(
-          MediaType.normalize(HttpApiSchema.getResponseEncoding(schema.ast).contentType)
+          MediaType.normalize(HttpApiSchema.getResponseEncodingSchema(schema).contentType)
         )
       }
       entry.noContent = entry.noContent || noContent
     }
   }
+
+  validateResponseExclusivity(schemas, HttpApiSchema.getStatusSuccessSchema)
 }
 
 function getStatusEntry(
@@ -1227,6 +1255,49 @@ function getStatusEntry(
   return entry
 }
 
+function validateResponseExclusivity(
+  schemas: ReadonlyArray<Schema.Constraint>,
+  getStatus: (schema: Schema.Constraint) => number
+) {
+  const statuses = new Map<number, {
+    headerContentType: string | undefined
+    readonly plainContentTypes: Set<string>
+  }>()
+  for (const schema of schemas) {
+    const status = getStatus(schema)
+    const withHeadersAnnotation = HttpApiSchema.getWithHeadersAnnotation(schema.ast)
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : withHeadersAnnotation?.body ?? schema
+    const contentType = HttpApiSchema.isNoContent(body.ast)
+      ? ""
+      : MediaType.normalize(
+        HttpApiSchema.isStreamSchema(body)
+          ? body.contentType
+          : HttpApiSchema.getResponseEncodingSchema(schema).contentType
+      )
+    let entry = statuses.get(status)
+    if (entry === undefined) {
+      entry = { headerContentType: undefined, plainContentTypes: new Set() }
+      statuses.set(status, entry)
+    }
+    const combineError = () =>
+      new Error(
+        `Cannot combine a response with headers with another response for status ${status} and content-type: ${
+          contentType || "<no content>"
+        }`
+      )
+    if (HttpApiSchema.isWithHeaders(schema) || withHeadersAnnotation !== undefined) {
+      if (entry.headerContentType !== undefined) {
+        throw new Error(`Cannot declare multiple responses with headers for status ${status}`)
+      }
+      if (entry.plainContentTypes.has(contentType)) throw combineError()
+      entry.headerContentType = contentType
+    } else {
+      if (entry.headerContentType === contentType) throw combineError()
+      entry.plainContentTypes.add(contentType)
+    }
+  }
+}
+
 function validateStreamSuccess(schema: HttpApiSchema.StreamSchema, method: HttpMethod) {
   if (method === "HEAD") {
     throw new Error("HEAD endpoints cannot declare streaming success responses")
@@ -1275,6 +1346,23 @@ function hasReservedEventLiteral(ast: AST.AST, seen: Set<AST.AST>): boolean {
 
 function transformResponse(schema: Schema.Top): Schema.Top {
   const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
+  const withHeaders = HttpApiSchema.getWithHeadersAnnotation(schema.ast)
+  if (withHeaders === undefined) {
+    return applyResponseEncoding(schema, encoding)
+  }
+  const headers = Schema.toEncoded(withHeaders.headers)
+  return Schema.Struct({
+    body: applyResponseEncoding(Schema.toEncoded(withHeaders.body), encoding),
+    headers
+  }).pipe(Schema.decodeTo(schema)).annotate({
+    "~httpApiWithHeaders": {
+      ...withHeaders,
+      headersCodec: Schema.toCodecStringTree(headers)
+    }
+  })
+}
+
+function applyResponseEncoding(schema: Schema.Top, encoding: HttpApiSchema.ResponseEncoding): Schema.Top {
   switch (encoding._tag) {
     case "Json":
       return Schema.toCodecJson(schema)