walk/parallel

Purpose

The walk/parallel module implements the Promise.any-style race strategy activated when policy.maxParallel > 1. It dispatches up to maxParallel candidates concurrently, returns the first to resolve, and aborts every pending candidate via a composed AbortSignal so they can release any held resources. Failures arriving before the first success are collected; if every candidate ends in transient failure, the walk throws ALL_CANDIDATES_FAILED with the per-leg cause chain populated.

Features

Concurrency cap honouring policy.maxParallel and the candidate count.
Composed abort propagation via anySignal([callerSignal, internal]).
Per-candidate counter and attempt-failed / attempt-succeeded events.
Semantic failures surface immediately, halting the race.
Honours policy.stopOnAbort on pre-aborted caller signals.

Usage: Basic Example

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

const bytes = await walkParallel(
    {
        uri,
        candidates,
        ctx,
        policy: { ...policy, maxParallel: 3 },
        events,
        signal,
    },
    async (candidate, s) => resolver.read(candidate, s),
);

Usage: Advanced Example

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

await walkParallel(
    { uri, candidates, ctx, policy, events, signal },
    async (candidate, s) => {
        const res = await fetch(candidate, { signal: s });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        return new Uint8Array(await res.arrayBuffer());
    },
);

API Reference

walkParallel<T>(opts: ParallelWalkOptions, dispatch: Dispatch<T>): Promise<T>
ParallelWalkOptions — { uri, candidates, ctx, policy, events, signal }.

Implementation Notes

The walk uses an internal AbortController that fires as soon as one candidate resolves; pending candidates observing the composed signal abort cooperatively. Completion bookkeeping (completed >= total) is the only path that throws ALL_CANDIDATES_FAILED after exhausting the work queue, ensuring the structured error always carries one entry per attempted candidate.

This module is part of the universal fallback URI plugin family. It coordinates with the recursion, walk, ops, observability, and classification modules through small, narrowly-typed value contracts. The implementation deliberately keeps surface area small so each piece can be substituted or instrumented independently without touching consumers. Refer to the package README for the end-to-end picture and to the spec delta for the requirement matrix this module helps satisfy.

2.6 KiB Raw Blame History