effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/http/HttpStaticServer.ts

@@ -1,4 +1,20 @@
 /**
+ * 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.
+ *
+ * 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`.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -16,10 +32,11 @@ import * as HttpServerResponse from "./HttpServerResponse.ts"
 /**
  * Creates an `HttpApp` that serves files from a directory.
  *
- * @example
+ * **Example** (Serving files from a directory)
+ *
  * ```ts
  * import { Effect } from "effect"
- * import * as HttpStaticServer from "effect/unstable/http/HttpStaticServer"
+ * import { HttpStaticServer } from "effect/unstable/http"
  *
  * const program = Effect.gen(function*() {
  *   const app = yield* HttpStaticServer.make({ root: "./public" })
@@ -27,8 +44,8 @@ import * as HttpServerResponse from "./HttpServerResponse.ts"
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make: (options: {
   readonly root: string
@@ -168,12 +185,11 @@ export const make: (options: {
 /**
  * Creates a layer that mounts static files on an `HttpRouter`.
  *
- * @example
+ * **Example** (Mounting static files on a router)
+ *
  * ```ts
  * import { Layer } from "effect"
- * import * as HttpRouter from "effect/unstable/http/HttpRouter"
- * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
- * import * as HttpStaticServer from "effect/unstable/http/HttpStaticServer"
+ * import { HttpRouter, HttpServerResponse, HttpStaticServer } from "effect/unstable/http"
  *
  * const ApiLayer = HttpRouter.add("GET", "/health", HttpServerResponse.text("ok"))
  *
@@ -185,8 +201,8 @@ export const make: (options: {
  * const AppLayer = Layer.mergeAll(ApiLayer, StaticFilesLayer)
  * ```
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly root: string

package/src/unstable/http/HttpTraceContext.ts

@@ -1,4 +1,22 @@
 /**
+ * Utilities for HTTP trace-context propagation.
+ *
+ * This module converts Effect `Tracer.Span` values to outbound tracing 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.
+ *
  * @since 4.0.0
  */
 import * as Option from "../../Option.ts"
