Serve errors
Reference for the errors in @streamsy/serve. Each Serve handler fails with a tagged error class that renders as a public JSON error response.
import { Serve, PublicErrorSchema } from "@streamsy/serve";
import { Schema, type Effect } from "effect";
import { HttpServerRespondable, type HttpServerResponse } from "effect/http";
import type { ReplayRecovery, ResumeRejectedReason } from "@streamsy/serve/contract";The Serve handlers fail with these errors when they reject a request or cannot encode a response. To declare them in an HttpApi, see HttpApiBuilder.
Each class is a Schema.TaggedError, so it is an Error with a _tag that you can yield*. Each fence shows the fields of a class and its HttpServerRespondable.symbol method, which renders the error as a JSON response with Http.securityHeaders and cache-control: no-store. responseHeaders starts as {}. The stream, state, and value handlers set it to their version and contract headers. The response sends these headers, and the JSON body leaves them out.
Serve.InvalidParams
interface InvalidParams {
readonly _tag: "InvalidParams";
readonly route: string;
readonly parameter: string;
readonly detail: string;
responseHeaders: Readonly<Record<string, string>>;
[HttpServerRespondable.symbol](): Effect.Effect<
HttpServerResponse.HttpServerResponse,
never,
never
>;
}
A mount route or params fails with Serve.InvalidParams when the path params do not decode or cannot form a canonical stream id. Its response status is 400.
route is the matched route pattern, and parameter is always "params". detail is "Invalid path parameters" when the params do not decode, and "Parameters cannot form a canonical stream id" when declaration.at throws.
Serve.ProtocolVersionUnsupported
interface ProtocolVersionUnsupported {
readonly _tag: "ProtocolVersionUnsupported";
readonly route: string;
readonly supported: 1;
readonly received: string;
readonly recovery: ReplayRecovery;
responseHeaders: Readonly<Record<string, string>>;
[HttpServerRespondable.symbol](): Effect.Effect<
HttpServerResponse.HttpServerResponse,
never,
never
>;
}
stream and state fail with Serve.ProtocolVersionUnsupported when the version header of the request is not "1". Its response status is 409.
route is the matched route pattern, received is the value of the version header, and supported is 1. recovery is "replay-from-start".
Serve.ResumeRejected
interface ResumeRejected {
readonly _tag: "ResumeRejected";
readonly route: string;
readonly reason: ResumeRejectedReason;
readonly recovery: ReplayRecovery;
responseHeaders: Readonly<Record<string, string>>;
[HttpServerRespondable.symbol](): Effect.Effect<
HttpServerResponse.HttpServerResponse,
never,
never
>;
}
stream and state fail with Serve.ResumeRejected when they cannot resume the read that the request asks for. Its response status is 409.
route is the matched route pattern. reason is "invalid-offset", "history-unavailable", or "contract-changed". recovery is "replay-from-start". See ResumeRejectedReason.
Serve.ContractChanged
interface ContractChanged {
readonly _tag: "ContractChanged";
readonly route: string;
readonly recovery: "refetch";
responseHeaders: Readonly<Record<string, string>>;
[HttpServerRespondable.symbol](): Effect.Effect<
HttpServerResponse.HttpServerResponse,
never,
never
>;
}
value fails with Serve.ContractChanged when the value contract header of the request differs from the current fingerprint. Its response status is 409.
route is the matched route pattern. recovery is "refetch", which tells the client to fetch the value again.
Serve.TransportUnavailable
interface TransportUnavailable {
readonly _tag: "TransportUnavailable";
readonly route: string;
readonly detail: string;
responseHeaders: Readonly<Record<string, string>>;
[HttpServerRespondable.symbol](): Effect.Effect<
HttpServerResponse.HttpServerResponse,
never,
never
>;
}
stream and state fail with Serve.TransportUnavailable when the read fails with a storage or transport fault. Its response status is 503.
route is the matched route pattern. detail is "Storage unavailable" for a StorageFault and "Transport unavailable" for a TransportFault.
Serve.WireEncodeFailed
interface WireEncodeFailed {
readonly _tag: "WireEncodeFailed";
readonly route: string;
readonly detail: string;
responseHeaders: Readonly<Record<string, string>>;
[HttpServerRespondable.symbol](): Effect.Effect<
HttpServerResponse.HttpServerResponse,
never,
never
>;
}
A handler fails with Serve.WireEncodeFailed when it cannot encode its response. Its response status is 500.
route is the matched route pattern. detail names the cause:
"Invalid collection metadata":statecannot decode the collection metadata of the address"Value cannot be encoded": thevalueschema cannot encode the result"Value is not finite JSON": the encodedvalueresult holds a non-finite number
Serve.ServeError
type ServeError =
| Serve.InvalidParams
| Serve.ProtocolVersionUnsupported
| Serve.ResumeRejected
| Serve.ContractChanged
| Serve.TransportUnavailable
| Serve.WireEncodeFailed;
Serve.ServeError is the union of the six Serve error classes. A value handler can also fail with the error of its compute Effect.
PublicErrorSchema
declare const PublicErrorSchema: Schema.TaggedUnion<{
readonly ContractChanged: Schema.TaggedStruct<
"ContractChanged",
{
readonly route: Schema.String;
readonly recovery: Schema.Literal<"refetch">;
}
>;
readonly InvalidParams: Schema.TaggedStruct<
"InvalidParams",
{
readonly route: Schema.String;
readonly parameter: Schema.String;
readonly detail: Schema.String;
}
>;
readonly ProtocolVersionUnsupported: Schema.TaggedStruct<
"ProtocolVersionUnsupported",
{
readonly route: Schema.String;
readonly supported: Schema.Literal<1>;
readonly received: Schema.String;
readonly recovery: Schema.Literal<"replay-from-start">;
}
>;
readonly ResumeRejected: Schema.TaggedStruct<
"ResumeRejected",
{
readonly route: Schema.String;
readonly reason: Schema.Literals<
readonly ["invalid-offset", "history-unavailable", "contract-changed"]
>;
readonly recovery: Schema.Literal<"replay-from-start">;
}
>;
readonly TransportUnavailable: Schema.TaggedStruct<
"TransportUnavailable",
{
readonly route: Schema.String;
readonly detail: Schema.String;
}
>;
readonly WireEncodeFailed: Schema.TaggedStruct<
"WireEncodeFailed",
{
readonly route: Schema.String;
readonly detail: Schema.String;
}
>;
}>;
PublicErrorSchema is the schema of the public error body. It validates and encodes the body, and its cases field holds one tagged schema for each error class. The body has the shape of PublicError, without responseHeaders, message, or stack.
When an HttpApi encodes a declared Serve error itself, the response leaves out the headers in responseHeaders. To keep them, convert the error with HttpServerRespondable.toResponse. See HttpApiBuilder.