Skip to content

Close the condition and mutation gate of cmd/server, and gate the files only Windows and macOS build - #1206

Merged
jmrplens merged 3 commits into
fix/orbit-query-current-dslfrom
fix/server-condition-gate-remainder
Oct 6, 2026
Merged

jmrplens merged 3 commits into
fix/orbit-query-current-dslfrom
fix/server-condition-gate-remainder

Conversation

@jmrplens

@jmrplens jmrplens commented Oct 6, 2026 •

Copy link
Copy Markdown
Owner

#1064 made the condition gate able to read cmd/server at all, by measuring it in a staged copy of the module without the files Linux does not build, and #1017 stayed open for what that left. Two things: the conditions and mutants of cmd/server that no test decided, and the files a Linux run leaves out, which nothing measured anywhere. This closes both.

cmd/server on Linux

At e19b579 gobco measured 2229 of 2270 conditions of cmd/server both ways. The 41 left are the list #1089 carried, less one closed since. Every one is answered here: the package now measures 2236 of 2236, the total lower because some conditions were removed rather than tested. The whole package was then put through gremlins, which had only ever run on the files a change touched. That run found 10 lived mutants and 1 timed out, all answered below. Its not-covered mutants sit where gremlins has no statement counter to read, and every one of them that compiles was applied by hand and fails the suite (see Measured).

Most of the answer is tests, each for a case nothing exercised: a shorter block checked after a longer one (longestAuthBlock), the guard's two refusals with no rejected-token cache, a challenge with no scope or no metadata URL, a capture of a handler that wrote nothing, a pseudo-version whose patch overflows an int, request ids a decoder never hands over (an unterminated string, +1, 4-2), both credentials on a terminal, a public URL that does not parse, an instance list entry with no host, the singular gitlabURL field, a prebuilt catalog on the dynamic and meta surfaces, a second WriteHeader and a second stop of the SSE heartbeat, a card preflight that names no header, a lone - among a peer's arguments, a probe target that does not parse, a peer that exited between being listed and having its command line read, WithGroup(""), forget among two shapes, a shape registry with no registration hook, a staging descriptor that names something other than a directory, closing a socket whose path is already gone, a listen carrying prompts or resource list-changed beside its resources, and the telemetry tool-name flag not registered at all. The Cygwin half of the terminal check is false on every platform but Windows, so it is reached through a seam, isCygwinTerminal, as osExecutable already is.

Some conditions could never take their other value, and those are code changes rather than tests:

  • transportBudget.window tested effectiveWindow <= 0, which newTransportBudget has already resolved to the default, so a budget that exists answers its own window. That is the lived mutant The condition gate cannot instrument cmd/server: gobco panics on build-constrained duplicates #1017 named, and the window now falls back in two places rather than the three AUB-002 described, so its comment in internal/tenancy says two (Limits disagree on what zero means, keep their defaults in two places, and state no rule for what happens at capacity #958 owns the rest of that).
  • requireExplicitInstance tested for a nil request, which an HTTP handler is never given; securityHeadersMiddleware tested for a nil body, which net/http never hands a server; newReadinessGate tested for a nil context, which no caller passes; listenUnix tested filepath.Dir for an empty string, which it never returns; and both Serve loops tested their error for nil, which Serve never returns.
  • isUnixSocketAddr asked about the native separator and then about /, so on every platform but Windows the second question was reached only when the first had said no to the same byte. One strings.ContainsAny asks both.
  • sdkLogHandler.WithGroup("") now returns the receiver, as slog's contract for the method says. Passing the empty name on was not harmless: the JSON handler opens a group with no name for it, so the attributes after it were nested under "" while this handler, seeing no group, still renamed them. The Logger never forwards an empty name, so nothing served changes.

The rest are mutants that no input can tell from the original, which is the code saying it carries something it does not need: a capacity hint in publicPaths, a servers counter in runProbe that only ever meant "a failure was recorded", an n > 0 guard before a scan that answers false for no bytes, a len(commit) > 7 before a cut that min makes, an IndexByte boundary that strings.Cut replaces, a deadline comparison context.WithTimeout already makes, a sort.Slice < that cmp.Compare replaces, the two branches of metricHostsFor that answered the environment's instance the same way, and the check that skips the catalog text rewriter when there is nothing to substitute, which now lives in catalogTextRewriter with a test of its own. The SSE heartbeat's idleness boundary took a parameter instead: writeKeepAlive is handed the tick it answers, so a test holds the exact interval, which a call to time.Since cannot. The readiness gate's exemption for unmarked connections timed out rather than dying, because its mutant deadlocks registration and the first test to register waited for it without a bound; that helper now waits at most testHTTPLivenessTimeout, and the mutant is killed in 37 seconds.

Eleven tagless switches had a case expression gremlins reports as not covered, since a case expression carries no statement counter of its own. They are rewritten as the chains of returns or ifs the repository already uses for that reason (isRequestID, validateTLSFiles, metricHostsFor, prepareStdioCatalog twice, shutdownHTTPServer, parseProbeTarget, sanitizedInput.Read and readLine, logKeyringChoice, inferTransport). sanitizedInput.Read gave its line handling to an accept method on the way, which golangci-lint's nesting rule asked for.

The Windows and macOS halves, in CI

The cross-platform job's Windows and macOS legs now run scripts/coverage-conditions.sh on cmd/server and internal/toolutil through bash, not make, with GOBCO_GATE=beyond:linux/amd64. The step gates. It fails the leg on a condition not evaluated both ways in a file that leg builds and linux/amd64 does not, and prints, counts and passes one in a file Linux builds too. Holding the shared files there as well would fail a leg over a test the platform skips, for a condition the Linux run decides both ways: measured on Windows, that is 20 conditions of cmd/server and 12 of internal/toolutil, every one of them both ways on Linux. That Linux run is the local one, GOBCO_GATE=all make coverage-conditions, which every touched package passes before it is committed. No CI step runs gobco on Linux, before this change or after it, so the shared files are held by that run and not by CI; the step's comment and the testing README say so.

