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

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -18,7 +18,6 @@ import type { FileSystem } from "../../FileSystem.ts"
 import { identity } from "../../Function.ts"
 import { stringOrRedacted } from "../../internal/redacted.ts"
 import * as Layer from "../../Layer.ts"
-import * as Option from "../../Option.ts"
 import type { Path } from "../../Path.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import { hasProperty } from "../../Predicate.ts"
@@ -58,7 +57,7 @@ import * as OpenApi from "./OpenApi.ts"
 /**
  * Registers an `HttpApi` with a `HttpRouter`.
  *
- * @category constructors
+ * @category layers
  * @since 4.0.0
  */
 export const layer = <Id extends string, Groups extends HttpApiGroup.Constraint>(
@@ -724,10 +723,10 @@ function decodePayload(
         }
         try {
           return decode(JSON.parse(text))
-        } catch (cause) {
+        } catch {
           return Effect.fail(
             new Schema.SchemaError(
-              new SchemaIssue.InvalidValue(Option.some(text), { message: `Invalid JSON: ${cause}` })
+              new SchemaIssue.InvalidValue({ message: "Expected a valid JSON body" })
             )
           )
         }
@@ -759,8 +758,12 @@ function handlerToHttpEffect(
   const encodeError = Schema.encodeUnknownEffect(makeErrorSchema(endpoint))
   const decodeParams = UndefinedOr.map(endpoint.params, Schema.decodeUnknownEffect)
   const decodeHeaders = UndefinedOr.map(endpoint.headers, Schema.decodeUnknownEffect)
-  const decodeQuery = UndefinedOr.map(endpoint.query, Schema.decodeUnknownEffect)
+  const decodeQuery = UndefinedOr.map(
+    endpoint.query,
+    (schema) => Schema.decodeUnknownEffect(Schema.toCodecArrayFromSingle(schema))
+  )
   const encodeStream = makeStreamEncoder(endpoint)
+  const encodeWithHeaders = makeWithHeadersEncoder(endpoint)
 
   const shouldParsePayload = endpoint.payload.size > 0 && !isRaw
   const payloadBy = shouldParsePayload ? buildPayloadDecoders(endpoint.payload) : undefined
@@ -798,15 +801,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,
@@ -919,6 +933,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) {
@@ -933,7 +978,7 @@ function makeStreamEncoder(endpoint: HttpApiEndpoint.Top): StreamEncoder | undef
     return (response, context) => {
       if (!Stream.isStream(response)) {
         return hasBuffered ? undefined : new Schema.SchemaError(
-          new SchemaIssue.InvalidValue(Option.some(response), { message: "Expected a streaming response" })
+          new SchemaIssue.InvalidValue({ message: "Expected a streaming response" })
         )
       }
 
@@ -952,7 +997,7 @@ function makeStreamEncoder(endpoint: HttpApiEndpoint.Top): StreamEncoder | undef
   return (response, context) => {
     if (!Stream.isStream(response)) {
       return hasBuffered ? undefined : new Schema.SchemaError(
-        new SchemaIssue.InvalidValue(Option.some(response), { message: "Expected a streaming response" })
+        new SchemaIssue.InvalidValue({ message: "Expected a streaming response" })
       )
     }
 
@@ -968,15 +1013,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
 }
@@ -1041,8 +1088,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, options) =>
+      encodeBody(body, options).pipe(
+        Effect.mapError((error) => error.issue),
+        Effect.flatMap((body) => encodeResponse(body, options))
+      ),
+    encodeHeaders
+  )
+  return $HttpServerResponse.pipe(Schema.decodeTo(schema, transformation))
+}
 
 function makeSuccessSchema(
   endpoint: HttpApiEndpoint.Top
@@ -1059,55 +1129,106 @@ 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({
-    decode: (res) => Effect.fail(new SchemaIssue.Forbidden(Option.some(res), { message: "Encode only schema" })),
+    decode: (input, options) =>
+      Effect.fail(
+        new SchemaIssue.Forbidden({ message: "Encode only schema" }, input, options)
+      ),
     encode
   })
 }
 
