effect 4.0.7 → 4.1.0

package/src/http-api/HttpApiError.ts

@@ -11,13 +11,16 @@
  * @since 4.0.0
  */
 import type * as ByteSize from "../ByteSize.ts"
+import type * as Cause from "../Cause.ts"
 import * as Data from "../Data.ts"
 import * as Effect from "../Effect.ts"
 import * as ErrorReporter from "../ErrorReporter.ts"
 import * as HttpServerRespondable from "../http/HttpServerRespondable.ts"
 import * as HttpServerResponse from "../http/HttpServerResponse.ts"
+import * as ProblemDetails from "../http/ProblemDetails.ts"
 import { hasProperty } from "../Predicate.ts"
 import * as Schema from "../Schema.ts"
+import type { Simplify } from "../Struct.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
 
 const badRequestResponse = HttpServerResponse.empty({ status: 400 })
@@ -449,6 +452,253 @@ export const ServiceUnavailableNoContent = ServiceUnavailable.pipe(HttpApiSchema
   decode: () => new ServiceUnavailable({})
 }))
 
+/**
+ * The constant members of a typed problem declaration.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface ProblemDeclaration<Type extends string, Status extends number> {
+  /**
+   * The problem type URI. It is the discriminator between problem classes that
+   * share a status.
+   */
+  readonly type: Type
+  /**
+   * The HTTP status of the response.
+   */
+  readonly status: Status
+  /**
+   * The short human-readable summary of the problem type.
+   */
+  readonly title: string
+}
+
+/**
+ * The standard problem members of a typed problem class.
+ *
+ * **Details**
+ *
+ * `type`, `status` and `title` are fixed by the declaration and are constructor
+ * defaults that are always encoded. `type` is the discriminator: a body with a
+ * different `type` is rejected. `status` and `title` decode to the declared
+ * value whatever the body carries, so the HTTP status stays authoritative.
+ * `detail` and `instance` are optional per-instance members that declared
+ * fields may replace.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface ProblemMembers<Type extends string, Status extends number> {
+  readonly type: Schema.tag<Type>
+  readonly status: FixedMember<Status>
+  readonly title: FixedMember<string>
+  readonly detail: OptionalMember<Schema.String>
+  readonly instance: OptionalMember<Schema.String>
+}
+
+type FixedMember<L extends string | number> = Schema.middlewareDecoding<
+  Schema.withDecodingDefaultKey<Schema.tag<L>>,
+  never
+>
+
+type OptionalMember<S extends Schema.Constraint> = Schema.middlewareDecoding<Schema.optionalKey<S>, never>
+
+/**
+ * The fields of a typed problem class: the standard members plus the declared
+ * extension fields.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export type ProblemFields<Type extends string, Status extends number, Fields extends Schema.Struct.Fields> = Simplify<
+  Omit<ProblemMembers<Type, Status>, keyof Fields> & Fields
+>
+
+/**
+ * The extension fields a typed problem may declare. The fixed members `type`,
+ * `status` and `title` are reserved.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export type ProblemExtensionFields = Schema.Struct.Fields & {
+  readonly type?: never
+  readonly status?: never
+  readonly title?: never
+}
+
+const problemEncoding: HttpApiSchema.ResponseEncoding = { _tag: "Json", contentType: ProblemDetails.contentType }
+
+/**
+ * The class returned by {@link Problem}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface ProblemClass<
+  Self,
+  Tag extends string,
+  Type extends string,
+  Status extends number,
+  Fields extends Schema.Struct.Fields,
+  Brand
+> extends
+  Schema.Class<
+    Self,
+    Schema.Struct<ProblemFields<Type, Status, Fields>>,
+    Cause.YieldableError & HttpServerRespondable.Respondable & Brand & { readonly _tag: Tag }
+  >
+{}
+
+type MissingSelfGeneric = "Missing `Self` generic - use `class Self extends HttpApiError.Problem<Self>()(...)`"
+
+/**
+ * Declares a typed RFC 9457 problem as a yieldable error class.
+ *
+ * **Details**
+ *
+ * The class is a `Schema.Error` whose `_tag` is the given tag, so `Effect.catchTag`
+ * works without `_tag` on the wire. It carries the `httpApiStatus` and
+ * `application/problem+json` annotations, so endpoints that declare it as an
+ * error render, document and decode it as a problem. Problem classes that
+ * share a status are told apart by `type`. The extension fields are validated
+ * on both sides and cannot replace `type`, `status` or `title`; unknown
+ * extensions are not kept. An undeclared instance still renders as a problem
+ * through `HttpServerRespondable`.
+ *
+ * **Example** (Declaring and using a typed problem)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { HttpApiEndpoint, HttpApiError } from "effect/http-api"
+ *
+ * class OutOfCredit extends HttpApiError.Problem<OutOfCredit>()("OutOfCredit", {
+ *   type: "https://example.com/probs/out-of-credit",
+ *   status: 403,
+ *   title: "You do not have enough credit."
+ * }, {
+ *   balance: Schema.Number
+ * }) {}
+ *
+ * const buy = HttpApiEndpoint.post("buy", "/buy", { error: OutOfCredit })
+ *
+ * const failing = Effect.fail(new OutOfCredit({ balance: 30 }))
+ * // Responds with 403 and { "type": "https://example.com/probs/out-of-credit",
+ * //   "status": 403, "title": "You do not have enough credit.", "balance": 30 }
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const Problem = <Self = never, Brand = {}>() =>
+<
+  const Tag extends string,
+  const Type extends string,
+  const Status extends number,
+  const Fields extends ProblemExtensionFields = {}
+>(
+  tag: Tag,
+  declaration: ProblemDeclaration<Type, Status>,
+  fields?: Fields,
+  annotations?: Schema.Annotations.Declaration<Self, readonly [Schema.Struct<ProblemFields<Type, Status, Fields>>]>
+): [Self] extends [never] ? MissingSelfGeneric
+  : ProblemClass<Self, Tag, Type, Status, Fields, Brand> =>
+{
+  const struct = Schema.Struct({
+    detail: ProblemDetails.optionalMember(Schema.String),
+    instance: ProblemDetails.optionalMember(Schema.String),
+    ...fields,
+    type: Schema.tag(declaration.type),
+    status: ProblemDetails.fixedMember(declaration.status),
+    title: ProblemDetails.fixedMember(declaration.title)
+  })
+  const encode = Schema.encodeUnknownEffect(struct)
+  const Base = Schema.Error<any, {}>(tag)(struct, {
+    description: declaration.title,
+    httpApiStatus: declaration.status,
+    "~httpApiEncoding": problemEncoding,
+    ...annotations as {}
+  })
+  Object.assign(Base.prototype, {
+    _tag: tag,
+    [ErrorReporter.ignore]: declaration.status < 500,
+    [HttpServerRespondable.symbol](this: object) {
+      return Effect.map(
+        encode(this),
+        (body) =>
+          HttpServerResponse.jsonUnsafe(body, { status: declaration.status, contentType: ProblemDetails.contentType })
+      )
+    }
+  })
+  Object.defineProperty(Base.prototype, "message", {
+    get(this: { readonly detail?: string }) {
+      return this.detail ?? declaration.title
+    },
+    configurable: true
+  })
+  return Base as any
+}
+
+/**
+ * One entry of `BadRequestProblem.errors`: the location of a request value
+ * that failed decoding and the reason.
+ *
+ * **Details**
+ *
+ * The first path segment names the request slot (`params`, `headers`, `query`
+ * or `payload`).
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const ProblemIssue = Schema.Struct({
+  path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
+  message: Schema.String
+})
+
+/**
+ * The problem rendered by `HttpApiMiddleware.layerProblemDetails` when a
+ * request fails decoding.
+ *
+ * **Details**
+ *
+ * The body is generic by default. `errors` is only filled when the layer is
+ * built with `includeDetails: true`.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.6
+ */
+export class BadRequestProblem extends Problem<BadRequestProblem>()("BadRequestProblem", {
+  type: ProblemDetails.blankType,
+  status: 400,
+  title: "Bad Request"
+}, {
+  errors: Schema.optionalKey(Schema.Array(ProblemIssue))
+}) {}
+
+/**
+ * The problem rendered by `HttpApiMiddleware.layerProblemDetails` when a
+ * response fails encoding.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.6
+ */
+export class InternalServerErrorProblem extends Problem<InternalServerErrorProblem>()("InternalServerErrorProblem", {
+  type: ProblemDetails.blankType,
+  status: 500,
+  title: "Internal Server Error"
+}) {}
+
 /**
  * Type-level identifier used to mark `HttpApiSchemaError` values.
  *

package/src/http-api/HttpApiMiddleware.ts

@@ -14,21 +14,25 @@
  */
 /** @effect-diagnostics floatingEffect:skip-file */
 /** @effect-diagnostics classSelfMismatch:off */
