Words the parked-timer bounds as the code has them - #135
Merged
Merged
Conversation
Three wording fixes to the parked-timer contract, no behaviour change. The StatifierOban.Timer.Delivery moduledoc section "A parked execution retries; it is never discarded" and the README's matching paragraph gave the exhaustion window as "about twelve days". Oban's default backoff waits 15 + 2^n seconds after attempt n plus a random 0-10% jitter, so the 19 retries of the default 20 attempts sum to about 12.1 days with no jitter and about 13.4 with the most; both now say twelve to thirteen and a half days and show the arithmetic. "Scheduling the same effect again does not revive it" holds only while the discarded job row survives, since that row is the dedup guard; both now say so, and that once the pruner removes the row a repeated schedule inserts a fresh job. The test stand-in's unpark/1 said it works as unpark/3 does, but it accepts only a parked scope and exits on any other, while statifier_persistence's unpark/3 answers an active execution unchanged. Its doc now says what it does. No changelog fragment (documentation and test support, per changelog.d/README.md). Full mix quality green on this tree. Refs: sob-em4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three wording fixes to the parked-timer contract, no behaviour change. Refs: sob-em4.
What changes
StatifierOban.Timer.Deliverymoduledoc section "A parked execution retries; it is never discarded" and the README's matching paragraph said Oban's default backoff spreads the default 20 attempts "over about twelve days". Both now say twelve to thirteen and a half days, and show where the range comes from: the wait after attemptnis15 + 2^nseconds plus a random 0-10% jitter.unpark/1. Its doc said it works "asunpark/3does". It accepts only a parked scope, and on any other scope a match inside the store fails and the call exits.statifier_persistence'sunpark/3answers an:activeexecution unchanged. The doc now describes what the stand-in does and why it is stricter. The code is unchanged (test support only).Review (in-turn, gate tier)
I read each claim against the locked dependencies. The backoff:
Oban.Worker.backoff/1in the locked Oban 2.23.1 clamps the attempt (a no-op atmax_attempts20, theOban.Jobdefault, which the timer worker does not override), then callsOban.Backoff.exponential(attempt, mult: 1, max_pow: 100, min_pad: 15), which gives15 + 2^n. After that it callsOban.Backoff.jitter(mode: :inc), which addstrunc(rand * 0.1 * time), so 0 to under 10%. Attempts 1 to 19 each schedule a retry, and the 20th is discarded. So the floor is19 * 15 + (2^20 - 2) = 285 + 1,048,574 = 1,048,859s, about 12.14 days. The ceiling adds at most 10% to each wait:1,153,735s, about 13.35 days. The docs round these to "about 12.1" and "about 13.4", and the range to "twelve to thirteen and a half days". The replay condition:StatifierOban.Timer.Worker's unique options cover every Oban state with an infinite period, so a surviving discarded row absorbs the insert. Once the row is pruned there is nothing left to conflict with. The stand-in: I checked the exit with a throwaway test that was not committed.unpark/1on an:activescope exits with{:badmatch, :active}from the store.statifier_persistence'sunpark/3doc says an:activeexecution answers{:ok, execution}with nothing written, and a terminal one answers{:discarded, execution}.Gate
Full
mix qualityis green on the committed tree (305 tests, credo, docs, dialyzer). No changelog fragment: this is documentation and test support, whichchangelog.d/README.mdexcludes.Provenance
The docs describe today's behaviour only. statifier_oban ADR-0010 (proposed) would later change what the parked paragraph says. ADR-0010's context repeats the old "about twelve days" when it quotes this section. This PR leaves the record untouched and lists that sentence as follow-up.