HttpServerRequest
Provides server-side access to the current incoming HTTP request.
HttpServerRequest is the context service used by handlers, middleware, schema decoders, multipart parsers, WebSocket upgrades, and adapters. A request stores its method, URL, original URL, headers, cookies, remote address, body stream, and platform source object. This module also includes request conversions and schema decoders for cookies, headers, search parameters, JSON, forms, URL-encoded bodies, and multipart bodies.
Accessors
upgradeChannel
Signature
declare function upgradeChannel<IE = never>(): Channel<
readonly [Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>],
HttpServerError | IE | SocketError,
void,
readonly [
string | Uint8Array<ArrayBufferLike> | CloseEvent,
string | Uint8Array<ArrayBufferLike> | CloseEvent,
],
IE,
unknown,
HttpServerRequest
>;Converting
fromClientRequest
Creates an HttpServerRequest view of an HttpClientRequest.
Details
If the client request can be converted to an absolute URL, that URL is used as the original URL.
Signature
declare function fromClientRequest(request: HttpClientRequest): HttpServerRequest;Wraps a Web Request as an HttpServerRequest.
Details
The request's current URL is stored without the scheme and host, while the original Web URL remains available as originalUrl.
Signature
declare function fromWeb(request: Request): HttpServerRequest;toClientRequest
Converts an HttpServerRequest into an HttpClientRequest.
Details
The converted request preserves the method, headers, body stream, and a URL derived from the request when possible.
Signature
declare function toClientRequest(request: HttpServerRequest): HttpClientRequest;Attempts to construct an absolute URL for a server request safely.
Details
The host comes from the host header, defaulting to localhost, and the protocol is https only when x-forwarded-proto is https; invalid URLs return Option.none.
Signature
declare function toURL(self: HttpServerRequest): Option<URL>;Converts an HttpServerRequest to a Web Request in Effect.
Details
The current context is used when streaming the request body into the Web request.
Signature
declare function toWeb(
self: HttpServerRequest,
options?: {
readonly signal?: AbortSignal;
},
): Effect<Request, RequestError>;toWebResult
Converts an HttpServerRequest safely to a Web Request as a Result.
Details
If the source is already a Web Request, it is returned unchanged. Otherwise an absolute URL is derived from the request; invalid URLs fail with a RequestParseError.
Signature
declare function toWebResult(
self: HttpServerRequest,
options?: {
readonly context?: Context<never>;
readonly signal?: AbortSignal;
},
): Result<Request, RequestError>;Models
HttpServerRequest interface
Server-side representation of an incoming HTTP request.
Details
It extends HttpIncomingMessage with request metadata, parsed cookies, multipart accessors, WebSocket upgrade support, and a modify method for creating adjusted request views.
Signature
interface HttpServerRequest extends HttpIncomingMessage<HttpServerError> {
readonly "~effect/http/HttpServerRequest": "~effect/http/HttpServerRequest";
readonly cookies: ReadonlyRecord<string, string>;
readonly method: HttpMethod;
readonly modify: (options: {
readonly headers?: Headers;
readonly remoteAddress?: Option<string>;
readonly url?: string;
}) => HttpServerRequest;
readonly multipart: Effect<Persisted, MultipartError, Scope | FileSystem | Path>;
readonly multipartStream: Stream<Part, MultipartError>;
readonly originalUrl: string;
readonly source: object;
readonly upgrade: Effect<Socket, HttpServerError>;
readonly url: string;
}Parsing
searchParamsFromURL
Converts a URL object's search parameters into a record.
Details
Repeated parameters are represented as arrays in insertion order.
Signature
declare function searchParamsFromURL(url: URL): ReadonlyRecord<string, string | Array<string>>;References
MaxBodySize
Context reference for the optional maximum size allowed when reading an incoming message body.
Signature
declare const MaxBodySize: Reference<Size | undefined>;Schemas
schemaBodyForm
Decodes the current request body as form data.
Details
Multipart requests are persisted and decoded as multipart data; other form requests are decoded from URL-encoded body parameters.
Signature
declare function schemaBodyForm<A, I extends Partial<Persisted>, RD>(
schema: ConstraintCodec<A, I, RD, unknown>,
options?: ParseOptions,
): Effect<
A,
SchemaError | HttpServerError | MultipartError,
Scope | FileSystem | Path | HttpServerRequest | RD
>;schemaBodyFormJson
Creates a decoder for a JSON value stored in a form field.
Details
For multipart requests, the named multipart field is decoded as JSON. For URL-encoded requests, the named parameter is decoded as JSON and then decoded with the supplied schema.
Signature
declare function schemaBodyFormJson<A, RD>(
schema: ConstraintDecoder<A, RD>,
options?: ParseOptions,
): (
field: string,
) => Effect<A, SchemaError | HttpServerError, Scope | FileSystem | Path | HttpServerRequest | RD>;schemaBodyJson
Reads the current request body as JSON and decodes it with the supplied schema.
Details
The effect can fail if the body cannot be read or parsed, or if schema decoding fails.
Signature
declare function schemaBodyJson<A, RD>(
schema: ConstraintDecoder<A, RD>,
options?: ParseOptions,
): Effect<A, SchemaError | HttpServerError, HttpServerRequest | RD>;schemaBodyMultipart
Persists the current multipart request body and decodes it with the supplied schema.
Details
The effect requires the services needed to persist multipart files, including a scope, file system, and path service.
Signature
declare function schemaBodyMultipart<A, I extends Partial<Persisted>, RD>(
schema: ConstraintCodec<A, I, RD, unknown>,
options?: ParseOptions,
): Effect<A, SchemaError | MultipartError, Scope | FileSystem | Path | HttpServerRequest | RD>;schemaBodyUrlParams
Reads the current request body as URL-encoded parameters and decodes them with the supplied schema.
Signature
declare function schemaBodyUrlParams<A, I extends Readonly<Record<string, string | readonly Array<string> | undefined>>, RD>(schema: ConstraintCodec<A, I, RD, unknown>, options?: ParseOptions): Effect<A, SchemaError | HttpServerError, HttpServerRequest | RD>schemaCookies
Decodes a schema from the cookies of the current request.
Signature
declare function schemaCookies<A, I extends Readonly<Record<string, string | undefined>>, RD>(
schema: ConstraintCodec<A, I, RD, unknown>,
options?: ParseOptions,
): Effect<A, SchemaError, HttpServerRequest | RD>;schemaHeaders
Decodes a schema from the headers of the current request.
Signature
declare function schemaHeaders<A, I extends Readonly<Record<string, string | undefined>>, RD>(
schema: ConstraintCodec<A, I, RD, unknown>,
options?: ParseOptions,
): Effect<A, SchemaError, HttpServerRequest | RD>;schemaSearchParams
Decodes a schema from the parsed search parameters of the current request.
Signature
declare function schemaSearchParams<A, I extends Readonly<Record<string, string | readonly Array<string> | undefined>>, RD>(schema: ConstraintCodec<A, I, RD, unknown>, options?: ParseOptions): Effect<A, SchemaError, ParsedSearchParams | RD>Services
HttpServerRequest
Service tag for the active server-side HTTP request.
When to use
Use to access the request currently being handled by HTTP server routes and middleware.
Signature
declare const HttpServerRequest: Service<HttpServerRequest, HttpServerRequest>;ParsedSearchParams
Service that contains decoded URL query parameters for the current request.
When to use
Use to access query parameters that have already been parsed for the current server request.
Details
Each key maps to a string value, or to an array when the parameter appears more than once.
Signature
declare class ParsedSearchParams extends Shape<
"effect/http/ParsedSearchParams",
ReadonlyRecord<string, string | Array<string>>,
this
> {
constructor(_: never);
}
Creates a channel backed by the current request's upgraded socket.
Details
The channel reads incoming socket messages and writes byte chunks to the socket, failing if the request cannot be upgraded or the socket fails.