HttpMiddleware
Wraps HTTP server apps with request and response behavior.
A middleware is a function from one HTTP server app effect to another. The app runs with the current HttpServerRequest in its context, so middleware can inspect or rewrite the request, provide request-scoped services, attach hooks before the response is sent, or observe the app exit. This module includes middleware for response logging, server tracing, forwarded proxy headers, parsed search parameters, and CORS response headers.
Compression
compression
Signature
declare function compression(options?: {
readonly algorithms?: readonly Array<CompressionAlgorithm>;
readonly compressible?: (contentType: string) => boolean;
readonly levels?: {
readonly br?: number;
readonly deflate?: number;
readonly gzip?: number;
readonly zstd?: number;
};
readonly minSize?: number;
}): <E, R>(httpApp: Effect<HttpServerResponse, E, R>) => Effect<HttpServerResponse, E, HttpServerRequest | R | HttpPlatform>Constructors
Layers
layerTracerDisabledForUrls
Creates a layer that disables server-side tracing for requests whose URL exactly matches one of the supplied URLs.
Signature
declare function layerTracerDisabledForUrls(urls: readonly Array<string>): Layer<never>Logging
Middleware that logs sent HTTP responses with request method, request URL, and response status annotations.
Signature
declare const logger: <E, R>(
httpApp: Effect.Effect<HttpServerResponse, E, HttpServerRequest | R>,
) => Effect.Effect<HttpServerResponse, E, HttpServerRequest | R>;withLoggerDisabled
Runs an effect with HTTP response logging disabled for the current server request.
Signature
declare function withLoggerDisabled<A, E, R>(
self: Effect<A, E, R>,
): Effect<A, E, HttpServerRequest | R>;Middleware
Middleware that handles CORS preflight requests and adds configured CORS headers to HTTP responses.
Signature
declare function cors(options?: {
readonly allowedHeaders?: readonly Array<string>;
readonly allowedMethods?: readonly Array<string>;
readonly allowedOrigins?: readonly Array<string> | Predicate<string>;
readonly credentials?: boolean;
readonly exposedHeaders?: readonly Array<string>;
readonly maxAge?: number;
}): <E, R>(httpApp: Effect<HttpServerResponse, E, R>) => Effect<HttpServerResponse, E, HttpServerRequest | R>Models
HttpMiddleware interface
Middleware that transforms an HTTP server app effect into another HTTP server app effect.
Signature
interface HttpMiddleware {
<E, R>(
self: Effect<HttpServerResponse, E, HttpServerRequest | R>,
): Effect<HttpServerResponse, any, any>;
}Other
HttpMiddleware
Namespace containing types associated with HttpMiddleware.
Parsing
searchParamsParser
Middleware that parses the current request URL's search parameters and provides them as ParsedSearchParams.
Signature
declare function searchParamsParser<E, R>(
httpApp: Effect<HttpServerResponse, E, R>,
): Effect<HttpServerResponse, E, HttpServerRequest | Exclude<R, ParsedSearchParams>>;Proxying
xForwardedHeaders
Middleware that trusts X-Forwarded-Host and X-Forwarded-For, updating the request host header and remote address.
Signature
declare const xForwardedHeaders: <E, R>(
httpApp: Effect<HttpServerResponse, E, HttpServerRequest | R>,
) => Effect<HttpServerResponse, E, HttpServerRequest | R>;Services
SpanNameGenerator
Context reference for generating server span names from HTTP server requests.
Signature
declare const SpanNameGenerator: Reference<(request: HttpServerRequest) => string>;TracerDisabledWhen
Context reference for a predicate that disables server-side tracing for matching requests.
Signature
declare const TracerDisabledWhen: Reference<Predicate<HttpServerRequest>>;Tracing
Middleware that creates a server trace span for each request and records request and response HTTP attributes.
Signature
declare const tracer: <E, R>(
httpApp: Effect.Effect<HttpServerResponse, E, HttpServerRequest | R>,
) => Effect.Effect<HttpServerResponse, E, HttpServerRequest | R>;
Middleware that compresses HTTP response bodies based on the request's
Accept-Encodingheader.Details
Content negotiation follows RFC 9110: the first algorithm in server preference order that the client accepts with a positive q-value and the platform supports is used. When no algorithm is acceptable the response is sent uncompressed.
The body transform is performed by the
HttpPlatformservice.Responses are skipped when the status is 1xx, 204, 206, or 304, when a
Content-Encodingis already present, whenCache-Control: no-transformis set, when the content type is absent or not compressible, when a known body length is belowminSize, or when the body is empty orFormData. A response carryingContent-Encoding: identityopts out of compression and has the header stripped before sending.Vary: Accept-Encodingis set on every response that was eligible by status and content type, including ones skipped by negotiation orminSize.Do not combine this middleware with Deno's automatic response compression. On edge runtimes that already apply automatic compression, the middleware is unnecessary. Platforms backed by Web
CompressionStreamalso cannot explicitly flush each input chunk, so incremental delivery depends on the runtime's implementation.Security
Compression can expose secrets through BREACH-style attacks when one response contains both secret data and attacker-controlled input and an attacker can observe the compressed response length. For affected routes, disable compression with
Content-Encoding: identityorCache-Control: no-transform, or usecompressibleto restrict which response content types can be compressed.