The script gained what the step needs. GOBCO_GATE makes the report a gate: unset it passes whatever it found, as before; all fails on any condition gobco names as never true, never false or never evaluated, which is the gate a touched package is held to locally; beyond:GOOS/GOARCH holds only the files the named platform does not build, asked of the go command under that platform and the same tags. A value it cannot read is refused before gobco runs. GOBCO_TEST_FLAGS hands gobco's go test flags of its own, here -timeout=30m, since gobco runs it with go test's ten-minute default and cmd/server is about three times slower on Windows.

Windows builds four sources of cmd/server Linux does not (conn_refused_windows.go, socket_mode_windows.go, probe_other.go, descriptor_limit_other.go) and two of internal/toolutil (download_output_other.go, file_utils_other.go); macOS builds only probe_other.go beyond Linux. Two of them carry conditions. The connection-refused check's two operands were already decided by its own test. The Windows listen's failure was decided by nothing, so socket_mode_windows_test.go now binds under a directory that does not exist, and binds where it can. Running golangci-lint over the package with GOOS=windows, which nothing in CI does, reported two findings in those files, both corrected here: Winsock's refusal constant is renamed errWSAEConnRefused, as errname asks of a sentinel error, and a misspelling in socket_mode_windows.go's file comment is fixed.

Measured

On the Windows Server 2025 test VM (Go 1.27.1, PortableGit 2.55.0's bash 5.3, 4 cores), the step as CI runs it: cmd/server 2180/2206, every condition of the four Windows-only files both ways, 20 shared conditions left to Linux; internal/toolutil 3836/3848, both Windows-only files both ways, 12 left to Linux; exit 0, 15 minutes for the two. The leg took 20 minutes before, so it stays well inside its 60. That run was on the tree before the last mutant fixes, which changed only files Linux builds too, before the rename above, which changes no condition, and before this branch moved onto the two layers below it in this stack, whose only change to these two packages is internal/toolutil/errors.go (the bound on a reflected message and Workhorse's Orbit query refusal), a file Linux builds too. That file adds 20 conditions to internal/toolutil which the Windows figure predates, all of them in the shared files the step does not gate; what it gates on Windows, the six files Linux does not build, is the same at the head.

On linux/amd64 at the head: cmd/server 2236/2236 and internal/toolutil 3870/3870 with GOBCO_GATE=all, and internal/tenancy, whose comments changed, 444/444. The register row and the testing README carry the 3870.

gremlins over the whole of cmd/server, --workers 2, in three groups of files run side by side on the same tree (main.go with the flag files; the gate, guard, probe, subscription, stdio and session-owner files; the rest): Killed 1249, Lived 10, Not covered 47, Timed out 1, of 1307 mutants. Every file a fix then changed was run again on the final tree: main.go Killed 354, Lived 0, Not covered 16; probe.go 73, 0, 2; health.go and readiness.go 50, 0, 0; and stdio.go, whose group had started before its line handling moved into accept, 58, 0, 0. None timed out. A gremlins dry run on the head lists the same 47 not-covered mutants (1242 runnable), every one of them in a place that has no statement counter of its own: a constant or package-level variable initializer, or the two Windows files, which gremlins mutates although Linux never compiles them. Not covered is not the same as asserted, so I applied the initializer mutants by hand and ran the whole cmd/server suite on each. The 23 that turn a + between strings into a - do not compile. The other 22, in 19 distinct forms (a timeout's * turned into /, a refusal code losing its sign, maxUnixPathLen's - 1 becoming + 1), each fail the suite: the HTTP server timeouts through TestHTTPServerTimeouts_AreDeadlinesRatherThanTheAbsenceOfOne, all three forms of idleTimeoutDisabled through TestIdleTimeoutDisabled_OutlastsEveryOtherDeadline, the two refusal codes through TestRefusalCodes_MirrorTheirStatusAndSitWhereTheSpecificationAllows, the socket path limit through TestMaxUnixPathLen_IsTheLongestPathAnAddressCanCarry, stdioRereadTimeout through TestRefreshStdioAuthority_FollowsTheInstanceUntilTheContextEnds, httpShutdownTimeout through four tests, TestHTTPShutdownTimeout_SitsInsideTheBracketItsCommentArgues among them, the probe's timeout and budget and the telemetry, startup-drain, stale-socket, pprof and shutdown-grace timeouts each through tests of their own, and sseKeepAliveInterval at zero by panicking time.NewTicker.

The script's tests (26, among them nine new for the gate, the test flags and the CI step) pass under bash 5 and under bash 3.2.57, the version macOS ships as /bin/bash, in a bash:3.2 container.

Gates

