HttpEffect unstable

Runs Effect HTTP server handlers at platform boundaries.

This module turns effects that produce HttpServerResponse values into Web Request handlers and other server adapters. It also applies middleware, converts failures into responses, runs hooks before a response is sent, and manages request scopes for streamed responses.

12 exports Since v4.0.0 Source

Combinators

toHandled

unstable

Since v4.0.0

Runs an HTTP server effect, sends the produced response with the supplied handler, and converts failures into HTTP responses. On handler failure, the request scope closes with the original cause. If the send handler returns an HttpServerResponse, such as the 101 response of an upgraded request, middleware observes it in place of the handler's response.

Signature

declare function toHandled<E, R, EH, RH>(self: Effect<HttpServerResponse, E, R>, handleResponse: (request: HttpServerRequest, response: HttpServerResponse) => Effect<unknown, EH, RH>, middleware?: HttpMiddleware): Effect<void, never, HttpServerRequest | Exclude<R, Scope> | Exclude<RH, Scope>>

Converting

fromWebHandler

unstable

Since v4.0.0

Adapts a Web Request handler into an HTTP server effect for the current HttpServerRequest.

Signature

declare function fromWebHandler(handler: (request: Request) => Promise<Response>): Effect<HttpServerResponse, HttpServerError, HttpServerRequest>

toWebHandler

unstable

Since v4.0.0

Converts an HTTP server effect into a Web Request handler using an empty base context.

Signature

declare const toWebHandler: <E>(self: Effect.Effect<HttpServerResponse, E, HttpServerRequest | Scope.Scope>, middleware?: HttpMiddleware) => (request: Request, context?: Context.Context<never>) => Promise<globalThis.Response>

toWebHandlerLayer

unstable

Since v4.0.0

Builds a Web Request handler for an HTTP server effect using a layer to provide its services, returning the handler with a dispose function.

Details

The layer is built immediately, so the cost is paid when the handler is created rather than on the first request. A layer that performs asynchronous work while building may still be in progress when the first request arrives, in which case that request waits for the build to finish. If the build fails, every request rejects with the build error.

Signature

declare function toWebHandlerLayer<E, R, Provided, LE, ReqR = Exclude<R, Scope | HttpServerRequest | Provided>>(self: Effect<HttpServerResponse, E, R>, layer: Layer<Provided, LE>, options?: {
  readonly memoMap?: MemoMap;
  readonly middleware?: HttpMiddleware;
}): {
  readonly dispose: () => Promise<void>;
  readonly handler: [ReqR] extends [never] ? (request: Request, context?: Context<never>) => Promise<Response> : (request: Request, context: Context<ReqR>) => Promise<Response>;
}

toWebHandlerLayerWith

unstable

Since v4.0.0

Builds a Web Request handler from a layer and handler factory, returning the handler with a dispose function for the layer scope.

Details

Signature

declare function toWebHandlerLayerWith<E, Provided, LE, R, ReqR = Exclude<R, Scope | HttpServerRequest | Provided>>(layer: Layer<Provided, LE>, options: {
  readonly memoMap?: MemoMap;
  readonly middleware?: HttpMiddleware;
  readonly toHandler: (context: Context<Provided>) => Effect<Effect<HttpServerResponse, E, R>, LE>;
}): {
  readonly dispose: () => Promise<void>;
  readonly handler: [ReqR] extends [never] ? (request: Request, context?: Context<never>) => Promise<Response> : (request: Request, context: Context<ReqR>) => Promise<Response>;
}

toWebHandlerWith

unstable

Since v4.0.0

Converts an HTTP server effect into a Web Request handler using the supplied base context and optional middleware.

Signature

declare function toWebHandlerWith<Provided, R = never, ReqR = Exclude<R, Scope | HttpServerRequest | Provided>>(context: Context<Provided>): <E>(self: Effect<HttpServerResponse, E, R>, middleware?: HttpMiddleware) => [ReqR] extends [never] ? (request: Request, context?: Context<never>) => Promise<Response> : (request: Request, context: Context<ReqR>) => Promise<Response>

Handlers

appendPreResponseHandler

unstable

Since v4.0.0

Registers an additional pre-response handler for the current HTTP server request.

Signature

declare function appendPreResponseHandler(handler: PreResponseHandler): Effect<void, never, HttpServerRequest>

PreResponseHandler

type unstable

Since v4.0.0

Function run with the current request and response just before the response is sent, allowing the response to be replaced or failing with HttpServerError.

Signature

type PreResponseHandler = (request: HttpServerRequest, response: HttpServerResponse) => Effect.Effect<HttpServerResponse, HttpServerError>

withPreResponseHandler

unstable

Since v4.0.0

Runs an effect after registering a pre-response handler for the current HTTP server request.

Signature

declare const withPreResponseHandler: {
  (handler: PreResponseHandler): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, HttpServerRequest | R>;
  <A, E, R>(self: Effect<A, E, R>, handler: PreResponseHandler): Effect<A, E, HttpServerRequest | R>;
}

Resource Management

scopeDisableClose

unstable

Since v4.0.0

Disables automatic closing for an HTTP request scope.

Gotchas

Use only when another owner will close the scope; otherwise resources attached to the request scope can leak.

Signature

declare function scopeDisableClose(scope: Scope): void

scopeTransferToStream

unstable

Since v4.0.0

Returns a streaming server response that closes the request scope when the body stream exits.

Signature

declare function scopeTransferToStream(response: HttpServerResponse): HttpServerResponse

Unsafe

appendPreResponseHandlerUnsafe

unstable

Since v4.0.0

Registers a pre-response handler for the supplied HTTP server request.

Signature

declare const appendPreResponseHandlerUnsafe: (request: HttpServerRequest, handler: PreResponseHandler) => void