effect 4.0.0-beta.103 → 4.0.0-beta.104

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -760,6 +760,7 @@ function handlerToHttpEffect(
   const decodeHeaders = UndefinedOr.map(endpoint.headers, Schema.decodeUnknownEffect)
   const decodeQuery = UndefinedOr.map(endpoint.query, Schema.decodeUnknownEffect)
   const encodeStream = makeStreamEncoder(endpoint)
+  const encodeWithHeaders = makeWithHeadersEncoder(endpoint)
 
   const shouldParsePayload = endpoint.payload.size > 0 && !isRaw
   const payloadBy = shouldParsePayload ? buildPayloadDecoders(endpoint.payload) : undefined
@@ -797,15 +798,26 @@ function handlerToHttpEffect(
           request.payload = yield* HttpApiSchemaError.wrap("Payload", result)
         }
       }
-      const response = yield* handler(request)
+      let response = yield* handler(request)
       if (Response.isHttpServerResponse(response)) {
         return response
       }
-      const streamResponse = encodeStream?.(response, context)
-      if (streamResponse !== undefined) {
-        return yield* HttpApiSchemaError.wrap("Body", streamResponse)
+      let responseHeaders: unknown | undefined
+      if (encodeWithHeaders !== undefined && HttpApiSchema.isWithHeadersValue(response)) {
+        responseHeaders = response.headers
+        response = response.body
       }
-      return yield* HttpApiSchemaError.wrap("Body", encodeSuccess(response))
+      const encoded = yield* HttpApiSchemaError.wrap(
+        "Body",
+        encodeStream?.(response, context) ??
+          (responseHeaders !== undefined ? encodeWithHeaders!.encodeBody(response) : encodeSuccess(response))
+      )
+      if (encodeWithHeaders === undefined || responseHeaders === undefined) return encoded
+      const encodedHeaders = yield* HttpApiSchemaError.wrap(
+        "ResponseHeaders",
+        encodeWithHeaders.encodeHeaders.get(encoded.status)!(responseHeaders)
+      )
+      return Response.setHeaders(encoded, encodedHeaders as any)
     })
   ).pipe(
     Effect.withErrorReporting,
@@ -918,6 +930,37 @@ type StreamEncoder = (response: unknown, context: Context.Context<never>) =>
   | Effect.Effect<HttpServerResponse, Schema.SchemaError, unknown>
   | undefined
 
+type WithHeadersEncoder = (headers: unknown) => Effect.Effect<unknown, Schema.SchemaError, unknown>
+
+interface WithHeadersEncoders {
+  readonly encodeBody: (body: unknown) => Effect.Effect<HttpServerResponse, Schema.SchemaError, unknown>
+  readonly encodeHeaders: ReadonlyMap<number, WithHeadersEncoder>
+}
+
+function makeWithHeadersEncoder(endpoint: HttpApiEndpoint.Top): WithHeadersEncoders | undefined {
+  const encodeHeaders = new Map<number, WithHeadersEncoder>()
+  const bodySchemas: Array<Schema.ConstraintEncoder<HttpServerResponse, unknown>> = []
+  for (const schema of endpoint.success) {
+    if (!HttpApiSchema.isWithHeaders(schema)) continue
+    encodeHeaders.set(HttpApiSchema.getStatusSuccessSchema(schema), Schema.encodeUnknownEffect(schema.headers))
+    if (!HttpApiSchema.isStreamSchema(schema.schema)) {
+      bodySchemas.push(toResponseSuccessSchema(schema))
+    }
+  }
+  if (encodeHeaders.size === 0) return undefined
+  // Branded response bodies encode against the header-carrying members only, so
+  // the encoded status always has a matching header schema.
+  const bodySchema: Schema.ConstraintEncoder<HttpServerResponse, unknown> = bodySchemas.length === 0
+    ? Schema.Never
+    : bodySchemas.length === 1
+    ? bodySchemas[0]
+    : Schema.Union(bodySchemas)
+  return {
+    encodeBody: Schema.encodeUnknownEffect(bodySchema),
+    encodeHeaders
+  }
+}
+
 function makeStreamEncoder(endpoint: HttpApiEndpoint.Top): StreamEncoder | undefined {
   const streamSchema = getStreamSuccessSchema(endpoint)
   if (streamSchema === undefined) {
@@ -967,15 +1010,17 @@ function makeStreamEncoder(endpoint: HttpApiEndpoint.Top): StreamEncoder | undef
 
 function getStreamSuccessSchema(endpoint: HttpApiEndpoint.Top) {
   for (const schema of endpoint.success) {
-    if (HttpApiSchema.isStreamSchema(schema)) {
-      return schema
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    if (HttpApiSchema.isStreamSchema(body)) {
+      return body
     }
   }
 }
 
 function hasBufferedSuccess(endpoint: HttpApiEndpoint.Top): boolean {
   for (const schema of endpoint.success) {
-    if (Schema.isSchema(schema) && !HttpApiSchema.isStreamSchema(schema)) return true
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    if (Schema.isSchema(body) && !HttpApiSchema.isStreamSchema(body)) return true
   }
   return endpoint.success.size === 0
 }
@@ -1040,8 +1085,31 @@ function renderSseEvent(event: Sse.EventEncoded) {
   })
 }
 
-const toResponseSuccessSchema = toResponseSchema(HttpApiSchema.getStatusSuccess)
-const toResponseErrorSchema = toResponseSchema(HttpApiSchema.getStatusError)
+const toResponseSuccessSchema = toResponseSchema(HttpApiSchema.getStatusSuccessSchema)
+const toResponseErrorSchemaPlain = toResponseSchema(HttpApiSchema.getStatusErrorSchema)
+
+function toResponseErrorSchema(
+  schema: Schema.Constraint
+): Schema.ConstraintEncoder<HttpServerResponse, unknown> {
+  if (!HttpApiSchema.isWithHeaders(schema)) return toResponseErrorSchemaPlain(schema)
+
+  const encodeBody = Schema.encodeUnknownEffect(schema.schema)
+  const encodeHeaders = Schema.encodeUnknownEffect(schema.headers)
+  const encodeResponse = getResponseEncode(
+    HttpApiSchema.getStatusErrorSchema(schema),
+    HttpApiSchema.getResponseEncodingSchema(schema),
+    HttpApiSchema.isNoContent(schema.schema.ast)
+  )
+  const transformation = withHeadersTransformation<HttpApiSchema.withHeaders<unknown, Schema.StringTree>>(
+    (body) =>
+      encodeBody(body).pipe(
+        Effect.mapError((error) => error.issue),
+        Effect.flatMap(encodeResponse)
+      ),
+    encodeHeaders
+  )
+  return $HttpServerResponse.pipe(Schema.decodeTo(schema, transformation))
+}
 
 function makeSuccessSchema(
   endpoint: HttpApiEndpoint.Top
@@ -1058,31 +1126,44 @@ function makeErrorSchema(
   return schemas.length === 1 ? schemas[0] : Schema.Union(schemas)
 }
 
-function toResponseSchema(getStatus: (ast: SchemaAST.AST) => number) {
-  const cache = new WeakMap<SchemaAST.AST, Schema.Top>()
+function toResponseSchema(getStatus: (schema: Schema.Constraint) => number) {
+  // WithHeaders wrappers share a single declaration AST, so they are cached by instance
+  const cache = new WeakMap<object, Schema.Top>()
 
   return (schema: Schema.Constraint): Schema.ConstraintEncoder<HttpServerResponse, unknown> => {
-    const cached = cache.get(schema.ast)
+    const key = HttpApiSchema.isWithHeaders(schema) ? schema : schema.ast
+    const cached = cache.get(key)
     if (cached !== undefined) {
       return cached as any
     }
+    const bodySchema = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
     const responseSchema = $HttpServerResponse.pipe(
-      Schema.decodeTo(schema, getResponseTransformation(getStatus, schema))
+      Schema.decodeTo(bodySchema, getResponseTransformation(getStatus, schema))
     )
-    cache.set(schema.ast, responseSchema)
+    cache.set(key, responseSchema)
     return responseSchema
   }
 }
 
 function getResponseTransformation(
-  getStatus: (ast: SchemaAST.AST) => number,
+  getStatus: (schema: Schema.Constraint) => number,
   schema: Schema.Constraint
-): SchemaTransformation.Transformation<unknown, Response.HttpServerResponse> {
-  const ast = schema.ast
+): SchemaTransformation.Transformation<unknown, Response.HttpServerResponse, never, unknown> {
+  const withHeaders = HttpApiSchema.getWithHeadersAnnotation(schema.ast)
+  if (withHeaders !== undefined) {
+    const encodeBody = getResponseEncode(
+      getStatus(withHeaders.body),
+      HttpApiSchema.getResponseEncoding(withHeaders.body.ast),
+      HttpApiSchema.isNoContent(withHeaders.body.ast)
+    )
+    return withHeadersTransformation(encodeBody, Schema.encodeUnknownEffect(withHeaders.headersCodec))
+  }
+
+  const bodySchema = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
   const encode = getResponseEncode(
-    getStatus(ast),
-    HttpApiSchema.getResponseEncoding(ast),
-    HttpApiSchema.isNoContent(ast)
+    getStatus(schema),
+    HttpApiSchema.getResponseEncodingSchema(schema),
+    HttpApiSchema.isNoContent(bodySchema.ast)
   )
 
   return SchemaTransformation.transformOrFail({
@@ -1091,6 +1172,23 @@ function getResponseTransformation(
   })
 }
 
+function withHeadersTransformation<T = unknown>(
+  encodeBody: (body: unknown) => Effect.Effect<Response.HttpServerResponse, SchemaIssue.Issue, unknown>,
+  encodeHeaders: (headers: unknown) => Effect.Effect<unknown, Schema.SchemaError, unknown>
+): SchemaTransformation.Transformation<T, Response.HttpServerResponse, never, unknown> {
+  return SchemaTransformation.transformOrFail<T, Response.HttpServerResponse, never, unknown>({
+    decode: () => Effect.fail(new SchemaIssue.Forbidden({ message: "Encode only schema" })),
+    encode: (value) => {
+      const pair = value as { readonly body: unknown; readonly headers: unknown }
+      return Effect.flatMap(encodeBody(pair.body), (response) =>
+        Effect.map(
+          encodeHeaders(pair.headers).pipe(Effect.mapError((error) => error.issue)),
+          (headers) => Response.setHeaders(response, headers as any)
+        ))
+    }
+  })
+}
+
 function getResponseEncode<E>(
   status: number,
   encoding: HttpApiSchema.ResponseEncoding,

package/src/unstable/httpapi/HttpApiClient.ts

@@ -68,15 +68,19 @@ export type ForApi<Api extends HttpApi.Constraint, E = never, R = never> = Api e
   HttpApi.HttpApi<infer _Id, infer Groups> ? Client<Groups, E, R> :
   never
 
-type SuccessType<S> = S extends HttpApiSchema.StreamSse<
-  infer _Events,
-  infer _Error,
-  infer _Value
-> ? Stream.Stream<
-    _Value,
-    _Error["Type"] | HttpClientError.HttpClientError | Schema.SchemaError | Sse.Retry | Sse.SseError,
-    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"] | HttpClientError.HttpClientError | Schema.SchemaError | Sse.Retry | Sse.SseError,
+      never
+    >
   : S extends HttpApiSchema.StreamUint8Array ? Stream.Stream<Uint8Array, HttpClientError.HttpClientError, never>
   : S extends Schema.Constraint ? S["Type"]
   : never
@@ -366,10 +370,11 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
           }
         }
         for (const streamSuccess of getStreamSuccessSchemas(endpoint)) {
+          const streamSchema = isWithHeadersStreamSuccess(streamSuccess) ? streamSuccess.schema : streamSuccess
           addResponseAlternative(
             successAlternatives,
-            HttpApiSchema.getStatusStream(streamSuccess),
-            streamSuccess.contentType,
+            HttpApiSchema.getStatusSuccessSchema(streamSuccess),
+            streamSchema.contentType,
             streamToResponse(streamSuccess)
           )
         }
@@ -722,9 +727,44 @@ const compilePath = (path: string) => {
 }
 
 function schemasToResponse(schemas: readonly [Schema.Constraint, ...Array<Schema.Constraint>]) {
-  const codec = toCodecArrayBuffer(schemas)
+  const hasWithHeaders = schemas.some((schema) =>
+    HttpApiSchema.isWithHeaders(schema) || HttpApiSchema.getWithHeadersAnnotation(schema.ast) !== undefined
+  )
+  const codec = hasWithHeaders
+    ? Schema.Union(schemas.map(toCodecArrayBufferWithHeaders))
+    : toCodecArrayBuffer(schemas)
   const decode = Schema.decodeEffect(codec)
-  return (response: HttpClientResponse.HttpClientResponse) => Effect.flatMap(response.arrayBuffer, decode)
+  return (response: HttpClientResponse.HttpClientResponse) =>
+    Effect.flatMap(
+      response.arrayBuffer,
+      hasWithHeaders
+        ? (body) => decode({ body, headers: response.headers })
+        : decode
+    )
+}
+
+function toCodecArrayBufferWithHeaders(schema: Schema.Constraint): Schema.Top {
+  const isWithHeaders = HttpApiSchema.isWithHeaders(schema)
+  const annotation = HttpApiSchema.getWithHeadersAnnotation(schema.ast)
+  if (annotation !== undefined) {
+    return Schema.Struct({
+      body: fromArrayBuffer(annotation.body),
+      headers: annotation.headersCodec
+    }).pipe(Schema.decodeTo(schema))
+  }
+  const body = isWithHeaders ? schema.schema : schema
+  return Schema.Struct({
+    body: fromArrayBuffer(body).pipe(Schema.decodeTo(body)),
+    headers: isWithHeaders ? schema.headers : Schema.Unknown
+  }).pipe(
+    Schema.decodeTo(
+      isWithHeaders ? schema : Schema.toType(schema),
+      SchemaTransformation.transform({
+        decode: (value) => isWithHeaders ? HttpApiSchema.withHeaders(value) : value.body,
+        encode: (value: any) => isWithHeaders ? value : { body: value, headers: undefined }
+      }) as any
+    )
+  )
 }
 
 type ResponseDecoder = (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<unknown, unknown, unknown>
@@ -768,9 +808,10 @@ function groupSchemasByContentType(
 ): Map<string, Arr.NonEmptyReadonlyArray<Schema.Top>> {
   const grouped = new Map<string, [Schema.Top, ...Array<Schema.Top>]>()
   for (const schema of schemas) {
-    const contentType = HttpApiSchema.isNoContent(schema.ast)
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    const contentType = HttpApiSchema.isNoContent(body.ast)
       ? ""
-      : MediaType.normalize(HttpApiSchema.getResponseEncoding(schema.ast).contentType)
+      : MediaType.normalize(HttpApiSchema.getResponseEncodingSchema(schema).contentType)
     const existing = grouped.get(contentType)
     if (existing === undefined) {
       grouped.set(contentType, [schema])
@@ -802,24 +843,35 @@ function failUnsupportedContentType(
 
 const reservedStreamFailureEvent = "effect/httpapi/stream/failure"
 
-function getStreamSuccessSchemas(endpoint: HttpApiEndpoint.Top): Array<HttpApiSchema.StreamSchema> {
-  const schemas: Array<HttpApiSchema.StreamSchema> = []
+type StreamSuccessSchema =
+  | HttpApiSchema.StreamSchema
+  | HttpApiSchema.WithHeaders<HttpApiSchema.StreamSchema, Schema.Top>
+
+const isWithHeadersStreamSuccess = (
+  schema: StreamSuccessSchema
+): schema is HttpApiSchema.WithHeaders<HttpApiSchema.StreamSchema, Schema.Top> => HttpApiSchema.isWithHeaders(schema)
+
+function getStreamSuccessSchemas(endpoint: HttpApiEndpoint.Top): Array<StreamSuccessSchema> {
+  const schemas: Array<StreamSuccessSchema> = []
   for (const schema of endpoint.success) {
-    if (HttpApiSchema.isStreamSchema(schema)) {
-      schemas.push(schema)
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    if (HttpApiSchema.isStreamSchema(body)) {
+      schemas.push(schema as StreamSuccessSchema)
     }
   }
   return schemas
 }
 
-function streamToResponse(streamSchema: HttpApiSchema.StreamSchema) {
+function streamToResponse(successSchema: StreamSuccessSchema) {
+  const isWithHeaders = isWithHeadersStreamSuccess(successSchema)
+  const streamSchema = isWithHeaders ? successSchema.schema : successSchema
   const sse = HttpApiSchema.isStreamUint8Array(streamSchema)
     ? undefined
     : {
       declaration: streamSchema,
       decoder: makeSseDecoder(streamSchema)
     }
-  return (response: HttpClientResponse.HttpClientResponse) =>
+  const toStream = (response: HttpClientResponse.HttpClientResponse) =>
     Effect.map(Effect.context<never>(), (context) =>
       Stream.provideContext(
         sse === undefined ?
@@ -827,6 +879,14 @@ function streamToResponse(streamSchema: HttpApiSchema.StreamSchema) {
           decodeSseStream(response.stream, sse.declaration, sse.decoder),
         context as Context.Context<unknown>
       ))
+  if (!isWithHeaders) return toStream
+
+  const decodeHeaders = Schema.decodeUnknownEffect(successSchema.headers)
+  return (response: HttpClientResponse.HttpClientResponse) =>
+    Effect.flatMap(
+      decodeHeaders(response.headers),
+      (headers) => Effect.map(toStream(response), (body) => HttpApiSchema.withHeaders({ body, headers }))
+    )
 }
 
 function makeSseDecoder(
@@ -940,31 +1000,34 @@ function toCodecArrayBuffer(schemas: readonly [Schema.Constraint, ...Array<Schem
   return Schema.Union(schemas.map(onSchema))
 
   function onSchema(schema: Schema.Constraint) {
-    const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
-    switch (encoding._tag) {
-      case "Json": {
-        // handle json codecs that transform void schemas to null
-        const encodedIsNull = SchemaAST.isNull(SchemaAST.toEncoded(schema.ast))
-        return UnknownFromArrayBuffer.pipe(Schema.decodeTo(
-          schema,
-          encodedIsNull ?
+    return fromArrayBuffer(schema).pipe(Schema.decodeTo(schema))
+  }
+}
+
+function fromArrayBuffer(schema: Schema.Constraint): Schema.Top {
+  const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
+  switch (encoding._tag) {
+    case "Json": {
+      // handle json codecs that transform void schemas to null
+      const encodedIsNull = SchemaAST.isNull(SchemaAST.toEncoded(schema.ast))
+      return encodedIsNull
+        ? UnknownFromArrayBuffer.pipe(
+          Schema.decodeTo(
+            Schema.Unknown,
             SchemaTransformation.transform({
               decode: (a) => a === undefined ? null : a,
               encode: (a) => a === null ? undefined : a
-            }) as any :
-            undefined
-        ))
-      }
-      case "FormUrlEncoded":
-        return StringFromArrayBuffer.pipe(
-          Schema.decodeTo(UrlParams.schemaRecord),
-          Schema.decodeTo(schema)
+            }) as any
+          )
         )
-      case "Uint8Array":
-        return Uint8ArrayFromArrayBuffer.pipe(Schema.decodeTo(schema))
-      case "Text":
-        return StringFromArrayBuffer.pipe(Schema.decodeTo(schema))
+        : UnknownFromArrayBuffer
     }
+    case "FormUrlEncoded":
+      return StringFromArrayBuffer.pipe(Schema.decodeTo(UrlParams.schemaRecord))
+    case "Uint8Array":
+      return Uint8ArrayFromArrayBuffer
+    case "Text":
+      return StringFromArrayBuffer
   }
 }
 

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>
@@ -945,9 +958,11 @@ export type SuccessConstraint = Schema.Top | ReadonlyArray<Schema.Top>
  */
 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)