Skip to Content
Reference@streamsy/core

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.

FaultComes from
StorageFaultA local storage adapter
TransportFaultThe remote Layer
EncodeFaultThe codec, before an append
DecodeFaultThe 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.

reasonMeaning
requestThe HTTP request failed, for example when the network dropped
responseThe response does not follow the protocol, for example a header is missing or wrong
decodeThe client cannot read or decode the response body
configurationThe 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) }),
);

On this page