effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/http/HttpRouter.ts

@@ -1,20 +1,43 @@
 /**
- * Layer-based server-side HTTP routing for Effect applications.
- *
- * This module provides the `HttpRouter` service and helpers for registering
- * method/path handlers, grouping routes under prefixes, decoding request
- * schemas from route and search parameters, and turning an application layer
- * into an `HttpServer` or Fetch-compatible handler. It is intended for HTTP
- * APIs, webhooks, and other server endpoints that want request-scoped services
- * and typed middleware to be composed through `Layer`.
- *
- * Route paths must be absolute paths beginning with `/`, or the wildcard `*`.
- * Prefixed routes remove the matched prefix from the request URL seen by the
- * handler, `HEAD` requests fall back to matching `GET` routes, and wildcard
- * paths ending in `/*` also match the prefix path itself. Use router middleware
- * when you need to provide request dependencies, handle configured route errors,
- * or modify route responses; server middleware wraps the wider server chain and
- * is not the right hook for changing the final response body or headers.
+ * Layer-based server-side routing for Effect HTTP applications.
+ *
+ * `HttpRouter` collects routes and router middleware while an application layer
+ * is being built, then exposes the registered route table as an
+ * `HttpServerResponse` effect for each incoming `HttpServerRequest`. Use it for
+ * APIs, webhooks, and Fetch handlers that want request-scoped services, schema
+ * decoding, and typed middleware to participate in the same `Layer` graph as
+ * the rest of the application.
+ *
+ * **Mental model**
+ *
+ * Route layers do not handle requests immediately. They register `Route` values
+ * into the current `HttpRouter`; `serve`, `toHttpEffect`, and `toWebHandler`
+ * build the layer, read the completed router, and run the matching handler for
+ * each request. During a request, the router provides `HttpServerRequest`,
+ * `Scope`, parsed search parameters, and `RouteContext`, so handlers can decode
+ * path, search, and body data or access services supplied by router middleware.
+ *
+ * **Common tasks**
+ *
+ * - Register individual routes with `add` or batches with `addAll`.
+ * - Group routes under a prefix with `addAll(..., { prefix })` or
+ *   `router.prefixed`.
+ * - Decode route, search, and JSON body data with `schemaPathParams`,
+ *   `schemaParams`, `schemaNoBody`, and `schemaJson`.
+ * - Apply route-scoped middleware with `middleware(...).layer`, or install
+ *   global router middleware for all routes.
+ * - Serve the layer with `serve` or create a Fetch-compatible handler with
+ *   `toWebHandler`.
+ *
+ * **Gotchas**
+ *
+ * Paths must be absolute `/` paths or the wildcard `*`. `HEAD` falls back to
+ * `GET`, and wildcard paths ending in `/*` also match the prefix path itself.
+ * For prefixed routes the matched prefix is removed from
+ * `HttpServerRequest.url` before the handler sees it. Middleware passed to
+ * `serve` wraps the wider server chain; use router middleware when you need to
+ * provide request dependencies, handle configured route errors, or change the
+ * response that will be sent.
  *
  * @since 4.0.0
  */
@@ -447,7 +470,7 @@ export const schemaPathParams = <A, I extends Readonly<Record<string, string | u
  *
  * **When to use**
  *
- * Use it to register routes or middleware with the router during layer
+ * Use when you use it to register routes or middleware with the router during layer
  * construction.
  *
  * **Example** (Registering routes during layer construction)

package/src/unstable/http/HttpServer.ts

