HttpServerError

Describes failures raised while handling HTTP server requests.

HttpServerError covers failures that happen while accepting a request, matching a route, running a handler, or building and sending a response. Request-scoped failures keep the request that caused them, and response failures keep the response being produced. This module also includes helpers for turning failed causes or exits into HTTP responses and an annotation for interrupts caused by client aborts.

13 exports Added in v4.0.0 Source

Error Handling

causeResponse

Added in v4.0.0 Source

Converts a failed handler cause into the HTTP response that should be sent and the cause that should be reported.

Details

Respondable failures and defects can choose their own response, defects that are already HttpServerResponse values are used directly, and pure interrupts produce either 499 for client aborts or 503 for server aborts.

Signature

declare function causeResponse<E>(cause: Cause<E>): Effect<readonly [HttpServerResponse, Cause<E>]>

causeResponseStripped

Added in v4.0.0 Source

Derives an HTTP response from a failed handler cause synchronously.

Details

If the cause contains a defect that is already an HttpServerResponse, that response is used and removed from the remaining cause. Otherwise the response defaults to 500.

Signature

declare function causeResponseStripped<E>(cause: Cause<E>): readonly [HttpServerResponse, Option<Cause<E>>]

exitResponse

Added in v4.0.0 Source

Extracts the response from a successful handler exit, or derives a response from the failure cause.

Signature

declare function exitResponse<E>(exit: Exit<HttpServerResponse, E>): HttpServerResponse

Errors

HttpServerError

Added in v4.0.0 Source

Tagged error for failures that occur while handling an HTTP server request.

Details

It wraps a HttpServerErrorReason, exposes the associated request and optional response, and can be converted to an HTTP response through the Respondable protocol.

Signature

declare class HttpServerError extends YieldableError<this> & {
  readonly _tag: "HttpServerError";
} & Readonly<{
  readonly reason: HttpServerErrorReason;
}> implements Respondable {
  constructor(props: {
    readonly reason: HttpServerErrorReason;
  });
  readonly "~effect/http/HttpServerError": "~effect/http/HttpServerError";
  stack: string;
  "~effect/ErrorReporter/ignore": boolean;
  message: string;
  request: HttpServerRequest;
  response: HttpServerResponse | undefined;
  "~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}

HttpServerErrorReason type

Added in v4.0.0 Source

Reason carried by an HttpServerError, either a request-level error or a response-level error.

Signature

type HttpServerErrorReason = RequestError | ResponseError

InternalError

Added in v4.0.0 Source

Error describing an unexpected server-side failure while handling a request.

Details

When converted to a response it produces an empty 500 response.

Signature

declare class InternalError extends YieldableError<this> & {
  readonly _tag: "InternalError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpServerRequest;
}> implements Respondable {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpServerRequest;
  });
  message: string;
  methodAndUrl: string;
  "~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}

RequestError type

Added in v4.0.0 Source

Union of errors that are tied directly to an incoming server request.

Signature

type RequestError = RequestParseError | RouteNotFound | InternalError

RequestParseError

Added in v4.0.0 Source

Error describing a failure to parse or read an incoming request.

Details

When converted to a response it produces an empty 400 response.

Signature

declare class RequestParseError extends YieldableError<this> & {
  readonly _tag: "RequestParseError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpServerRequest;
}> implements Respondable {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpServerRequest;
  });
  message: string;
  methodAndUrl: string;
  "~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}

ResponseError

Added in v4.0.0 Source

Error describing a failure related to an HTTP response.

Details

It carries the request and response involved in the failure. When converted to a response it produces an empty 500 response.

Signature

declare class ResponseError extends YieldableError<this> & {
  readonly _tag: "ResponseError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpServerRequest;
  readonly response: HttpServerResponse;
}> implements Respondable {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpServerRequest;
    readonly response: HttpServerResponse;
  });
  message: string;
  methodAndUrl: string;
  "~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}

RouteNotFound

Added in v4.0.0 Source

Error indicating that no route matched the incoming request.

Details

When converted to a response it produces an empty 404 response, and it is ignored by the error reporter.

Signature

declare class RouteNotFound extends YieldableError<this> & {
  readonly _tag: "RouteNotFound";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpServerRequest;
}> implements Respondable {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpServerRequest;
  });
  readonly "~effect/ErrorReporter/ignore": true;
  message: string;
  methodAndUrl: string;
  "~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}

ServeError

Added in v4.0.0 Source

Error wrapping a low-level failure from the HTTP server implementation.

Signature

declare class ServeError extends YieldableError<this> & {
  readonly _tag: "ServeError";
} & Readonly<{
  readonly cause: unknown;
}> {
  constructor(args: {
    readonly cause: unknown;
  });
}

Guards

isHttpServerError

Added in v4.0.0 Source

Returns true when the supplied value is an HttpServerError.

Signature

declare function isHttpServerError(u: unknown): u is HttpServerError

Services

ClientAbort

Added in v4.0.0 Source

Context annotation used to mark an interrupt as caused by the client aborting the request.

Details

causeResponse uses this annotation to map a pure client abort to a 499 response instead of a server abort response.

Signature

declare class ClientAbort extends Shape<"effect/http/HttpServerError/ClientAbort", true, this> {
  constructor(_: never);
  static annotation: Context<StackTrace | ClientAbort>;
}