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

    Concepts

    • The key is the client's promise that two requests are the same request. It arrives in the Idempotency-Key header as an RFC 8941 String, and the ledger sees it unquoted. The draft recommends a UUID; the ledger only requires printable ASCII within maxKeyLength.
    • The scope is whose key it is: a user id, an API key id, a tenant. Keys from two scopes never meet. It is required because a shared key space lets one client read another's response by guessing, and only your auth layer knows which client is calling.
    • The fingerprint is what the request looked like, as a string that is equal when the requests are. mycocepurus-smithii/http hashes method, path and query, and the body bytes. It leaves headers out, because a trace id or a refreshed token would turn every retry into a mismatch.

    The store id is <namespace length>:<namespace>:<scope length>:<scope>:<key>, lengths in decimal UTF-16 code units, so scope user-1, key k and no namespace is 0::6:user-1:k. Nothing is hashed or escaped. The lengths are what keep a : inside a scope or namespace from making two ids equal: joined bare, scope t:alice with key pay and scope t with key alice:pay would be the same entry, and one client would replay the other's response.

    maxKeyLength bounds the client's key only. The id is longer by the namespace, the scope, their lengths and four :, and that longer string is what your store indexes.

    The id format is part of what is stored. A release that changes it, which the changelog marks as breaking, leaves every earlier entry unreachable: a retry that straddles the deploy runs the action again, and the old entries sit in the store until their own expiry.

    Both are required and in milliseconds.

    • leaseFor is how long a claim is honoured. It should be longer than your slowest action, or a slow first attempt and its retry both run. Once it passes, the attempt holding it is presumed dead and the next request with that key is treated as the first.
    • retainFor is how long a completed outcome is replayed. It is your clients' retry horizon. Past it, the same key runs the action again.

    The window travels with the entry, so a store's own expiry is a hint for reclaiming space rather than the source of truth: the ledger re-checks the age on the way out.

    Before the action runs, store.claim writes an in-flight entry if and only if nothing live is held under the key. There is no in-memory map of in-flight keys inside the ledger, because a map would give a different answer in one process than in twenty.

    A second copy that arrives while the claim is held is refused with in-flight, as the draft says. A caller who wants concurrent in-process copies to share one execution puts Firefly's SingleFlight in front.

    Each claim carries a random owner. Storing the outcome and releasing the key are compare-and-set and compare-and-delete against it. An attempt can outlive leaseFor while a retry claims the key; when the first attempt then finishes or fails, an unconditional write or delete would hit the retry's claim, and a third copy would run beside the retry. With the owner check the late attempt leaves the claim alone, reports lost-claim, and its value is returned (or its error rethrown) without being stored.

    Everything shouldStore says yes to, including failures. The draft says a retried request sees the result of the first, success or error, and Stripe does the same: a client that got a 402 and retries should see the same 402, not a second attempt to charge the card. storeAnything is that answer. If a 503 from your handler should be retryable instead, write a shouldStore that says no to it, and the key is released so the retry runs.

    An action that throws is not stored. The key is released and the error is rethrown unchanged.

    onEvent receives a plain object for each step, with a type of claim, replay (with its age), store, skip, release (with the action's error), refuse (with its code), lost-claim (a run outlived its lease and found its claim gone) or store-error (with the operation that failed). A listener that throws is ignored.

    Pass now to the ledger and to MemoryStore, and move it by hand. The suite here has no setTimeout in it. Every refusal is a MycocepurusError with a code, so a test can assert on the code.