@@ -1,21 +1,34 @@
 /**
- * Service and helpers for running Effect HTTP applications on a concrete server
- * runtime.
- *
- * This module defines the `HttpServer` service tag used by platform integrations
- * to expose a listening server, plus accessors for serving an
- * `HttpServerResponse` effect, formatting and logging server addresses, and
- * building test clients against a running server. It is intended for low-level
- * server runtimes, router integrations, HTTP API tests, and applications that
- * need to start serving from a provided `Layer`.
- *
- * The server supplies `HttpServerRequest` for each request, so application
- * effects should rely on the server for request-scoped data while still
- * providing their other services through the surrounding environment. `serve`
- * returns a `Layer` whose listener lifetime is managed by the layer scope; use
- * `serveEffect` when composing directly in an effect with an explicit `Scope`.
- * Test clients only support TCP addresses, and rewrite `0.0.0.0` to
- * `127.0.0.1` for local requests.
+ * Runtime boundary for serving Effect HTTP responses on a concrete HTTP server.
+ *
+ * `HttpServer` is the service implemented by platform adapters and consumed by
+ * routers, API layers, tests, and applications that start serving from a
+ * `Layer`. It exposes the listening address and a `serve` operation that runs
+ * an `HttpServerResponse` effect for each incoming request.
+ *
+ * **Mental model**
+ *
+ * The server owns the listener and supplies `HttpServerRequest` for every
+ * request. The application effect only describes how to produce a response, so
+ * request-scoped data comes from the server while the rest of the environment is
+ * still provided by the surrounding layer graph. `serve` ties listener lifetime
+ * to a layer scope, and `serveEffect` performs the same work inside an explicit
+ * `Scope`.
+ *
+ * **Common tasks**
+ *
+ * - Build a server service from a platform adapter with `make`.
+ * - Serve an HTTP app with `serve` or `serveEffect`.
+ * - Format or log the listening address with `formatAddress`,
+ *   `addressFormattedWith`, `logAddress`, or `withLogAddress`.
+ * - Create a test client that targets the running server with `makeTestClient`
+ *   or `layerTestClient`.
+ *
+ * **Gotchas**
+ *
+ * Middleware is applied at the server boundary, after the server has supplied
+ * the request service. Test clients only support TCP addresses, and rewrite
+ * `0.0.0.0` to `127.0.0.1` for local requests.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerError.ts

@@ -1,23 +1,36 @@
 /**
- * Error types and response conversion helpers used by the HTTP server runtime.
- *
- * This module models the failure cases that can happen around a server request:
- * malformed or unreadable requests, unmatched routes, unexpected handler
- * failures, response construction or delivery failures, and lower-level server
- * implementation failures. These errors keep the relevant request, and for
- * response failures the response that was being produced, so applications can
- * report, inspect, or translate failures without losing HTTP context.
- *
- * Most users encounter these errors when decoding request bodies, implementing
- * fallback routes, adding error reporting, or customizing how handler failures
- * become responses. Request parse errors become `400` responses, missing routes
- * become `404` responses and are ignored by the error reporter, and internal or
- * response errors become `500` responses. A `ResponseError` records the response
- * involved in the failure, but its default conversion intentionally sends an
- * empty `500` instead of reusing a response that may already be invalid or
- * partially failed. Handler causes can also contain respondable failures,
- * response defects, or interrupts; the conversion helpers preserve those
- * distinctions, including `499` for client aborts and `503` for server aborts.
+ * Error model used by the unstable HTTP server runtime.
+ *
+ * This module defines the tagged failures that can occur while a server accepts
+ * a request, matches a route, runs a handler, or builds and sends a response.
+ * Request-scoped failures keep the request that caused them, and response
+ * failures keep the response that was being produced, so applications can log,
+ * report, or translate failures without reconstructing HTTP context.
+ *
+ * **Mental model**
+ *
+ * {@link HttpServerError} wraps a concrete {@link HttpServerErrorReason}.
+ * {@link RequestParseError}, {@link RouteNotFound}, and {@link InternalError}
+ * describe failures before or during request handling, while
+ * {@link ResponseError} describes a failure tied to a response that was already
+ * being built or sent. {@link ServeError} represents lower-level server
+ * implementation failures outside an individual handler response.
+ *
+ * **Common tasks**
+ *
+ * Use {@link isHttpServerError} to refine unknown failures, inspect `request`
+ * and `response` when reporting failures, and use {@link causeResponse} or
+ * {@link exitResponse} when a handler cause or exit must be translated into the
+ * HTTP response sent to the client.
+ *
+ * **Gotchas**
+ *
+ * The default response mapping is intentionally small: request parse errors
+ * become `400`, route misses become ignored `404` failures, internal and
+ * response errors become `500`, client aborts marked with {@link ClientAbort}
+ * become `499`, and server-side interrupts become `503`. A
+ * {@link ResponseError} does not reuse the failed response when converted; it
+ * produces an empty `500` because that response may be invalid or partly sent.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerRequest.ts

@@ -1,20 +1,37 @@
 /**
- * Utilities for working with the request visible to HTTP server handlers.
+ * Server-side access to the current incoming HTTP request.
  *
- * This module defines `HttpServerRequest`, the request-scoped context service
- * used by server effects, middleware, schema decoders, multipart parsers,
- * WebSocket upgrades, and conversions between Effect HTTP requests, client
- * requests, and Web `Request` values. Handlers commonly use it to inspect the
- * method, URL, headers, cookies, remote address, and body, or to decode those
- * parts with schemas instead of parsing raw values by hand.
+ * This module defines the `HttpServerRequest` context service used by HTTP
+ * handlers, middleware, schema decoders, multipart parsers, WebSocket upgrades,
+ * and adapters. A request value carries the method, URL, original URL, headers,
+ * cookies, remote address, body stream, and platform source object, plus helpers
+ * for converting to and from Effect client requests and Web `Request` values.
  *
- * Body access is effectful because reading, parsing, schema decoding, or
- * multipart persistence can fail. Streaming request bodies may be single-use
- * depending on the underlying platform, while cached accessors such as text,
- * JSON, URL parameters, array buffers, and persisted multipart data reuse the
- * first read. Multipart persistence also requires `Scope`, `FileSystem`, and
- * `Path` services, and search parameter decoding depends on the
- * `ParsedSearchParams` service being provided by the router or adapter.
+ * **Mental model**
+ *
+ * Server handlers read the current request from context. Metadata such as the
+ * method, URL, headers, and cookies is available directly, while body access is
+ * effectful because reading, parsing, schema decoding, or multipart persistence
+ * can fail. Schema helpers decode cookies, headers, search parameters, JSON
+ * bodies, URL-encoded bodies, multipart bodies, and form JSON without each
+ * handler needing to parse raw values by hand.
+ *
+ * **Common tasks**
+ *
+ * - Inspect request metadata or derive a modified request view.
+ * - Decode cookies, headers, search parameters, or body content with schemas.
+ * - Upgrade a request to a WebSocket channel.
+ * - Convert between server requests, client requests, and Web `Request` values.
+ *
+ * **Gotchas**
+ *
+ * Streaming request bodies may be single-use depending on the underlying
+ * platform. Cached accessors such as text, JSON, URL parameters, array buffers,
+ * and persisted multipart data reuse the first read. Multipart persistence
+ * requires `Scope`, `FileSystem`, and `Path` services. Search parameter decoding
+ * depends on the `ParsedSearchParams` service being provided by the router or
+ * adapter, and body size limits are controlled through the re-exported
+ * `MaxBodySize` fiber reference.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerRespondable.ts

@@ -1,20 +1,34 @@
 /**
- * Protocol and conversion helpers for values that can become HTTP server
- * responses.
+ * Protocol for values that can render themselves as HTTP server responses.
  *
  * This module lets server-side domain errors, HTTP API errors, and helper
- * modules describe how they should be sent to a client without constructing an
- * `HttpServerResponse` at every call site. Implement `Respondable` on values
- * that should choose their own status, headers, cookies, or body when a route
- * fails or a server helper recovers by sending a response.
- *
- * Conversion is intentionally conservative. Existing `HttpServerResponse`
- * values are returned directly, fallback conversion maps schema errors to `400`
- * and no-such-element errors to `404`, and otherwise uses the caller-provided
- * fallback. Errors raised while running a respondable conversion become defects
- * with `toResponse`, while the fallback helpers catch conversion failures and
- * use the fallback response. Defect conversion only gives special handling to
- * `HttpServerResponse` and `Respondable` values.
+ * values describe the response they should send to a client. Implement
+ * `Respondable` when a value should choose its own status, headers, cookies, or
+ * body during route error handling without forcing every call site to construct
+ * an `HttpServerResponse` directly.
+ *
+ * **Mental model**
+ *
+ * A respondable value owns the last step from domain-level information to an
+ * `HttpServerResponse`. Server error handling can ask the value for a response,
+ * while unknown failures still go through a caller-provided fallback response.
+ * Existing `HttpServerResponse` values are already respondable for conversion
+ * purposes and are returned directly.
+ *
+ * **Common tasks**
+ *
+ * Use `toResponse` when the value is known to implement the protocol and
+ * conversion failures should become defects. Use `toResponseOrElse` when
+ * handling unknown failures from route effects and a fallback response should be
+ * used when no conversion is available. Use `toResponseOrElseDefect` for defect
+ * recovery, where only explicit response-like values receive special handling.
+ *
+ * **Gotchas**
+ *
+ * Fallback conversion is intentionally conservative. Schema errors become `400`
+ * responses, no-such-element errors become `404` responses, and other values use
+ * the supplied fallback. The fallback helpers also catch failures raised while
+ * running a respondable conversion; `toResponse` does not.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerResponse.ts

@@ -1,23 +1,45 @@
 /**
- * Server-side HTTP response values and constructors for Effect HTTP handlers.
- *
- * This module defines `HttpServerResponse`, the immutable response model returned
- * from routers and server effects, together with constructors for empty,
- * redirect, text, HTML, JSON, URL-encoded, raw, form-data, stream, and file
- * bodies. It also includes combinators for adjusting status, headers, cookies,
- * and bodies, plus conversions to and from Web `Response` and client responses.
- *
- * Response constructors choose status defaults for common cases: `204` for
- * `empty`, `302` for `redirect`, and `200` for responses with bodies. Body
- * metadata is mirrored into headers, so content type and content length carried
- * by the body are written to `content-type` and `content-length`, overriding
- * existing values when present. JSON helpers can fail while encoding or
- * serializing unless the unsafe constructor is used.
- *
- * Cookies are tracked separately from the normal header map so they can be
- * encoded as `Set-Cookie` headers when converting to platform responses. Use the
- * effectful cookie helpers when invalid cookie names, values, or options should
- * stay in the Effect error channel.
+ * The `HttpServerResponse` module provides immutable response values for Effect
+ * HTTP servers. Handlers return an {@link HttpServerResponse}, then the runtime
+ * converts it to a platform response such as a Web `Response`.
+ *
+ * **Mental model**
+ *
+ * - A response is a status, optional status text, headers, cookies, and an HTTP
+ *   body.
+ * - Constructors set practical defaults: {@link empty} uses `204`,
+ *   {@link redirect} uses `302`, and body constructors use `200`.
+ * - Body metadata is reflected into headers when a response is created or when
+ *   the body is replaced.
+ * - Cookies are stored separately from the normal header map and become
+ *   `Set-Cookie` headers during conversion.
+ * - Constructors that encode data can return effects when encoding may fail.
+ *
+ * **Common tasks**
+ *
+ * - Create empty, redirect, text, HTML, JSON, or URL-encoded responses with
+ *   {@link empty}, {@link redirect}, {@link text}, {@link html}, {@link json},
+ *   {@link schemaJson}, or {@link urlParams}.
+ * - Send binary, raw, form-data, stream, or file bodies with {@link uint8Array},
+ *   {@link raw}, {@link formData}, {@link stream}, {@link file}, or
+ *   {@link fileWeb}.
+ * - Adjust status, headers, and bodies with {@link setStatus},
+ *   {@link setHeader}, {@link setHeaders}, and {@link setBody}.
+ * - Manage cookies with {@link setCookie}, {@link expireCookie},
+ *   {@link removeCookie}, and their unsafe variants.
+ * - Convert responses with {@link toWeb}, {@link fromWeb},
+ *   {@link toClientResponse}, and {@link fromClientResponse}.
+ *
+ * **Gotchas**
+ *
+ * - Body content type and content length override existing `content-type` and
+ *   `content-length` headers when body metadata is present.
+ * - {@link json} and {@link schemaJson} capture encoding failures in the Effect
+ *   error channel; {@link jsonUnsafe} throws instead.
+ * - {@link setCookie} and {@link expireCookie} validate cookie output in the
+ *   Effect error channel; unsafe cookie helpers throw on invalid cookies.
+ * - `Set-Cookie` headers are produced from the response cookie collection, not
+ *   by manually editing the normal header map.
  *
  * @since 4.0.0
  */
