Faults and retry
Reference for ProjectionFault and ProjectionRetry in @streamsy/projection. A projection fails with a ProjectionFault that names where the run stopped and why.
import { ProjectionFault, ProjectionRetry } from "@streamsy/projection";
import type { Context, Schedule } from "effect";A runner fails with a ProjectionFault, or with the error of the handler itself. follow retries retryable projection faults under ProjectionRetry. Attached bindings use their own backoff; ProjectionRetry paces retryable failures of the runner's own storage operations. See Faults.
ProjectionFault
interface ProjectionFault {
readonly _tag: "ProjectionFault";
readonly phase: "load" | "read" | "pin" | "process" | "checkpoint";
readonly reason:
| "history-unavailable"
| "identity-mismatch"
| "invalid-record"
| "invalid-source"
| "invalid-options"
| "invalid-output"
| "token-conflict"
| "output-busy"
| "range-unreproducible"
| "stale-epoch"
| "storage-failure"
| "unsupported-composition";
readonly input?: string;
readonly retryable: boolean;
}
ProjectionFault is a Schema.TaggedError, so it is an Error with a _tag that you can yield*. phase says where the run stopped, and reason says why. input names the input when one input caused the fault. The fault also has a message string and an optional cause that holds the underlying failure, such as a StorageFault.
| Phase | Where the run stopped |
|---|---|
load | The record, the input identity, or the options |
read | An input read |
pin | The pin write, the read of a pinned range, or an output append |
process | The handler result, or a write while the handler ran |
checkpoint | The checkpoint write after the handler. The handler has run |
| Reason | Meaning |
|---|---|
history-unavailable | An input does not have the history after its checkpoint offset |
identity-mismatch | An input differs from the stored identity, or awaitOffset names a different attached version or generation |
invalid-record | The stored record or state does not decode, or a pinned unit does not fit the Commit |
invalid-source | An input read is invalid, does not advance, or does not decode |
invalid-options | limit or repairIntervalMs is not a positive safe integer |
invalid-output | An output item does not encode, or an output stream is missing, closed, or refused the append |
output-busy | An output stream is busy; retry later |
token-conflict | Another writer changed the record first |
range-unreproducible | A pinned range cannot be read again |
stale-epoch | A newer generation has written to an output |
storage-failure | Storage, transport, or SQL failed |
unsupported-composition | The Commit or the storage cannot do what the projection asks |
retryable is true for token-conflict and output-busy. It is also true for storage-failure, unless cause is a StreamsFault whose retryable is false. Every other reason is non-retryable. Attached runners stop the binding, trigger stream or runner that hit a non-retryable fault; handler errors and defects retry. follow fails its stream on handler errors, defects and non-retryable faults. run retries no fault. After history-unavailable or range-unreproducible, recover with a new generation.
ProjectionRetry
declare const ProjectionRetry: Context.Reference<Schedule.Schedule<unknown>>;
ProjectionRetry is a Context.Reference that holds the default retry schedule of Projection.follow, Projection.attach, and ProjectionWakeup. The retry option of follow or passRetry of either attach host takes precedence over it.
For attached runners the schedule controls timing only: the runner calls it once per retryable failed pass with no input. A dying step is logged and treated as exhaustion. Retryable binding failures back off separately, by default from 1 s doubling to 1 hour under the declaration's binding retry policy, in both durability modes; a finite pass policy does not stop them.
The default schedule never stops. Its delay starts at 200 ms, doubles after each retry, has jitter, and is at most 30 s. To change the default for every runner, provide another schedule for ProjectionRetry.
import { Effect, Schedule } from "effect";
import { ProjectionRetry } from "@streamsy/projection";
const withRetry = Effect.provideService(ProjectionRetry, Schedule.spaced("1 second"));CheckpointStore
Reference for the checkpoint store in @streamsy/projection and @streamsy/projection/checkpoint. The store keeps the offsets and the state of each projection key in one compare-and-set record.
SqlStorage
Reference for the SqlStorage namespace in @streamsy/storage. It keeps streams in a SQLite, Postgres, or MySQL database through an Effect SqlClient that you provide.