Skip to content

HttpPlatform

Platform-specific support for serving files as HTTP server responses.

HttpPlatform is the boundary between the portable HTTP response model and the runtime that knows how to stream bytes from the host platform. Server code uses this service when it needs to return local files, static assets, downloads, byte ranges, or Web File-like values without constructing the response body by hand.

8 exports Added in v4.0.0 Source

Compression

Compression interface

Added in v4.0.0 Source

Platform primitive for HTTP response compression.

Details

algorithms advertises what the platform can encode; content negotiation happens in the shared HttpMiddleware.compression middleware.

compressResponse is only called when compression is definitely happening — all skip logic runs in the shared middleware first. The platform owns the body transform and removes Content-Length when the compressed size is not known in advance. The make wrapper owns the Content-Encoding and Vary headers.

Signature

interface Compression {
  readonly algorithms: ReadonlySet<CompressionAlgorithm>;
  readonly compressResponse: (
    response: HttpServerResponse,
    algorithm: CompressionAlgorithm,
    options?: CompressionOptions,
  ) => Effect<HttpServerResponse>;
}

CompressionAlgorithm type

Added in v4.0.0 Source

Content codings that HTTP response compression can apply.

Signature

type CompressionAlgorithm = "gzip" | "deflate" | "br" | "zstd";

CompressionOptions interface

Added in v4.0.0 Source

Options passed to a platform when compressing a response body.

Details

The level scale depends on the algorithm. Platforms without a level knob, such as the Web CompressionStream implementation, ignore it.

Signature

interface CompressionOptions {
  readonly level?: number;
}

compressionTransformWeb

Added in v4.0.0 Source

Creates a compression body transform backed by the Web CompressionStream API, for use with makeCompressionWeb.

Details

The format string is passed through to the runtime, so runtime-specific formats such as Bun's "brotli" and "zstd" are usable. CompressionStream has no compression level knob, so CompressionOptions.level does not apply.

Signature

declare const compressionTransformWeb: (
  format: string,
) => (stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>;

makeCompressionWeb

Added in v4.0.0 Source

Creates a Compression implementation from Web ReadableStream transforms.

Details

All supported bodies are transformed as streams. The Content-Length header is dropped in every case.

Signature

declare const makeCompressionWeb: (options: {
  readonly algorithms: Iterable<CompressionAlgorithm>;
  readonly transform: (
    algorithm: CompressionAlgorithm,
    options?: CompressionOptions,
  ) => (stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>;
}) => Compression;

Constructors

make

Added in v4.0.0 Source

Creates an HttpPlatform service from platform-specific file response constructors, using FileSystem and Etag.Generator.

Signature

declare const make: (impl: {
  readonly compression: Compression;
  readonly fileResponse: (
    path: string,
    status: number,
    statusText: string | undefined,
    headers: Headers.Headers,
    start: number,
    end: number | undefined,
    contentLength: number,
  ) => Response.HttpServerResponse;
  readonly fileWebResponse: (
    file: Body.HttpBody.FileLike,
    status: number,
    statusText: string | undefined,
    headers: Headers.Headers,
    options?: {
      readonly bytesToRead?: FileSystem.SizeInput;
      readonly chunkSize?: FileSystem.SizeInput;
      readonly offset?: FileSystem.SizeInput;
    },
  ) => Response.HttpServerResponse;
  readonly platform: "deno" | "node" | "bun" | "web";
}) => Effect.Effect<HttpPlatform["Service"], never, Etag.Generator | FileSystem.FileSystem>;

Layers

layer

Added in v4.0.0 Source

Provides the default HttpPlatform implementation for serving file paths and File-like values as streamed HTTP responses.

Details

The layer uses the FileSystem and weak ETag services to add file metadata headers such as etag and last-modified.

Signature

declare const layer: Layer<HttpPlatform, never, FileSystem>;

Services

HttpPlatform

Added in v4.0.0 Source

Service for platform-specific HTTP response helpers, including file-backed server responses.

Signature

declare class HttpPlatform extends Shape<
  "effect/http/HttpPlatform",
  {
    readonly compression: Compression;
    readonly fileResponse: (
      path: string,
      options?: WithContent & {
        readonly bytesToRead?: SizeInput;
        readonly chunkSize?: SizeInput;
        readonly offset?: SizeInput;
      },
    ) => Effect<HttpServerResponse, PlatformError>;
    readonly fileWebResponse: (
      file: FileLike,
      options?: WithContent & {
        readonly bytesToRead?: SizeInput;
        readonly chunkSize?: SizeInput;
        readonly offset?: SizeInput;
      },
    ) => Effect<HttpServerResponse>;
    readonly platform: "deno" | "node" | "bun" | "web";
  },
  this
> {
  constructor(_: never);
}