@@ -420,7 +442,7 @@ export const urlParams = (
  *
  * **When to use**
  *
- * Use this when the underlying runtime already understands the body value, such
+ * Use when the underlying runtime already understands the body value, such
  * as a Web `Response`, `Blob`, or `ReadableStream`; the body is passed through
  * for later platform conversion.
  *
@@ -787,7 +809,7 @@ export const expireCookie: {
  *
  * **When to use**
  *
- * Use `setCookie` when cookie errors should be represented as `CookiesError`
+ * Use when cookie errors should be represented as `CookiesError`
  * failures.
  *
  * @category combinators
@@ -800,7 +822,7 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookie` when cookie errors should be represented as `CookiesError`
+   * Use when cookie errors should be represented as `CookiesError`
    * failures.
    *
    * @category combinators
@@ -813,7 +835,7 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookie` when cookie errors should be represented as `CookiesError`
+   * Use when cookie errors should be represented as `CookiesError`
    * failures.
    *
    * @category combinators
@@ -845,7 +867,7 @@ export const setCookieUnsafe: {
  *
  * **When to use**
  *
- * Use `expireCookie` when cookie errors should be represented as `CookiesError`
+ * Use when cookie errors should be represented as `CookiesError`
  * failures.
  *
  * @category combinators
@@ -858,7 +880,7 @@ export const expireCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use `expireCookie` when cookie errors should be represented as `CookiesError`
+   * Use when cookie errors should be represented as `CookiesError`
    * failures.
    *
    * @category combinators
@@ -874,7 +896,7 @@ export const expireCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use `expireCookie` when cookie errors should be represented as `CookiesError`
+   * Use when cookie errors should be represented as `CookiesError`
    * failures.
    *
    * @category combinators
@@ -1074,7 +1096,7 @@ export const setCookies: {
  *
  * **When to use**
  *
- * Use `setCookies` when cookie errors should be represented as `CookiesError`
+ * Use when cookie errors should be represented as `CookiesError`
  * failures.
  *
  * @category combinators
@@ -1087,7 +1109,7 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookies` when cookie errors should be represented as `CookiesError`
+   * Use when cookie errors should be represented as `CookiesError`
    * failures.
    *
    * @category combinators
@@ -1108,7 +1130,7 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookies` when cookie errors should be represented as `CookiesError`
+   * Use when cookie errors should be represented as `CookiesError`
    * failures.
    *
    * @category combinators

package/src/unstable/http/HttpStaticServer.ts

@@ -1,19 +1,36 @@
 /**
  * Static file serving for Effect HTTP applications.
  *
- * This module builds request handlers and router layers that serve files from a
- * configured root directory. It is intended for public assets such as compiled
- * front-end bundles, images, fonts, downloads, documentation sites, and single
- * page applications that need an `index.html` fallback.
+ * `HttpStaticServer` turns HTTP requests into file responses rooted at a
+ * configured directory. Use {@link make} when you need an application value, or
+ * {@link layer} when static files should be mounted onto an `HttpRouter`,
+ * optionally under a URL prefix.
  *
- * Requests are resolved relative to the configured root after decoding and
- * normalizing the URL path. Malformed paths, null bytes, and `..` traversal
- * outside the root are rejected, but the module still serves anything the
- * configured `FileSystem` can reach below that root. Keep secrets out of the
- * served tree, be careful with symlinks or generated files, and remember that
- * dotfiles are not hidden automatically. File responses include content type,
- * optional cache control, byte-range support, and conditional request handling
- * based on the metadata supplied by `HttpPlatform`.
+ * **Mental model**
+ *
+ * The request path is decoded, normalized, and resolved below `root`. Invalid
+ * paths, null bytes, and `..` traversal outside `root` fail as route-not-found
+ * errors. A matching file is served through `HttpPlatform.fileResponse`, a
+ * matching directory serves `index` when configured, and `spa: true` falls back
+ * to the index file for extensionless HTML requests.
+ *
+ * **Common tasks**
+ *
+ * - Serve a public assets directory with {@link make}
+ * - Mount static assets beside API routes with {@link layer}
+ * - Add `Cache-Control` headers with `cacheControl`
+ * - Extend MIME type detection with `mimeTypes`
+ * - Support single-page application routing with `spa: true`
+ *
+ * **Gotchas**
+ *
+ * - {@link layer} installs `GET` routes only; handle other methods elsewhere.
+ * - Dotfiles are served when they live under `root`; keep secrets outside the
+ *   served tree.
+ * - Symlinks or generated files reachable from `root` may expose more than
+ *   expected.
+ * - Conditional requests and byte ranges depend on metadata supplied by
+ *   `HttpPlatform`.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpTraceContext.ts

@@ -1,21 +1,34 @@
 /**
- * Utilities for HTTP trace-context propagation.
+ * HTTP propagation helpers for Effect tracing context.
  *
- * This module converts Effect `Tracer.Span` values to outbound tracing headers
+ * This module converts Effect `Tracer.Span` values into outbound trace headers
  * and decodes inbound propagation headers into `Tracer.ExternalSpan` parents.
- * It is used by traced HTTP clients to continue the current span across an
- * outbound request, and by server middleware to parent request spans from
- * upstream services. The helpers are also useful for adapters or middleware
- * that need to bridge Effect tracing with W3C Trace Context or B3-compatible
- * systems.
- *
- * Outbound propagation writes both W3C `traceparent` and compact B3 `b3`
- * headers. Inbound decoding prefers W3C `traceparent`, then compact B3, then
- * multi-header B3 (`x-b3-*`). Header names in `Headers.Headers` are expected to
- * be lowercase; use the safe header constructors when accepting raw platform
- * headers. Invalid or unsupported header shapes simply decode to `Option.none`,
- * so callers should treat missing trace context as "start a new trace" rather
- * than as an error.
+ * HTTP clients use it to continue the current span across outgoing requests, and
+ * server middleware uses it to parent request spans from upstream services.
+ *
+ * **Mental model**
+ *
+ * Propagation is metadata, not tracing storage. {@link toHeaders} serializes the
+ * current span into HTTP headers for the next service. {@link fromHeaders}
+ * inspects incoming headers and returns an external parent span when a supported
+ * propagation format is present.
+ *
+ * **Common tasks**
+ *
+ * - Add outbound propagation headers with {@link toHeaders}
+ * - Decode an inbound parent span with {@link fromHeaders}
+ * - Use {@link w3c}, {@link b3}, or {@link xb3} directly when an adapter needs a
+ *   specific propagation format
+ *
+ * **Gotchas**
+ *
+ * - Outbound propagation writes both W3C `traceparent` and compact B3 `b3`
+ *   headers
+ * - Inbound decoding prefers W3C `traceparent`, then compact B3, then
+ *   multi-header B3 (`x-b3-*`)
+ * - Header names in `Headers.Headers` are expected to be lowercase
+ * - Missing or unsupported trace context decodes to `Option.none`, so callers
+ *   should start a new trace when no parent is returned
  *
  * @since 4.0.0
  */

package/src/unstable/http/Multipart.ts

@@ -1,21 +1,41 @@
 /**
- * Utilities for parsing and working with HTTP `multipart/form-data` request
- * bodies.
- *
- * This module converts multipart byte streams into typed `Part` values, either
- * as decoded text `Field` values or streamed `File` values. It is used by HTTP
- * server request handling for browser form submissions, API endpoints that
- * accept file uploads, and mixed payloads where structured fields accompany one
- * or more uploaded files. Persisted helpers collect fields into records and
- * write files into scoped temporary paths that can be decoded with schemas.
- *
- * Multipart bodies can be large and are often backed by one-shot request
- * streams, so prefer streaming file content unless the file is small enough to
- * collect with `contentEffect`. Persisted file paths are valid only while their
- * scope is open, and client-provided filenames should be treated as metadata
- * rather than trusted filesystem paths. Parser limits for part count, field
- * size, file size, total body size, and field MIME type handling are provided
- * through the module's context references.
+ * Parses and persists HTTP `multipart/form-data` request bodies.
+ *
+ * `Multipart` turns incoming byte streams into typed {@link Part} values. Text
+ * parts become decoded {@link Field} values, while upload parts remain streamed
+ * {@link File} values until they are collected or written to scoped temporary
+ * files. The persisted representation can then be decoded with schemas for
+ * request handlers that receive fields and uploaded files together.
+ *
+ * **Mental model**
+ *
+ * Multipart parsing is incremental. {@link makeChannel} consumes request body
+ * chunks and emits fields or files as soon as the parser reaches each part. A
+ * `File` owns a one-shot byte stream for that upload; {@link toPersisted}
+ * drains those file streams into scoped paths and collects text fields into a
+ * {@link Persisted} record.
+ *
+ * **Common tasks**
+ *
+ * - Parse a request body stream into {@link Part} values with {@link makeChannel}.
+ * - Persist parsed parts with {@link toPersisted} before schema decoding.
+ * - Decode persisted forms with {@link schemaPersisted}, {@link schemaJson},
+ *   {@link PersistedFileSchema}, or {@link SingleFileSchema}.
+ * - Configure parser limits with {@link limitsServices} or the `Max*` context
+ *   references.
+ *
+ * **Gotchas**
+ *
+ * Multipart request bodies are usually one-shot streams. Read each file stream
+ * once, and use `contentEffect` only when the file is small enough to hold in
+ * memory. Paths produced by {@link toPersisted} are scoped resources and stop
+ * being valid when the scope closes. Client-provided file names are metadata,
+ * not trusted filesystem paths.
+ *
+ * **See also**
+ *
+ * {@link Part}, {@link Field}, {@link File}, {@link Persisted},
+ * {@link makeChannel}, {@link toPersisted}.
  *
  * @since 4.0.0
  */