beads/cmd/bd/max_rows.go
Julian Knutsen 6f8d153417
test(proxy): harden history and remote front doors (#6293)
* test(proxy): harden history and remote front doors

* fix(proxy): preserve ready claim and compact refusal contracts

* fix(proxy): validate ready claim row caps preprovider

* fix(proxy): key capability front door on command paths

Review fixes for the proxied-server capability front door.

Blocking: validateProxyCapabilitiesBeforeProvider keyed on cobra's leaf
Name(), and `bd ready` and `bd mol ready --gated` share the leaf name
"ready". The max-rows refusal written for the former also refused the
latter for anyone with BEADS_MAX_ROWS exported — a proxy-supported
command that has no --max-rows flag to refuse. Every branch and both
policy tables now key on proxyCommandPath (the path below the root),
with an explicit "mol ready" row saying so. The compact refusal moves
from "compact" to "admin compact" for the same reason: root `bd compact`
is a different command with its own proxied route, and its message now
names `bd admin compact --dolt` rather than a `compact --dolt` that the
root command has no flag for.

Blocking: the allow path had no coverage, and it is the direction that
needs it — a refusal that stops firing degrades to the older late
failure, but one that fires too widely breaks a working command at the
front door where nothing catches it. Added a real-command-tree allow
table (a parentless cobra command has no path and matches no rule, which
is how a synthetic test tree reports success for a refusal that never
fired), a drift guard that every table key names a command that exists,
and an e2e allow matrix running the proxy-supported set against a live
managed-local proxied project, once clean and once under
BEADS_MAX_ROWS=5. `bd ready` under that cap is in the same table as the
control: it must still refuse.

Row cap resolved once on the proxied claim path, via resolveMaxRowsQuiet
rather than by hoisting the claim early-return above resolveMaxRows. The
duplicate line is the malformed-BEADS_MAX_ROWS advisory, which is a side
effect of resolving; the front door now resolves silently and the
command body stays the sole warner, so the message appears exactly where
it did before the front door existed. Hoisting would have moved the
`--max-rows -1` usage rejection back behind provider construction and
regressed TestReadyClaimValidatesMaxRowsBeforeProvider, which this PR
added.

Also folded in, all in-theme:

- ProxyOutcomeNA asserts clean (it states the command lacks the flag,
  which is nothing to refuse), and a rule carrying neither code nor
  message falls back to a generic one instead of rendering as a bare
  "Error: " with exit 1.
- The list/--repo row said notApplicable(); list_proxied_server.go
  refuses it. A policy table that contradicts the command is worse than
  a missing row.
- preflight binds --json to &jsonOutput like every other command's local
  --json. commandJSONFlagChanged suppresses the config-driven default
  whenever a local --json is set, so an unbound flag left
  `bd preflight --json` with jsonOutput=false.
- Deleted the proxied no-op in doctor.go. "doctor" is in the refusal
  table now, so the front door returns exit 1 before RunE ever runs.
  CHANGELOG records that flip (exit 0 with a stderr note becomes exit 1
  with proxy.doctor.unsupported) and that --json refusals are strict
  JSON on stdout.
- Deleted the dead tail block in validateProxyMaintenanceBeforeProvider:
  it could only run for a space-free path, which the table lookup above
  it had already handled.
- TestHistoryDirectOnlyRefusalContract iterates its own expectation
  table, so all 13 declared rows are asserted rather than 11.

- HandleProxyCapabilityError(nil) returns nil. Every AssertProxy* allow
  path returns nil and this wraps that return value directly, so the
  natural way to add the next rule -- a bare
  `return HandleProxyCapabilityError(AssertProxy...(...))` with no
  preceding `if` -- would have rendered an allowed capability as
  "Error: <nil>" with exit 1. Latent today: all five nil-capable call
  sites are guarded by conditions whose rules resolve to refused().
- The third front-door branch, the skipsStoreInit route into
  validateProxyMaintenanceBeforeProvider, keys on proxyCommandPath like
  the other two, and "doctor" joins the path list in
  TestProxyFrontDoorBranchesUseRealCommandPaths so the drift guard
  covers all three. It returns unconditionally, so a future
  `bd <parent> doctor` matching on the leaf name would have taken nil
  back from the now path-keyed validator and returned early past
  guardLegacyNoStoreCommand and getDoltAutoCommitMode.

* test: make direct and proxied history ordering fixtures deterministic

Assign distinct fixture timestamps and assert the expected newest-first sequence so same-second writes cannot make SQL/proxy parity flaky.

Agent: Codex (unknown model, unknown reasoning)

* test(proxy): expect scoped admin compact refusal

Agent: Codex (unknown model, unknown reasoning)

* fix(proxy): restore typed refusals and settle the ready --claim contract

Maintainer review fixes for #6293.

Major: `bd list --repo` under --proxied-server was the one live refusal this
PR converted from a typed ProxyCapabilityError to a bare errors.New. The
pre-provider gate covers `create` only, so runListProxiedServer is list's sole
enforcement point: --json got prose on stderr instead of
{"code":"proxy.repo.unsupported",...,"mutates":false} on stdout, while the PR
simultaneously added a "list"/ProxyCapRepo policy row that no non-test call
site could reach. The call site is typed again and keyed on the command path,
which makes that row the single source of the message. list.go's wrapper now
passes an already-rendered exitError through instead of re-wrapping it, so the
typed refusal no longer picks up a trailing "Error: exit code 1".

Major: the front door's new --claim early return contradicted ready.go, which
is untouched and still refuses any positive cap "including on --claim" -- so
the bypass never let a claim through. It only moved the refusal after provider
setup and, with max_rows.go downgraded to HandleErrorRespectJSON, stripped the
stable code: `bd ready --max-rows 5 --json` answered proxy.max_rows.unsupported
while `bd ready --claim --max-rows 5 --json` answered a bare {"error":...}. One
refusal, two shapes, selected by an unrelated flag. Settled toward the
documented contract, and toward the pre-existing
TestReadyRefusesMaxRowsUnderProxiedServerOnClaim which already pinned it:
--claim is not exempt. The early return is gone and
rejectResolvedMaxRowsUnderProxiedServer is typed again, so the front door and
its backstop in ready.go render identically. The claim path keeps what it
gained -- a malformed or negative value is still rejected before any provider
work, resolved quietly so the advisory still prints exactly once. The three
comments that disagreed about this contract now agree.

Also folded in, all in-theme:

- The create/show proxied fallbacks are typed again and marked as the dead
  defensive paths they are. Same downgrade, shadowed by the gate rather than
  live, so nothing failed when the contract left them.
- compact.go's dead fallback carries the gate's corrected wording
  ("bd admin compact --dolt"), and the table comment no longer asserts the
  message did not change in the same hunk that changed it.
- The "mol ready" row's comment says what the row is -- a documentation pin.
  Path keying is the guard it was crediting itself for.
- Tests: the strict-JSON shape (code/mutates/exit) of the list --repo refusal,
  claim-and-bulk parity plus the backstop for the max-rows refusal, and
  preflight's --json binding in both directions -- including the config half
  end-to-end, since flag.Value.Set never sets Changed and the config default
  only lands inside refreshBoundCommandConfig.
- CHANGELOG: #5859 sits in exactly one section again (it is not an ancestor of
  v1.3.0), plus an [Unreleased] entry for this PR's own user-visible deltas,
  including the bd preflight json-config change.

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-23 03:19:22 -07:00

