mycocepurus-smithii - v2.0.1
    Preparing search index...

    Interface Store<T>

    Where the keys live. Async everywhere, including in memory, so that moving from a process-local store to a networked one is a constructor change.

    Three methods MUST be atomic, each as one operation:

    • claim is the whole guarantee: two callers claiming one key at once see exactly one "claimed". It MUST treat a claim whose lease has expired, and a completion whose retention has expired, as absent, so a retry of a dead attempt can become the first attempt. SET NX PX in Redis and INSERT ... ON CONFLICT DO NOTHING in Postgres are this method.
    • complete and release compare, then write or delete. An attempt can outlive its lease while a retry claims the key; when the first attempt finally finishes, a blind write would overwrite the retry's claim and a blind delete would remove it, letting a third copy run beside the retry. In Redis each is a Lua script that reads the entry, checks it is a live claim with owner, and only then runs SET ... PX or DEL. In Postgres they are UPDATE ... WHERE key = $1 AND owner = $2 AND expires_at > now() and DELETE ... WHERE key = $1 AND owner = $2, with the row count saying whether it happened.
    interface Store<T = unknown> {
        claim(
            key: string,
            entry: {
                claimedAt: number;
                fingerprint: string;
                leaseFor: number;
                owner: string;
                state: "in-flight";
            },
        ): Promise<Entry<T> | "claimed">;
        complete(
            key: string,
            entry: {
                fingerprint: string;
                retainFor: number;
                state: "complete";
                storedAt: number;
                value: T;
            },
            owner: string,
        ): Promise<boolean>;
        forget(key: string): Promise<void>;
        release(key: string, owner: string): Promise<boolean>;
    }

    Type Parameters

    • T = unknown

    Implemented by

    Index
    • Write entry only if nothing live is held under key. Returns "claimed", or what is held.

      Parameters

      • key: string
      • entry: {
            claimedAt: number;
            fingerprint: string;
            leaseFor: number;
            owner: string;
            state: "in-flight";
        }
        • claimedAt: number

          When the claim was taken.

        • fingerprint: string
        • leaseFor: number

          How long past claimedAt the claim is honoured before the attempt is presumed dead.

        • owner: string

          Random per attempt. complete and release act only while the claim under the key still carries it, so an attempt that outlived its lease cannot touch the claim of the attempt that replaced it.

        • state: "in-flight"

      Returns Promise<Entry<T> | "claimed">

    • Replace the claim with the outcome, only if key holds a live claim whose owner is owner. Returns whether it did. entry.retainFor is a hint for reclaiming space; the age is re-checked on the way out and store expiry is never trusted for correctness.

      Parameters

      • key: string
      • entry: {
            fingerprint: string;
            retainFor: number;
            state: "complete";
            storedAt: number;
            value: T;
        }
        • fingerprint: string
        • retainFor: number

          How long past storedAt the value is replayed.

        • state: "complete"
        • storedAt: number

          When the action finished.

        • value: T
      • owner: string

      Returns Promise<boolean>

    • Drop whatever is held, whoever holds it. Called by Ledger.forget.

      Parameters

      • key: string

      Returns Promise<void>

    • Drop the claim, only if key holds a claim whose owner is owner. Returns whether it did. Called when an action threw or shouldStore declined.

      Parameters

      • key: string
      • owner: string

      Returns Promise<boolean>