Skip to content

feat: proxy: activity: ETag and 304 for the activity revision (#1971) - #1990

Merged
joanestebanr merged 5 commits into
feat/445-proxy-reorg-activity-trackerfrom
feat/1971-activity-etag
Nov 18, 2026
Merged

joanestebanr merged 5 commits into
feat/445-proxy-reorg-activity-trackerfrom
feat/1971-activity-etag

Conversation

@joanestebanr

@joanestebanr joanestebanr commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #1986 (base branch feat/445-proxy-reorg-activity-tracker). It will be retargeted to develop once #1986 merges.

🔄 Changes Summary

  • Activity endpoint (GET /tracker/v1/activity/from/{from_address}): HTTP conditional requests on the activity revision. This is the last optional item of feat: proxy: API: expose finality, claimed_finalized and a per-address revision #1971.
    • Every 200 carries the revision of its body as the ETag header, between double quotes (a strong entity tag, RFC 9110).
    • A request whose If-None-Match holds that value is answered 304 Not Modified, with the ETag and no body, while the revision is unchanged. GetActivity is not called for a 304.
    • The ETag is the revision, so it is the same for every filterBridges, page_number and page_size of an address.
    • If-None-Match accepts 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.
    • A 304 only replaces a 200. Validation, flush_cache and registering the address (with includeTracking) run as before; 400, 500 and 503 keep their status and carry no ETag.
    • A registry that keeps no revision sends no ETag and never answers 304.
  • CurrentAPIRevision 7 -> 8, with its history entry.
  • runCommand writes a response with no body when a command returns no object.

⚠️ Breaking Changes

  • None. The body is unchanged and a client that does not send If-None-Match never receives a 304.

📋 Config Updates

  • None. For a browser to send If-None-Match cross-origin, the operator must list it in [REST.CORS].AllowedHeaders (existing setting).

🔌 API Updates

🔌 Bridge service API

  • No changes.

🔌 Proxy API

  • 🔌 AProxy API Update: GET /tracker/v1/activity/from/{from_address}, additive, api_revision 8.
    • New response headers on 200 and 304: ETag: "<revision>" and Cache-Control: no-store.
    • New optional request header If-None-Match, and new response 304 Not Modified (no body).
    • No endpoint added or removed, no change to the body.

🔌 Others API

  • None.

✅ Testing

  • 🤖 Automatic: new unit tests in bridgetracker/api/activity_etag_test.go
    • no header: 200 with the ETag of the body's revision;
    • If-None-Match: current tag, weak tag, *, list, several header lines -> 304; another revision, unquoted revision, empty header -> 200;
    • the same ETag for different filters and pages (including a page past the end), and a 304 on each;
    • revision changed -> 200 with the new ETag;
    • flush_cache and includeTracking still applied on a 304;
    • 400 / 503 / 500 never turned into a 304, and carry no ETag (including a 500 while reading the entries);
    • registry without a revision: no ETag, no 304;
    • through the real router: the 304 has an empty body and no Content-Type.
  • Run locally on this branch: make build, make lint (0 issues), go vet ./..., go test -race ./bridgetracker/..., go test ./proxy/... ./bridgeservice/...: all pass.
  • Not run: e2e, and no manual test against a browser.

🐞 Issues

🔗 Related PRs

📝 Notes

Decisions validated by the owner:

  • api_revision 7 -> 8 is kept. The change is additive; the bump lets a client tell from GET /health whether an instance answers 304.
  • Cache-Control: no-store next to the ETag is kept. The revision leaves out finalized, the claimed -> claimed_finalized step, last_updated_timestamp, tracking and warnings, so a 304 means "nothing the revision covers changed", not "the body is identical". no-store keeps a browser from revalidating a stored 200 on its own and handing a stale body to a page that never sent If-None-Match.
  • CORS: no code change, documented in API.md. If-None-Match must be allowed by [REST.CORS].AllowedHeaders: the proxy default ["*"] allows it, an explicit list must add it. ETag is not exposed to cross-origin scripts, so a browser client on another origin builds the tag from the body's revision.

Other notes:

  • The tag is strong only in syntax: it identifies the revision, not the bytes of the body. This is documented in API.md.
  • Doc fix in the revision rules of API.md: a bridge re-included in another block or transaction changes revision; a claim changes it only when its transaction changes, not when the same claim tx moves to another block (only claim.tx_hash is hashed).
  • Swagger: only the bridge tracker spec was regenerated (swag v1.16.4), and the unrelated generator drift (the Duration enum, format of integers) is left out.

🤖 Generated with Claude Code

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]>
@joanestebanr

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T14:38:38.570401Z 6d92fe0 Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: 83bb0deced

ℹ️ 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".

…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]>
@joanestebanr

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread bridgetracker/api/activity_command.go Outdated
Comment on lines +411 to +413
for _, candidate := range strings.Split(line, ",") {
candidate = strings.TrimSpace(candidate)
if candidate == ifNoneMatchAny || strings.TrimPrefix(candidate, weakETagPrefix) == etag {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

joanestebanr and others added 2 commits November 18, 2026 10:26
…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]>
@joanestebanr

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 6d92fe05e0

ℹ️ 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".

- 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]>
@joanestebanr
joanestebanr merged commit 5859d6f into feat/445-proxy-reorg-activity-tracker Nov 18, 2026
11 checks passed
@joanestebanr
joanestebanr deleted the feat/1971-activity-etag branch November 18, 2026 16:11
joanestebanr added a commit that referenced this pull request Nov 19, 2026
…, #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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant