walk/sequential

Purpose

The walk/sequential module implements the default ordered fall-through walk strategy. It iterates the candidate list in declaration order, dispatches each candidate via a caller-supplied dispatcher, and returns the first successful result. Transient failures fall through to the next candidate; semantic failures surface immediately; aborts cut the walk per policy. On exhaustion it throws ALL_CANDIDATES_FAILED with every per-leg error preserved, or CIRCULAR_REFERENCE when every candidate cycles back to an already-visited URI.

Features

Ordered fall-through with EventBusLike attempt-failed / attempt-succeeded emissions per candidate.
Cycle skipping via hasVisited + cycle-detected event emission.
Per-candidate OTel counter increments (fallback_total).
Foreign throwable wrapping into structured FallbackUriError.
decorateRecursive injects the recursion-context id into nested fallback:// candidates so re-entries see the parent context.

Usage: Basic Example

import { walkSequential } from "@suaveplan/storage-uri-plugin-fallback/walk";

const value = await walkSequential(
    {
        uri,
        candidates,
        ctx,
        policy,
        events,
        signal,
    },
    async (candidate, s) => resolver.read(candidate, s),
);

Usage: Advanced Example

import {
    candidateScheme,
    decorateRecursive,
    walkSequential,
} from "@suaveplan/storage-uri-plugin-fallback/walk";

const decorated = candidates.map((c) => decorateRecursive(c, ctx));
console.log(candidateScheme(decorated[0]));

API Reference

walkSequential<T>(opts: SequentialWalkOptions, dispatch: Dispatch<T>): Promise<T>
SequentialWalkOptions — { uri, candidates, ctx, policy, events, signal }.
Dispatch<T> — (candidateUri, signal) => Promise<T>.
candidateScheme(uri) — extracts the lowercased scheme.
decorateRecursive(candidate, ctx) — appends __fbctx=<ctx.id> to fallback:// candidates.

Implementation Notes

The walk respects policy.stopOnAbort: when true (default), an aborted caller signal is checked before each candidate and throws FALLBACK_URI.ABORTED immediately. The recorded counter outcome for cycle-skipped candidates is "semantic" to align with the classifier's treatment of cycle detection as a non-transient surface.

2.3 KiB Raw Blame History