+import * as Cause from "../Cause.ts"
 import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
+import * as ErrorReporter from "../ErrorReporter.ts"
 import type * as HttpClientError from "../http/HttpClientError.ts"
 import type * as HttpClientRequest from "../http/HttpClientRequest.ts"
 import type * as HttpClientResponse from "../http/HttpClientResponse.ts"
 import type * as HttpRouter from "../http/HttpRouter.ts"
+import * as HttpServerRespondable from "../http/HttpServerRespondable.ts"
 import type { HttpServerResponse } from "../http/HttpServerResponse.ts"
 import { getStackTraceLimit, setStackTraceLimit } from "../internal/stackTraceLimit.ts"
 import * as Layer from "../Layer.ts"
 import { hasProperty } from "../Predicate.ts"
 import type * as Schema from "../Schema.ts"
+import * as SchemaIssue from "../SchemaIssue.ts"
 import { Scope } from "../Scope.ts"
 import type { unhandled } from "../Types.ts"
 import type * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
-import { HttpApiSchemaError } from "./HttpApiError.ts"
+import { BadRequestProblem, HttpApiSchemaError, InternalServerErrorProblem } from "./HttpApiError.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import type * as HttpApiSecurity from "./HttpApiSecurity.ts"
 
@@ -513,6 +517,96 @@ export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Require
       )
   )
 