This is the third layer of a stack: it sits on the Orbit query layer for #1031, which sits on the layer raising the bound on GitLab's reflected message, which sits on main at fbf81ff. Since the base this branch was first measured on, 862e393, nothing below it has changed cmd/server, and what main had gained before that, since the base the mutation runs measured, changes only string literals there (help text, a flag's usage, the first-run guidance), which no mutator touches, so the cmd/server mutation figures carry. Below it, #1199 changed IDN-013's text and added one of its declared sites in internal/tenancy, and the two layers changed internal/toolutil/errors.go; those two packages' figures were measured again. Everything below ran on the head of this branch; the one conflict of the rebase was docs/development/testing/testing.md, which was regenerated rather than merged.

  • go build ./..., and go test -count=1 -cover: cmd/server, internal/tenancy and internal/toolutil 100.0% of statements.
  • GOBCO_GATE=all make coverage-conditions: cmd/server 2236/2236, internal/toolutil 3870/3870, internal/tenancy 444/444. The internal/toolutil figure was taken again after the layer below began refusing a null message in Workhorse's query refusal, which added its four conditions.
  • make coverage-mutants PKG=./internal/tenancy: Killed 239, Lived 0, Not covered 67 (every one an iota or constant declaration), Timed out 0. cmd/server as above.
  • golangci-lint run --build-tags e2e on ./cmd/server/... and ./internal/tenancy/...: clean, and clean on cmd/server under GOOS=windows and GOOS=darwin.
  • go vet of cmd/server and internal/toolutil for windows and darwin on amd64 and arm64: clean.
  • make check-test-subtests, check-test-goroutines, check-test-file-names, check-action-ids, check-md-escaping, check-doc-tool-names, check-surface-quality, check-tenancy, check-sdk-context, check-dead-consts, check-e2e-static, check-orbit-record, check-gateway-chars, audit-catalog-first, check-action-grants-derivation, audit-1to1, audit-1to1-sdk, audit-1to1-paths and audit-1to1-grants: all pass.
  • check-testing-docs, check-llms, check-tool-reference, check-lhm-manifest, check-footprint, check-site-stats and check-action-grants: all pass.
  • go run ./cmd/format_md_tables/ --check, node scripts/check-doc-links.mjs, markdownlint-cli2 on the changed Markdown, make check-em-dash: pass.
  • python3 -m unittest scripts/coverage_conditions_sh_test.py: 26 tests pass under bash 5.2. The run under bash 3.2.57 in a bash:3.2 container was before the rebase, which changed neither the script nor its tests.
  • actionlint v1.7.7 on ci.yml: no findings. That run had no shellcheck on its path, so shellcheck 0.9.0 was run on its own over the step's run block and over scripts/coverage-conditions.sh: no findings. Before the rebase, actionlint v1.7.7 with shellcheck 0.10.0 had found none either.

Decisions I took here

  • The cross-platform step gates rather than reports, and gates only the files Linux does not build, for the reason above. The shared files stay with the local GOBCO_GATE=all run on Linux that a touched package passes before it is committed; this change adds no Linux gobco step to CI.
  • The step runs on Windows and macOS only. Linux builds none of the files it would hold.
  • A Go runtime crash of The Windows CI leg crashes intermittently inside the Go runtime #467 fails this step the way it fails the unit suite's first run, and the answer is the same: rerun the failed job. The step does not reproduce the crash-aware runner's retry.
  • Conditions no input can reach were removed rather than tested through their impossible state, and equivalent mutants were answered by rewriting the code they sat in rather than by declaring them.
  • The two stale test comments the godoc audit reported in main_test.go were corrected on the way, since the package was being held to its gates anyway.

Not done

  • The macOS leg was not run: no macOS machine was available. What it depends on was checked instead: the script's tests under bash 3.2.57, and its tools being the ones a macOS runner has (BSD awk, tar, mktemp and tr behave the way the tests exercise them). macOS builds only probe_other.go beyond Linux, which carries no condition, so the leg holds nothing today and is there for the next file only it builds.
  • gremlins does not honor build constraints either, so the two Windows files' mutants are reported not covered on Linux and measured nowhere. A gremlins run on Windows would answer them, and that is not this change.
  • The e2e harness and retiring the staged copy wait on gobco honoring build tags, register row 73, and stay with Measure the e2e harness's conditions once gobco can instrument it, and retire the staged module copy #1099.

Closes #1017.

gobco measured 2229 of 2270 conditions of cmd/server both ways, and
gremlins had only ever run on the files a change touched. The package
now measures 2236 of 2236. A whole-package gremlins pass found 10 lived
mutants and 1 timed out; each was answered below, and every file the
answers changed was run again with none lived and none timed out.

Most of the answer is tests, each for a case nothing exercised. The
Cygwin half of the terminal check is false on every platform but
Windows, so it is reached through a seam, isCygwinTerminal.

Conditions that could never take their other value are removed rather
than tested: transportBudget.window tested a window its constructor
had already resolved, which is why AUB-002's comment in
internal/tenancy now says the window falls back in two places; a nil
request, a nil body, a nil context, an empty filepath.Dir and a nil
error from Serve are things the code is never handed. isUnixSocketAddr
asks one strings.ContainsAny instead of two questions about the same
byte, and sdkLogHandler.WithGroup("") returns the receiver as slog's
contract says, where it used to nest the attributes after it under an
empty group the JSON handler opened.

Equivalent mutants are answered by rewriting the code they sat in: a
capacity hint, a counter that only meant "a failure was recorded", a
guard before a scan that answers false for no bytes, a cut min makes,
an IndexByte boundary strings.Cut replaces, a deadline comparison
context.WithTimeout already makes, a sort comparator cmp.Compare
replaces, two branches of metricHostsFor that answered alike, and the
catalog text rewriter's empty check, now catalogTextRewriter.
writeKeepAlive is handed the tick it answers, so a test holds the
exact interval. The fine-grained shell helper waits for registration
with a bound, which turns the readiness gate's deadlocking mutant from
a timeout into a kill.

Eleven tagless switches whose case expressions gremlins reports as not
covered are rewritten as chains of returns or ifs, and
sanitizedInput.Read hands its line handling to an accept method.
scripts/coverage-conditions.sh measures a package in a staged copy of
the module without the files the go command does not build here
(upstream-bugs row 73), so the platform halves of cmd/server and
internal/toolutil were measured nowhere.

