Repository navigation
Rate-limit the discovery documents per client address - #1483
Conversation
The SEP-2127 card, the legacy enumerating card and, in oauth mode, the RFC 9728 metadata are answered to anyone before authentication, and nothing bounded how often one caller could ask. The legacy card is 141 KB on the dynamic surface. Issue 1053 decided the shape, and this is it. Each client address, keyed as the authentication budgets key one (the peer, or the address a trusted proxy names, an IPv6 address by its /64), draws on one token bucket for the three documents: 20 a second with 200 in hand by default, 0 for either setting turning it off. Every request to a document path is charged whatever its method, so a 304 revalidation and a CORS preflight cost what a fetch does; /health and the MCP endpoint are not. A refusal is the gate's 429 with Retry-After: 1, code -42900 and readable from any origin, charged to no budget, and its log line carries the limit's two figures and never the address. The middleware sits outside the CORS layer, which answers a trusted origin's preflight before the mux, and inside host validation, so a request refused for its Host is charged nothing; a test pins each side. The table holds 4096 addresses and gives a new one the place of the least recently used, which is how EvictOldest reads for a bucket. Neither that nor stopping the count at the bound limits a caller cycling more addresses than the table, which any IPv6 /48 can, and F-36 accepts that gap. What eviction buys is that an address that keeps asking stays counted, so a flood has to keep cycling, where a table that stopped counting would let a few thousand single requests leave every newcomer uncounted until the sweep. The table is swept of refilled buckets on AUB-005's interval, and that row now names it. Register row RTC-008 declares it, with its values, settings and sites, and F-36 records that no process-wide bucket stands beside it, by the issue's decision: one would let a flood from many addresses deny discovery to every caller. Validate now holds a key before admission to INV-004 as it holds a requester's, which is what makes the finding necessary, and RetryAfterRefill names the register constant the fixed Retry-After comes from. The settings are --discovery-rate-limit-rps and --discovery-rate-limit-burst, and GITLAB_MCP_DISCOVERY_RATE_LIMIT_RPS and GITLAB_MCP_DISCOVERY_RATE_LIMIT_BURST through the HTTP overlay. A malformed or out-of-range value refuses startup, both are HTTP-only flags, and both are announced in the startup record.
The HTTP module fetches each document at every path it is published at under a --public-url prefix, in both auth modes, from an address of its own with a bucket of two: the fetch is served, its revalidation is the second request and answered 304, and the preflight after them is refused with the register's 429, while /health and the MCP endpoint still answer the spent address. It also holds the forwarded address to a trusted proxy, the zero to turning the bucket off through the flag and the variable, and the shipped default to refusing one address past its burst of 200. The stdio module names the two flags as HTTP-only and ignored there.
The discovery bound puts RTC-008 in force in one arm and off in the other, both in oauth mode behind the loopback proxy. Its verbs are document verbs, a GET with no credential and a revalidation of the tag each arm reads first, each recorded under a row of its own. The flood comes from an address per noisy lane; the quiet population is a hosted client's egress address, every lane sharing it, each a user fetching the metadata and the card and then calling. A bucket on the address is offered what every lane sharing that address offers together, so the plan's arithmetic and the default quiet rate count lanes per key, and a bucket can name the flags that set its rate and burst. The bound defaults five times the shipped rate per address, not four: a lane cycles four verbs on fixed ticks and its bucket refills a token every so many ticks, so a multiple of four would hand every token to the same documents. The stand-in serves the three documents with tags and a bucket of its own, so the harness is tested end to end without the server.
The HTTP server page gains a section on the bucket, in English and Spanish: what it charges, its refusal, its two settings, why no process-wide bucket stands beside it, and the figures the defaults were sized from. The CLI, environment, configuration, remote deployment and security pages name the settings and what the address key means behind a proxy the server is not told to believe. The configuration reference lists both settings, the specification records RTC-008 and F-36 and the wider INV-004 check, and CLAUDE.md gains the variables' row.
RetiredEnvUses looked for the bare suffix of every setting this server defines and reported each one it found as "no longer read (removed in 3.1.0)". That is true of the 28 settings 3.0.0 read and of no other: the four authentication budgets became settings in 3.1.0 after the release had stopped reading old spellings, and the discovery documents' two arrive with this change. A bare AUTH_FAILURE_LIMIT or DISCOVERY_RATE_LIMIT_RPS in a shell belongs to another tool if to anybody, and the warning sent its operator to rename a variable this server never read. The settings with an old spelling are now a closed list, hadOldSpelling, which a test holds to those 28 and to the settings the server still defines, so a setting added later needs nothing for its bare suffix to go unreported. The environment reference, in English and Spanish, and the configuration page say which settings have none.
There was a problem hiding this comment.
jmrplens has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 59 minutes. View limit details
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Sorry @jmrplens, your pull request is larger than the review limit of 150,000 diff characters |
|
…kage through it, and give the listen ceiling its flag (#1522) Refs #957 (second of three layers). This is the fifth layer of the configuration stack, on top of the first layer of #957, which recorded the malformed values the issue keeps and taught G14 to find every `GITLAB_MCP_` read outside the configuration rule. This one moves the reads: the twelve variables that layer found are on `prefixedNames` and read through `config.Getenv` or `config.TrimmedGetenv`, the listen ceiling gains the flag `INV-017` asks of a limit in HTTP mode, and F-13 is answered. Every spelling an operator sets today keeps working, and every setting keeps the malformed-value policy it had. The last layer changes the telemetry identity's policy and the rest of the user documentation in both languages. ## What was wrong At the parent, G14 found thirteen variables read around the configuration package. `GITLAB_MCP_ENV_FILE` is the read the issue keeps, since it names the dotenv file to load and is read once before any file is. The other twelve were the issue's to move: `MAX_LISTEN_STREAMS` and `STDIO_MAX_LINE_BYTES` with `os.Getenv` in `cmd/server`, the three telemetry identity settings and the tool-name dimension there too, the telemetry switch with `os.LookupEnv` in `internal/telemetry`, the three `ALLOWED_*_DIRS` with `os.Getenv` in `internal/toolutil`, `DESCRIPTION_SUBSTITUTIONS` with `os.Getenv` in `internal/gatewaycompat`, and `ALLOW_PRIVATE_INSTANCES` through `config.TrimmedGetenv` under its full name, which the helper reads verbatim because the list cannot hold it. The rows that name them (`HLD-001`, `RQB-004`, `IDN-009`, `IDN-014`, `AUT-006`, `DST-003`) carried F-13 for it, and the gate answered the switch and the substitutions with declarations that said they waited for this layer. `INV-017` also asks a limit for a flag in HTTP mode, and the listen ceiling had none, which the register stated as `Source: EnvOnly` and which only F-13 let through `Validate`. ## What changed The twelve names are on `prefixedNames`, in name order, and each reader reads its setting through the configuration package under its suffix, beside the full name its package exports: the warnings of the two ceilings and of the telemetry switch, and the error of a rotation that does not parse, give an operator that name, and the tests set every setting by it. The suffix and the full name are two constants where a package already exported the full one (`toolutil.UploadDirAllowlistEnv` and its two siblings, `gitlabclient.AllowPrivateInstancesEnv`, `gatewaycompat.EnvVar`, the telemetry package's names), and a test holds each pair together: the existing reader tests set the full name and expect the reader to see it, and a new one does it for the three allow-lists. `allowedLocalDirs` takes the setting's suffix now, and `envBool` in the telemetry package hands its value to `parseEnvBool`, which the switch calls with what `config.Getenv` read. An unset variable and an empty one read alike under every reader, as they did. None of the twelve ever answered to another name, and none is reported as one: `RetiredEnvUses` looks only at the closed list of the settings 3.0.0 read (`hadOldSpelling`), so a bare `TELEMETRY` or `ALLOWED_UPLOAD_DIRS` exported by another tool is left alone. `--max-listen-streams` is an env-backed flag: it writes `GITLAB_MCP_MAX_LISTEN_STREAMS` before anything reads it, as `--allow-private-instances` and `--description-substitutions` do, so it applies on both transports, wins over the variable when passed, and a value it does not parse warns and keeps the default, the exception `HLD-001` records. `HLD-001` is configurable now. The help documents the flag in the tool surface group and names it among the flags a stdio run reads, and a test holds both of its ceilings, 64 and the process-wide 512, to the register's values. Both transport modules pass the flag to the real binary beside a variable that allows five streams, and the second listen is refused at the flag's ceiling of one, over HTTP and on stdio, where the flag is not named among those a stdio run ignores. The site's CLI, environment, configuration and HTTP server pages, in English and Spanish, list it where they list the flags that write a variable, and the environment reference no longer says the listen ceiling is set by the environment alone. The local allow-lists showed a gap in the register. `AUT-006` was `EnvOnly`, which `Validate` lets through only with a finding, and once its reads moved F-13 no longer described it. But HTTP mode never reads those lists: a server reached over HTTP refuses every caller-supplied local path before the list is consulted (`RQB-008`), so `INV-017`'s flag would configure nothing. The register gains a source for that, `StdioEnvOnly`, a value only an environment variable changes, of a setting only stdio reads. `Validate` holds it to its variables and its malformed-value policy, refuses a flag on it and a row that does not exist on stdio, and no finding excuses those, since each is the row contradicting itself. `EnvOnly` still needs a finding, and its message now names the clause it departs from. `AUT-006` is the one row on the new source. All six rows drop F-13, which no row carries any more, and `TestDecisions_AFindingNoRowCarries_IsAnsweredByItsIssue` lists it among the findings answered by their issue. G14 keeps F-13 as the finding a row would need if one of its variables were read another way again. The two declarations that waited for this layer are gone, so `readAroundConfig` holds the env file's alone. The two suffix constants in `cmd/server` that G10 reads as limit-shaped are sites of their rows. The contributor configuration page, CLAUDE.md's sentence on the configuration rule, `cmd-utilities.md`, the repository map, `adding-a-limit.md`, ADR-0023 and the specification say what the tree does now, and the specification records F-13 as answered with what moved. ## Where this departs from the plan The plan names "a set of never-retired names". The tree already has it: `hadOldSpelling`, the closed list of the settings 3.0.0 read, which #1483 introduced after the plan was written, is what `RetiredEnvUses` iterates, so a name the list gains is never reported as a removed spelling. I added a test that sets the twelve bare suffixes and expects no report, rather than a second list. The plan puts the table test in `internal/config/env_name_test.go`. The readers live in packages `internal/config` cannot import, and the flags in `cmd/server`, so the table is in `cmd/server/env_flags_test.go`, the one package that sees every reader and every flag; `internal/config` holds the list membership and the retired-name behavior. The plan expected F-13 to be dropped row by row, and did not foresee that `AUT-006` would then fail `Validate`. `StdioEnvOnly` is how I answered that; the alternatives were a flag for each allow-list, which the issue does not ask for and HTTP mode would never read, or keeping a finding that no longer describes the row. `internal/config/env_file.go` is in the plan's file list and is unchanged: its variable is the read the issue keeps. The plan leaves the user documentation to the last layer. The flag's own entries are here, in the commit that adds it, so that no head of this stack serves a flag the site says does not exist; what the site says about the other variables, and about the telemetry identity's refusal, stays with the last layer. Two commits change code the issue does not name, so that the mutation gate measures everything in the files this layer touches, and neither changes behavior. In `internal/gatewaycompat` gremlins reported seven mutants not covered and one lived at the parent, none on a line this layer moves: the seven are the conditions of tagless switch cases in the two splitters and the schema walk, which Go's coverage gives no block of their own, so they are chains of ifs now and the walk's keyword handling is a function of its own; the lived one was `growthLimit`'s comparison, whose boundary mutant returns the same number where the two bounds meet, so it is `max` now. In `cmd/server` the five entries of `envBackedFlags` that built their variable as `config.EnvPrefix` plus a suffix were reported not covered for the same reason, a package-level composite literal carrying no statement counter, and they spell the variable in full now, as the substitutions' entry already did. In the commit that moves the private-instance opt-out, `gitlabclient.AllowPrivateInstancesEnv`, beside the suffix constant it adds, is spelled in full for the same reason. `internal/gatewaycompat` was one statement short of full coverage at the parent, the return for a schema whose JSON cannot be decoded. A raw schema carrying a number no float64 holds takes it, and I added that case to the existing test. ## How I tested it Tests first, each seen failing before the code it holds. At the parent the new register tests do not compile (`StdioEnvOnly` is undefined); with the source declared and the rule unchanged, the seven `TestValidate_ThroughConfig` cases that expect a refusal and `TestDecisions_LocalAllowLists_AreReadFromStdiosEnvironmentAlone` failed. Before each group of reads moved, `TestPrefixedEnvNames_HoldTheSettingsIssue957Moved` failed for each of its names and the table failed on each row's list membership, while its policy subtests passed, which is the point: the policies do not change. The listen ceiling's two flag subtests failed with the flag undefined, and so did the two transport cases, against a binary built from this branch with the flag's entry removed, which exits on `flag provided but not defined: -max-listen-streams`. With `RetiredEnvUses` iterating `prefixedNames` instead of the closed list, `TestRetiredEnvUses_ASettingIssue957Moved_HasNoOldSpelling` fails and reports all twelve bare suffixes as removed spellings. And with the parent's readers put back under this branch's register and gate, `make check-tenancy` reports one G14 finding per variable, twelve, plus the two G1 findings for the suffix constants the rows name; on the branch it reports none. The table, `TestSettingsMovedByIssue957_AValueOfEach_GetsItsPolicyAtTheEnvironmentAndTheFlag`, has one row per setting, twelve rows and 37 leaf cases. Each feeds the variable a value its reader cannot use and one it can, and where the setting has a flag, the flag each value with the variable set to the other, so the flag is seen to win in both directions. A well-formed value must take effect, which also proves the reader reads that variable, and a malformed one must do what the row's policy says: warn and keep the default (the two ceilings, the tool name), refuse (a substitution rule that does not parse, which refuses startup; and an identity or a rotation that does not parse, whose reader returns the error, which is all the table observes for them), skip the entry and keep the rest (the allow-lists, through an upload, a download destination and an import archive in a directory only the variable names), or read as off (the private-instance opt-out, through the door's check of a caller-named private address, and the telemetry switch, whose flag the flag package refuses instead). A row the register names is held to it: the row names the variable, the flag exactly when there is one, and the policy the reader keeps. The key has no malformed value, since every text is a key. The identity and its rotation are where the table measures less than the register states. `IDN-009` says a value that does not parse refuses startup, and today the server logs the reader's error and records nothing about callers instead, which is #1170. That promise is the last layer's to keep, as the plan has it, and there these two rows are to observe the refused start rather than the reader's error; here each says what it observes. `GITLAB_MCP_TEST_SNAPSHOT_PARITY=deferred go test ./... -count=1` passes at the head, 294 packages with tests on `main` at `8e959c3d8`, as this is below the top of the stack, and without the deferral the nine packages that guard a committed-artifact comparison pass as well. `go test ./internal/... ./cmd/server ./cmd/bench_resources` passes. The two transport modules pass in full against the binary built from this tree, `make test-e2e-stdio` (261 tests) and `make test-e2e-http` (736, the 8 that need Docker for the proxy layer skipped), the new case of each among them, and the `e2e` packages compile. Statement coverage is 100.0% for every package this branch touches: `internal/config`, `internal/tenancy`, `internal/telemetry`, `internal/gatewaycompat`, `internal/gitlab`, `internal/toolutil`, `cmd/audit_tenancy` and `cmd/server`. gobco reports every condition evaluated both ways in `internal/tenancy` (568/568), `internal/config` (384/384), `internal/telemetry` (372/372), `cmd/audit_tenancy` (1028/1028), `internal/gitlab` (708/708), `internal/toolutil` (4368/4368, measured again after the rebase onto `main` at `8e959c3d8`, which added code of its own to the package, on the stack's top, where the package is this layer's) and `cmd/server` (2356/2356); it cannot instrument `internal/gatewaycompat`, whose external tests use a helper of its `export_test.go`, at the parent as on the branch, and this branch adds no condition there. `make coverage-mutants` leaves no mutant alive in any package this branch touches, measured at the head: `internal/gatewaycompat` 42 killed, `internal/toolutil` over `file_utils.go` 98, `internal/config` 179, `internal/tenancy` 337, `internal/telemetry` over `telemetry.go` 37, `internal/gitlab` over `destination.go` 105, `cmd/audit_tenancy` over `declarations.go` 23, and `cmd/server` over the five files it changes besides `main.go` (`env_flags.go`, `stdio.go`, `subscriptions.go`, `telemetry.go`, `telemetry_identity.go`) 165, none timed out. The first two report nothing not covered. The others report the tool artifact `docs/development/testing/README.md` describes, mutations of package-level constant and variable initializers that carry no statement counter, none on a line this branch changes: `internal/config` 9 (`config.go`'s size and duration products), `internal/tenancy` 66 (the negative codes, the `iota + 1` enumerations, `grants.go` and `values.go`, as at the parent), `internal/telemetry` 1 (`shutdownTimeout`), `internal/gitlab` 4 (the three concatenations of the advice built from `AllowPrivateInstancesEnv`, and the lookup timeout's product), `cmd/audit_tenancy` 5 (the two module-path concatenations and three reasons written as concatenations), and `cmd/server` 9, the messages of the shared watch endings and of two JSON-RPC errors in `subscriptions.go`, built as concatenations. Before the commit that spells the env-backed flags' variables in full, `cmd/server` reported 14, the other five being those entries, and `internal/gitlab` reported 5 while `AllowPrivateInstancesEnv` was built from the prefix. `main.go` is left out of the run, as in the layers below: what this branch changes there is the help text, lines of one string literal with no operator a mutant could change. `make check-tenancy` reports 0 findings over 90 rows, 393 declared sites and 34 settings read, and `make check-dead-consts` finds no unexported constant left unread. `make check-test-subtests`, `make check-test-goroutines`, `make check-test-file-names`, `make check-e2e-static`, `make check-md-tables`, `go run ./cmd/godoc_tool/ audit`, `go run ./cmd/audit_doc_tool_names/ --check`, `golangci-lint run --build-tags e2e` and `golangci-lint fmt --diff` over the touched packages, `golangci-lint run` and `go vet` over the two transport modules under their `httpe2e` and `stdioe2e` tags, `go vet`, `markdownlint-cli2` on every changed page and `node scripts/check-doc-links.mjs` all pass. No Docker run was made for this layer, which changes no catalog action. `go run ./cmd/gen_testing_docs/ --check` reports `docs/development/testing/testing.md` stale for the test functions this stack adds, which the stack's top layer regenerates once. For the site pages this layer changes, `pnpm run i18n:check`, `facts:check`, `chips:check`, `llms:check`, `build` and `lint` pass. Its sizing page keeps naming the listen ceiling by its variable in the table of knobs, which every other row names by a flag: with the flag there, the English and Spanish tables land on different sides of the stacking threshold, which `facts:check` refuses, and the variable is as true as the flag. --------- Signed-off-by: José M. Requena Plens <mail@jmrp.io>
gitlab-mcp-server 3.4.0 is live (deployed by the update timer on 2026-10-31). This brings the site up to date with it; the deploy after merging also picks up the canonical `#person`, which jmrp.io has updated (the build downloads it since #58, so nothing in this diff carries it). ## Snapshots - Card and surface snapshots refreshed. Still 977 actions: none added or retired, 20 with rewritten descriptions or required parameters, and four fine-grained entries moved (`access.approve_group` and the three Orbit reads). Permissions are still judged at GitLab 19.5.0, and the strict fine-grained extractor met no field it does not know. The card keeps its 2 tools, 37 prompts, 8 resources and 37 templates. ## Limits notice 3.4.0 changes two defaults this deployment runs on, and the gitlab limits notice (EN and ES) now says both: - Failed sign-ins are keyed on an IPv6 address's /64, and once ten /64s of one IPv6 /48 have had a token refused inside the distinct-token window, the whole /48 is blocked up the same ladder (jmrplens/gitlab-mcp-server#1481, register row AUB-006, a constant no flag sets). A token the deployment is already serving stays exempt from every block, which the notice now says too. - The documents served without a credential, both server cards and the RFC 9728 metadata, get a bucket per client address: 20 requests a second in bursts of 200 (jmrplens/gitlab-mcp-server#1483, RTC-008). ## Checked and left as is - Re-measured on 3.4.0: the supported protocol list, `scopes_supported: ["api"]` and the `WWW-Authenticate` challenge; the per-credential budget (60/s, burst 40, catalogue at a tenth) in the replicas' startup log. - The catalog's tier is still Ultimate (the tier test passes) and the documentation site still says 872 on Free/CE and up to 1,099 on GitLab.com. - #1519 gives each limit's zero one meaning: the deployment's flags and environment set no limit to zero, so nothing moves here. The plaintext-listener warning of #1561 is already answered by `GITLAB_MCP_ALLOW_PLAINTEXT_HTTP=true` (logged at INFO). ## Checks - Every `ci.yml` step passes locally; a scratch build with the refreshed `#person` passes html-validate.



Closes #1053.
This is the fourth layer of the authentication-budget stack, on top of the transport-source bound of #982. It puts the three documents the server publishes without a credential behind one token bucket per client address, as the decisions of 2026-10-06 and 2026-10-17 on the issue set out: on by default with figures I measured for it,
0to turn it off, one per-address row in the tenant policy register with the finding that records why it has no process partner, one bucket shared by the three documents, preflights counted,/healthleft out, and a fixedRetry-Afterin the register.What was wrong
The SEP-2127 card (
/server-card,/mcp/server-cardand both under the--public-urlprefix), the legacy enumerating card (/.well-known/mcp/server-card.json) and, in oauth mode, the RFC 9728 metadata are answered to anyone, before authentication, and nothing bounded how often one caller could ask. The server-card extension asks a server to rate-limit requests for its card. The legacy card is 141 KB on the dynamic surface, so two addresses flooding it drew 141 MB/s of egress from the process in my measurement, and every request is a full trip through the HTTP stack.What changed
cmd/server/discovery_rate.goaddsdiscoveryRateLimiter: arate.Limiterper client address in a table of at most 4096 (tenancy.DiscoveryTrackedAddresses), keyed exactly as the authentication budgets key an address (budgetKey(clientIP(...)): the peer, or behind--trusted-proxiesthe address--trusted-proxy-headernames, an IPv6 address by its/64). Its middleware charges every request whose path is one of the documents' paths (discoveryDocumentPaths, the same pathsserveHTTPOnmounts the documents at, prefix included), whatever the method, so a304revalidation and a CORS preflight cost what a fetch does, and passes everything else untouched. A request the bucket cannot pay for is answered429withRetry-After: 1, the gate's JSON-RPC body with code-42900and the words "Too many requests for the discovery documents from this address. Retry later.",Access-Control-Allow-Origin: *andRetry-Afterexposed, so a browser client can read the refusal the way it reads the documents. The refusal is charged to no authentication budget, and it is logged through the same once-a-window throttle the other refusals use, in words that name the limit and not the address.The middleware sits on the root chain, outside the CORS layer and inside host validation. Outside CORS because
corsMiddlewareanswers a trusted origin's preflight itself before the mux is reached, so a bucket wrapped around the document handlers would never see the preflights the decision says to count. Inside host validation so that a request refused for itsHostreaches no document and costs nothing. A test incmd/serverpins each side, and the e2e pins the first on the binary, where the--public-urlorigin is trusted with no--trusted-origins. A table at its bound gives a new address the place of the one used least recently, and the five-minute sweep the authentication tables run on (AUB-005's interval, whose row now names this table too) forgets every bucket that has refilled.The settings are
--discovery-rate-limit-rpsand--discovery-rate-limit-burst, andGITLAB_MCP_DISCOVERY_RATE_LIMIT_RPSandGITLAB_MCP_DISCOVERY_RATE_LIMIT_BURSTthrough the HTTP env overlay, both added toprefixedNames(and given no old spelling, below). Defaults are 20 a second and 200, maxima 1000 and 10000,0for either turns the bucket off, and a malformed, negative, NaN or out-of-range value refuses startup with a message naming the flag (validateDiscoveryRateBounds, called fromvalidateHTTPPoolAndRateBounds). Both are HTTP-only flags, so a stdio run that is given one names it at startup and ignores it, and both are announced in the HTTP startup record, zero included, so an operator who turned the bucket off reads that it is off.The register and the specification
RTC-008is the new row: Allow, a Rate onKeyAddresswith no stdio key, class A,Table: true,AtCapacity: EvictOldest,ProtectsProcesswith no partner, configurable withRefuseStartupandZeroOff, decided by issue 1053 and carrying F-36. Its six values are invalues.gowith their pins (DiscoveryRate,DiscoveryBurst,DiscoveryRateMax,DiscoveryBurstMax,DiscoveryTrackedAddresses,DiscoveryRetryAfter), the server and config constants are declared aliases of them, and every enforcing site is declared on the row, whichmake check-tenancyholds: 89 rows, 387 declared sites, 0 findings.F-36 records the decision of 2026-10-17 that no bucket keyed on the process stands beside this one, a departure from
INV-004: a bucket the whole process shared would let a flood from many addresses deny discovery to every caller, a hosted client's shared egress address first. Recording it needed one change toValidate: itsINV-004check looked only at requester keys, so a per-address row protecting the process with no partner passed without a finding. It now holds a key before admission toINV-004as it holds a requester's, since an address is as mintable as a credential, andRTC-008passes by F-36. No other row is affected; the tenancy suite says so.Retry-Afterneeded a source of its own,RetryAfterRefill, a register constant of a bucket's own (DiscoveryRetryAfter), because the decision asked for a fixed second rather than one derived from the bucket's state, andcmd/audit_tenancy's declarations namediscoveryRetryAfteras the read that satisfies it.Two things differ from the plan this layer was written against, and in both the issue and the code won. The plan said
StopCountingat capacity; I choseEvictOldest, read for a bucket as least recently used, since a bucket has no expiry (the enum's comment now says so). Neither rule limits a caller holding more addresses than the table, which any IPv6/48does: under eviction it cycles them and finds each forgotten when it returns, and against a table that stopped counting it would fill the table and then ask from one more address uncounted until the sweep. Refusing newcomers at the bound would close the gap only by denying discovery to every new address while the flood lasts, which is what the missing partner avoids, so the gap is part of what F-36 accepts, and the row, the specification and the HTTP server page say so. What eviction changes is the cost: an address that keeps asking stays counted, so a flood has to keep cycling through more than 4096 addresses, drawing about one burst from each before it is forgotten, where a table that stopped counting would let a few thousand single requests from distinct/64s leave every newcomer uncounted until the sweep. Evicting also forgets a record against its own address and takes no holding from anybody (INV-005). The plan said to wrap the document handlers; that would miss the preflights CORS answers first, as above.The old spellings
Adding the two variables to
prefixedNamesmadeRetiredEnvUseslook for their bare suffixes and report aDISCOVERY_RATE_LIMIT_RPSin somebody's shell as "no longer read (removed in 3.1.0)", a name no version ever read. The same was already true of the four authentication budgets, which became settings in 3.1.0 after that release had stopped reading old spellings. The last commit makes the settings with an old spelling a closed list,hadOldSpelling, the 28 that 3.0.0 read, held by a test to that count and to the settings the server still defines, so a setting added later needs nothing for its bare suffix to go unreported. The environment reference now says 28 settings and 22 bare names, in English and Spanish, and names the six that have none. This changes behavior for the four authentication budgets too: a bareAUTH_FAILURE_LIMITno longer produces the warning, which was wrong for them.Validation checklist for
RTC-008:KeyAddress, the authentication budgets' key, with its mint cost as the register already states it; no new key.EvictOldestover a table of 4096, least recently used, for the reason above, with the gap past 4096 addresses recorded under F-36.429, code-42900,Retry-After: 1from the register, the words above, readable from any origin; on stdio the documents are not served and the row has no key.0turns it off, a malformed value refuses startup.mcpotel.ServerMiddleware, so a refusal reaches the HTTP server span and metric as a 429 with its method, like every other gate refusal (that layer records no route or path, by design), and the log line carries the limit's two figures and nothing else, never the address, which a test holds to that exact set of attributes.The measurement (VAL-012)
cmd/bench_resourcesgains adiscoverybound formake bench-fairness BOUND=discovery: document verbs (the card, its revalidation with a tag read before the arm, the legacy card, the metadata), each a row of its own; a flood from one address per noisy lane; and a quiet population that is a hosted client's egress address, eight lanes sharing one address, each a user fetching the metadata and the card and then callingtools/call. The bucket is per address, so the plan's arithmetic counts what one bucket is offered rather than what one lane offers.BenchmarkDiscoveryDocumentsincmd/serverprices one request through the real handler chain. I ran both on a 16-thread i5-14400 in a container held to 5 cores:tools/callat 10 to 15 ms at the median in both arms.indistinguishable, for the harness's saturation reason: discovery requests at the rates one address can be held to do not contend for the machine, so what the bucket bounds is each address's draw, not the quiet tenant's latency.That sized the defaults. At 20 a second one address costs the process at most about 2.2 ms of processor a second and 2.8 MB/s of egress on the legacy card. A hosted client's shared egress address has 72,000 discovery requests an hour, so a client that fetches the metadata and the card on every connection connects 36,000 users an hour from one address before its bucket runs dry. A burst of 200 lets a reconnect wave of 100 users from one address through at once.
Retry-Afteris a fixed second, inside which a bucket refilling at 20 a second, or at any rate of one a second or more, has a request to give again; at a configured rate below one a second it is shorter than the refill, which the HTTP server page says. 4096 addresses is the authentication tables' figure, a few hundred kilobytes.The first run used four times the rate per address, and it showed an artifact of the open-loop schedule rather than of the bucket: a lane cycles its four verbs on fixed ticks, a token refilled every fourth tick, and two of the four documents got every token. The bound now defaults five times the rate, and a test holds the ticks per token and the verb count to sharing no factor.
Documentation
The site's HTTP server page gains a section on the bucket in English and Spanish, and the CLI, environment, configuration, remote deployment and security pages name the two settings and what the address key means behind a proxy: behind a proxy the server is not told to believe, every caller shares the proxy's one bucket, so either name the real address or turn it off. The HTTP server page also says what the fixed
Retry-Aftermeans below one request a second, and that a caller cycling more addresses than the table holds is held back by no bucket, so a deployment exposed to that limits these paths at its proxy as well.docs/development/configuration.mdlists both settings and the closed list of old spellings, the specification recordsRTC-008and F-36,docs/development/cmd-utilities.mdand thebench-fairnesscomment describe the new bound, andCLAUDE.mdgains only the variables' row.How it was tested
The tests came first, and every new one is red on the parent as it stood before the stack was rebased onto
main(d14bb760c, now5db3a1700), with this layer's test files copied onto its tree:cmd/server,internal/config,internal/tenancyandcmd/bench_resourcesdo not build (discoveryRateLimiter,DiscoveryRateLimitRPS,RTC-008's constants anddocumentRequestare undefined);cmd/audit_tenancyfailsTestRunMain_TheTree_PassesTheGateon the gate's summary; the fourTestDiscoveryRate_*cases oftest/e2e/httpfail against the parent binary (it refuses the two flags at startup, announces no bucket and serves every fetch), and the stdio case fails onflag provided but not defined: -discovery-rate-limit-rps.cmd/server/discovery_rate_test.go: the burst and its refill, addresses kept apart, the least recent address evicted at the table's bound, the sweep forgetting refilled buckets, zero turning the bucket off, the document paths per mode and prefix, only the document paths charged (a fetch, a preflight and a HEAD from one bucket;/health,/mcpand unserved paths untouched), the refusal's status, body and headers, its log line held to the limit's two figures and no other attribute, the key through a trusted proxy and by/64, andserveHTTPOnwired end to end in both auth modes under a prefix (200, then 304, then a refused preflight from the trusted public origin, with/healthand/mcpstill answered), a request with an undeclaredHostat every document path refused 403 and charged nothing, plus the bounds validation table. The placement tests were shown red on mutants ofserveHTTPOn: with the bucket inside the CORS layer every preflight is answered 204, in the unit test and in the e2e alike, and with it outside host validation the 403s spend the bucket and the next good fetch is refused. A log line given the address fails the attribute test.internal/config:hadOldSpellingheld to the 28 settings 3.0.0 read and to the settings the server defines, andRetiredEnvUsesreporting nothing for the bare suffixes of the four authentication budgets and of the two discovery settings, red on the old loop over every setting.cmd/serverflags, help, startup record and env overlay,internal/tenancy(the row, its pins, F-36, the widenedINV-004check) andcmd/audit_tenancy.test/e2e/http/discovery_rate_test.godrives the real binary: each document at every path under a prefix in both modes, the forwarded address believed only from a trusted proxy,0through the flag and the variable, and the shipped default refusing one address past its burst of 200.test/e2e/stdionames the two flags as ignored on stdio.make test-e2e-http: 703 tests, 8 skipped (the ones that need Docker), none failed.make test-e2e-stdio: 246 tests, none failed (235 before the rebase below;mainadded eleven, Make the stdio pin of register row 11 tell its two failures apart #1469).make check-tenancy,check-dead-consts,check-test-goroutines,check-test-subtests,check-test-file-names,check-doc-tool-names,check-action-ids,check-e2e-static,check-gateway-chars,check-sdk-contextandcheck-md-escapingpass, thee2esuite compiles, andgolangci-lintwith thee2e,httpe2eandstdioe2etags reports nothing on the touched packages.internal/tenancy454/454,internal/config436/436,cmd/audit_tenancy994/994 (1016/1016 before the rebase below, the 22 fewer being in the scaffolding Share the scaffolding the source gates had copied, in goprogram and a new sourcegate package #1479 moved out of the package),cmd/server2356/2356,cmd/bench_resources1592/1592.make coverage-mutantson the files this changes, the others excluded withGREMLINS_FLAGS=--exclude-files, 0 lived and 0 timed out everywhere:cmd/server(discovery_rate.go,main.go,env_overlay.go,http_only_flags.go) 434 killed;internal/config(config.go,http_overlay.go,env_name.go) 176;internal/tenancy(decision.go,validate.go,decisions.go,decisions_allow.go,decisions_admit.go,values.go) 185;cmd/audit_tenancy(declarations.go) 22;cmd/bench_resources(fairness.go,fairness_run.go,fairness_result.go,presenter.go,rpc.go) 465. The not-covered mutants (16, 9, 41, 5 and 9) are all in package-level constant and variable initializers, which carry no statement counter, the tool artifactdocs/development/testing/README.mddescribes. Two of them are lines this layer adds,DiscoveryRetryAfter = 1 * time.Secondand the discovery bound's defaults, and the tests pin both values; every other one is on a line this layer does not touch.i18n:check,facts:check,chips:checkandllms:checkpass, the Markdown tables are formatted, markdownlint is clean andscripts/check-doc-links.mjsfinds every link and anchor.I then rebased the stack onto
mainata0e4e6cf6, with no conflict and every commit's patch unchanged, so the results above were measured on the branch as it stood on19746966465, except the two figures that say otherwise. Of the packages this layer touches,mainmovedcmd/serverandcmd/bench_resourcesin their tests and by one blank line infairness.go(#1472) andcmd/audit_tenancyin its scaffolding (#1479). At this headgo build ./...,go vet,golangci-lint --build-tags e2eandgo teston the five packages pass, each still at 100.0% of statements;make check-tenancystill reports 89 rows, 387 declared sites and 0 findings;make test-e2e-httpandmake test-e2e-stdiopass; gobco oncmd/audit_tenancyis the 994/994 above; andmake check-closed-serversandmake check-godocs, the two gatesmaingained since (#1474, #1478), pass. I did not repeat the mutation runs.