Expose HttpApi.ParseOptions for schema decoding and encoding (#8269)

Author: tim-smart

.changeset/tidy-apis-parse.md

@@ -0,0 +1,11 @@
+---
+"effect": patch
+---
+
+Add `HttpApi.ParseOptions` to configure server and client codecs at the API, group, or endpoint level.
+
+`Sse.decodeSchema` and `ChannelSchema.decode` accept parse options, and `Schema.Cause` encodes reasons to their wire fields.
+
+SSE decoding omits absent IDs, including with default options. Use `Schema.optional(Schema.String)` instead of `Schema.UndefinedOr(Schema.String)` for IDs. With `onExcessProperty: "error"`, declare `event` (default: `"message"`) and any `id`, including inherited IDs.
+
+`HttpApiSchema.StreamSse` data-mode types and OpenAPI schemas now make `id` optional.

packages/effect/src/ChannelSchema.ts

@@ -12,6 +12,7 @@ import * as Channel from "./Channel.ts"
 import * as Effect from "./Effect.ts"
 import { dual } from "./Function.ts"
 import * as Schema from "./Schema.ts"
+import type * as SchemaAST from "./SchemaAST.ts"
 
 /**
  * Creates a channel that encodes non-empty chunks of schema values into the
@@ -96,7 +97,8 @@ export const encodeUnknown: <S extends Schema.Constraint>(
  * @since 4.0.0
  */
 export const decode = <S extends Schema.Constraint>(
-  schema: S
+  schema: S,
+  options?: SchemaAST.ParseOptions
 ) =>
 <IE = never, Done = unknown>(): Channel.Channel<
   Arr.NonEmptyReadonlyArray<S["Type"]>,
@@ -107,7 +109,7 @@ export const decode = <S extends Schema.Constraint>(
   Done,
   S["DecodingServices"]
 > => {
-  const decode = Schema.decodeEffect(Schema.NonEmptyArray(schema))
+  const decode = Schema.decodeEffect(Schema.NonEmptyArray(schema), options)
   return Channel.fromTransform((upstream, _scope) => Effect.succeed(Effect.flatMap(upstream, (chunk) => decode(chunk))))
 }
 
@@ -131,7 +133,8 @@ export const decode = <S extends Schema.Constraint>(
  * @since 4.0.0
  */
 export const decodeUnknown: <S extends Schema.Constraint>(
-  schema: S
+  schema: S,
+  options?: SchemaAST.ParseOptions
 ) => <IE = never, Done = unknown>() => Channel.Channel<
   Arr.NonEmptyReadonlyArray<S["Type"]>,
   IE | Schema.SchemaError,

packages/effect/src/Schema.ts

@@ -10550,7 +10550,16 @@ export function CauseReason<E extends Constraint, D extends Constraint>(
                   return Cause_.makeInterruptReason(e.fiberId)
               }
             },
-            encode: identity
+            encode: (reason) => {
+              switch (reason._tag) {
+                case "Fail":
+                  return { _tag: "Fail" as const, error: reason.error }
+                case "Die":
+                  return { _tag: "Die" as const, defect: reason.defect }
+                case "Interrupt":
+                  return { _tag: "Interrupt" as const, fiberId: reason.fiberId }
+              }
+            }
           })
         )
     }

packages/effect/src/unstable/encoding/Sse.ts

@@ -20,6 +20,7 @@ import { hasProperty } from "../../Predicate.ts"
 import * as Pull from "../../Pull.ts"
 import * as Result from "../../Result.ts"
 import * as Schema from "../../Schema.ts"
+import type * as SchemaAST from "../../SchemaAST.ts"
 import * as SchemaTransformation from "../../SchemaTransformation.ts"
 
 const SseErrorTypeId = "~effect/encoding/Sse/SseError"
@@ -166,8 +167,12 @@ export interface EventCodec extends
  *
  * **Details**
  *
- * The schema receives the untagged event shape containing `id`, `event`, and
- * string `data`.
+ * The schema receives `{ event, data, id? }`, with string `data`. Absent IDs are
+ * omitted, even with default options: use `Schema.optional(Schema.String)`, not
+ * `Schema.UndefinedOr(Schema.String)`, to accept events without an ID.
+ *
+ * With `onExcessProperty: "error"`, declare `event` (default: `"message"`) and
+ * `id` if the stream carries IDs, including inherited IDs.
  *
  * @category decoding
  * @since 4.0.0
@@ -178,7 +183,8 @@ export const decodeSchema = <
   Done
 >(
   schema: S,
-  options?: DecodeOptions
+  options?: DecodeOptions,
+  parseOptions?: SchemaAST.ParseOptions
 ): Channel.Channel<
   NonEmptyReadonlyArray<S["Type"]>,
   IE | Retry | SseError | Schema.SchemaError,