@@ -6,16 +24,26 @@ import * as Tracer from "../../Tracer.ts"
 import * as Headers from "./Headers.ts"
 
 /**
- * @since 4.0.0
+ * Function type for decoding tracing headers into an external span.
+ *
+ * Returns `Option.none` when the headers do not contain a supported or valid trace
+ * context.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface FromHeaders {
   (headers: Headers.Headers): Option.Option<Tracer.ExternalSpan>
 }
 
 /**
- * @since 4.0.0
+ * Encodes a span into HTTP trace propagation headers.
+ *
+ * The generated headers include both compact B3 (`b3`) and W3C `traceparent`
+ * formats.
+ *
  * @category encoding
+ * @since 4.0.0
  */
 export const toHeaders = (span: Tracer.Span): Headers.Headers =>
   Headers.fromRecordUnsafe({
@@ -29,8 +57,13 @@ export const toHeaders = (span: Tracer.Span): Headers.Headers =>
   })
 
 /**
- * @since 4.0.0
+ * Decodes an external span from HTTP trace propagation headers.
+ *
+ * W3C `traceparent` is tried first, followed by compact B3 (`b3`) and then
+ * multi-header B3 (`x-b3-*`).
+ *
  * @category decoding
+ * @since 4.0.0
  */
 export const fromHeaders = (headers: Headers.Headers): Option.Option<Tracer.ExternalSpan> => {
   let span = w3c(headers)
@@ -45,8 +78,13 @@ export const fromHeaders = (headers: Headers.Headers): Option.Option<Tracer.Exte
 }
 
 /**
- * @since 4.0.0
+ * Decodes an external span from the compact B3 `b3` header.
+ *
+ * Returns `Option.none` when the header is missing or does not contain trace and
+ * span identifiers.
+ *
  * @category decoding
+ * @since 4.0.0
  */
 export const b3: FromHeaders = (headers) => {
   if (!("b3" in headers)) {
@@ -64,8 +102,13 @@ export const b3: FromHeaders = (headers) => {
 }
 
 /**
- * @since 4.0.0
+ * Decodes an external span from multi-header B3 propagation headers.
+ *
+ * The decoder reads `x-b3-traceid`, `x-b3-spanid`, and optional `x-b3-sampled`
+ * headers.
+ *
  * @category decoding
+ * @since 4.0.0
  */
 export const xb3: FromHeaders = (headers) => {
   if (!(headers["x-b3-traceid"]) || !(headers["x-b3-spanid"])) {
@@ -82,8 +125,12 @@ const w3cTraceId = /^[0-9a-f]{32}$/i
 const w3cSpanId = /^[0-9a-f]{16}$/i
 
 /**
- * @since 4.0.0
+ * Decodes an external span from the W3C `traceparent` header.
+ *
+ * Only version `00` headers with valid trace and span identifiers are accepted.
+ *
  * @category decoding
+ * @since 4.0.0
  */
 export const w3c: FromHeaders = (headers) => {
   if (!(headers["traceparent"])) {

package/src/unstable/http/Multipart.ts

@@ -1,4 +1,22 @@
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -25,23 +43,37 @@ import * as IncomingMessage from "./HttpIncomingMessage.ts"
 import * as MP from "./Multipasta.ts"
 
 /**
+ * Type identifier used to brand multipart part values.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId = "~effect/http/Multipart"
 
 /**
- * @since 4.0.0
+ * A parsed multipart part.
+ *
+ * A part is either a text `Field` or a streamed `File`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Part = Field | File
 
 /**
+ * Namespace containing shared multipart part model types.
+ *
  * @since 4.0.0
  */
 export declare namespace Part {
   /**
-   * @since 4.0.0
+   * Common protocol implemented by multipart part values.
+   *
+   * It provides the multipart type identifier, tag, and inspectable behavior shared
+   * by fields, files, and persisted files.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Proto extends Inspectable.Inspectable {
     readonly [TypeId]: typeof TypeId
@@ -50,8 +82,13 @@ export declare namespace Part {
 }
 
 /**
- * @since 4.0.0
+ * Multipart form field containing a decoded text value.
+ *
+ * The `key` is the field name, `contentType` is the part media type, and `value`
+ * is the decoded field content.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Field extends Part.Proto {
   readonly _tag: "Field"
@@ -61,20 +98,29 @@ export interface Field extends Part.Proto {
 }
 
 /**
+ * Returns `true` when a value is a multipart `Part`.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isPart = (u: unknown): u is Part => Predicate.hasProperty(u, TypeId)
 
 /**
+ * Returns `true` when a value is a multipart text `Field`.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isField = (u: unknown): u is Field => isPart(u) && u._tag === "Field"
 
 /**
- * @since 4.0.0
+ * Multipart file part.
+ *
+ * The file content is exposed as a byte stream. `contentEffect` collects the full
+ * file into memory and should be used only when the file size is acceptable.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface File extends Part.Proto {
   readonly _tag: "File"
@@ -86,14 +132,21 @@ export interface File extends Part.Proto {
 }
 
 /**
+ * Returns `true` when a value is a multipart `File`.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isFile = (u: unknown): u is File => isPart(u) && u._tag === "File"
 
 /**
- * @since 4.0.0
+ * Multipart file part that has been written to the filesystem.
+ *
+ * The `path` points to the persisted file while the scope used to persist the
+ * multipart data remains open.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface PersistedFile extends Part.Proto {
   readonly _tag: "PersistedFile"
@@ -104,15 +157,22 @@ export interface PersistedFile extends Part.Proto {
 }
 
 /**
+ * Returns `true` when a value is a persisted multipart file.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isPersistedFile = (u: unknown): u is PersistedFile =>
   Predicate.hasProperty(u, TypeId) && Predicate.isTagged(u, "PersistedFile")
 
 /**
- * @since 4.0.0
+ * Record representation of persisted multipart data.
+ *
+ * Field names map to text values, arrays of text values, or arrays of
+ * `PersistedFile` values.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Persisted {
   readonly [key: string]: ReadonlyArray<PersistedFile> | ReadonlyArray<string> | string
@@ -121,8 +181,13 @@ export interface Persisted {
 const MultipartErrorTypeId = "~effect/http/Multipart/MultipartError"
 
 /**
+ * Reason carried by a `MultipartError`.
+ *
+ * It identifies parser and limit failures such as oversized files or fields, too
+ * many parts, total body size limits, parse errors, and internal errors.
+ *
+ * @category errors
  * @since 4.0.0
- * @category Errors
  */
 export class MultipartErrorReason extends Data.Error<{
   readonly _tag: "FileTooLarge" | "FieldTooLarge" | "BodyTooLarge" | "TooManyParts" | "InternalError" | "Parse"
@@ -130,13 +195,19 @@ export class MultipartErrorReason extends Data.Error<{
 }> {}
 
 /**
+ * Error raised while parsing, streaming, or persisting multipart form data.
+ *
+ * The `reason` field contains the concrete `MultipartErrorReason`.
+ *
+ * @category errors
  * @since 4.0.0
- * @category Errors
  */
 export class MultipartError extends Data.TaggedError("MultipartError")<{
   readonly reason: MultipartErrorReason
 }> {
   /**
+   * Creates a multipart error from a reason tag and optional cause.
+   *
    * @since 4.0.0
    */
   static fromReason(reason: MultipartErrorReason["_tag"], cause?: unknown): MultipartError {
@@ -144,11 +215,15 @@ export class MultipartError extends Data.TaggedError("MultipartError")<{
   }
 
   /**
+   * Marks this value as a multipart error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [MultipartErrorTypeId] = MultipartErrorTypeId
 
   /**
+   * Uses the concrete multipart error reason as the public message.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -157,14 +232,21 @@ export class MultipartError extends Data.TaggedError("MultipartError")<{
 }
 
 /**
+ * Schema type for persisted multipart files.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export interface PersistedFileSchema extends Schema.declare<PersistedFile> {}
 
 /**
+ * Schema for persisted multipart files.
+ *
+ * The encoded form contains the field key, original file name, content type, and
+ * filesystem path.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export const PersistedFileSchema: PersistedFileSchema = Schema.declare(
   isPersistedFile,
@@ -200,14 +282,21 @@ export const PersistedFileSchema: PersistedFileSchema = Schema.declare(
 )
 
 /**
+ * Schema for an array of persisted multipart files.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export const FilesSchema: Schema.$Array<PersistedFileSchema> = Schema.Array(PersistedFileSchema)
 
 /**
+ * Schema for exactly one persisted multipart file.
+ *
+ * The encoded form is a one-element file array, while the decoded value is the
+ * single `PersistedFile`.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export const SingleFileSchema: Schema.decodeTo<PersistedFileSchema, Schema.$Array<PersistedFileSchema>> = FilesSchema
   .check(
@@ -223,8 +312,13 @@ export const SingleFileSchema: Schema.decodeTo<PersistedFileSchema, Schema.$Arra
   )
 
 /**
+ * Creates a decoder for persisted multipart data using the supplied schema.
+ *
+ * The returned function decodes an unknown input into the schema output and fails
+ * with `SchemaError` when validation fails.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export const schemaPersisted = <A, I extends Partial<Persisted>, RD, RE>(
   schema: Schema.Codec<A, I, RD, RE>
@@ -232,8 +326,13 @@ export const schemaPersisted = <A, I extends Partial<Persisted>, RD, RE>(
   Schema.decodeUnknownEffect(schema)
 
 /**
+ * Creates a decoder for a JSON-encoded field in persisted multipart data.
+ *
+ * The selected field is parsed from a JSON string and decoded with the supplied
+ * schema.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export const schemaJson = <A, I, RD, RE>(schema: Schema.Codec<A, I, RD, RE>, options?: ParseOptions | undefined): {
   (
@@ -253,8 +352,14 @@ export const schemaJson = <A, I, RD, RE>(schema: Schema.Codec<A, I, RD, RE>, opt
 }
 
 /**
- * @since 4.0.0
+ * Builds the low-level multipart parser configuration from request headers and
+ * the current fiber context.
+ *
+ * Parser limits are read from the multipart references, including maximum parts,
+ * field size, file size, total body size, and field MIME type overrides.
+ *
  * @category Config
+ * @since 4.0.0
  */
 export const makeConfig = (
   headers: Record<string, string>
@@ -275,8 +380,14 @@ export const makeConfig = (
   })
 
 /**
- * @since 4.0.0
+ * Creates a channel that parses multipart byte chunks into multipart parts.
+ *
+ * The channel consumes non-empty batches of `Uint8Array` chunks and emits
+ * non-empty batches of parsed `Part` values, failing with `MultipartError` for
+ * parser and limit failures.
+ *
  * @category Parsers
+ * @since 4.0.0
  */
 export const makeChannel = <IE>(headers: Record<string, string>): Channel.Channel<
   Arr.NonEmptyReadonlyArray<Part>,
@@ -464,6 +575,12 @@ const defaultWriteFile = (path: string, file: File) =>
   )
 
 /**
+ * Runs a channel of byte chunks and collects all output into a single
+ * `Uint8Array`.
+ *
+ * This materializes the full content in memory.
+ *
+ * @category converting
  * @since 4.0.0
  */
 export const collectUint8Array = <OE, OD, R>(
@@ -482,8 +599,14 @@ export const collectUint8Array = <OE, OD, R>(
   })
 
 /**
+ * Persists a stream of multipart parts into a record.
+ *
+ * Text fields are collected as strings, and file parts are written to files in a
+ * scoped temporary directory. Persisted file paths remain valid for the lifetime
+ * of the scope.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const toPersisted = (
   stream: Stream.Stream<Part, MultipartError>,
@@ -560,8 +683,13 @@ class PersistedFileImpl extends PartBase implements PersistedFile {
 }
 
 /**
+ * Creates a context containing multipart parser limit settings.
+ *
+ * The context can provide maximum part count, field size, file size, total body
+ * size, and MIME types that should be parsed as fields.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const limitsServices = (options: {
   readonly maxParts?: number | undefined
@@ -590,13 +718,19 @@ export const limitsServices = (options: {
 }
 
 /**
+ * Namespace containing multipart parser limit option types.
+ *
  * @since 4.0.0
- * @category fiber refs
  */
 export declare namespace withLimits {
   /**
-   * @since 4.0.0
+   * Options for overriding multipart parser limits.
+   *
+   * These settings control maximum part count, field size, file size, total body
+   * size, and MIME types that should be treated as fields instead of files.
+   *
    * @category fiber refs
+   * @since 4.0.0
    */
   export type Options = {
     readonly maxParts?: number | undefined
@@ -608,24 +742,36 @@ export declare namespace withLimits {
 }
 
 /**
+ * Context reference for the maximum number of multipart parts allowed.
+ *
+ * The default is `undefined`, meaning no explicit part-count limit.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const MaxParts = Context.Reference<number | undefined>("effect/http/Multipart/MaxParts", {
   defaultValue: () => undefined
 })
 
 /**
+ * Context reference for the maximum size of a multipart field value.
+ *
+ * The default limit is 10 MiB.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const MaxFieldSize = Context.Reference<FileSystem.SizeInput>("effect/http/Multipart/MaxFieldSize", {
   defaultValue: constant(FileSystem.Size(10 * 1024 * 1024))
 })
 
 /**
+ * Context reference for the maximum size of a multipart file part.
+ *
+ * The default is `undefined`, meaning no explicit per-file limit.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const MaxFileSize = Context.Reference<FileSystem.SizeInput | undefined>(
   "effect/http/Multipart/MaxFileSize",
@@ -633,8 +779,13 @@ export const MaxFileSize = Context.Reference<FileSystem.SizeInput | undefined>(
 )
 
 /**
+ * Context reference for MIME type fragments that should be parsed as multipart
+ * fields instead of files.
+ *
+ * The default treats `application/json` parts as fields.
+ *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const FieldMimeTypes = Context.Reference<ReadonlyArray<string>>("effect/http/Multipart/FieldMimeTypes", {
   defaultValue: constant(["application/json"])

package/src/unstable/http/Multipasta/HeadersParser.ts

@@ -3,7 +3,7 @@
  */
 
 /**
- * @since 4.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * from "multipasta/HeadersParser"

package/src/unstable/http/Multipasta/Node.ts

@@ -3,7 +3,7 @@
  */
 
 /**
- * @since 4.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * from "multipasta/node"

package/src/unstable/http/Multipasta/Search.ts

@@ -3,7 +3,7 @@
  */
 
 /**
- * @since 4.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * from "multipasta/Search"

package/src/unstable/http/Multipasta/Web.ts

@@ -3,7 +3,7 @@
  */
 
 /**
- * @since 4.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * from "multipasta/web"

package/src/unstable/http/Multipasta.ts

@@ -3,7 +3,7 @@
  */
 
 /**
- * @since 4.0.0
  * @category re-exports
+ * @since 4.0.0
  */
 export * from "multipasta"