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

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, 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
@@ -1058,47 +1126,92 @@ 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: () => Effect.fail(new SchemaIssue.Forbidden({ 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 }))
         }
@@ -1107,7 +1220,11 @@ function getResponseEncode<E>(
           return Effect.succeed(Response.text(s, { status, contentType: encoding.contentType }))
         } catch {
           return Effect.fail(
-            new SchemaIssue.InvalidValue({ message: "Expected a JSON-serializable response body" })
+            new SchemaIssue.InvalidValue(
+              { expected: "a JSON-serializable response body" },
+              e,
+              options
+            )
           )
         }
       })

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
   }
 }
 
@@ -1002,41 +1065,59 @@ function getEncodePayloadSchemaFromBody(
   const out = $HttpBody.pipe(Schema.decodeTo(
     schema,
     SchemaTransformation.transformOrFail<unknown, HttpBody.HttpBody>({
-      decode() {
-        return Effect.fail(new SchemaIssue.Forbidden({ 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({ 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 {
               return Effect.fail(
-                new SchemaIssue.InvalidValue({ message: "Expected a JSON-serializable request body" })
+                new SchemaIssue.InvalidValue(
+                  { expected: "a JSON-serializable request body" },
+                  t,
+                  options
+                )
               )
             }
           }
           case "Text": {
             if (typeof t !== "string") {
               return Effect.fail(
-                new SchemaIssue.InvalidValue({ 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({ 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({ message: "Expected a Uint8Array" })
+                new SchemaIssue.InvalidValue(
+                  { message: "Expected a Uint8Array" },
+                  t,
+                  options
+                )
               )
             }
             return Effect.succeed(HttpBody.uint8Array(t, encoding.contentType))