Skip to Content
Reference@streamsy/projection

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.

PhaseWhere the run stopped
loadThe record, the input identity, or the options
readAn input read
pinThe pin write, the read of a pinned range, or an output append
processThe handler result, or a write while the handler ran
checkpointThe checkpoint write after the handler. The handler has run
ReasonMeaning
history-unavailableAn input does not have the history after its checkpoint offset
identity-mismatchAn input differs from the stored identity, or awaitOffset names a different attached version or generation
invalid-recordThe stored record or state does not decode, or a pinned unit does not fit the Commit
invalid-sourceAn input read is invalid, does not advance, or does not decode
invalid-optionslimit or repairIntervalMs is not a positive safe integer
invalid-outputAn output item does not encode, or an output stream is missing, closed, or refused the append
output-busyAn output stream is busy; retry later
token-conflictAnother writer changed the record first
range-unreproducibleA pinned range cannot be read again
stale-epochA newer generation has written to an output
storage-failureStorage, transport, or SQL failed
unsupported-compositionThe 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"));

On this page