@@ -190,9 +196,12 @@ export const decodeSchema = <
 > =>
   Channel.pipeTo(
     decode<IE, Done>(options),
-    ChannelSchema.decode(EventEncoded.pipe(
-      Schema.decodeTo(schema)
-    ))()
+    ChannelSchema.decode(
+      Event.pipe(
+        Schema.decodeTo(schema, transformEvent)
+      ),
+      parseOptions
+    )()
   )
 
 /**
@@ -561,7 +570,10 @@ export const transformEvent = SchemaTransformation.transform<{
   readonly event: string
   readonly data: string
 }>({
-  decode: (event) => event,
+  decode: (event) =>
+    event.id === undefined
+      ? { event: event.event, data: event.data }
+      : { id: event.id, event: event.event, data: event.data },
   encode: (event) => ({
     _tag: "Event",
     id: event.id,

packages/effect/src/unstable/httpapi/HttpApi.ts

@@ -15,6 +15,7 @@ import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Record from "../../Record.ts"
 import type * as Schema from "../../Schema.ts"
+import type * as SchemaAST from "../../SchemaAST.ts"
 import type { PathInput } from "../http/HttpRouter.ts"
 import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
@@ -336,3 +337,24 @@ export class AdditionalSchemas extends Context.Service<
   AdditionalSchemas,
   ReadonlyArray<Schema.Constraint>
 >()("effect/httpapi/HttpApi/AdditionalSchemas") {}
+
+/**
+ * Schema parse options for server and client codecs, set on an API, group, or
+ * endpoint.
+ *
+ * **Details**
+ *
+ * Endpoint options override group options, which override API options. Objects
+ * are replaced, not merged. Without an annotation, Schema defaults apply.
+ *
+ * Header codecs receive all HTTP headers, so `onExcessProperty: "error"` rejects
+ * undeclared headers such as `content-type`. Annotate the API before passing it
+ * to `HttpApiBuilder.group` or `HttpApiBuilder.endpoint`.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export class ParseOptions extends Context.Service<
+  ParseOptions,
+  SchemaAST.ParseOptions
+>()("effect/httpapi/HttpApi/ParseOptions") {}

packages/effect/src/unstable/httpapi/HttpApiBuilder.ts

@@ -44,7 +44,7 @@ import * as Response from "../http/HttpServerResponse.ts"
 import type { HttpServerResponse } from "../http/HttpServerResponse.ts"
 import * as Multipart from "../http/Multipart.ts"
 import * as UrlParams from "../http/UrlParams.ts"
-import type * as HttpApi from "./HttpApi.ts"
+import * as HttpApi from "./HttpApi.ts"
 import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
 import { HttpApiSchemaError } from "./HttpApiError.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
@@ -151,7 +151,7 @@ export const group = <
       : result
     const routes: Array<HttpRouter.Route<any, any>> = []
     for (const item of handlers.handlers.values()) {
-      routes.push(handlerToRoute(group as any, item, services))
+      routes.push(handlerToRoute(api, group as any, item, services))
     }
     return Context.makeUnsafe(
       new Map([[group.key, {
@@ -509,6 +509,7 @@ export const endpoint = <
     const group = api.groups[groupIdentifier] as unknown as HttpApiGroup.Top
     const endpoint = group.endpoints[endpointIdentifier]
     return Effect.succeed(handlerToHttpEffect(
+      api,
       group,
       endpoint,
       Context.omit(Scope.Scope)(context),
@@ -721,11 +722,12 @@ type PayloadDecoder =
   }
 
 function buildPayloadDecoders(
-  payloadMap: HttpApiEndpoint.PayloadMap
+  payloadMap: HttpApiEndpoint.PayloadMap,
+  options: SchemaAST.ParseOptions | undefined
 ): Map<string, PayloadDecoder> {
   const result = new Map<string, PayloadDecoder>()
   payloadMap.forEach(({ encoding, schemas }, contentType) => {
-    const decode = Schema.decodeUnknownEffect(Schema.Union(schemas))
+    const decode = Schema.decodeUnknownEffect(Schema.Union(schemas), options)
     if (encoding._tag === "Multipart") {
       result.set(contentType, { _tag: "Multipart", mode: encoding.mode, limits: encoding.limits, decode })
     } else {
@@ -800,25 +802,29 @@ function decodePayload(
 }
 
 function handlerToHttpEffect(
+  api: Pick<HttpApi.Top, "annotations">,
   group: HttpApiGroup.Top,
   endpoint: HttpApiEndpoint.Top,
   context: Context.Context<any>,
   handler: HttpApiEndpoint.Handler<HttpApiEndpoint.Constraint, any, any>,
   isRaw: boolean
 ) {
-  const encodeSuccess = Schema.encodeUnknownEffect(makeSuccessSchema(endpoint))
-  const encodeError = Schema.encodeUnknownEffect(makeErrorSchema(endpoint))
-  const decodeParams = UndefinedOr.map(endpoint.params, Schema.decodeUnknownEffect)
-  const decodeHeaders = UndefinedOr.map(endpoint.headers, Schema.decodeUnknownEffect)
+  const annotations = Context.merge(Context.merge(api.annotations, group.annotations), endpoint.annotations)
+  const options = Context.getOrUndefined(annotations, HttpApi.ParseOptions)
+  const decodeUnknownEffect = <S extends Schema.Constraint>(schema: S) => Schema.decodeUnknownEffect(schema, options)
+  const encodeSuccess = Schema.encodeUnknownEffect(makeSuccessSchema(endpoint), options)
+  const encodeError = Schema.encodeUnknownEffect(makeErrorSchema(endpoint), options)
+  const decodeParams = UndefinedOr.map(endpoint.params, decodeUnknownEffect)
+  const decodeHeaders = UndefinedOr.map(endpoint.headers, decodeUnknownEffect)
   const decodeQuery = UndefinedOr.map(
     endpoint.query,
-    (schema) => Schema.decodeUnknownEffect(Schema.toCodecArrayFromSingle(schema))
+    (schema) => decodeUnknownEffect(Schema.toCodecArrayFromSingle(schema))
   )
-  const encodeStream = makeStreamEncoder(endpoint)
-  const encodeWithHeaders = makeWithHeadersEncoder(endpoint)
+  const encodeStream = makeStreamEncoder(endpoint, options)
+  const encodeWithHeaders = makeWithHeadersEncoder(endpoint, options)
 
   const shouldParsePayload = endpoint.payload.size > 0 && !isRaw
-  const payloadBy = shouldParsePayload ? buildPayloadDecoders(endpoint.payload) : undefined
+  const payloadBy = shouldParsePayload ? buildPayloadDecoders(endpoint.payload, options) : undefined
 
   return applyMiddleware(
     group,
@@ -886,6 +892,7 @@ function handlerToHttpEffect(
 
 /** @internal */
 export function handlerToRoute(
+  api: Pick<HttpApi.Top, "annotations">,
   group: HttpApiGroup.Top,
   handler: HandlerRuntime,
   context: Context.Context<any>
@@ -894,7 +901,7 @@ export function handlerToRoute(
   return HttpRouter.route(
     endpoint.method,
     HttpApiPath.toRouterPath(endpoint.path, endpoint.params) as HttpRouter.PathInput,
-    handlerToHttpEffect(group, endpoint, context, handler.handler, handler.isRaw),
+    handlerToHttpEffect(api, group, endpoint, context, handler.handler, handler.isRaw),
     { uninterruptible: handler.uninterruptible }
   )
 }
@@ -992,12 +999,15 @@ interface WithHeadersEncoders {
   readonly encodeHeaders: ReadonlyMap<number, WithHeadersEncoder>
 }
 
-function makeWithHeadersEncoder(endpoint: HttpApiEndpoint.Top): WithHeadersEncoders | undefined {
+function makeWithHeadersEncoder(
+  endpoint: HttpApiEndpoint.Top,
+  options: SchemaAST.ParseOptions | undefined
+): 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))
+    encodeHeaders.set(HttpApiSchema.getStatusSuccessSchema(schema), Schema.encodeUnknownEffect(schema.headers, options))
     if (!HttpApiSchema.isStreamSchema(schema.schema)) {
       bodySchemas.push(toResponseSuccessSchema(schema))
     }