The script gains GOBCO_GATE. Unset it reports as before; all fails on
any condition gobco names as never true, never false or never
evaluated; beyond:GOOS/GOARCH fails only on such a condition in a file
this build compiles and the named platform does not, asked of the go
command under that platform and the same tags, and prints, counts and
passes the rest. A value it cannot read is refused before gobco runs.
GOBCO_TEST_FLAGS hands gobco's go test flags of its own.

The cross-platform job's Windows and macOS legs run the script through
bash on both packages with GOBCO_GATE=beyond:linux/amd64 and
-timeout=30m, so a condition left one-way in a file Linux does not
build fails the leg. The shared files stay with the GOBCO_GATE=all run
a touched package passes on Linux before it is committed, which no CI
step runs.

socket_mode_windows_test.go decides the Windows listen's failure,
which nothing exercised. golangci-lint under GOOS=windows reported
two findings in those files: Winsock's refusal constant is renamed
errWSAEConnRefused, and a misspelling in a file comment is fixed.

Closes #1017
The cross-platform step's comment said the files Linux builds too were
measured by "the Linux gate", and no CI job runs gobco on Linux: what
holds them is the GOBCO_GATE=all run every touched package passes
before it is committed. The step's comment, the testing README and the
script's own description of the beyond: gate now say so.

The comment also called descriptor_limit_other.go the non-Unix
descriptor limit. Its constraint is !linux && !darwin, so it builds on
FreeBSD and the other Unix systems too; it is named instead.
@sourcery-ai

sourcery-ai Bot commented Oct 6, 2026

Copy link
Copy Markdown

Sorry @jmrplens, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 5 days and 20 hours by commenting @sourcery-ai review. Upgrade to get a review now.

@jmrplens
jmrplens added this pull request to stack #1208 October 6, 2026 06:35
@coderabbitai

coderabbitai Bot commented Oct 6, 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: e995b997-9a7c-4232-9716-c85670a575cb
📥 Commits

Reviewing files that changed from the base of the PR and between 9398eaf and e563cc5.

📒 Files selected for processing (42)
  • .github/skills/increase-test-coverage/SKILL.md
  • .github/workflows/ci.yml
  • Makefile
  • cmd/server/auth_gate.go
  • cmd/server/auth_gate_test.go
  • cmd/server/bearer_guard_test.go
  • cmd/server/conn_refused_windows.go
  • cmd/server/conn_refused_windows_test.go
  • cmd/server/etag_test.go
  • cmd/server/fine_grained_test.go
  • cmd/server/first_run.go
  • cmd/server/first_run_test.go
  • cmd/server/health.go
  • cmd/server/health_test.go
  • cmd/server/jsonrpc_id.go
  • cmd/server/jsonrpc_id_test.go
  • cmd/server/listen.go
  • cmd/server/main.go
  • cmd/server/main_linux_test.go
  • cmd/server/main_test.go
  • cmd/server/pprof.go
  • cmd/server/probe.go
  • cmd/server/probe_test.go
  • cmd/server/readiness.go
  • cmd/server/sdk_log.go
  • cmd/server/sdk_log_test.go
  • cmd/server/shape_test.go
  • cmd/server/socket_mode_unix_test.go
  • cmd/server/socket_mode_windows.go
  • cmd/server/socket_mode_windows_test.go
  • cmd/server/stdio.go
  • cmd/server/subscriptions_test.go
  • cmd/server/telemetry_identity.go
  • cmd/server/telemetry_test.go
  • cmd/server/transport.go
  • docs/development/testing/README.md
  • docs/development/testing/testing.md
  • docs/development/upstream-bugs.md
  • internal/tenancy/budget.go
  • internal/tenancy/decisions_admit.go
  • scripts/coverage-conditions.sh
  • scripts/coverage_conditions_sh_test.py
  • Autopilot · 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.

@github-actions github-actions Bot added ci Build pipeline, workflows, or lint configuration transport stdio and HTTP transports, the server process, and the transport e2e modules platform Windows and macOS specific source, and the cross-platform CI leg labels Oct 6, 2026
@jmrplens jmrplens added this to the 3.2.0 milestone Oct 6, 2026
@jmrplens jmrplens changed the title fix/server condition gate remainder Close the condition and mutation gate of cmd/server, and gate the files only Windows and macOS build Oct 6, 2026
@github-actions github-actions Bot added the v3.2.0 Targeted at the 3.2.0 release label Oct 6, 2026
@sonarqubecloud

sonarqubecloud Bot commented Oct 6, 2026

Copy link
Copy Markdown

@jmrplens
jmrplens merged commit f4c169d into main Oct 6, 2026
5 checks passed
@jmrplens
jmrplens deleted the fix/server-condition-gate-remainder branch October 6, 2026 07:21
jmrplens added a commit that referenced this pull request Oct 6, 2026
The condition gate (gobco, through `scripts/coverage-conditions.sh`)
runs on Linux before I commit, and since #1206 the Windows and macOS
legs of CI gate only the files those systems alone build. A figure for a
whole package on Windows or macOS still had to be taken by hand: the
`internal/toolutil` figures I quoted in #1206 came from a Windows
virtual machine, before 20 more conditions landed in `errors.go`, and I
had no way to take them on macOS at all.

`.github/workflows/conditions.yml` measures it on demand. It is
triggered by `workflow_dispatch` and by nothing else, takes the
packages, the gate (`all` or `beyond:linux/amd64`) and the systems
(`windows-latest`, `macos-latest`, `ubuntu-latest`), and fans out over
package by system. Each run is `scripts/coverage-conditions.sh` through
bash, exactly as the CI legs and `make coverage-conditions` run it, so
every figure is the gate's own on that system. An empty package list
means every package whose built files differ between two of the
platforms `.goreleaser.yml` builds, found by listing the module under
each of them, which today is `cmd/server`, `internal/toolutil` and
`internal/tools/packages`.

