Skip to content

Rate-limit the discovery documents per client address - #1483

Merged
jmrplens merged 5 commits into
issue-982-transport-boundfrom
issue-1053-discovery-rate
Oct 22, 2026
Merged

jmrplens merged 5 commits into
issue-982-transport-boundfrom
issue-1053-discovery-rate

Conversation

@jmrplens

@jmrplens jmrplens commented Oct 21, 2026 •

Copy link
Copy Markdown
Owner

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, 0 to 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, /health left out, and a fixed Retry-After in the register.

What was wrong

The SEP-2127 card (/server-card, /mcp/server-card and both under the --public-url prefix), 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.go adds discoveryRateLimiter: a rate.Limiter per 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-proxies the address --trusted-proxy-header names, an IPv6 address by its /64). Its middleware charges every request whose path is one of the documents' paths (discoveryDocumentPaths, the same paths serveHTTPOn mounts the documents at, prefix included), whatever the method, so a 304 revalidation and a CORS preflight cost what a fetch does, and passes everything else untouched. A request the bucket cannot pay for is answered 429 with Retry-After: 1, the gate's JSON-RPC body with code -42900 and the words "Too many requests for the discovery documents from this address. Retry later.", Access-Control-Allow-Origin: * and Retry-After exposed, 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 corsMiddleware answers 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 its Host reaches no document and costs nothing. A test in cmd/server pins each side, and the e2e pins the first on the binary, where the --public-url origin 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-rps and --discovery-rate-limit-burst, and GITLAB_MCP_DISCOVERY_RATE_LIMIT_RPS and GITLAB_MCP_DISCOVERY_RATE_LIMIT_BURST through the HTTP env overlay, both added to prefixedNames (and given no old spelling, below). Defaults are 20 a second and 200, maxima 1000 and 10000, 0 for 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 from validateHTTPPoolAndRateBounds). 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-008 is the new row: Allow, a Rate on KeyAddress with no stdio key, class A, Table: true, AtCapacity: EvictOldest, ProtectsProcess with no partner, configurable with RefuseStartup and ZeroOff, decided by issue 1053 and carrying F-36. Its six values are in values.go with 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, which make check-tenancy holds: 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 to Validate: its INV-004 check 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 to INV-004 as it holds a requester's, since an address is as mintable as a credential, and RTC-008 passes by F-36. No other row is affected; the tenancy suite says so.

Retry-After needed 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, and cmd/audit_tenancy's declarations name discoveryRetryAfter as 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 StopCounting at capacity; I chose EvictOldest, 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 /48 does: 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 prefixedNames made RetiredEnvUses look for their bare suffixes and report a DISCOVERY_RATE_LIMIT_RPS in 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 bare AUTH_FAILURE_LIMIT no longer produces the warning, which was wrong for them.

Validation checklist for RTC-008:

  • VAL-001: Allow.
  • VAL-002: KeyAddress, the authentication budgets' key, with its mint cost as the register already states it; no new key.
  • VAL-003: class A, stated and reason unit the process.
  • VAL-004: a ceiling on a rate, not a share.
  • VAL-005: it protects the process and has no process partner, by issue 1053's decision, recorded as F-36.
  • VAL-006: EvictOldest over a table of 4096, least recently used, for the reason above, with the gap past 4096 addresses recorded under F-36.
  • VAL-007: the gate's 429, code -42900, Retry-After: 1 from the register, the words above, readable from any origin; on stdio the documents are not served and the row has no key.
  • VAL-008: charges nothing; no authentication budget sees a discovery refusal.
  • VAL-009: 20 a second and 200, maxima 1000 and 10000, configurable, 0 turns it off, a malformed value refuses startup.
  • VAL-010: no new telemetry. The middleware sits inside 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.
  • VAL-011: nothing on stdio, where no document is served; the two flags are named and ignored there.
  • VAL-012: the measurement below.

The measurement (VAL-012)

