Repository navigation
feat: proxy: activity: ETag and 304 for the activity revision (#1971) - #1990
Conversation
GET /tracker/v1/activity/from/{from_address} now sends the revision of its
body as the ETag header (between double quotes, a strong entity tag) and
answers 304 Not Modified, with the ETag and no body, to a request whose
If-None-Match holds it, so the poll a client uses to watch the revision
does not download a page.
- The ETag is the revision, so it is the same whatever filterBridges,
page_number and page_size say. If-None-Match accepts a list, "*" and
weak tags (weak comparison, RFC 9110).
- A 304 only replaces a 200: validation, flush_cache and registering the
address run as before, and errors keep their status and carry no ETag.
The entries are not read for a 304.
- Cache-Control: no-store goes with the ETag. The revision does not cover
finalized, last_updated_timestamp, tracking or warnings, so an HTTP cache
must not revalidate on its own and serve a stored body to a client that
never sent If-None-Match.
- A registry that keeps no revision sends no ETag.
- CurrentAPIRevision 7 -> 8 (additive), with its history entry.
- docs/bridgetracker/API.md and the bridge tracker swagger regenerated
(swag v1.16.4; unrelated generator drift left out).
Refs #1971
Co-Authored-By: Claude Fable 5.2 <[email protected]>
|
@codex review |
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Codex Review: Didn't find any major issues. Delightful! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
…nse (#1971) The ETag and Cache-Control headers were set before the entries were read, so a 500 from GetActivity carried the ETag of a body the client never received. They are now set only on the 304 and, for a 200, once the entries have been read. Also corrects the comment of ActivityCache.GetActivityRevision: the access is counted by RegisterAndAwait, and GetActivity may not be called (304). Co-Authored-By: Claude Fable 5.2 <[email protected]>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ff096111e4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| for _, candidate := range strings.Split(line, ",") { | ||
| candidate = strings.TrimSpace(candidate) | ||
| if candidate == ifNoneMatchAny || strings.TrimPrefix(candidate, weakETagPrefix) == etag { |
There was a problem hiding this comment.
Parse wildcard matches outside quoted entity tags
For a valid header such as If-None-Match: "other,*,revision", splitting on commas produces a standalone * candidate, so this returns 304 regardless of the current revision. That asterisk belongs to a single nonmatching opaque entity tag, not a wildcard, and the response should be 200 with the current activity. Parse the list with quoted-tag boundaries preserved, or recognize the wildcard only when it is the entire field value.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 6d92fe0: * is now the wildcard only when it is the whole field value, so "other,*,revision" gets the 200. Tests added for a * inside a quoted tag, a * inside a list and the revision inside another tag.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
…it is the whole value (#1971) The header was split on commas before looking for "*", so a quoted entity tag holding commas, such as "other,*,revision", produced a standalone "*" and was answered 304 whatever the current revision. "*" is now the wildcard only when it is the entire field value, as the header's grammar defines. Co-Authored-By: Claude Fable 5.2 <[email protected]>
|
@codex review |
|
Codex Review: Didn't find any major issues. 🚀 Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
- Revision rules: a bridge re-included in another block or transaction changes the revision; a claim changes it only when its transaction changes, not when the same claim tx moves to another block. This matches the table of hashed fields and the code. - ETag/304: a browser client on another origin needs If-None-Match allowed by [REST.CORS].AllowedHeaders (the proxy default ["*"] allows it; an explicit list must add it), and ETag is not exposed to cross-origin scripts, so such clients build the tag from the body's revision. Co-Authored-By: Claude Fable 5.2 <[email protected]>
5859d6f
into
feat/445-proxy-reorg-activity-tracker
…, #1969, #1970) (#1986) > This PR brings the content of the integration branch `feat/445-proxy-reorg-wave1` to `develop`: the squash commits of #1981 and #1982, cherry-picked unchanged (no conflicts). Both were already reviewed and approved in those PRs; the finality resolver (#1979) and the API contract (#1980) they build on are already in `develop`. > > On top of them, a9c639c fixes a Codex P2 found on this PR: `reverifyClaim` now also compares `BlockTimestamp`, so a claim re-included at the same height in another block takes the new timestamp (test `TestReverifyStepsClaimReincludedAtSameHeight`). This fix is not in #1982 or in the integration branch. > > Three stacked PRs were then squash-merged into this branch: #1991 (1d57fd2, e2e acceptance scenarios), #1988 (788be65, L2->L1 leaf finality) and #1990 (5859d6f, ETag and `304` for the activity revision). ## 🔄 Changes Summary - **Activity scan (#1981, #1968, #1969)**: `GET /tracker/v1/activity/from/{from_address}` - The scan of the bridge service stops at the first bridge that is known **and final**. Non-final bridges are re-read on every refresh: they are corrected in place if they moved to another tx, block or timestamp, and removed if they are gone. - An entry is settled only when the claim is confirmed and both the bridge block (origin) and the claim block (destination) are final. Until then it keeps being refreshed and can go back from `claimed` to `readyToClaim` or `pending`. - No bridge-service error, including the `503` returned while it resolves a reorg, removes anything. - The activity `revision` is kept in the in-memory cache and in SQLite, with the same value for the same data and across restarts. - New metrics: `bridgetracker_activity_reorgs_detected_total`, `..._entries_corrected_total` and `..._entries_removed_total`. - **Tracker (#1982, #1970)**: a tracking is final only when its `Claimed` step is backed by a claim in a final block. Until then, on every engine tick: - the origin block hash is re-checked, and the bridge tx is resolved again if it changed; - the claim is re-checked with `isClaimed()`, and the tracking goes back to `WaitingClaim` if the claim is gone; - at `readyToClaim`, the GER injection and the L1 info leaf are re-checked. - Backward moves are persisted and pushed to WebSocket subscribers. A failing check (an RPC error or a `503`) never moves a tracking backwards. - **L2->L1 leaf finality ([#1988](#1988), #1987)**: at `readyToClaim` on L2->L1, once `l1-info-tree-index` returns the stored index, the tracker asks the same bridge-service instance for `injected-l1-info-leaf?network_id=0` and marks the `WaitingL1InfoLeafAvailable` step final when `block_finalized` is `true`. After that, the leaf is not re-checked. An omitted `block_finalized`, a `404` or an error keep the previous behaviour (re-checked every tick). L1->L2 and L2->L2 are unchanged. - **ETag and `304` on the activity endpoint ([#1990](#1990), last item of #1971)**: every `200` of `GET /tracker/v1/activity/from/{from_address}` carries the activity `revision` as a strong `ETag`, plus `Cache-Control: no-store`. A request whose `If-None-Match` matches gets `304 Not Modified` with no body. `400`, `500` and `503` keep their status and carry no `ETag`. `CurrentAPIRevision` goes from 7 to 8. CORS is only documented: the proxy default `[REST.CORS].AllowedHeaders = ["*"]` already allows `If-None-Match`, and an explicit list must add it. It also fixes the `API.md` rule on when a claim changes the `revision`: only when its tx changes, not when the same tx moves to another block. - **E2E reorg acceptance tests ([#1991](#1991), #1972)**: scenarios A1-A6, B1-B4, C1, D1-D2, E1-E4 and F1-F4 cause real reorgs on the anvil chains of `anvil-2chains` and check the activity endpoint, the tracker endpoint and its WebSocket before and after. Each scenario first asserts that aggkit reported the reorg (`last-reorg-event`). Test code and test env only (`ActivityPollInterval = "5s"` and optional config overrides in `test/e2e/envs/anvil-2chains`). ##⚠️ Breaking Changes - 🔌 **API/CLI**: no names or values are removed, but behaviour changes: - `claimed` is no longer terminal: it can go back to `readyToClaim` or `pending` after a reorg. The terminal state is `claimed_finalized`. - `tracking_status` only reads `finished`, and the WebSocket only closes, once the claim is final. With the claim done but not yet final, it stays `running`. - `creation_timestamp` of an activity entry can change if a reorg moves the bridge to another block. ## 📋 Config Updates - None. The SQLite migration `bridgetracker0005` adds `activity_bridge.revision_hash`. - For a browser to send `If-None-Match` cross-origin, `[REST.CORS].AllowedHeaders` must allow it: the default `["*"]` does, an explicit list must add it. ## 🔌 API Updates ### 🔌 Bridge service API - No changes. ### 🔌 Proxy API - 🔌 **AProxy API Update**: the `api_revision` 7 fields introduced by #1980 are populated now: `finalized`, `claimed_finalized` and `revision` in the activity endpoint, and `claimed_finalized` and `bridge_status.block_finalized` in the tracker endpoints and WebSocket. No endpoints are added or removed. Clients must accept `claimed_finalized` before this is deployed (agglayer/sdk#47, agglayer/agglayer-dev-ui#64). - 🔌 **AProxy API Update (#1990)**: `api_revision` 8, additive. The activity endpoint accepts the optional `If-None-Match` request header, answers `304 Not Modified` (no body) when it matches, and sends `ETag: "<revision>"` and `Cache-Control: no-store` on `200` and `304`. The body does not change. ## ✅ Testing - 🤖 **Automatic**: unit tests from #1981 and #1982. - Activity, run against both stores: bridge removed, bridge re-included in another block, claim reorged out or moved, `503` keeping the state, final entries not re-read, restart in the middle of a non-final state. - Tracker: every backward transition on L1->L2, L2->L1 and L2->L2, origin reorged out and re-included, `503` and transient errors leaving the state unchanged, final trackings making no calls, WebSocket backward updates. - Run locally on this branch: `go build ./...`, `go vet`, `go test -race ./bridgetracker/...`, `go test ./proxy/...`, `make lint`. - 🤖 **Unit tests from #1988**: `TestReverifyStepsL2ToL1LeafFinality`, `TestReverifyStepsLeafFinalityOnlyWithoutInjectionStep`, `TestGERSourceL1InfoLeafFinalized` and `TestEngineL2ToL1FinalLeafIsNotCheckedAgain`. - 🤖 **Unit tests from #1990**: `bridgetracker/api/activity_etag_test.go` (`If-None-Match` variants, the same `ETag` across filters and pages, errors never turned into `304`, registry without a revision, the `304` through the real router). - 🤖 **E2E against real reorgs (#1991)**: the new CI groups `proxy-reorg-activity`, `proxy-reorg-claims`, `proxy-reorg-tracker-revision` and `proxy-reorg-resilience` in `test-go-e2e.yml` run in this PR's CI. ## 🐞 Issues - Closes #1968 - Closes #1969 - Closes #1970 - Closes #1972 - Closes #1987 - Closes #1971 - Part of agglayer/pm#445 ## 🔗 Related PRs - #1981 and #1982: the original PRs, reviewed and approved against the integration branch. - #1979 (finality resolver) and #1980 (API contract): already merged into `develop`. - #1991 (e2e acceptance scenarios), #1988 (L2->L1 leaf finality) and #1990 (ETag and `304`): stacked PRs, reviewed there and squash-merged into this branch. - agglayer/sdk#47 and agglayer/agglayer-dev-ui#64: clients accepting `claimed_finalized`. ## 📝 Notes These design decisions are still open, recorded as implemented: - (a) `tracking_status` only reads `finished` once the claim is final. - (b) An unclaimed bridge in a final block reads `finalized=true` and goes back to `false` when it is claimed, until the claim is final. - (c) An origin tx that is reorged out and not re-included within `UnresolvedTimeout` (30 s by default) ends in a terminal error. - (d) On L2->L1 the L1 info leaf used to be polled on every tick while the bridge is at `readyToClaim`. #1988 now stops once the leaf is reported final. Its own open point is that the leaf's finality is only asked when the index matches the stored one; if the leaf moved after an L1 reorg, it keeps being re-checked every tick. Issues in aggkit found by the e2e tests of #1991 (none is a proxy problem, none is fixed here): - #1992: after an L2 reorg removes a GER injection, the aggoracle does not inject that GER again, so the bridges that depend on it stay unclaimable until a later GER is injected. The tests work around it by forcing a later GER on L1. - The aggsender certifies non-final L2 blocks when `BridgeL2Sync` is at `LatestBlock`. If a certificate carrying a bridge of a non-final block settles and the bridge is then reorged out, the aggsender cannot build another certificate and the network's settlement stops. The tests hold the aggsender during each scenario. No issue opened yet. Other notes: - With several bridge-service instances behind a load balancer, a lagging instance can make non-final activity entries be removed and re-added until they converge. - The generated swagger carries unrelated drift (the `Duration` enum and `block_finalized` in the bridge-service payloads), as noted in #1982. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
🔄 Changes Summary
GET /tracker/v1/activity/from/{from_address}): HTTP conditional requests on the activityrevision. This is the last optional item of feat: proxy: API: expose finality, claimed_finalized and a per-address revision #1971.200carries therevisionof its body as theETagheader, between double quotes (a strong entity tag, RFC 9110).If-None-Matchholds that value is answered304 Not Modified, with theETagand no body, while the revision is unchanged.GetActivityis not called for a304.ETagis the revision, so it is the same for everyfilterBridges,page_numberandpage_sizeof an address.If-None-Matchaccepts a list of tags,*and weak tags (W/"..."), compared weakly as RFC 9110 defines for this header. The bare revision without quotes does not match.304only replaces a200. Validation,flush_cacheand registering the address (withincludeTracking) run as before;400,500and503keep their status and carry noETag.ETagand never answers304.CurrentAPIRevision7 -> 8, with its history entry.runCommandwrites a response with no body when a command returns no object.If-None-Matchnever receives a304.📋 Config Updates
If-None-Matchcross-origin, the operator must list it in[REST.CORS].AllowedHeaders(existing setting).🔌 API Updates
🔌 Bridge service API
🔌 Proxy API
GET /tracker/v1/activity/from/{from_address}, additive,api_revision8.200and304:ETag: "<revision>"andCache-Control: no-store.If-None-Match, and new response304 Not Modified(no body).🔌 Others API
✅ Testing
bridgetracker/api/activity_etag_test.go200with theETagof the body's revision;If-None-Match: current tag, weak tag,*, list, several header lines ->304; another revision, unquoted revision, empty header ->200;ETagfor different filters and pages (including a page past the end), and a304on each;200with the newETag;flush_cacheandincludeTrackingstill applied on a304;400/503/500never turned into a304, and carry noETag(including a500while reading the entries);ETag, no304;304has an empty body and noContent-Type.make build,make lint(0 issues),go vet ./...,go test -race ./bridgetracker/...,go test ./proxy/... ./bridgeservice/...: all pass.🐞 Issues
🔗 Related PRs
📝 Notes
Decisions validated by the owner:
api_revision7 -> 8 is kept. The change is additive; the bump lets a client tell fromGET /healthwhether an instance answers304.Cache-Control: no-storenext to theETagis kept. The revision leaves outfinalized, theclaimed->claimed_finalizedstep,last_updated_timestamp,trackingandwarnings, so a304means "nothing the revision covers changed", not "the body is identical".no-storekeeps a browser from revalidating a stored200on its own and handing a stale body to a page that never sentIf-None-Match.API.md.If-None-Matchmust be allowed by[REST.CORS].AllowedHeaders: the proxy default["*"]allows it, an explicit list must add it.ETagis not exposed to cross-origin scripts, so a browser client on another origin builds the tag from the body'srevision.Other notes:
API.md.API.md: a bridge re-included in another block or transaction changesrevision; a claim changes it only when its transaction changes, not when the same claim tx moves to another block (onlyclaim.tx_hashis hashed).Durationenum,formatof integers) is left out.🤖 Generated with Claude Code