The summary job writes one table into the job summary: package, system,
gobco's figure as covered of total, how many conditions were not
evaluated both ways and how many of those the gate held, then every such
condition with its file and line (a condition written across lines is
joined onto one, so it stays one row), then why any run that could not
measure could not. Each run's raw gobco output and its record are
uploaded as an artifact. No figure fails the workflow; a run that cannot
measure at all (a package go cannot load, a failing test, a 0/0 report,
a runtime crash) fails its own job and says why in one annotation. The
measuring step removes setup-go's problem matcher before the script
prints anything: it would file every condition gobco names as an error
annotation, so a run that measured would look failed, and past GitHub's
ten per step the step's own annotation would be dropped.

To tell a held figure from no figure, `scripts/coverage-conditions.sh`
now exits 3 when its gate holds a condition, a status no other failure
uses: every other one exits 1 or 2 (`go run` reports any failure of
gobco as 1). The CI step, the Makefile target and
`scripts/check-spec-conditions.sh` read any non-zero status as a
failure, as before, and the script's Python tests now pin 3 for the
gate.

The plan and the table are a new command, `cmd/measure_conditions`,
rather than shell in the workflow. `plan` validates the inputs (only the
three hosted runners, a package path in the characters this module's
directories use, a gate the script reads) and prints the matrix;
`summarize` reads the records wherever download-artifact puts them,
joins them to the plan, and refuses a record that disagrees with the
plan or with its own status rather than tabulating a guess. Its tests
hold the workflow file to the record format they read. It is at 100% of
statements, 174/174 conditions under gobco, and 108 mutants killed with
none lived or not covered under gremlins.

The workflow holds `contents: read` and nothing more, every `uses:` is
pinned to the SHA `ci.yml` already pins, and no step resolves code at
run time. `make check-supply-chain` passes, and so does actionlint 1.7.7
with shellcheck on it.

`docs/development/testing/README.md` says how to dispatch it and that
its figures are measured, not inferred.
`docs/development/cmd-utilities.md`, `CLAUDE.md`, the Copilot
instructions and the testing reference name the new command, and the
testing reference records its measured coverage rather than n/a.

GitHub offers a workflow for dispatch only once its file is on the
default branch, so this pull request cannot run it. The first dispatch
happens after the merge, for `cmd/server` and `internal/toolutil` on all
three systems, and it is what the issue's last acceptance line asks for:
`gh workflow run conditions.yml -f packages="./cmd/server
./internal/toolutil" -f systems="windows-latest macos-latest
ubuntu-latest" -f gate=all`. I will link that run on the issue, and
reopen it if the run does not produce the table.

