Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
ef091a6
test(faucet): give the fake GitHub a Date, a slow page and a stale cu…
ThomasK33 Nov 16, 2026
85299f8
feat(faucet): store the Date of the last head read as the redelivery …
ThomasK33 Nov 16, 2026
3052c1a
fix(faucet): scan redeliveries by attempt times and a checked Date, n…
ThomasK33 Nov 16, 2026
52f022b
docs(faucet): describe the redelivery clocks, the two residual risks …
ThomasK33 Nov 16, 2026
97cdda6
style(faucet): drop two comments that restate the redelivery scan
ThomasK33 Nov 16, 2026
29508db
style(faucet): cut the redelivery clock comments to what the code can…
ThomasK33 Nov 16, 2026
64a8a9b
refactor(faucet): put what the redelivery comments said into names an…
ThomasK33 Nov 16, 2026
0bba736
test(faucet): name the offsets of the redelivery clock tests and chec…
ThomasK33 Nov 16, 2026
da6ffd2
docs(faucet): say exactly what faucet's clock and a Date do in the scan
ThomasK33 Nov 16, 2026
5e1c632
fix(faucet): fail a redelivery run whose store returned a top without…
ThomasK33 Nov 16, 2026
586d154
fix(faucet): allow a Date the second that it drops when checking it a…
ThomasK33 Nov 16, 2026
c8a7083
fix(faucet): make migration 000008 fence the redelivery runs of the b…
ThomasK33 Nov 16, 2026
4483bd7
fix(faucet): keep the gaps of a changed hook as the run logs them
ThomasK33 Nov 16, 2026
551f69b
fix(faucet): end the gap of an unread range at the oldest attempt rea…
ThomasK33 Nov 16, 2026
cbf2046
docs(faucet): state when an empty list, a gap, the migration and its …
ThomasK33 Nov 16, 2026
819ceb9
docs(faucet): link the follow-up issues of the redelivery limits
ThomasK33 Nov 16, 2026
f3c380b
style(faucet): drop narration comments from the round-4 redelivery fixes
ThomasK33 Nov 16, 2026
c873800
test(faucet): name the statements of the build before migration 00000…
ThomasK33 Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .agents/skills/verify-faucet/features/redeliver.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@
- The reply is 200 JSON `{"busy", "pages", "attempts", "tracked", "asked", "recovered", "gave_up": {"limit", "expired"}, "gaps", "pending", "ranges"}`: pages and attempts read, deliveries that became pending, requests GitHub accepted, deliveries recovered, deliveries given up by reason, gaps recorded, deliveries still pending and ranges of the list still unread.
- A delivery qualifies when an attempt failed (any answer outside 200 to 299, or none), its event and action have a rule in `Normalize`, and faucet has no event with its GUID. A later attempt that succeeded, or a stored event, recovers it with no further request.
- A delivery is asked for at most 7 times, at 0, 10, 30, 70, 150, 310 and 630 minutes after the run that first read it, and at most 50 asks go out per run, the delivery that has waited longest first. The ask count is raised in the statement that claims the delivery, before the request. After the last ask and 5 minutes the delivery is given up with `reason=limit`. GitHub keeps a delivery for 72 hours, counted from its first attempt, and a delivery still pending then is given up with `reason=expired`.
- A run reads the newest attempts first, down to the newest attempt of the run before it less 5 minutes (the overlap that catches an attempt GitHub wrote late), and at most 20 pages. A stretch it cannot read is a range: its cursor and its two times are rows of `faucet_redelivery_ranges`, and later runs read the ranges, newest first, with the pages that the head read leaves. A range whose old end leaves GitHub's retention unread becomes a gap, and so does the time before the first run's lookback of 24 hours (`cause` `expired unread` and `before tracking began`).
- A run reads the newest attempts first, down to the newest attempt of the run before it less 5 minutes (the overlap that catches an attempt GitHub wrote late), and at most 20 pages. A stretch it cannot read is a range: its cursor and its two times are rows of `faucet_redelivery_ranges`, and later runs read the ranges, newest first, with the pages that the head read leaves. A range whose old end leaves GitHub's retention unread becomes a gap, and so does the time before the first run's lookback of 24 hours below the newest attempt (`cause` `expired unread` and `before tracking began`).
- One run holds a lease (`faucet_redelivery_scan`) at a time. A second run that starts meanwhile answers `busy: true` and does nothing.
- A page that fails to list stops the asks of the run, and so does a request that GitHub refuses (500 with the counts of the run and `"error": "redelivery failed"`, so the outcomes recorded before the failure still reach a reply. No response or log holds the hook token or GitHub's body). A refused ask still counts, and a rate limit is told from a denial in the log and handled the same way. The settle step needs no GitHub, so an expiry is still given up.
- A run keeps to the 25 second deadline of the route: half for reading the list (a page not back by then is dropped, and the rest is an open range), then the settle, asks until 80 percent, and the purge. A slow list costs pages, never the asks.
- A pending delivery belongs to the webhook that held the lease when it was tracked. After the webhook is replaced, a run does not ask the new one for the old one's deliveries: they end `recovered` or `expired`.
- The position of a run is GitHub's time: the newest attempt, or the `Date` header when the list is empty, never faucet's clock.
- The position of a run is the time of the newest attempt that it read. An empty list leaves it. The position never comes from faucet's clock or from GitHub's `Date` header, and a `Date` can only lower where a read stops. The `Date` says where a gap ends (72 hours before it, plus 1 hour of slack), and the `Date` of the last run says where a gap after a silence starts (6 hours and 5 minutes before it). A first page whose `Date` is missing, or more than 1 hour behind the newest attempt, fails the run: 500, and no asks.
- A final delivery and a recorded gap are deleted 72 hours after their last attempt, so each give-up is logged once. Pending deliveries, open ranges and the scan row stay.
- Without the hook settings the route answers 503 with `redelivery is not configured`, after the secret check.
- Only the hook token goes to GitHub, and only to two endpoints: `GET .../hooks/{id}/deliveries` and `POST .../deliveries/{attempt}/attempts`.
Expand All @@ -35,7 +35,8 @@ No charter. The stub's control calls are the only way to put deliveries in place

## Gotchas

- The first run records the part of GitHub's 72 hours before its 24 hour lookback as one gap, so a first reply says `gaps: 1`. That is the design, not a fault.
- The first run that reads an attempt records the part of GitHub's 72 hours before its 24 hour lookback as one gap, so its reply says `gaps: 1`. Both are counted from the newest attempt, not from the time of the run. A run on an empty list says `gaps: 0`. That is the design, not a fault.
- The stub sends Node's `Date` header, which is the stub's clock. A test of a `Date` that leads, lags or is missing belongs in `faucet/redeliver_gaps_test.go`, where the fake GitHub sets it.
- A delivery that is given up stays lost until someone redelivers it by hand.
- A stored cursor is GitHub's opaque value. If GitHub keeps refusing it, the range is retried by every run until it expires, and then it is a gap.
- GitHub lists an attempt when it ends, so an attempt that ended more than 5 minutes late and sits below the position of the last run is not read.
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,5 @@ Faucet is a Go library with a thin server (`cmd/faucet`). Read `README.md` first
- The end-to-end checks live in `verify/` and are described by the `verify-faucet` skill in `.agents/skills/`.
- Redelivery selection keeps persisted state; no stateless sliding-window sweep (see #10).
- Redelivery never derives a read position or bound from faucet's clock: the two clocks differ, and a position ahead of GitHub's drops the next failure unseen. It uses times that GitHub gave (attempt times, the `Date` header). A run also keeps to its context deadline by construction: the scan has its own time budget, so the asks and the purge always run.
- Known exception on main: the retention floor and first-run lookback (see README, redelivery limits); a redesign needs a design review first.
- The scan takes no read bound and no gap from faucet's clock (see #26). That clock is only the time of record that a step gives the store (`ScanStep.Now`). A read bound comes from an attempt time, and a `Date` can only lower it (the first run after an empty list or the migration); the types in `faucet/redelivertime.go` enforce it. A gap ends at a page `Date` that passed the check (not more than S = 1h behind the newest attempt known), and a gap after a silence starts at the stored `Date` less M = 6h. M and S are the trust window (see README, redelivery limits); a change to them needs a design review first.
- No selection shortcut that skips, suppresses or merges an overlap read or an open range (see #22).
Loading
Loading