docs: correct the rate limiting description for the shipped design - #7
Merged
Merged
Conversation
Three fixes from implementing COW-1128. An unknown address is admitted at the lowest tier, not rejected: the service cannot distinguish a never-seen address from an empty one, and rejecting on absence would lock out every new sub-solver. The per-IP filter belongs to the edge, not the request path. A request rejected there costs no socket, no ecrecover, and no connection-pool slot — but only if the origin is unreachable directly, otherwise the forwarded client-IP header is attacker-controlled. The synchronous rejection table gains the escrow floor gate, and the integration guide gains 429 and 503 semantics with Retry-After.
Review of the implementation moved the gate to POST only. Effective escrow balance reads as zero from the moment a sub-solver requests a withdrawal, so a gate on every verb left it unable to cancel — or even see — the proposals it still had live, while they stayed live until they expired. Refusing a cancellation is the wrong direction: it is the action that reduces exposure for both sides. The design document's rate limiting paragraph and pipeline table, the overview's synchronous-rejection table, and the integration guide's error table and rate-limit section all said or implied the gate applies everywhere.
The consolidated 'why proposals get discarded' table was dropped when overview.md was refactored into a navigation page. Restore it as a subsection of the proposal lifecycle, including the escrow floor gate row (submission-only) added on this branch.
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
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.
Four corrections to the rate limiting description, from implementing COW-1128 in
bleu/byos-service-ts(PR #49). Each is a place where the shipped design and the document disagree, and in each case the document is the one that needs to move.The document said signers below the minimum escrow are "rejected outright". The service cannot do that: it cannot distinguish a never-seen address from an empty one without a chain read on the request path, which the same paragraph forbids. So an unknown address is admitted at the lowest tier and only a known-underfunded one is rejected. Rejecting on absence would lock out every new sub-solver on its first request. The reject-early pipeline also attributed the IP filter to the request path; it belongs at the edge, where a rejected request costs no socket, no
ecrecover, and no connection-pool slot — but only while the origin is unreachable directly, otherwise the forwarded client-IP header is attacker-controlled and anything keyed on it is poisoned. That caveat is now stated rather than assumed, since it is the load-bearing precondition for the whole layer.The floor gate is also scoped to submission, which came out of reviewing the implementation. Effective escrow balance reads as zero from the moment a sub-solver requests a withdrawal, so a gate on every verb left it unable to cancel — or even see — the proposals it still had live, while they stayed live until they expired. Refusing a cancellation is the wrong direction: it is the action that reduces exposure for both sides. The design document's paragraph and pipeline table, the overview's rejection table, and the integration guide's error table all said or implied otherwise.
The overview's synchronous-rejection table gains the escrow floor gate, and the integration guide gains a section on
429,503andRetry-After, plus rows in its error table. The guide is explicit that the reference clients ignoreRetry-Afterand that this is a limitation of the examples rather than a pattern to copy.Once this merges,
byos-service-tsbumps its submodule pointer.