effect 4.0.0-beta.103 → 4.0.0-beta.105

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -29,10 +29,27 @@ declare module "../../Schema.ts" {
        * @internal
        */
       readonly "~httpApiEncoding"?: Encoding | undefined
+      /**
+       * Marks schemas produced by `encodeToWithHeaders`, carrying the body and
+       * headers schemas so integrations can split the encoded pair.
+       * @internal
+       */
+      readonly "~httpApiWithHeaders"?: WithHeadersAnnotation | undefined
     }
   }
 }
 
+/**
+ * Annotation payload attached by `encodeToWithHeaders`.
+ *
+ * @internal
+ */
+export interface WithHeadersAnnotation {
+  readonly body: Schema.Top
+  readonly headers: Schema.Top
+  readonly headersCodec: Schema.Top
+}
+
 /**
  * HTTP API body encoding metadata used by payloads and responses.
  *
@@ -483,6 +500,315 @@ function defaultStreamContentType(mode: StreamMode): string {
   }
 }
 
+/**
+ * Runtime brand key used to mark `WithHeaders` response schemas.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const WithHeadersTypeId = "~effect/httpapi/HttpApiSchema/WithHeaders"
+
+/**
+ * Type-level brand identifier used by `WithHeaders`.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export type WithHeadersTypeId = typeof WithHeadersTypeId
+
+/**
+ * Runtime brand key used to mark `WithHeaders` response values.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const WithHeadersValueTypeId = "~effect/httpapi/HttpApiSchema/WithHeadersValue"
+
+/**
+ * Type-level brand identifier used by `WithHeaders` response values.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export type WithHeadersValueTypeId = typeof WithHeadersValueTypeId
+
+/**
+ * A response schema wrapping a body schema together with a response headers
+ * schema.
+ *
+ * **Details**
+ *
+ * `WithHeaders` is a branded declaration schema: it carries the inner success
+ * schema and the headers schema as properties, and server, client, and OpenAPI
+ * integrations detect the brand and handle body and headers separately. It is
+ * supported for error responses, though {@link encodeToWithHeaders} is usually
+ * more convenient there because handlers can fail with the domain error value.
+ *
+ * - `schema` is the inner response schema. Success responses may wrap
+ *   `StreamSse` and `StreamUint8Array`; error responses remain non-streaming.
+ *   Nesting `WithHeaders` is rejected at construction.
+ * - `headers` is any schema; endpoint construction applies
+ *   `Schema.toCodecStringTree` unless codecs are disabled, so leaves become
+ *   `string | undefined` on the wire and `undefined` leaves are omitted from the response.
+ * - Status and response-encoding annotations are resolved from the wrapper
+ *   first, falling through to the inner schema.
+ * - A header-carrying response cannot share its status and content type with
+ *   another response in the same success or error union. Endpoint construction
+ *   rejects ambiguous declarations, including those made with
+ *   {@link encodeToWithHeaders}.
+ * - `Rebuild` preserves the brand and both parts, so `.annotate` keeps the
+ *   wrapper intact.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface WithHeaders<S extends Schema.Top, H extends Schema.Top> extends
+  Schema.Bottom<
+    withHeaders<S["Type"], H["Type"]>,
+    withHeaders<S["Encoded"], Schema.StringTree>,
+    S["DecodingServices"] | H["DecodingServices"],
+    S["EncodingServices"] | H["EncodingServices"],
+    SchemaAST.Declaration,
+    WithHeaders<S, H>
+  >
+{
+  readonly "Rebuild": WithHeaders<S, H>
+  readonly [WithHeadersTypeId]: typeof WithHeadersTypeId
+  readonly schema: S
+  readonly headers: H
+}
+
+/**
+ * The Type of a `WithHeaders` schema: what handlers return and what the
+ * client resolves to, constructed via {@link withHeaders}.
+ *
+ * `body` is the inner success value. For stream success schemas it is the
+ * `Stream` itself, so headers are decided before the body starts streaming.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface withHeaders<A, H> {
+  readonly [WithHeadersValueTypeId]: WithHeadersValueTypeId
+  readonly body: A
+  readonly headers: H
+}
+
+/** @internal */
+export const isWithHeadersValue = (u: unknown): u is withHeaders<unknown, unknown> =>
+  Predicate.hasProperty(u, WithHeadersValueTypeId)
+
+const withHeadersValueSchema = Schema.declare(isWithHeadersValue)
+
+/**
+ * Wraps a success schema with a response headers schema.
+ *
+ * Headers accept either a schema or a fields shorthand, mirroring the
+ * request-side headers option.
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { HttpApiSchema } from "effect/unstable/httpapi"
+ *
+ * const schema = HttpApiSchema.WithHeaders(Schema.String, {
+ *   "x-total-count": Schema.FiniteFromString
+ * })
+ * const response: typeof schema.Type = HttpApiSchema.withHeaders({
+ *   body: "created",
+ *   headers: { "x-total-count": 1 }
+ * })
+ *
+ * HttpApiSchema.isWithHeaders(schema) // => true
+ * response.body // => "created"
+ * response.headers // => { "x-total-count": 1 }
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export function WithHeaders<S extends Schema.Top, H extends Schema.Struct.Fields>(
+  schema: S,
+  headers: H
+): WithHeaders<S, Schema.Struct<H>>
+export function WithHeaders<S extends Schema.Top, H extends Schema.Top>(
+  schema: S,
+  headers: H
+): WithHeaders<S, H>
+export function WithHeaders(
+  schema: Schema.Top,
+  headers: Schema.Top | Schema.Struct.Fields
+): WithHeaders<Schema.Top, Schema.Top> {
+  if (isWithHeaders(schema)) {
+    throw new Error("WithHeaders schemas cannot be nested")
+  }
+  return Schema.make<WithHeaders<Schema.Top, Schema.Top>>(withHeadersValueSchema.ast, {
+    [WithHeadersTypeId]: WithHeadersTypeId,
+    schema,
+    headers: Schema.isSchema(headers) ? headers : Schema.Struct(headers)
+  })
+}
+
+/**
+ * Constructs a `WithHeaders` response value from a body and headers.
+ *
+ * The returned value is branded so servers and clients can detect it exactly,
+ * including in mixed success unions. The same shape is used on both sides: a
+ * value received from a client can be returned from another handler unchanged.
+ *
+ * See {@link WithHeaders} for an example that constructs a schema and its
+ * corresponding response value.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const withHeaders = <A, H>(options: {
+  readonly body: A
+  readonly headers: H
+}): withHeaders<A, H> => ({
+  [WithHeadersValueTypeId]: WithHeadersValueTypeId,
+  body: options.body,
+  headers: options.headers
+})
+
+/**
+ * Returns `true` when a schema is a `WithHeaders` response schema.
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { HttpApiSchema } from "effect/unstable/httpapi"
+ *
+ * const schema = HttpApiSchema.WithHeaders(Schema.String, {
+ *   "x-request-id": Schema.String
+ * })
+ *
+ * HttpApiSchema.isWithHeaders(schema) // => true
+ * HttpApiSchema.isWithHeaders(Schema.String) // => false
+ * ```
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export const isWithHeaders = (u: unknown): u is WithHeaders<Schema.Top, Schema.Top> =>
+  Schema.isSchema(u) && Predicate.hasProperty(u, WithHeadersTypeId)
+
+/** @internal */
+export function rebuildWithHeaders(
+  self: WithHeaders<Schema.Top, Schema.Top>,
+  schema: Schema.Top,
+  headers: Schema.Top
+): WithHeaders<Schema.Top, Schema.Top> {
+  return Schema.make<WithHeaders<Schema.Top, Schema.Top>>(self.ast, {
+    [WithHeadersTypeId]: WithHeadersTypeId,
+    schema,
+    headers
+  })
+}
+
+/**
+ * Schema type returned by `encodeToWithHeaders`, encoding as a `{ body, headers }`
+ * pair while decoding to the source schema type.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export interface encodeToWithHeaders<
+  S extends Schema.Top,
+  Body extends Schema.Top,
+  Headers extends Schema.Struct.Fields
+> extends
+  Schema.decodeTo<
+    Schema.toType<S>,
+    Schema.Struct<{
+      readonly body: Body
+      readonly headers: Schema.Struct<Headers>
+    }>
+  >
+{}
+
+/**
+ * Encodes a schema as a `{ body, headers }` pair, folding response headers into
+ * an opaque domain type such as an error class.
+ *
+ * **Details**
+ *
+ * The encoded side is the pair of the body schema and the headers fields; the
+ * Type stays the source schema's Type. The body schema is authoritative for
+ * everything wire-level: status, content type, and response encoding resolve
+ * from the body schema's annotations.
+ *
+ * The mappings are pure total functions: validation lives in the body and
+ * header schemas, the mappings only reshape valid data.
+ *
+ * Streams used as the body schema turn mid-stream transport errors into
+ * defects on the client. Stream responses should use {@link WithHeaders},
+ * which preserves the body stream's error channel in the generated client.
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { HttpApiSchema } from "effect/unstable/httpapi"
+ *
+ * class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", {
+ *   userId: Schema.Int
+ * }) {}
+ *
+ * const UserNotFoundWithHeaders = UserNotFound.pipe(
+ *   HttpApiSchema.encodeToWithHeaders({
+ *     body: HttpApiSchema.Empty(404),
+ *     headers: {
+ *       "x-user-id": Schema.Int
+ *     }
+ *   }, {
+ *     decode: ({ headers }) => new UserNotFound({ userId: headers["x-user-id"] }),
+ *     encode: (error) => ({
+ *       headers: { "x-user-id": error.userId },
+ *       body: undefined
+ *     })
+ *   })
+ * )
+ *
+ * const encoded = Schema.encodeSync(UserNotFoundWithHeaders)(new UserNotFound({ userId: 123 }))
+ * encoded // => { body: undefined, headers: { "x-user-id": 123 } }
+ * ```
+ *
+ * @see {@link WithHeaders} for the structural wrapper recommended for success
+ * responses, including streams.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export function encodeToWithHeaders<
+  S extends Schema.Top,
+  Body extends Schema.Top,
+  Headers extends Schema.Struct.Fields
+>(options: {
+  readonly body: Body
+  readonly headers: Headers
+}, transformation: {
+  readonly decode: (
+    value: Schema.Struct.Type<{ readonly body: Body; readonly headers: Schema.Struct<Headers> }>
+  ) => S["Type"]
+  readonly encode: (
+    value: S["Type"]
+  ) => Schema.Struct.Type<{ readonly body: Body; readonly headers: Schema.Struct<Headers> }>
+}) {
+  return (self: S): encodeToWithHeaders<S, Body, Headers> => {
+    const body = options.body
+    const headers = Schema.Struct(options.headers)
+    const status = resolveHttpApiStatus(body.ast)
+    const encoding = resolveHttpApiEncoding(body.ast)
+    return Schema.Struct({ body, headers }).pipe(
+      Schema.decodeTo(
+        Schema.toType(self),
+        SchemaTransformation.transform(transformation)
+      )
+    ).annotate({
+      "~httpApiWithHeaders": { body, headers, headersCodec: Schema.toEncoded(headers) },
+      ...(status !== undefined ? { httpApiStatus: status } : undefined),
+      ...(encoding !== undefined ? { "~httpApiEncoding": encoding } : undefined)
+    })
+  }
+}
+
 /**
  * Runtime brand key used to mark schemas as buffered multipart payloads.
  *
@@ -683,6 +1009,9 @@ export const isNoContent = (ast: SchemaAST.AST): boolean => {
 
 const resolveHttpApiEncoding = SchemaAST.resolveAt<Encoding>("~httpApiEncoding")
 
+/** @internal */
+export const getWithHeadersAnnotation = SchemaAST.resolveAt<WithHeadersAnnotation>("~httpApiWithHeaders")
+
 const resolveHttpApiStatus = SchemaAST.resolveAt<number>("httpApiStatus")
 
 const defaultJsonEncoding: Encoding = {
@@ -719,6 +1048,22 @@ export function getStatusSuccess(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 200
 }
 
+/** @internal */
+export function getStatusSuccessSchema(schema: Schema.Constraint): number {
+  if (isWithHeaders(schema)) {
+    return resolveHttpApiStatus(schema.ast) ?? getStatusSuccess(schema.schema.ast)
+  }
+  return getStatusSuccess(schema.ast)
+}
+
+/** @internal */
+export function getResponseEncodingSchema(schema: Schema.Constraint): ResponseEncoding {
+  if (isWithHeaders(schema) && resolveHttpApiEncoding(schema.ast) === undefined) {
+    return getResponseEncoding(schema.schema.ast)
+  }
+  return getResponseEncoding(schema.ast)
+}
+
 /** @internal */
 export function getStatusStream(self: StreamSchema): number {
   return getStatusSuccess(self.ast)
@@ -728,3 +1073,11 @@ export function getStatusStream(self: StreamSchema): number {
 export function getStatusError(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 500
 }
+
+/** @internal */
+export function getStatusErrorSchema(schema: Schema.Constraint): number {
+  if (isWithHeaders(schema)) {
+    return resolveHttpApiStatus(schema.ast) ?? getStatusError(schema.schema.ast)
+  }
+  return getStatusError(schema.ast)
+}

package/src/unstable/httpapi/OpenApi.ts

@@ -369,11 +369,30 @@ function fromApiWith<Id extends string, Groups extends HttpApiGroup.Constraint>(
       const method = endpoint.method.toLowerCase() as OpenAPISpecMethodName
 
       function processResponseBodies(bodies: ResponseBodies, defaultDescription: () => string) {
-        for (const [status, { content, descriptions, streamContent }] of bodies) {
+        for (const [status, { content, descriptions, headers, streamContent }] of bodies) {
           const description = descriptions.size > 0 ? Array.from(descriptions).join(" | ") : defaultDescription()
           InternalRecord.assignProperty(op.responses, status, {
             description
           })
+          for (const schema of headers) {
+            const ast = SchemaAST.getLastEncoding(schema.ast)
+            if (SchemaAST.isObjects(ast)) {
+              for (const ps of ast.propertySignatures) {
+                const name = String(ps.name).toLowerCase()
+                if (name === "content-type") continue
+                op.responses[status].headers ??= {}
+                InternalRecord.assignProperty(op.responses[status].headers, name, {
+                  schema: {},
+                  required: !SchemaAST.isOptional(ps.type)
+                })
+                pathOps.push({
+                  _tag: "parameter",
+                  ast: ps.type,
+                  path: ["paths", path, method, "responses", String(status), "headers", name, "schema"]
+                })
+              }
+            }
+          }
           if (content !== undefined) {
             content.forEach((map, encoding) => {
               map.forEach((schemas, contentType) => {
@@ -568,7 +587,7 @@ function fromApiWith<Id extends string, Groups extends HttpApiGroup.Constraint>(
       processResponseBodies(
         extractResponseBodies(
           HttpApiEndpoint.getErrorSchemas(endpoint),
-          HttpApiSchema.getStatusError,
+          HttpApiSchema.getStatusErrorSchema,
           resolveDescriptionOrIdentifier
         ),
         () => "Error"
@@ -673,6 +692,7 @@ type ResponseBodies = Map<
   {
     descriptions: Set<string>
     content: Content | undefined // undefined means no content
+    headers: Array<Schema.Constraint>
     streamContent: StreamContent | undefined
   }
 >
@@ -682,19 +702,20 @@ const reservedStreamFailureEvent = "effect/httpapi/stream/failure"
 function extractSuccessResponseBodies(endpoint: HttpApiEndpoint.Top): ResponseBodies {
   return extractResponseBodies(
     HttpApiEndpoint.getSuccessSchemas(endpoint),
-    HttpApiSchema.getStatusSuccess,
+    HttpApiSchema.getStatusSuccessSchema,
     resolveDescriptionOrIdentifier
   )
 }
 
 function extractResponseBodies(
   schemas: Array<Schema.Constraint>,
-  getStatus: (ast: SchemaAST.AST) => number,
+  getStatus: (schema: Schema.Constraint) => number,
   getDescription: (ast: SchemaAST.AST) => string | undefined
 ): ResponseBodies {
   const map = new Map<number, {
     descriptions: Set<string>
     content: Content | undefined
+    headers: Array<Schema.Constraint>
     streamContent: StreamContent | undefined
   }>()
 
@@ -703,16 +724,25 @@ function extractResponseBodies(
   return map
 
   function process(schema: Schema.Constraint) {
-    if (HttpApiSchema.isStreamSchema(schema)) {
-      addStreamContent(schema)
-      return
-    }
-    const ast = schema.ast
-    const status = getStatus(ast)
-    if (HttpApiSchema.isNoContent(ast)) {
-      addNoContent(status, getDescription(schema.ast) ?? "<No Content>")
+    const annotation = HttpApiSchema.getWithHeadersAnnotation(schema.ast)
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : annotation?.body ?? schema
+    const headers = HttpApiSchema.isWithHeaders(schema) ? schema.headers : annotation?.headersCodec
+    const status = getStatus(schema)
+    const ast = body.ast
+    if (HttpApiSchema.isStreamSchema(body)) {
+      addStreamContent(body, status)
+    } else if (HttpApiSchema.isNoContent(ast)) {
+      addNoContent(status, getDescription(schema.ast) ?? getDescription(ast) ?? "<No Content>")
     } else {
-      addContent(schema, status, HttpApiSchema.getResponseEncoding(ast))
+      addContent(
+        body,
+        status,
+        HttpApiSchema.getResponseEncodingSchema(schema),
+        getDescription(schema.ast) ?? getDescription(ast)
+      )
+    }
+    if (headers !== undefined) {
+      map.get(status)!.headers.push(headers)
     }
   }
 
@@ -722,6 +752,7 @@ function extractResponseBodies(
       map.set(status, {
         descriptions: new Set([description]),
         content: undefined,
+        headers: [],
         streamContent: undefined
       })
     } else {
@@ -731,14 +762,19 @@ function extractResponseBodies(
     }
   }
 
-  function addContent(schema: Schema.Constraint, status: number, encoding: HttpApiSchema.Encoding) {
-    const description = getDescription(schema.ast)
+  function addContent(
+    schema: Schema.Constraint,
+    status: number,
+    encoding: HttpApiSchema.Encoding,
+    description: string | undefined
+  ) {
     const statusMap = map.get(status)
     const { _tag, contentType } = encoding
     if (statusMap === undefined) {
       map.set(status, {
         descriptions: new Set(description !== undefined ? [description] : []),
         content: new Map([[_tag, new Map([[contentType, new Set([schema])]])]]),
+        headers: [],
         streamContent: undefined
       })
     } else {
@@ -765,19 +801,24 @@ function extractResponseBodies(
     }
   }
 
-  function addStreamContent(stream: HttpApiSchema.StreamSchema) {
-    const status = HttpApiSchema.getStatusStream(stream)
+  function addStreamContent(
+    stream: HttpApiSchema.StreamSchema,
+    status: number
+  ) {
     const statusMap = map.get(status)
     if (statusMap === undefined) {
       map.set(status, {
         descriptions: new Set(),
         content: undefined,
+        headers: [],
         streamContent: new Map([[stream.contentType, stream]])
       })
-    } else if (statusMap.streamContent === undefined) {
-      statusMap.streamContent = new Map([[stream.contentType, stream]])
     } else {
-      statusMap.streamContent.set(stream.contentType, stream)
+      if (statusMap.streamContent === undefined) {
+        statusMap.streamContent = new Map([[stream.contentType, stream]])
+      } else {
+        statusMap.streamContent.set(stream.contentType, stream)
+      }
     }
   }
 }
@@ -1042,8 +1083,17 @@ export type OpenApiSpecContent = {
 export interface OpenApiSpecResponse {
   description: string
   content?: OpenApiSpecContent
+  headers?: Record<string, OpenAPISpecHeader>
 }
 
+/**
+ * Generated OpenAPI response header object.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type OpenAPISpecHeader = Omit<OpenAPISpecParameter, "name" | "in">
+
 /**
  * Generated OpenAPI media type object containing the JSON Schema for a request or response body.
  *

package/src/unstable/observability/OtlpExporter.ts

@@ -167,7 +167,7 @@ export const make: (
     readonly label: string
     readonly exportInterval: Duration.Input
     readonly maxBatchSize: number | "disabled"
-    readonly body: (data: Array<any>) => HttpBody
+    readonly body: (data: Array<any>) => readonly [body: HttpBody, onSuccess: Effect.Effect<void>]
     readonly shutdownTimeout: Duration.Input
   }
 ) => Effect.Effect<
@@ -208,9 +208,11 @@ export const make: (
       }
       buffer = []
     }
+    const [body, onSuccess] = options.body(items)
     return client.execute(
-      HttpClientRequest.setBody(request, options.body(items))
+      HttpClientRequest.setBody(request, body)
     ).pipe(
+      Effect.andThen(onSuccess),
       Effect.asVoid,
       Effect.withTracerEnabled(false)
     )

package/src/unstable/observability/OtlpLogger.ts

@@ -71,7 +71,7 @@ export const make: (
     headers: options.headers,
     maxBatchSize: options.maxBatchSize ?? 1000,
     exportInterval: options.exportInterval ?? Duration.seconds(1),
-    body: (data) =>
+    body: (data) => [
       serialization.logs({
         resourceLogs: [{
           resource: otelResource,
@@ -81,6 +81,8 @@ export const make: (
           }]
         }]
       }),
+      Effect.void
+    ],
     shutdownTimeout: options.shutdownTimeout ?? Duration.seconds(3)
   })