firefly-limiter - v1.0.3
    Preparing search index...

    Dependency

    For most services this is the only thing you construct. Make one per upstream and share it with every call site that talks to that upstream, so its breaker sees all of their calls.

    import { Dependency, exponential, retryAnything } from "firefly-limiter";

    export const payments = new Dependency({
    name: "payments",
    attempts: 3,
    backoff: exponential({ base: 200, max: 10_000 }),
    shouldRetry: retryAnything,
    deadline: 5_000,
    breaker: { threshold: 5, resetAfter: 30_000 },
    });

    The policies are always stacked in this order:

    retry -> hedge? -> breaker? -> limiter? -> bulkhead? -> timeout
    

    Anything you did not configure is left out. onEvent and clock are passed to every piece, so you set them once.

    share and fallback sit outside the stack and are set per call: share needs a key, and fallback's result type belongs to one call.

    Option What it is
    name What this dependency is called, in health() output and your own logs.
    attempts Total attempts per call, not additional ones. 1 never retries.
    backoff How long to wait between attempts. See Policies.
    shouldRetry Whether a failure is worth repeating.
    deadline Deadline for one attempt, in milliseconds.
    breaker When to stop calling this dependency, or false.

    None has a default. Pass breaker: false if you don't want a breaker.

    shouldRetry has no default because a 409 is fatal to one caller and expected by another. retryAnything repeats everything. Under a firefly-limiter/http transport, use retryableTransportError.

    Option Add it when
    bulkhead One slow upstream must not consume every socket or worker.
    rateLimit The API publishes a rate limit, or you are being polite.
    budget Retries must not multiply an outage across concurrent callers.
    hedge The p99 is the problem, not the failures.
    maxElapsed A whole call, across all its attempts, has a time budget.
    onEvent You want the decisions in your metrics or logs.
    clock You are testing, or you keep time yourself.

    budget is shared by the retries and the hedged attempts. Each option's fields are documented on its policy in Policies, minus onEvent and clock, which the dependency supplies.

    run takes the action and returns the result:

    const invoice = await payments.run((signal) => charge(id, signal));
    

    wrap returns the wrapped action instead, to call later. The signal is passed when you call it, since a wrapped action can be called more than once:

    const charge = payments.wrap((signal) => post(id, signal));
    queue.push(charge);
    const today = await rates.run(readRates, {
    share: "today",
    fallback: () => cached,
    signal: request.signal,
    });

    share joins this call to any call to the same dependency already running under the same key, so twenty callers make one request and share its attempts. Nothing is kept once the call settles.

    fallback answers instead of failing: stale data, an empty list. It sits outside everything, so it also catches Firefly's own refusals, such as an open circuit. The handler receives the failure. If it throws, the call rejects with what it threw.

    signal abandons this call.

    health() returns this, and reading it changes no state:

    {
    name: "payments",
    circuit: "closed", // or "open", "half-open", or "none" if breaker: false
    failures: 0, // what the breaker is currently counting
    inFlight: 0,
    queued: 0,
    tokens: 10, // only when there is a rate limiter
    retries: 10, // only when there is a retry budget
    }

    The pieces are readable too: payments.breaker, .bulkhead, .limiter, .budget (each undefined when not configured), .shared for the single-flight, and .options for the options it was built from. .policy is the whole stack as one policy, which is what you hand to a transport.

    Use stack directly when you need a different order, when two dependencies must share a breaker, or when the work is not a service call. Dependency is built from the same public pieces, and stack still checks the order.