Faults
Reference for the faults in @streamsy/core. A fault reports a failure of the store, the network, or the codec, and a protocol error reports a rejected request.
import {
DecodeFault,
EncodeFault,
StorageFault,
StreamsFault,
TransportFault,
isRetryableFault,
isStreamsFault,
} from "@streamsy/core";A fault means that a call could not complete because the store, the network, or the codec failed. A protocol error means that the request ran and the server rejected it. The protocol errors are on the Errors page.
Each fault is a Schema.TaggedError, like the protocol errors, so it is an Error with a _tag that you can yield* in Effect.gen. Each block below shows the _tag and the fields that the fault adds. Every fault also has a message string and an optional cause that holds the underlying failure.
| Fault | Comes from |
|---|---|
StorageFault | A local storage adapter |
TransportFault | The remote Layer |
EncodeFault | The codec, before an append |
DecodeFault | The codec, during a read |
Fault classes
StorageFault
interface StorageFault {
readonly _tag: "StorageFault";
readonly operation: string;
readonly retryable: boolean;
}
A storage adapter fails with StorageFault when its store fails. operation names the storage call that failed. The adapter sets retryable to true when the same call can succeed later.
TransportFault
interface TransportFault {
readonly _tag: "TransportFault";
readonly operation: string;
readonly reason: "request" | "response" | "decode" | "configuration";
readonly status?: number;
readonly retryable: boolean;
}
The remote Layer fails with TransportFault when it cannot complete a call. When the host answers with a protocol rejection, the remote Layer fails with that protocol error instead.
reason | Meaning |
|---|---|
request | The HTTP request failed, for example when the network dropped |
response | The response does not follow the protocol, for example a header is missing or wrong |
decode | The client cannot read or decode the response body |
configuration | The remote configuration is not valid, or the client cannot build the request |
status is the HTTP status of the response, when a response arrived. retryable is a getter. It returns true when reason is request, or when status is 429 or 500 and above.
EncodeFault
interface EncodeFault {
readonly _tag: "EncodeFault";
}
An append fails with EncodeFault when one of its items does not encode with the codec of the address. The append fails before it sends anything, so the stream does not change. cause holds the schema error.
DecodeFault
interface DecodeFault {
readonly _tag: "DecodeFault";
}
A read fails with DecodeFault at the first stored message that does not decode with the codec of the address. message names the stream and the index of the message in its batch, and cause holds the schema error. The read does not skip the message, so the application chooses the offset to continue from. See Read › Errors.
Unions and guards
StreamsFault
type StreamsFault = StorageFault | TransportFault;
StreamsFault is a storage fault or a transport fault. The failure type of every stream method includes it. The value StreamsFault is the Schema of the same union, so you can decode or check a value with it.
isStreamsFault
declare function isStreamsFault<I>(input: I): input is I & (StorageFault | TransportFault);
isStreamsFault returns true for a StorageFault or a TransportFault. It returns false for a protocol error, an EncodeFault, or a DecodeFault.
isRetryableFault
declare function isRetryableFault(error: unknown): error is StreamsFault;
isRetryableFault returns true for a StreamsFault whose retryable is true. follow retries only the faults that pass this check, and it resumes from the offset it had reached.
A retried append can write its items twice. When the reply to an append is lost, the items can already be in the stream. To make a retry safe, send a producer position with the append. The example below retries a read:
import { Effect, Schedule } from "effect";
import { isRetryableFault } from "@streamsy/core";
import { Notes } from "./streams.ts";
const all = Effect.flatMap(Notes, (notes) => notes.collect({})).pipe(
Effect.retry({ while: isRetryableFault, schedule: Schedule.recurs(3) }),
);