+function withHeadersTransformation<T = unknown>(
+  encodeBody: (
+    body: unknown,
+    options?: SchemaAST.ParseOptions
+  ) => Effect.Effect<Response.HttpServerResponse, SchemaIssue.Issue, unknown>,
+  encodeHeaders: (
+    headers: unknown,
+    options?: SchemaAST.ParseOptions
+  ) => Effect.Effect<unknown, Schema.SchemaError, unknown>
+): SchemaTransformation.Transformation<T, Response.HttpServerResponse, never, unknown> {
+  return SchemaTransformation.transformOrFail<T, Response.HttpServerResponse, never, unknown>({
+    decode: (input, options) =>
+      Effect.fail(
+        new SchemaIssue.Forbidden({ message: "Encode only schema" }, input, options)
+      ),
+    encode: (value, options) => {
+      const pair = value as { readonly body: unknown; readonly headers: unknown }
+      return Effect.flatMap(encodeBody(pair.body, options), (response) =>
+        Effect.map(
+          encodeHeaders(pair.headers, options).pipe(Effect.mapError((error) => error.issue)),
+          (headers) => Response.setHeaders(response, headers as any)
+        ))
+    }
+  })
+}
+
 function getResponseEncode<E>(
   status: number,
   encoding: HttpApiSchema.ResponseEncoding,
   isNoContent: boolean
-): (e: E) => Effect.Effect<Response.HttpServerResponse, SchemaIssue.InvalidValue, never> {
+): (
+  e: E,
+  options?: SchemaAST.ParseOptions
+) => Effect.Effect<Response.HttpServerResponse, SchemaIssue.InvalidValue, never> {
   switch (encoding._tag) {
     case "Json": {
-      return ((e) => {
+      return ((e, options) => {
         if (e === undefined || isNoContent) {
           return Effect.succeed(Response.empty({ status }))
         }
         try {
           const s = JSON.stringify(e)
           return Effect.succeed(Response.text(s, { status, contentType: encoding.contentType }))
-        } catch (error) {
-          return Effect.fail(new SchemaIssue.InvalidValue(Option.some(e), { message: globalThis.String(error) }))
+        } catch {
+          return Effect.fail(
+            new SchemaIssue.InvalidValue(
+              { expected: "a JSON-serializable response body" },
+              e,
+              options
+            )
+          )
         }
       })
     }

package/src/unstable/httpapi/HttpApiClient.ts

@@ -15,8 +15,7 @@ import * as Cause from "../../Cause.ts"
 import type * as Context from "../../Context.ts"
 import * as Effect from "../../Effect.ts"
 import { identity } from "../../Function.ts"
-import * as internalRecord from "../../internal/record.ts"
-import * as Option from "../../Option.ts"
+import * as InternalRecord from "../../internal/record.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaAST from "../../SchemaAST.ts"
@@ -62,22 +61,26 @@ export type Client<Groups extends HttpApiGroup.Constraint, E = never, R = never>
  * Derives the typed client interface for an `HttpApi`, preserving any additional
  * client error and service requirements supplied by the caller.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ForApi<Api extends HttpApi.Constraint, E = never, R = never> = Api extends
   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,
-    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
@@ -367,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)
           )
         }
@@ -520,10 +524,10 @@ export const makeWith = <ApiId extends string, Groups extends HttpApiGroup.Const
     ...options,
     onGroup({ group }) {
       if (group.topLevel) return
-      internalRecord.set(client, group.identifier, {})
+      InternalRecord.assignProperty(client, group.identifier, {})
     },
     onEndpoint({ endpoint, endpointFn, group }) {
-      internalRecord.set(
+      InternalRecord.assignProperty(
         group.topLevel ? client : client[group.identifier],
         endpoint.identifier,
         endpointFn
@@ -565,7 +569,7 @@ export const group = <
     ...options,
     predicate: ({ group }) => group.identifier === options.group,
     onEndpoint({ endpoint, endpointFn }) {
-      internalRecord.set(client, endpoint.identifier, endpointFn)
+      InternalRecord.assignProperty(client, endpoint.identifier, endpointFn)
     }
   }).pipe(Effect.map(() => client)) as any
 }
@@ -629,7 +633,7 @@ export const endpoint = <
  *
  * **Example** (Building typed URLs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi"
  *
@@ -647,8 +651,7 @@ export const endpoint = <
  *
  * buildUrl.users.getUser({
  *   params: { id: "123" }
- * })
- * //=> "https://api.example.com/users/123"
+ * }) // => "https://api.example.com/users/123"
  * ```
  *
  * @category constructors
@@ -662,7 +665,7 @@ export const urlBuilder = <Api extends HttpApi.Constraint>(api: Api, options?: {
   HttpApi.reflect(api as unknown as HttpApi.Top, {
     onGroup({ group }) {
       if (group.topLevel) return
-      internalRecord.set(builder, group.identifier, {})
+      InternalRecord.assignProperty(builder, group.identifier, {})
     },
     onEndpoint({ group, endpoint }) {
       const makeUrl = compilePath(endpoint.path)
@@ -688,7 +691,7 @@ export const urlBuilder = <Api extends HttpApi.Constraint>(api: Api, options?: {
         const url = query === "" ? path : `${path}?${query}`
         return options?.baseUrl === undefined ? url : new URL(url, options.baseUrl.toString()).toString()
       }
-      internalRecord.set(
+      InternalRecord.assignProperty(
         group.topLevel ? builder : builder[group.identifier],
         endpoint.identifier,
         endpointBuilder
@@ -724,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>
@@ -770,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])
@@ -804,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 ?
@@ -829,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(
@@ -942,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
   }
 }
 
@@ -1004,39 +1065,59 @@ function getEncodePayloadSchemaFromBody(
   const out = $HttpBody.pipe(Schema.decodeTo(
     schema,
     SchemaTransformation.transformOrFail<unknown, HttpBody.HttpBody>({
-      decode(httpBody) {
-        return Effect.fail(new SchemaIssue.Forbidden(Option.some(httpBody), { message: "Encode only schema" }))
+      decode(input, options) {
+        return Effect.fail(
+          new SchemaIssue.Forbidden({ message: "Encode only schema" }, input, options)
+        )
       },
-      encode(t) {
+      encode(t, options) {
         switch (encoding._tag) {
           case "Multipart":
-            return Effect.fail(new SchemaIssue.Forbidden(Option.some(t), { message: "Payload must be a FormData" }))
+            return Effect.fail(
+              new SchemaIssue.Forbidden(
+                { message: "Payload must be a FormData" },
+                t,
+                options
+              )
+            )
           case "Json": {
             try {
               const body = JSON.stringify(t)
               return Effect.succeed(HttpBody.text(body, encoding.contentType))
-            } catch (error) {
-              return Effect.fail(new SchemaIssue.InvalidValue(Option.some(t), { message: globalThis.String(error) }))
+            } catch {
+              return Effect.fail(
+                new SchemaIssue.InvalidValue(
+                  { expected: "a JSON-serializable request body" },
+                  t,
+                  options
+                )
+              )
             }
           }
           case "Text": {
             if (typeof t !== "string") {
               return Effect.fail(
-                new SchemaIssue.InvalidValue(Option.some(t), { message: "Expected a string" })
+                new SchemaIssue.InvalidValue({ message: "Expected a string" }, t, options)
               )
             }
             return Effect.succeed(HttpBody.text(t, encoding.contentType))
           }
           case "FormUrlEncoded": {
             if (!Predicate.isObject(t)) {
-              return Effect.fail(new SchemaIssue.InvalidValue(Option.some(t), { message: "Expected a record" }))
+              return Effect.fail(
+                new SchemaIssue.InvalidValue({ message: "Expected a record" }, t, options)
+              )
             }
             return Effect.succeed(HttpBody.urlParams(UrlParams.fromInput(t as any), encoding.contentType))
           }
           case "Uint8Array": {
             if (!(t instanceof Uint8Array)) {
               return Effect.fail(
-                new SchemaIssue.InvalidValue(Option.some(t), { message: "Expected a Uint8Array" })
+                new SchemaIssue.InvalidValue(
+                  { message: "Expected a Uint8Array" },
+                  t,
+                  options
+                )
               )
             }
             return Effect.succeed(HttpBody.uint8Array(t, encoding.contentType))