cmd/bench_resources gains a discovery bound for make 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 calling tools/call. The bucket is per address, so the plan's arithmetic counts what one bucket is offered rather than what one lane offers. BenchmarkDiscoveryDocuments in cmd/server prices one request through the real handler chain. I ran both on a 16-thread i5-14400 in a container held to 5 cores:

  • One request is a round trip of 40 to 95 microseconds whatever the document, dominated by HTTP itself; a refusal costs about what the metadata does. The SEP-2127 card is 1,371 bytes, the legacy card 140,934, the metadata 288, a refusal 132.
  • Sixteen addresses flooding at 100 a second each: 0.25 and 0.30 cores busy without the bucket, 0.26 and 0.22 with it; every flooding address refused four requests in five with it in force, each document row served its share; the shared egress address refused nothing in either arm; the quiet tenant's tools/call at 10 to 15 ms at the median in both arms.
  • Two addresses at 2,000 a second each: 0.42 to 0.47 cores without the bucket, 0.37 with it, most of what remains being the refusals themselves (about 92 microseconds each against about 110 served); the legacy card's egress falls from 141 MB/s to about 1.6 MB/s; the shared egress address refused nothing.
  • The verdict of every run is 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-After is 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-After means 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.md lists both settings and the closed list of old spellings, the specification records RTC-008 and F-36, docs/development/cmd-utilities.md and the bench-fairness comment describe the new bound, and CLAUDE.md gains 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, now 5db3a1700), with this layer's test files copied onto its tree: cmd/server, internal/config, internal/tenancy and cmd/bench_resources do not build (discoveryRateLimiter, DiscoveryRateLimitRPS, RTC-008's constants and documentRequest are undefined); cmd/audit_tenancy fails TestRunMain_TheTree_PassesTheGate on the gate's summary; the four TestDiscoveryRate_* cases of test/e2e/http fail against the parent binary (it refuses the two flags at startup, announces no bucket and serves every fetch), and the stdio case fails on flag 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, /mcp and 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, and serveHTTPOn wired end to end in both auth modes under a prefix (200, then 304, then a refused preflight from the trusted public origin, with /health and /mcp still answered), a request with an undeclared Host at every document path refused 403 and charged nothing, plus the bounds validation table. The placement tests were shown red on mutants of serveHTTPOn: 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: hadOldSpelling held to the 28 settings 3.0.0 read and to the settings the server defines, and RetiredEnvUses reporting 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/server flags, help, startup record and env overlay, internal/tenancy (the row, its pins, F-36, the widened INV-004 check) and cmd/audit_tenancy.
  • test/e2e/http/discovery_rate_test.go drives the real binary: each document at every path under a prefix in both modes, the forwarded address believed only from a trusted proxy, 0 through the flag and the variable, and the shipped default refusing one address past its burst of 200. test/e2e/stdio names 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; main added 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-context and check-md-escaping pass, the e2e suite compiles, and golangci-lint with the e2e, httpe2e and stdioe2e tags reports nothing on the touched packages.
  • Statement coverage is 100% and condition coverage (gobco) complete on every touched package: internal/tenancy 454/454, internal/config 436/436, cmd/audit_tenancy 994/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/server 2356/2356, cmd/bench_resources 1592/1592.
  • make coverage-mutants on the files this changes, the others excluded with GREMLINS_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 artifact docs/development/testing/README.md describes. Two of them are lines this layer adds, DiscoveryRetryAfter = 1 * time.Second and the discovery bound's defaults, and the tests pin both values; every other one is on a line this layer does not touch.
  • The site builds and lints, i18n:check, facts:check, chips:check and llms:check pass, the Markdown tables are formatted, markdownlint is clean and scripts/check-doc-links.mjs finds every link and anchor.

I then rebased the stack onto main at a0e4e6cf6, with no conflict and every commit's patch unchanged, so the results above were measured on the branch as it stood on 19746966465, except the two figures that say otherwise. Of the packages this layer touches, main moved cmd/server and cmd/bench_resources in their tests and by one blank line in fairness.go (#1472) and cmd/audit_tenancy in its scaffolding (#1479). At this head go build ./..., go vet, golangci-lint --build-tags e2e and go test on the five packages pass, each still at 100.0% of statements; make check-tenancy still reports 89 rows, 387 declared sites and 0 findings; make test-e2e-http and make test-e2e-stdio pass; gobco on cmd/audit_tenancy is the 994/994 above; and make check-closed-servers and make check-godocs, the two gates main gained since (#1474, #1478), pass. I did not repeat the mutation runs.

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.

@greptile-apps greptile-apps 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.