+/**
+ * Middleware that renders request decoding and response encoding failures as
+ * RFC 9457 problems.
+ *
+ * **Details**
+ *
+ * It declares `HttpApiError.BadRequestProblem` at 400 and
+ * `HttpApiError.InternalServerErrorProblem` at 500, so the OpenAPI document and
+ * generated clients of an API using it know both responses. Provide it with
+ * {@link layerProblemDetails}.
+ *
+ * **Example** (Opting in to problem details)
+ *
+ * ```ts
+ * import { Layer, Schema } from "effect"
+ * import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api"
+ *
+ * const Users = HttpApiGroup.make("users").add(
+ *   HttpApiEndpoint.get("list", "/users", { query: { page: Schema.Number } })
+ * )
+ * const Api = HttpApi.make("api").add(Users).middleware(HttpApiMiddleware.ProblemDetails)
+ *
+ * // A request whose query fails decoding now responds with 400 and
+ * // { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Request validation failed" }
+ * const ServerLive = HttpApiBuilder.layer(Api).pipe(
+ *   Layer.provide(HttpApiMiddleware.layerProblemDetails())
+ * )
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.6
+ */
+export class ProblemDetails extends Service<ProblemDetails>()("effect/http-api/HttpApiMiddleware/ProblemDetails", {
+  error: [BadRequestProblem, InternalServerErrorProblem]
+}) {}
+
+const formatIssues = SchemaIssue.makeFormatterStandardSchemaV1()
+
+const toPathSegment = (segment: PropertyKey | { readonly key: PropertyKey }): string | number => {
+  const key = typeof segment === "object" ? segment.key : segment
+  return typeof key === "number" ? key : String(key)
+}
+
+const toProblemIssues = (error: HttpApiSchemaError) => {
+  const slot = error.kind.toLowerCase()
+  return formatIssues(error.cause.issue).issues.map((issue) => ({
+    path: [slot, ...(issue.path ?? []).map(toPathSegment)],
+    message: issue.message
+  }))
+}
+
+/**
+ * Provides the {@link ProblemDetails} middleware.
+ *
+ * **Details**
+ *
+ * A request decoding failure becomes a `400` problem with a generic `detail`
+ * and no information about the request or the schema. With
+ * `includeDetails: true` the problem also carries `errors`, one entry per
+ * issue with the path of the offending value prefixed by its request slot and
+ * the issue message. A response encoding failure is reported to the configured
+ * error reporters, as it is without the middleware, and becomes a `500`
+ * problem with no detail.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.6
+ */
+export const layerProblemDetails = (options?: {
+  readonly includeDetails?: boolean | undefined
+}): Layer.Layer<ProblemDetails> => {
+  const includeDetails = options?.includeDetails === true
+  return layerSchemaErrorTransform(ProblemDetails, (error) => {
+    if (error.kind === "Body" || error.kind === "ResponseHeaders") {
+      return Effect.andThen(
+        ErrorReporter.report(Cause.fail(error)),
+        HttpServerRespondable.toResponse(new InternalServerErrorProblem())
+      )
+    }
+    return Effect.fail(
+      new BadRequestProblem(
+        includeDetails ? { ...requestValidationFailed, errors: toProblemIssues(error) } : requestValidationFailed
+      )
+    )
+  })
+}
+
+const requestValidationFailed = { detail: "Request validation failed" }
+
 /**
  * Provides a client-side middleware implementation for a middleware that is required by generated clients.
  *

package/src/http-api/HttpApiSchema.ts

@@ -17,6 +17,7 @@ import { constVoid, type LazyArg } from "../Function.ts"
 import { hasBody, type HttpMethod } from "../http/HttpMethod.ts"
 import * as HttpStatus from "../http/HttpStatus.ts"
 import type * as Multipart_ from "../http/Multipart.ts"
+import * as ProblemDetails from "../http/ProblemDetails.ts"
 import * as Predicate from "../Predicate.ts"
 import * as Schema from "../Schema.ts"
 import * as SchemaAST from "../SchemaAST.ts"
@@ -264,6 +265,85 @@ export function asNoContent<S extends Schema.Constraint>(options: {
   }
 }
 
+/**
+ * Schema type returned by `asProblem`, encoding as a problem details body
+ * while decoding to the original schema type.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export interface asProblem<S extends Schema.Constraint> extends
+  Schema.decodeTo<
+    Schema.toType<S>,
+    Schema.Struct<{
+      readonly type: Schema.tag<string>
+      readonly status: Schema.middlewareDecoding<Schema.withDecodingDefaultKey<Schema.tag<number>>, never>
+      readonly title: Schema.middlewareDecoding<Schema.withDecodingDefaultKey<Schema.tag<string>>, never>
+    }>
+  >
+{}
+
+/**
+ * Renders an error class as an RFC 9457 problem.
+ *
+ * **Details**
+ *
+ * The server encodes the error as an `application/problem+json` body carrying
+ * `type`, `title` and the status of the class. Generated clients decode a body
+ * with the same `type` back into an instance by calling `decode`, which
+ * defaults to constructing the class without arguments; a body with a
+ * different `type` is rejected.
+ *
+ * **Example** (A built-in error as a problem)
+ *
+ * ```ts
+ * import { HttpApiEndpoint, HttpApiError, HttpApiSchema } from "effect/http-api"
+ *
+ * const user = HttpApiEndpoint.get("user", "/user", {
+ *   error: HttpApiError.NotFound.pipe(HttpApiSchema.asProblem({ title: "Not Found" }))
+ * })
+ * // A NotFound failure responds with 404 and
+ * // { "type": "about:blank", "title": "Not Found", "status": 404 }
+ * ```
+ *
+ * @see {@link asNoContent} for the empty-body equivalent.
+ *
+ * @stability unstable
+ * @category encoding
+ * @since 4.0.6
+ */
+export function asProblem<S extends Schema.Constraint & (new() => S["Type"])>(options: {
+  /**
+   * The problem type URI. Defaults to `about:blank`.
+   */
+  readonly type?: string | undefined
+  readonly title: string
+  readonly decode?: LazyArg<S["Type"]> | undefined
+}) {
+  return (self: S): asProblem<S> => {
+    const status = getStatusError(self.ast)
+    const type = options.type ?? ProblemDetails.blankType
+    const body = { type, status, title: options.title }
+    const decode = options.decode ?? (() => new self())
+    const problem = Schema.Struct({
+      type: Schema.tag(type),
+      status: ProblemDetails.fixedMember(status),
+      title: ProblemDetails.fixedMember(options.title)
+    })
+    return problem.pipe(
+      Schema.decodeTo(
+        Schema.toType(self),
+        SchemaTransformation.transform({
+          decode,
+          encode: () => body
+        })
+      ),
+      asJson({ contentType: ProblemDetails.contentType })
+    )
+  }
+}
+
 type StreamMode = "sse" | "uint8array" | "ndjson"
 
 /**
@@ -678,10 +758,9 @@ const upgradeSchema = Schema.declare(Socket.isSocket).pipe(status(101))
  *
  * **When to use**
  *
- * Use as the only success schema of an endpoint that hands over its
- * connection as a raw byte stream after `101 Switching Protocols`. For
- * WebSocket, upgrade the request with `HttpServerRequest.upgrade` and
- * connect with `Socket.makeWebSocket` instead.
+ * Use when an endpoint hands over its connection as a raw byte stream after
+ * `101 Switching Protocols`. For WebSocket, upgrade the request with
+ * `HttpServerRequest.upgrade` and connect with `Socket.makeWebSocket` instead.
  *
  * **Details**
  *
@@ -698,9 +777,17 @@ const upgradeSchema = Schema.declare(Socket.isSocket).pipe(status(101))
  * The endpoint may declare a buffered payload, which is decoded before the
  * handler runs. Streaming payloads are rejected.
  *
+ * The endpoint may also declare buffered or no-content successes at statuses
+ * other than `101`, for a server that declines the upgrade (RFC 9110 §7.8).
+ * The handler then either calls `upgrade` and returns nothing, or returns one
+ * of those successes without calling it. An endpoint declares at most one
+ * upgrade, and streaming successes cannot be combined with it.
+ *
  * The client sends `Connection: Upgrade` and `Upgrade: protocol`, and returns
  * the response headers with the connection, decoded with `headers` when
- * declared. Other responses are decoded as the endpoint's errors.
+ * declared. Ordinary success responses are decoded as usual, and
+ * `HttpApiClient.isUpgraded` tells the two apart. Other responses are decoded
+ * as the endpoint's errors.
  *
  * **Example** (Declaring an exec start endpoint)
  *
@@ -711,15 +798,19 @@ const upgradeSchema = Schema.declare(Socket.isSocket).pipe(status(101))
  * const start = HttpApiEndpoint.post("start", "/exec/:id/start", {
  *   params: { id: Schema.String },
  *   payload: Schema.Struct({ Detach: Schema.Boolean, Tty: Schema.Boolean }),
- *   success: HttpApiSchema.Upgrade({
- *     protocol: "tcp",
- *     headers: {
- *       "content-type": Schema.Literals([
- *         "application/vnd.docker.raw-stream",
- *         "application/vnd.docker.multiplexed-stream"
- *       ])
- *     }
- *   })
+ *   success: [
+ *     HttpApiSchema.Upgrade({
+ *       protocol: "tcp",
+ *       headers: {
+ *         "content-type": Schema.Literals([
+ *           "application/vnd.docker.raw-stream",
+ *           "application/vnd.docker.multiplexed-stream"
+ *         ])
+ *       }
+ *     }),
+ *     // a detached exec answers with an empty 200 instead
+ *     HttpApiSchema.Empty(200)
+ *   ]
  * })
  * ```
  *

package/src/index.ts

@@ -164,12 +164,6 @@ export * as Context from "./Context.ts"
  */
 export * as Cron from "./Cron.ts"
 
-/**
- * @stability unstable
- * @since 4.0.0
- */
-export * as Crypto from "./Crypto.ts"
-
 /**
  * @stability stable
  * @since 2.0.0
@@ -290,6 +284,12 @@ export * as Formatter from "./Formatter.ts"
  */
 export * as Function from "./Function.ts"
 
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as Glob from "./Glob.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0