docs(relay): a repeated idempotency key replays, it does not 409 - #1
Merged
Conversation
The gateway grew a translation layer for `/v1/relay/*` (nautilus v1.7.3) and the published reference was corrected to match what Relay actually does: a second send with an `idempotency_key` that was already accepted returns 202 with the *originally* accepted message — same id, same timestamp — rather than a 409. A retry of a request whose response was never seen therefore needs no special handling; there is no duplicate to tell apart from a success. `test_send_409_duplicate` asserted the old promise. Replaced with `test_send_replays_a_repeated_idempotency_key`, which drives two sends under one key and asserts the same message comes back. Error mapping is not lost with it — `test_send_400_error` and the two 429 tests already cover that, on statuses the API really returns. Docstrings now say what the parameters do: the idempotency semantics above, `limit` clamped at 100 rather than rejected, and `next_cursor` null on the last page — so paginate until `has_more` is False, not until `data` comes back empty. Until v1.7.3 `cursor` and `event_type` were forwarded to an upstream that names them differently and ignores what it does not recognise, so both were silently no-ops and a paginating client re-read page one forever. `Message.status` is documented as always `"accepted"`: it records that Relay took the event, not what each subscriber endpoint did with it. No behaviour change — the request this SDK builds was already the documented one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Follows nautilus v1.7.3, which gave
/v1/relay/*a translation layer so the gateway answers the contract we publish instead of its upstream's.Docs and one test — no behaviour change. The request this SDK builds was already the documented one.
The test asserted a promise the API does not keep
test_send_409_duplicatemocked a409and expectedVerneAPIError. A second send with anidempotency_keythat was already accepted returns202with the originally accepted message — sameid, sametimestamp. That is the more useful contract: a retry of a request whose response you never saw needs no special handling, because there is no duplicate to tell apart from a success.Replaced with
test_send_replays_a_repeated_idempotency_key, which drives two sends under one key and asserts the same message comes back. Error mapping is not lost with it —test_send_400_errorand the two 429 tests already cover that, on statuses the API really returns.Worth knowing: until v1.7.3 the key did nothing at all. It is a body member in our reference and a header at the upstream, and the upstream drops body members it does not recognise — so every send was non-idempotent no matter what the caller passed. The gateway now maps it across.
Docstrings
Both the sync and async resources, saying what the parameters really do:
limitabove 100 is clamped to 100 rather than rejectednext_cursorisNoneon the last page — paginate untilhas_moreisFalse, not untildatacomes back emptyUntil v1.7.3
cursorandevent_typewere forwarded to an upstream that names them differently and ignores what it does not recognise, so both were silently no-ops and a paginating client re-read page one forever.Message.statusis documented as always"accepted": it records that Relay took the event, not what each subscriber endpoint did with it.Not in this PR
SPEC_PYTHON.mdsays the same things and has the same corrections applied locally, but it is untracked in this repository — left for whoever adds it.Companion PRs
Same correction in vrn-sdk-node, vrn-sdk-php and nautilus-rs.
🤖 Generated with Claude Code