Closes #1210
jmrplens added a commit that referenced this pull request Oct 8, 2026
… under the race detector by its own budget, and dial closed listeners only outside the parallel phase (#1258)

The release rehearsal of 2026-10-08 (run 37707835685, on main at
7519408) failed its race gate in two jobs. In the unit suite,
`TestCreateServer_FineGrained_EveryListingNarrowedAndFinalized` stopped
at `register did not return within 30s`. In the stdio transport module,
the `a_paid_namespace_plan` case of
`TestTokenScope_FineGrainedTokenWithoutMetadataRead_StartsWhole` stopped
at `the server did not answer within 30s`, and the server's own log
shows why: 24 seconds between detecting the tier and finishing the
registration of 1088 individual tools. The scheduled race run of
2026-10-05 and the rehearsal of 2026-10-01 passed the same gate.

Nothing got slower between those runs. I timed main at both ends and in
between, with and without the detector, and they agree within noise.
What changed is that the bound on `register` in the unit test is new
(#1206 added it on 2026-10-06, and the race workflow runs only on
Mondays and in rehearsals, so this rehearsal was the first run under the
detector to meet it), the stdio budget had only about five seconds of
margin over the start it waits for even on a fast machine, and the
runner of 2026-10-08 was about 1.3 times slower per core than the one of
2026-10-05. Under the race detector a registration of the individual
surface runs ten to fourteen times slower than an ordinary one, on one
core, so a fixed 30 seconds was a bet on the runner.

Two things were wrong, and this fixes both.

Registration listed its own tools twice over an in-memory session: once
only to log how many there were, and again to build the `gitlab://tools`
manifest, with nothing registering a tool in between. A listing marshals
every tool's schemas, so the first of the two was about a fifth of a
registration, with or without the detector. It is now made once and its
answer is both the count and the manifest's tools;
`countRegisteredTools` is gone, and a failed listing is one warning that
says the manifest is not served.

Measured on the same five-core machine against main at 7519408, cold
processes, median of three runs under the detector and of five without:

| What | main | this branch |
| --- | ---: | ---: |
| Cold registration of the individual surface, race | 16.05 s | 13.08 s
|
| Warm registration, race | 6.31 s | 3.38 s |
| Fine-grained stdio start (Ultimate, 1088 tools), first tools/list
answered, race | 24.07 s | 20.14 s |
| Classic stdio start (Ultimate, 962 tools), first tools/list answered,
race | 22.36 s | 19.01 s |
| Fine-grained stdio start (Free, 868 tools), first tools/list answered,
race | 19.17 s | 16.32 s |
| `register` inside the failing unit test, race, 4 CPUs, the test alone
(two runs of its whole package) | 21.57 s (21.20, 21.47) | 15.85 s
(15.61, 15.59) |
| Cold registration, ordinary build | 1.25 s | 1.03 s |
| Warm registration, ordinary build | 0.47 s | 0.26 s |
| Fine-grained stdio start, first tools/list answered, ordinary build |
1.83 s | 1.56 s |

That alone does not get a slow runner comfortably under 30 seconds: 20
seconds on this machine is about 27 on the runner that failed. So a wait
on a whole registration now has a bound of its own, chosen by a
build-tag seam on the race tag: 30 seconds in an ordinary run, as before
(60 where a stdio test already allowed that), and three minutes under
the detector, which is four times the worst registration I measured (43
seconds on half a core, before this change) and still a bound, so a
registration that never returns is reported by the test that waited for
it. `cmd/server` had no such seam, so it gains `main_race_test.go` and
`main_norace_test.go` with `testCatalogBuildTimeout`, following the
pattern of the stdio harness, whose `harness_race_test.go` and
`harness_norace_test.go` gain `callTimeout` for `call` and
`registrationTimeout` for the tests that read the answer themselves. In
`cmd/server` the new bound is used for every wait on a registration: the
fine-grained shell, the settling of shape registrations, the catalog
wait, the HTTP test client (whose comment already said its budget was
about the first request building a catalog under the detector), a stdio
start's held listing and its catalog-ready line, and the server card
builds. In the stdio module it bounds the first listing of an
individual-surface start, held or read through `call`, and its
catalog-ready line. Every other liveness wait keeps the bound it had.

`TestCreateServer_StartupSelfInspection_ListsTheToolsOnce` pins the
single listing (it fails on main, with two) and holds the logged count
to what a client is listed.
`TestCreateServer_StartupInspectionIsNotChargedToTheCatalogBucket` used
to notice an unmarked self-inspection because the second listing was
refused on a bucket that holds one; with one listing that refusal no
longer happens, so it now asks for the client's first `tools/list`,
which a charged startup would have spent, and I checked that it fails
with the inspection mark removed.
`TestCreateServer_ToolManifestInspectionError` now requires the one
warning a failed listing logs, and that the tools, a workflow guide and
the prompts are still served beside the missing manifest, which gives
the negative check above a positive twin.

Running the whole unit suite under the detector on this branch turned up
one more failure, unrelated to registration:
`TestClearStaleSocket_DeadSocketIsRemoved` found the socket it had just
closed `already served by another process`, and passed when the package
ran again. `clearStaleSocket` was right. A child process gets a copy of
every descriptor at fork and loses the close-on-exec ones only at exec,
so while a sibling test is between the two, a listener a test has closed
is still listening in the child and the probe's connect succeeds. Beside
only the package's two tests that start processes during the parallel
phase, the unchanged test failed in 242 of 3000 runs (269 under the
detector) and in none without them, and the "nothing listening" case of
`TestRunProbe_ExplicitTarget` failed once in 3000 the same way, its
connect reset instead of refused. Both now run outside the parallel
phase, where no test can be starting a process: `deadUnixSocket` says
why, once, for the two dead-socket tests, and the refusal case is
`TestRunProbe_ATargetNothingListensOn_IsReportedRefused`. They pass all
3000 runs beside the same siblings, with and without the detector, and
all 500 beside a scratch sibling that starts processes for the first 150
ms of every parallel phase, where the unchanged tests failed 49 times. I
swept the module for the same shape. In `cmd/bench_resources`,
`TestFreePorts_ReturnsAPortThatCanBeBound` and
`TestFreePorts_SuccessiveCalls_DoNotCollide` both bind a port the moment
`freePorts` releases it and were already sequential; no parallel test of
that package starts a process today, and the comments now say why both
have to stay sequential. Every other test that closes a listener and
then expects it gone either accepts any failure, sits in a package whose
tests start no process, or reserves its port outside the parallel phase
(`test/e2e/http`'s `freePort` callers, `test/e2e/collector`, the
harness's HTTP sessions in `test/e2e/gitlab`, `cmd/server`'s pprof
test), where no process is being started. Timing alone would not protect
them: a child's copy usually goes within a millisecond, but one was
measured holding a closed listener for 11 ms under the detector and for
40 ms with the CPUs loaded.

## Gates

On the tree with both commits, through `rgo` on four CPUs to match the
hosted runner, with the race workflow's own commands: the unit job (`go
test -race -count=1 -timeout 60m ./cmd/... ./internal/...` with the
request inventory recording) passed 288 packages in 1128 s with no data
race, `TestCreateServer_FineGrained_EveryListingNarrowedAndFinalized`
included; the stdio transport job passed 57 of 57 in 761 s,
`TestTokenScope_FineGrainedTokenWithoutMetadataRead_StartsWhole` in
39.75 s across both its cases; the HTTP transport job passed 193 with 8
skips (seven need Docker, one skips itself under the detector), and the
collector job passed what it can without Docker. Without the detector
the unit suite and the stdio module pass. `go build`, `go vet` (with the
stdio and HTTP tags too), the e2e compile, golangci-lint on the touched
packages, `make check-test-file-names`, `check-test-goroutines`,
`check-test-subtests`, `check-dead-consts`, `check-tenancy` and
`gen_testing_docs --check` all pass.

`main.go` is the only production file whose code changed. Its mutation
run (gremlins scoped to it) killed 349 with none living, both mutants on
the changed lines among them; the 16 not covered are package-level
constant expressions that are not covered on main either, at the same
lines. Condition coverage of `cmd/server` is 2236 of 2236 and statement
coverage 100 %. After the review fixes, which touched only tests and
comments, the whole `cmd/server` package under the detector, the stdio
tests whose bounds changed, the bench tests, both packages without the
detector, the stdio module, coverage and lint were run again and pass.

This unblocks the release rehearsal that #1232 is waiting on.
jmrplens added a commit that referenced this pull request Oct 26, 2026
Closes #958

This is the second layer of #958, on top of the register layer that gave
a zero which does not mean off a way to be a stated exception
(`ZeroBy`), stated the capacity rule and gave every fixed bound its
reason. That layer left F-34 on four rows and F-16 on four, because what
they record changes with code. This one changes that code, and no row
carries either finding afterwards. It also folds in items 1 and 3 of
#1171 and D7 of #529, which are the same code.

## What changed

Zero now means off wherever it has a meaning, through the flag and the
variable alike, and switches nothing else off. Where neither no limit
nor a limit of nothing is a deployment anybody could want, it is refused
at startup and recorded as a stated exception. This is the decision of
2026-09-28.

- `GITLAB_MCP_SESSION_TIMEOUT=0` refused the start while
`--session-timeout=0` was accepted. Both readers, stdio's `config.Load`
and HTTP mode's overlay, now read it as off (`END-005`), and the startup
warning a stateful deployment with no idle timeout gets names both
spellings: `--session-timeout=0 (or GITLAB_MCP_SESSION_TIMEOUT=0)`.
- Every duration variable whose zero means off took the bare `0` and
refused `0s`, which the flag of the same name accepts.
`parseDisableableDurationEnv` now reads a zero as a duration, so `0`,
`0s`, `0ms` and `0h0m0s` mean the same, and a negative duration is still
refused. That covers the session timeout, the revalidation interval, the
pool idle timeout, the action timeout, the drain delay and the two
authentication windows.
- A failure window of zero switched the failure budget off and the
distinct-credential budget with it, because the escalation steps by that
window (`AUB-003` followed `AUB-001` off). The escalation now steps by
the default window, so only its own limit or window turns it off.
- `--oauth-cache-ttl=0` and negative values started a server: in oauth
mode one that replaced them with the default 15 minutes and a warning,
and in legacy mode one that never read them, while
`GITLAB_MCP_OAUTH_CACHE_TTL=0` refused the start in either mode. The
flag now refuses them at startup in either mode too
(`refuseNonPositiveOAuthCacheTTL`), so the two spellings start the same
deployments. A zero TTL would expire every token as it is verified,
since the verifier stamps the TTL into the token's expiration. The
range, 1m to 2h, is still checked only in oauth mode, where the TTL is
used, through the flag and the variable alike. `ADM-005` records this
through `ZeroBy` as the fifth stated exception, beside the pool size,
the burst, the credential age ceiling and the watcher ceiling. The
normalization at the point of use stays, for a `Config` no validation
saw.
- The pool stated three of the configuration's defaults a second time
(size, revalidation interval, idle timeout), held equal to the register
by a Pin. They are aliases of the register's constants now, so
`ADM-009`, `POL-001` and `POL-004` declare Alias sites and G2 holds
them. No row declares a Pin any longer. I left the role and G4 in place
for a value that has to be stated twice later, and removed the
register's unused helper for one; the register test asks the three pool
rows for no Pin, not the whole register.
- The fallback to the default window for a budget that reads another
budget's window was written twice for the transport-source budget, in
the function that builds it and in its constructor, and twice in the
`/48` aggregate's builder, and not at all for the escalation step, which
was the defect above. `windowOrDefault` in `cmd/server` is that
fallback, written once, and the transport-source budget, the escalation
step and the `/48` aggregate read it.
- `blockedByBudget` was implemented twice, body for body, in the legacy
gate and the bearer guard, kept in step by a comment. The four budgets
are one embedded type, `authBudgets`, and `blockedByBudget` is its
method, so both layers answer with one implementation.

The register records issue 958 on `ADM-005`, `ADM-009`, `AUB-001`,
`AUB-002`, `AUB-003`, `END-005` and `POL-004` (`POL-001` already did),
F-16 and F-34 join the answered findings, and the specification, the
contributor configuration page and the site's environment, CLI,
configuration, HTTP server and security pages say the same in English
and Spanish.

Two places where the code on this base differs from what the issue
describes. The issue counts three copies of the transport-source
budget's fallback; #1206 had already removed one, and the `/48`
aggregate from #954 had added two of its own, so the helper replaces
those four and is what the escalation step reads too. And the issue
describes the flag's zero as selecting the default, which is what oauth
mode did; legacy mode never read the flag, but the variable's zero
already refused the start there, so the flag refuses it in both modes
and not only where the TTL is used. No real deployment meets a zero it
did not ask for, since the flag defaults to 15 minutes; the `cmd/server`
tests that build an HTTP configuration by hand now carry that default,
as they carry the default pool size.

## Release note

`--oauth-cache-ttl` now refuses `0` and negative values at startup in
either authentication mode, as `GITLAB_MCP_OAUTH_CACHE_TTL` already did.
An oauth deployment that passed one used to run at the 15-minute
default, and a legacy one ignored it. `GITLAB_MCP_SESSION_TIMEOUT=0` now
turns the idle timeout off instead of refusing the start, every duration
variable whose zero means off accepts `0s` as well as `0`, and
`--auth-failure-window=0` no longer turns off the distinct-credential
budget.

## How it was tested

I wrote the tests first and ran them against the parent, where each was
red for the reason it names, then green on this branch:

- `internal/config`:
`TestLoad_AZeroDuration_TurnsItsSettingOffHoweverWritten` and
`TestLoadHTTPEnvOverlay_AZeroDuration_TurnsItsSettingOffHoweverWritten`
set every duration variable whose zero means off to `0`, `0s`, `0ms`,
`0h0m0s` and ` 0s `, and to `-1s`. On the parent the session timeout
refused all five zeros (`duration must be positive, got 0s`) and every
other variable refused the four that are not the bare digit. Two more
pin that the OAuth cache TTL's variable still refuses every zero and
`-5m`.
- `cmd/server`:
`TestAuthSprayBudget_AFailureWindowOfZero_LeavesItOnAtTheDefaultStep`
failed on the parent because a zero window built no distinct-credential
budget at all.
`TestValidateHTTPAuthConfig_ANonPositiveOAuthCacheTTL_IsRefused` failed
because `0s` and `-5m0s` passed in both modes, and holds that a legacy
TTL below the range still passes. The warning test failed until the line
named the variable.
`TestValidateHTTPRuntimeConfig_NegativeBodyLimit_Rejected` passed on the
parent for the pool size's refusal, not its own; it now gives the pool
and the TTL their defaults and asserts the body limit's message. The
window tests of the transport-source budget now go through
`transportFailureBudget`, which owns the fallback.
- `internal/tenancy`: seven register tests failed on the parent. They
pin the rows above, F-16 and F-34 carried by no row, the pool's three
defaults declared as aliases with no Pin left on their rows, and
`AUB-003` following no row off.
- `test/e2e/http`: `TestZeroSettings_*` drive the real binary.
`GITLAB_MCP_SESSION_TIMEOUT=0` and `0s` with `--stateless=false` start
and log the warning; each duration variable at `0s` starts;
`--auth-failure-window=0 --auth-distinct-token-limit=2` still answers a
stream of distinct refused credentials with `429` and a `Retry-After` of
about 60 seconds; `--oauth-cache-ttl=0`, `0s` and `-5m` refuse the start
with `--oauth-cache-ttl must be positive` in oauth and in legacy mode,
and `GITLAB_MCP_OAUTH_CACHE_TTL=0` refuses it in both with `invalid
OAUTH_CACHE_TTL value`. On the parent the first two refused the start,
the third never blocked, and the flag cases of the fourth started and
ran until the harness killed them, in both modes.
- `test/e2e/stdio`:
`TestZeroSettings_AZeroDurationInTheEnvironment_IsServed` serves a tool
call with `GITLAB_MCP_SESSION_TIMEOUT` at `0` and `0s` and every other
duration variable at `0s`. All eight cases refused the start on the
parent.

At the head:

- `GITLAB_MCP_TEST_SNAPSHOT_PARITY=deferred go test ./... -count=1`:
every package passes (294) on this branch rebased onto `main` at
`8e959c3d8` (#1513), since this layer sits below the stack's top and
regenerates nothing.
- `make check-tenancy`: 89 rows, 390 declared sites, 0 findings. `make
check-dead-consts`, `make check-e2e-static`, `make check-test-subtests`,
`make check-test-goroutines`, `make check-test-file-names`, `make
check-doc-tool-names` and `go test -tags e2e -c -o /dev/null
./test/e2e/gitlab/...` pass.
- `make test-e2e-http`: 728 tests, 8 skipped for want of Docker. `make
test-e2e-stdio`: 255 tests.
- Code identity for the alias step: the parent's tree, and the same tree
with only the pool's three constants aliased, build to binaries
identical in every allocated section but `.gopclntab` (`audit_tenancy
-compare-binaries`, and `make tenancy-code-identity BASE_TREE=<parent>`
run from the aliased tree).
- Statement coverage is 100% in `internal/config`, `internal/tenancy`,
`internal/serverpool`, `cmd/audit_tenancy` and `cmd/server`, and `make
coverage-conditions GOBCO_GATE=all` evaluates every condition both ways
in each (436, 534, 418, 994 and 2350).
- `make coverage-mutants`: no mutant lives. `internal/config` killed
213, `internal/tenancy` 319, the three `cmd/server` files this layer
rewrote (`auth_blocks.go`, `auth_gate.go`, `bearer_guard.go`) 196,
`internal/serverpool/pool.go` 125 and `cmd/audit_tenancy/pin.go` 11. The
ones reported not covered are all in package-level constant expressions
this layer does not touch (`iota + 1`, negative codes and duration
products in `config.go`, `codes.go`, `decision.go`, `grants.go`,
`values.go`, `auth_gate.go` and `pool.go`), which no coverage profile
places, and two in the stand-in program under
`cmd/server/testdata/peer`, which the run walks into. The aliases remove
two of them from `pool.go`. For `main.go`, too large for a run of its
own, I applied the two mutants of the new `ttl > 0` in
`refuseNonPositiveOAuthCacheTTL` by hand: `ttl >= 0` fails
`TestValidateHTTPAuthConfig_ANonPositiveOAuthCacheTTL_IsRefused` in both
modes, and `ttl <= 0` fails every test that starts HTTP mode with the
default TTL, `TestRunWithContext_SuccessHTTPIndividualTools` first.
- `golangci-lint run` on the touched packages and the two transport
modules is clean, and `golangci-lint fmt --diff` has nothing to change.
- Site: `i18n:check`, `facts:check`, `chips:check`, `llms:check`,
`build` and `lint` pass, as do `node scripts/check-doc-links.mjs`,
`markdownlint-cli2` on every changed page and `go run
./cmd/format_md_tables/ --check`.

---------

Signed-off-by: José M. Requena Plens <mail@jmrp.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci Build pipeline, workflows, or lint configuration platform Windows and macOS specific source, and the cross-platform CI leg transport stdio and HTTP transports, the server process, and the transport e2e modules v3.2.0 Targeted at the 3.2.0 release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The condition gate cannot instrument cmd/server: gobco panics on build-constrained duplicates

1 participant