Skip to content

Hygiene: comment budget, shared request helpers, dead client verbs, two fixes - #13

Merged
CMGS merged 7 commits into
masterfrom
review/hygiene-2-2026-09-03
Sep 3, 2026
Merged

Hygiene: comment budget, shared request helpers, dead client verbs, two fixes#13
CMGS merged 7 commits into
masterfrom
review/hygiene-2-2026-09-03

Conversation

@CMGS

@CMGS CMGS commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Four commits over the extensions controllers, pkg/e2bcompat, pkg/sandboxd, the examples and the tagged harnesses. No file under pkg/scale, controllers/ or api/ is touched.

review: comment budget — 83 comment lines out, 2 in. Numbered section labels, restated code, the #1107 adoption rationale written four times, the triggeredAdoptionEntry and ensureClaimIdentityLabels docs repeated at their call sites, the duplicated SandboxTemplate -> claims TODO, and 17 numbered step-narration comments in the lifecycle example. The spaced // nolint:revive directives were inert prose (golangci-lint only honours //nolint); lint stays at 0 issues. on both GOOS without them.

review: named signatures and shared helpers

  • staleCheck bundles the four template-state parameters isSandboxStale took over 8 lines; buildSandboxCR drops poolNameHash, which it derives from the pool name the same way the caller does.
  • One decodeBody / decodeOptionalBody pair replaces six copies of the decode-or-400 block. The required/optional split is deliberate: createSandbox and setTimeout must keep rejecting an absent body, which decodeOptional accepted.
  • Client.sendNoBody replaces the request/auth/drain/status skeleton in Release, DeleteCheckpoint and sandboxVerb, keeping each call's error text and accepted statuses.
  • pollVisible (examples) and pollDetail (e2e) replace seven hand-rolled deadline loops; the six must() forwarders now call benchutil.Must directly.

cut: uncalled client verbsClaimCheckpoint and Promote (with CheckpointClaimSpec, PromoteSpec, PromoteResult) have no caller in sandbox-operator, vk-sandbox, instar or sandbox; the grep is in the commit body. Client.Sandboxes and SandboxSummary were on the same list but are live: vk-sandbox reaches them from provider.go, create.go, orphan.go and inventory/publisher.go, so they stay.

fix:version.Print panicked on a template error rather than returning it, and the collectors were registered from a var-initializer IIFE, an init() in disguise that ran in every binary importing the package. Register() is now called once from the operator's main, the only process serving a controller-runtime metrics endpoint. Both have regression tests.

Gates

All with GOWORK=off:

$ make lint
==> golangci-lint GOOS=linux
0 issues.
==> golangci-lint GOOS=darwin
0 issues.

$ make fmt-check     # exit 0
$ asl ./...          # exit 0, no findings
$ GOOS=linux asl ./...  # exit 0, no findings
$ make vet-tagged    # all 7 tagged harnesses type-check
$ go test -race -count=1 ./...   # every package ok

CMGS added 4 commits September 3, 2026 14:11
Delete numbered section labels, restated code, step narration, and the
rationales repeated at godoc and call site; the spaced // nolint:revive
directives were inert prose (lint stays at 0 issues without them).
Bundle the warm-pool staleness inputs behind staleCheck, fold the six
e2b decode-or-400 blocks and the three body-less sandboxd verbs into one
helper each, and drop the must() forwarders that only called benchutil.
Client.ClaimCheckpoint and Client.Promote have no caller in the family:

  $ grep -rn --include='*.go' '\.ClaimCheckpoint(\|\.Promote(\|PromoteSpec\|CheckpointClaimSpec' \
      sandbox-operator vk-sandbox instar sandbox | grep -v /vendor/
  sandbox-operator/pkg/sandboxd/lifecycle.go:143:func (c *Client) ClaimCheckpoint(...)
  sandbox-operator/pkg/sandboxd/lifecycle.go:189:func (c *Client) Promote(...)
  instar/taskpack/bake/apply.go:85:  digest, err := guest.Promote(ctx, sp.Snapshot)
  instar/taskpack/node.go:68:        tpl, err := g.sb.Promote(ctx, name)

The two instar hits are its own guest SDK, not this client. Client.Sandboxes
and SandboxSummary stay: vk-sandbox reaches them from provider.go, create.go,
orphan.go and inventory/publisher.go.

ensureClaimIdentityLabels now calls setOrDeleteLabel instead of repeating it,
and getOrCreateSandbox drops the template parameter its only call site passes
as nil.
version.Print panicked on a template error instead of returning it, and
template.Must panicked on a parse error; both now surface to the only
caller, which prints them and exits non-zero.

The collectors were registered from a var-initializer IIFE, an init() in
disguise that ran in every binary importing the package whether or not it
serves /metrics. Register() is now called once from the operator's main,
the only process with a controller-runtime metrics server.
@CMGS
CMGS force-pushed the review/hygiene-2-2026-09-03 branch from a9d0ee0 to 1150aaf Compare September 3, 2026 06:13
CMGS added 3 commits September 3, 2026 14:19
Print parses a package constant into a fixed struct, so a parse or execute
error is a programmer error a test of Print catches, not a runtime failure
reachable under the deployment contract. Returning it cost the caller an
os.Exit branch for an impossible path. version.go is back to its master
form; the Print test stays.
The test asserted the collectors were absent before Register, which held
only on the first run of a process against the package-global registry:

  $ GOWORK=off go test -count=2 ./internal/metrics/
  --- FAIL: TestRegisterIsExplicitAndIdempotentlyRefused (0.00s)
      metrics_test.go:126: collectors registered before Register was called, count = 1

Register now takes the Registerer, main passes controller-runtime's, and
the test drives its own, so absent -> present -> duplicate holds under
-count=2 and -shuffle=on.
The names and the if !decodeBody(...) { return } call shape carry every
fact the three godocs stated, and unexported helpers get none.
@CMGS
CMGS merged commit 9b3a533 into master Sep 3, 2026
2 checks passed
@CMGS
CMGS deleted the review/hygiene-2-2026-09-03 branch September 3, 2026 06:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant