Skip to content

docs(failover): pins and failed replies on the backup page match router main (MAG-4923) - #105

Open
avitenzer wants to merge 1 commit into
mainfrom
docs/MAG-4923-backup-page-pins-and-failure-replies
Open

avitenzer wants to merge 1 commit into
mainfrom
docs/MAG-4923-backup-page-pins-and-failure-replies

Conversation

@avitenzer

Copy link
Copy Markdown
Contributor

Jira ticket: MAG-4923

The "Primary and backup nodes" page (#81) was checked against smart-router c17c2cce (v1.6.5). Since then, smart-router #578 (pins), #587 (failed replies), #671 (headers on a no-answer reply), #675 (MAG-4729) and #670 (MAG-4731) changed what it describes. This PR brings the page, and the matching lines of api/directives.md, back in line with router main 10c1db19 (v1.6.8-36).

configuration/failover/backup.md

  • Pinning. A plain lava-select-provider covers the first attempt only. Its retry or hedge goes through normal selection and can reach a backup. With lava-select-provider-strict: true, and on a sticky request, the named node answers or the request fails, with no Lava-Retries header (504 if it stays silent). The "when a backup gets traffic" row says the same.
  • Sticky sessions. A node error or a busy node fails the request, and the session keeps its node. "Or this request already tried it" is gone. So is the MAG-4731 known issue, fixed by #670.
  • What the caller gets.
    • A node's answer goes back as is: status, body and Content-Type.
    • All 429 returns the node's 429 (was 503).
    • An expired budget returns 504 no answer from upstream within <budget> (was 500 context deadline exceeded).
    • A write that every node answered gets the node's status.
    • The unclear-write 500 names its causes.
    • Failed replies carry the Lava-* headers. Only a request that reached no node has none.
  • Archive warning. lava-extension: archive now gets Lava-Extension-Unavailable: archive when the only archive node is out of rotation, and that reply is not cached (MAG-4729).
  • MAG-4730 (subscriptions) is still open (#677), so that section is unchanged.

api/directives.md

  • The pin's "when to use" line and its "unreachable node" line: a plain pin is retried on another node.
  • Pinned write: a 429 from the pinned node sends a plain-pinned write to the other nodes. A sticky or strict write gets the 429.
  • Response headers: the intro (failed replies carry them), Lava-Provider-Address (lists the nodes asked when none answered), Lava-Retries (absent on a write and on a sticky or strict request), and Lava-Extension-Unavailable (also an extension no node could serve for this request).

How it was checked

A real router boot of main 10c1db19 against the provider simulator: 2 primaries and 1 backup, plus a 3-primary run for the pinned-write case. Every row of the failure table, the pin cases (backup, unknown, blocked, plain, strict, strict and silent), sticky with blocked primaries and recovery, and the archive backup down at boot were sent live, and the status, body and headers were read off the reply. The --shared-state and busy-node cases come from the code and the router's tests (TestVerify_B_SharedClaimAllPrimariesBlocked, TestStickyPodLocal_BusyProviderFailsRatherThanMoving, TestSharedSticky_NoPrimaryToClaimServesFromBackupUnpinned). REST and Tendermint come from TestFailedRelayReply_EndToEnd_MAG4481.

mkdocs build --strict passes.

Other open docs PRs on the same lines

🤖 Generated with Claude Code

…er main (MAG-4923)

The "Primary and backup nodes" page was written against smart-router
c17c2cce (v1.6.5). Since then #578 changed pins, #587 changed failed
replies, #671 kept the headers on a reply no node answered, and #675
and #670 fixed two of the page's known issues.

backup.md:
- A plain lava-select-provider covers the first attempt only. Its retry
  or hedge can reach a backup. With lava-select-provider-strict: true,
  and for a sticky request, the named node answers or the request fails,
  with no Lava-Retries header.
- Sticky sessions: a node error or a busy node fails the request and
  the session keeps its node. Remove the MAG-4731 known issue (#670).
- What the caller gets: a node's answer goes back as is (status, body,
  Content-Type). All 429 is the node's 429, not 503. A budget that ends
  is 504 "no answer from upstream within <budget>", not 500. A write
  every node answered gets the node's status. Failed replies carry the
  Lava-* headers; only a request that reached no node has none.
- The archive warning: lava-extension: archive now gets
  Lava-Extension-Unavailable when the archive node is out of rotation,
  and that reply is not cached (MAG-4729, #675).

directives.md:
- The pin's "when to use" and "unreachable node" lines: a plain pin is
  retried on another node.
- A pinned write refused with 429 is sent to the other nodes; a sticky
  or strict one gets the 429.
- Response headers: failed replies carry them. Lava-Provider-Address
  lists the nodes asked when none answered. Lava-Retries is absent on a
  write and on a sticky or strict request. Lava-Extension-Unavailable
  also covers an extension no node could serve for this request.

Checked against smart-router main 10c1db19 (v1.6.8-36) with a real
router boot against the provider simulator (2 or 3 primaries, 1
backup): every table row, the pin and sticky cases and the archive case
were sent live. The --shared-state and busy-node cases come from the
code and the router's tests.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

This branch has not been deployed

No deployments
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