228 lines
9.8 KiB
Go

package main
import (
"errors"
"fmt"
"os"
"strconv"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/storage/issueops"
)
// maxRowsEnvVar names the environment variable that opts in to the defensive
// row cap. Used as both the lookup key and the source attribution string in
// error messages.
const maxRowsEnvVar = "BEADS_MAX_ROWS"
// maxRowsFlagName is the --max-rows flag name. Declared as a constant so the
// flag lookup and the source attribution string stay in sync.
const maxRowsFlagName = "max-rows"
// addMaxRowsFlag registers the --max-rows int flag on cmd. Use on every
// user-facing command that should honor the per-invocation cap override
// (designer §2.2 / §4). Help text matches the designer spec verbatim.
func addMaxRowsFlag(cmd *cobra.Command) {
cmd.Flags().Int(maxRowsFlagName, 0,
"Hard upper bound on rows fetched from storage. Returns a non-zero exit (code 2) "+
"and an error to stderr if exceeded. 0 disables (the default). Overrides "+
"BEADS_MAX_ROWS for this invocation. Useful in CI/agent rigs that want a "+
"circuit breaker against pathological queries. Not supported under "+
"--proxied-server: an explicit --max-rows or BEADS_MAX_ROWS cap errors out "+
"rather than silently going unenforced.")
}
// addRoutedMaxRowsFlag registers --max-rows on a command whose cap is HONORED on
// both routes, so the help text must not repeat the proxied-server refusal above.
//
// It exists because that refusal is a fact about a command's implementation
// rather than about the flag: a command whose cap reaches a query path that
// threads one is honored on both routes. `bd dep tree` was the first and `bd
// list` the second — its cap used to be rejected under --proxied-server because
// the unit-of-work query path read no MaxRows at all. The next command to move
// onto a role that threads it calls this instead of the function above and
// deletes its rejectMaxRowsUnderProxiedServer call in the same edit.
func addRoutedMaxRowsFlag(cmd *cobra.Command) {
cmd.Flags().Int(maxRowsFlagName, 0,
"Hard upper bound on rows returned. Returns a non-zero exit (code 2) "+
"and an error to stderr if exceeded. 0 disables (the default). Overrides "+
"BEADS_MAX_ROWS for this invocation. Useful in CI/agent rigs that want a "+
"circuit breaker against pathological queries. Honored on both the direct "+
"and the --proxied-server route.")
}
// rejectMaxRowsUnderProxiedServer errors out when an explicit --max-rows
// flag or BEADS_MAX_ROWS env cap resolves to a nonzero cap but the command
// is about to divert to proxied-server mode. The proxied repository path
// (internal/storage/domain/db) doesn't thread MaxRows through the UOW
// pipeline, so silently ignoring the cap there would be the worst outcome
// for a safety flag — reject explicitly instead of no-oping. Call this
// after usesProxiedServer() is known true but before diverting to the
// *ProxiedServer function, on every command that calls addMaxRowsFlag.
func rejectMaxRowsUnderProxiedServer(cmd *cobra.Command) error {
maxRows, _, err := resolveMaxRows(cmd)
if err != nil {
return err
}
return rejectResolvedMaxRowsUnderProxiedServer(maxRows)
}
// rejectResolvedMaxRowsUnderProxiedServer is rejectMaxRowsUnderProxiedServer
// split out for callers that have already resolved the cap for their own
// purposes (e.g. to build a filter) and would otherwise call resolveMaxRows
// a second time — resolveMaxRowsEnvOnly emits a stderr warning on a
// malformed BEADS_MAX_ROWS every time it runs, so a second resolve doubles
// that warning under proxied mode (be-x42v.4 round-4 follow-up).
func rejectResolvedMaxRowsUnderProxiedServer(maxRows int) error {
if maxRows > 0 {
return HandleProxyCapabilityError(AssertProxyCapability(ProxyModeProxied, ProxyCapMaxRows))
}
return nil
}
// resolveMaxRows picks the effective cap from --max-rows then BEADS_MAX_ROWS.
// Returns (cap, source, err) where cap == 0 disables the cap and source is
// one of "--max-rows", "BEADS_MAX_ROWS", or "". A negative flag or bad int
// is a usage error: err is non-nil (exit code 1, main.go's
// exitCodeFromError convention — see HandleErrorRespectJSON) and the
// caller must propagate it immediately (`if err != nil { return err }`),
// mirroring how gatherListInput's callers already handle its (T, error)
// return. A non-integer env value emits a warning to stderr and is ignored
// (returns cap == 0, err == nil).
//
// Precedence (designer §2.1):
//
// 1. --max-rows N (flag changed, highest)
// 2. BEADS_MAX_ROWS=N (env var)
// 3. disabled (default; cap == 0)
//
// --max-rows 0 explicitly disables the cap even when BEADS_MAX_ROWS=N is set.
// This is intentional: ops shells with a global env can run a known-unbounded
// query without unsetting the env first.
func resolveMaxRows(cmd *cobra.Command) (int, string, error) {
if cmd != nil && cmd.Flags().Changed(maxRowsFlagName) {
n, err := cmd.Flags().GetInt(maxRowsFlagName)
if err != nil {
return 0, "", HandleErrorRespectJSON("--max-rows: %v", err)
}
if n < 0 {
return 0, "", HandleErrorRespectJSON("--max-rows must be non-negative; got %d", n)
}
return n, "--" + maxRowsFlagName, nil
}
maxRows, source := resolveMaxRowsEnvOnly()
return maxRows, source, nil
}
// resolveMaxRowsEnvOnly reads BEADS_MAX_ROWS without consulting any flag.
// Used by the doctor family of commands (designer §4): bd doctor, bd lint,
// bd doctor-conventions, bd doctor-pollution. These are internal sweeps
// where the operator may want a guardrail via env var but no per-invocation
// flag is needed.
//
// On a bad env value, emits a warning to stderr and returns (0, ""). The
// command proceeds with the cap disabled rather than aborting — failing
// closed here would break automation that has a global BEADS_MAX_ROWS set
// but accidentally got a typo.
func resolveMaxRowsEnvOnly() (int, string) {
n, source, raw, ok := parseMaxRowsEnv()
if !ok {
fmt.Fprintf(os.Stderr,
"Warning: %s=%q is not a non-negative integer; ignoring.\n",
maxRowsEnvVar, raw)
return 0, ""
}
return n, source
}
// parseMaxRowsEnv reads BEADS_MAX_ROWS without warning about a malformed
// value. Returns (cap, source, raw, ok); ok is false only for a value that is
// present but unusable, in which case the cap is disabled exactly as
// resolveMaxRowsEnvOnly disables it. An unset or empty variable is a valid
// "no cap" and reports ok.
func parseMaxRowsEnv() (int, string, string, bool) {
raw, ok := os.LookupEnv(maxRowsEnvVar)
if !ok || raw == "" {
return 0, "", raw, true
}
n, err := strconv.Atoi(raw)
if err != nil || n < 0 {
return 0, "", raw, false
}
return n, maxRowsEnvVar, raw, true
}
// resolveMaxRowsQuiet resolves the effective cap like resolveMaxRows but never
// emits the malformed-BEADS_MAX_ROWS advisory.
//
// It exists for the proxied capability front door, which resolves the cap in
// PersistentPreRunE to decide a refusal before the provider is constructed.
// Every command that reads the cap resolves it again in its own body, and the
// advisory is a side effect of resolving, so warning in the front door too
// would print one typo twice. The body's resolution stays the one that warns:
// the message keeps appearing exactly once, at the same point in the output it
// appeared at before the front door existed. A malformed value disables the
// cap, so the front door reaching the same "no cap" conclusion silently is the
// correct decision, not a suppressed one.
//
// An explicit --max-rows is still resolved through resolveMaxRows: that path
// never reads the environment, and rejecting a negative flag before the
// provider opens is the front door's job.
//
// No source string, unlike resolveMaxRows: the front door decides whether a
// cap is set, not how to attribute one in a message. The command body resolves
// the source for the message it prints.
func resolveMaxRowsQuiet(cmd *cobra.Command) (int, error) {
if cmd != nil && cmd.Flags().Changed(maxRowsFlagName) {
n, _, err := resolveMaxRows(cmd)
return n, err
}
n, _, _, _ := parseMaxRowsEnv()
return n, nil
}
// handleMaxRowsError checks whether err is a *issueops.ErrTooManyRows from
// the storage layer and, if so, emits the two-line stderr error message
// (designer §2.3) and returns an exit-coded error (code 2, main.go's
// exitCodeFromError convention — see &exitError{Code: 2} elsewhere in this
// package, e.g. list_input.go's skip-labels-conflict check). Returns nil
// when err is nil or any other type, letting the caller continue its
// existing error path (typically `return HandleError(...)`).
//
// Every caller must check the return value and propagate it immediately:
//
// if capErr := handleMaxRowsError(err); capErr != nil {
// return capErr
// }
// return HandleError("%v", err)
//
// This used to call os.Exit(2) directly, which — since it runs from deep
// inside RunE, sometimes several calls below it — bypassed both the
// calling command's own `defer func() { metrics.CloseEventAndAdd(evt) }()`
// and main()'s post-ExecuteC metrics.CloseAndFlush(), stranding queued
// metrics. Returning through RunE like every other command error lets both
// run before process exit.
//
// The error is intentionally rendered without ANSI color and without
// touching stdout: a half-rendered JSON array on stdout would cause `jq`
// downstream to fail in a way unrelated to the cap, hiding the real cause.
func handleMaxRowsError(err error) error {
if err == nil {
return nil
}
var capErr *issueops.ErrTooManyRows
if !errors.As(err, &capErr) {
return nil
}
source := capErr.Source
if source == "" {
source = maxRowsEnvVar
}
fmt.Fprintf(os.Stderr, "Error: too many rows: %d found, %s=%d exceeded.\n",
capErr.Found, source, capErr.Cap)
fmt.Fprintln(os.Stderr,
" Refine the query (add filters, set --limit), or raise the cap with")
fmt.Fprintln(os.Stderr,
" --max-rows N or BEADS_MAX_ROWS=N.")
return &exitError{Code: 2}
}