@@ -1011,12 +1021,15 @@ function makeWithHeadersEncoder(endpoint: HttpApiEndpoint.Top): WithHeadersEncod
     ? bodySchemas[0]
     : Schema.Union(bodySchemas)
   return {
-    encodeBody: Schema.encodeUnknownEffect(bodySchema),
+    encodeBody: Schema.encodeUnknownEffect(bodySchema, options),
     encodeHeaders
   }
 }
 
-function makeStreamEncoder(endpoint: HttpApiEndpoint.Top): StreamEncoder | undefined {
+function makeStreamEncoder(
+  endpoint: HttpApiEndpoint.Top,
+  options: SchemaAST.ParseOptions | undefined
+): StreamEncoder | undefined {
   const successSchema = getStreamSuccessSchema(endpoint)
   if (successSchema === undefined) {
     return undefined
@@ -1045,7 +1058,7 @@ function makeStreamEncoder(endpoint: HttpApiEndpoint.Top): StreamEncoder | undef
     }
   }
 
-  const sseEncoder = makeSseEncoder(streamSchema)
+  const sseEncoder = makeSseEncoder(streamSchema, options)
 
   return (response, context) => {
     if (!Stream.isStream(response)) {
@@ -1090,13 +1103,14 @@ interface SseStreamEncoder {
 }
 
 function makeSseEncoder<Events extends Sse.EventCodec, Error extends Schema.Constraint>(
-  streamSchema: HttpApiSchema.StreamSse<Events, Error, unknown>
+  streamSchema: HttpApiSchema.StreamSse<Events, Error, unknown>,
+  options: SchemaAST.ParseOptions | undefined
 ): SseStreamEncoder {
   const CauseSchema = Schema.toCodecJson(Schema.Cause(streamSchema.error, Schema.Defect()))
   return {
     sseMode: streamSchema.sseMode,
-    encodeEvents: Schema.encodeUnknownEffect(Schema.Array(streamSchema.events)) as any,
-    encodeCause: Schema.encodeUnknownEffect(Schema.fromJsonString(CauseSchema))
+    encodeEvents: Schema.encodeUnknownEffect(Schema.Array(streamSchema.events), options) as any,
+    encodeCause: Schema.encodeUnknownEffect(Schema.fromJsonString(CauseSchema), options)
   }
 }