jmrplens has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

@jmrplens
jmrplens added this pull request to stack #1486 October 21, 2026 23:21
@coderabbitai

coderabbitai Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You'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.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Repository: jmrplens/gitlab-mcp-server/.coderabbit.yaml
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 33ab95a0-f354-472d-919b-5b3e435abca8
📥 Commits

Reviewing files that changed from the base of the PR and between 5db3a17 and b37e828.

📒 Files selected for processing: 54
  • .github/copilot-instructions.md
  • CLAUDE.md
  • Makefile
  • cmd/audit_tenancy/declarations.go
  • cmd/audit_tenancy/main_test.go
  • cmd/bench_resources/fairness.go
  • cmd/bench_resources/fairness_result.go
  • cmd/bench_resources/fairness_run.go
  • cmd/bench_resources/fairness_run_test.go
  • cmd/bench_resources/fairness_test.go
  • cmd/bench_resources/presenter.go
  • cmd/bench_resources/presenter_test.go
  • cmd/bench_resources/rpc.go
  • cmd/bench_resources/rpc_test.go
  • cmd/bench_resources/testdata/standin/main.go
  • cmd/server/discovery_rate.go
  • cmd/server/discovery_rate_test.go
  • cmd/server/env_overlay.go
  • cmd/server/env_overlay_test.go
  • cmd/server/http_only_flags.go
  • cmd/server/main.go
  • cmd/server/main_test.go
  • docs/development/cmd-utilities.md
  • docs/development/configuration.md
  • docs/development/tenant-policy-spec.md
  • internal/config/config.go
  • internal/config/env_name.go
  • internal/config/env_name_test.go
  • internal/config/http_overlay.go
  • internal/config/http_overlay_test.go
  • internal/tenancy/decision.go
  • internal/tenancy/decision_test.go
  • internal/tenancy/decisions.go
  • internal/tenancy/decisions_admit.go
  • internal/tenancy/decisions_allow.go
  • internal/tenancy/decisions_test.go
  • internal/tenancy/validate.go
  • internal/tenancy/validate_test.go
  • internal/tenancy/values.go
  • internal/tenancy/values_test.go
  • site/src/content/docs/configuration.mdx
  • site/src/content/docs/es/configuration.mdx
  • site/src/content/docs/es/operations/http-server.mdx
  • site/src/content/docs/es/operations/remote-deployment.mdx
  • site/src/content/docs/es/operations/security.mdx
  • site/src/content/docs/es/reference/cli.mdx
  • site/src/content/docs/es/reference/environment.mdx
  • site/src/content/docs/operations/http-server.mdx
  • site/src/content/docs/operations/remote-deployment.mdx
  • site/src/content/docs/operations/security.mdx
  • site/src/content/docs/reference/cli.mdx
  • site/src/content/docs/reference/environment.mdx
  • test/e2e/http/discovery_rate_test.go
  • test/e2e/stdio/http_only_flags_test.go
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sourcery-ai

sourcery-ai Bot commented Oct 21, 2026

Copy link
Copy Markdown

Sorry @jmrplens, your pull request is larger than the review limit of 150,000 diff characters

@jmrplens jmrplens added this to the 3.4.0 milestone Oct 21, 2026
@jmrplens jmrplens changed the title issue 1053 discovery rate Rate-limit the discovery documents per client address Oct 21, 2026
@github-actions github-actions Bot added transport stdio and HTTP transports, the server process, and the transport e2e modules tooling The audit and generator commands under cmd/, and the Makefile targets that run them labels Oct 21, 2026
@sonarqubecloud

Copy link
Copy Markdown

@jmrplens
jmrplens merged commit 491eb0a into main Oct 22, 2026
39 checks passed
@jmrplens
jmrplens deleted the issue-1053-discovery-rate branch October 22, 2026 03:21
jmrplens added a commit that referenced this pull request Oct 26, 2026
…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>
jmrplens added a commit to jmrplens/mcp.jmrp.io that referenced this pull request Nov 1, 2026
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

tooling The audit and generator commands under cmd/, and the Makefile targets that run them transport stdio and HTTP transports, the server process, and the transport e2e modules v3.4.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Rate-limit the unauthenticated discovery documents, with a switch to turn it off

1 participant