beads/cmd/bd/max_rows.go
Julian Knutsen e29abaea37
Converge Offset and MaxRows on all three legs, and fix the panic and the breaker hole under them (#5435)
Offset and MaxRows were mirror-image splits: the unit-of-work seam honored
Offset and refused MaxRows; the two store legs did the opposite. Three contract
cases absorbed that with an "either HONORED or REFUSED with a typed
*ErrUnsupported" disjunction.

A contract that asserts a capability is either honored or refused is not pinning
semantics — it is ratifying a split. All three are gone, along with
assertReaderUnsupported. Converging upward rather than uow-matches-server is the
owner's one ratified exception, because the server refusing MaxRows was a
capability gap rather than a semantics choice.

Offset now runs in the shared page epilogue on every leg rather than in whichever
seam could render it: the skip must happen in the caller's display order, which
is not SQL-expressible for --sort id, and a row the database skips is a row the
query matched.

Two bugs fixed under it.

The panic: domain/db rendered LIMIT 18446744073709551615 OFFSET k for an
unbounded query, and Dolt sized a buffer from limit+offset and returned a
recovered makeslice panic instead of rows. The contract case had been shaped
around it, bounding every request, with a comment calling it a storage-seam bug
that predates the role. It now drives the unbounded shape.

The breaker hole, found by review: proxied bd list --watch with an offset and a
cap counted the cap against post-skip rows while the page route counted
pre-skip, so the same flags produced opposite verdicts — L=10, k=2, M=3 over 5
rows returned a page on one route and ErrTooManyRows on the other. Newly
reachable since 3b2385922 removed the proxied --max-rows rejection ahead of the
watch dispatch, and it falsified the comment claiming no caller combines an
offset with a cap.

MaxRows semantics are now ratified and documented: the cap counts the rows the
query TOUCHED (offset+limit), not the rows the caller receives. A skipped row is
still a matched row. Review reported the Limit+Offset == MaxRows boundary as an
off-by-one; measured under those semantics the code was already correct and the
doc was wrong, so the fix was the doc plus pinning the behaviour.

A seventh cannot-fail test was caught mid-slice: an unreachable "under a
defensive cap" branch in searchWindowFor absorbed the exact regression the new
MaxRows-behind-offset arm exists to catch, and the mutation returned
INCONCLUSIVE. Removed.

Equivalence of the epilogue skip to a SQL OFFSET was checked rather than
assumed. One narrow uncovered exception stands: under --sort title, SQL
collation and Go byte-compare can disagree on non-ASCII and then pick different
skip sets. Conformance seeds ASCII.
2026-08-08 11:37:09 -07:00

186 lines
7.9 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 HandleErrorRespectJSON("--max-rows / BEADS_MAX_ROWS is not supported in proxied-server mode")
}
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) {
raw, ok := os.LookupEnv(maxRowsEnvVar)
if !ok || raw == "" {
return 0, ""
}
n, err := strconv.Atoi(raw)
if err != nil || n < 0 {
fmt.Fprintf(os.Stderr,
"Warning: %s=%q is not a non-negative integer; ignoring.\n",
maxRowsEnvVar, raw)
return 0, ""
}
return n, maxRowsEnvVar
}
// 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}
}