beads/cmd/bd/proxy_capability.go
Julian Knutsen c507f3b4c9
fix(proxy): unsplit bd ready --gated, and stop policing a flag bd list lacks (#6697)
* fix(proxy): unsplit `bd ready --gated`, and stop policing a flag `bd list` lacks

Post-merge review of #6293 (landed as 6f8d15341) found two majors. Both are
incomplete-fix defects in that PR's own work, not regressions: each is a claim
the PR made that its code does not support.

1. `bd ready --gated` still inherited the max-rows refusal that `bd mol ready
   --gated` was freed from. The two spellings are documented as the same
   gate-resume scan, and on the proxied route they literally are one:
   `runReadyProxiedGated` discards its `readyInput` and calls the same
   `findGateReadyMolecules` as `runMolReadyGatedProxiedServer`. Neither threads
   a row cap. But the new front door keys on `path == "ready"`, which fires for
   every `bd ready` invocation, so with `BEADS_MAX_ROWS` exported only the
   `mol` spelling worked. #6293 moved the refusal off the shared cobra leaf
   name and onto the command; the arm is the level it actually belongs at.

   Both refusal sites are exempted, because exempting one only moves the split:
   `ready.go`'s in-RunE backstop calls `AssertProxyCapability` with an empty
   command, so it always resolves the mode-wide refusal and cannot honor a
   command-specific allow. `readyGatedArm` is the single predicate they share.

   `--claim` stays refused, including `--claim --gated`. That pair is a usage
   error (`gatherReadyInput`), not a gated run, so the mutating arm keeps its
   refusal on every path into it and this exemption cannot reopen it.

2. `list`'s `ProxyCapRepo` row was flipped from `notApplicable()` to
   `repoRefusal`, promising a typed refusal for `bd list --repo` — but `--repo`
   is registered only on `createCmd` (create.go:940), so cobra rejects
   `bd list --repo` as an unknown flag before any of this runs. The row, the
   comment above `repoRefusal`, the CHANGELOG contract and the test that
   "proved" it all described a command line that cannot exist. The policy table
   is the audit source of truth this PR argues for; a row refusing a flag the
   command does not have is worse than the N/A row it replaced.

   Restored to `notApplicable()` and the CHANGELOG retargeted at
   `bd create --repo`, which exists and is gated. `runListProxiedServer`'s
   defensive branch goes back to the mode-wide assert: keyed on the `list` row
   it would now resolve to "allowed" and let a repo override through, which is
   the opposite of what the branch is for.

Tests: both fixes are pinned by tests that fail without them, checked by
reverting each guard in place.

- `bd ready --gated` under `BEADS_MAX_ROWS=5` joins the front-door allow matrix
  against the real command tree, and the e2e allow matrix beside its `mol`
  twin. `--claim` and `--claim --gated` are pinned as still-refused, so
  widening the exemption to a bare `--gated` check does not pass.
- The RunE backstop gets its own unit pin rather than being left to the
  env-gated proxied e2e lane; it asserts two-sidedly, since a guard that
  swallowed the error would pass a "no refusal" check alone.
- `TestProxyCapabilityRowsNameFlagsTheCommandRegisters` is the drift guard the
  review asked for: the existing one pins paths, which is why it could not see
  a row naming a real command and a flag that does not exist. It runs both
  directions — a refused/honored row must name a flag the command registers, an
  N/A row must name one it does not.
- The two `list --repo` tests #6293 added both asserted the false premise, not
  just the one the review named; both are retargeted at the reachable
  `bd create --repo` site and at the corrected row.

Deliberately out of scope: the four non-gating minors and the nit from the same
review are left for separate follow-ups against main.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(changelog): record the `bd ready --gated` proxied row-cap fix

The behavior change in the previous commit is user-visible -- a command line
that exited 1 under a cap now runs -- so it gets its own [Unreleased] bullet
rather than riding along under #6293's entry, which describes the refusal as
it shipped.

Notes the ignored-cap consequence explicitly: `--gated` alongside a cap is now
dropped rather than refused, which is what the direct route has always done.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-24 00:42:51 -07:00

388 lines
17 KiB
Go

package main
import (
"fmt"
"github.com/spf13/cobra"
)
// ProxyCapability identifies a command feature whose availability differs by
// storage topology.
type ProxyCapability string
const (
ProxyCapReadonly ProxyCapability = "readonly"
ProxyCapMaxRows ProxyCapability = "max-rows"
ProxyCapWatch ProxyCapability = "watch"
ProxyCapRepo ProxyCapability = "repo"
)
// ProxyMode identifies the selected storage topology.
type ProxyMode string
const (
ProxyModeDirect ProxyMode = "direct"
ProxyModeProxied ProxyMode = "proxied-server"
)
// ProxyTopology distinguishes the provider deployment shape. The backup family
// is the first policy that genuinely differs across these: a Dolt backup
// destination is resolved on the machine running dolt, so "the server bd
// spawned itself" and "a server somebody else runs" are different answers to
// the same command (see capability_registry.go's backup rows).
type ProxyTopology string
const (
ProxyTopologyAny ProxyTopology = "any"
ProxyTopologyManagedLocal ProxyTopology = "managed-local"
ProxyTopologyExternalTCP ProxyTopology = "external-tcp"
ProxyTopologyExternalUnix ProxyTopology = "external-unix"
// ProxyTopologyTeamServer is a workspace whose database is owned by
// beads-team-server. It is a shape rather than a transport: bts owns the
// store's schema and identity whether bd reaches it over a port, a socket,
// or a child bd started, so the ownership fact decides capability policy and
// the transport does not.
ProxyTopologyTeamServer ProxyTopology = "team-server"
// ProxyTopologyUnknown is what a workspace bd cannot classify reports. It is
// never honored by a topology-keyed row, which is the fail-closed half of
// the policy: a workspace that cannot prove it owns its Dolt server does not
// get the privileges of one that can.
ProxyTopologyUnknown ProxyTopology = "unknown"
)
// ProxyCapabilityOutcome describes what the front door does with a feature.
type ProxyCapabilityOutcome string
const (
ProxyOutcomeHonored ProxyCapabilityOutcome = "honored"
ProxyOutcomeRefused ProxyCapabilityOutcome = "refused"
ProxyOutcomeDelegated ProxyCapabilityOutcome = "delegated"
ProxyOutcomeNA ProxyCapabilityOutcome = "N/A"
// ProxyOutcomeRefusedInRunE records a path the gate permits and that the
// command then refuses itself, untyped, from RunE. It is inventory, not
// policy: nothing enforces it. See capability_registry.go.
ProxyOutcomeRefusedInRunE ProxyCapabilityOutcome = "refused-in-run"
)
// proxyCapabilityRule is the stable contract for one command/argument/topology
// capability. Mutates is false for all refusals; ExitCode is used by the CLI
// when rendering a typed refusal. Reason and Tracking say why a refusal exists
// and who closes it — see the header of capability_registry.go.
type proxyCapabilityRule struct {
Outcome ProxyCapabilityOutcome
Code string
Message string
ExitCode int
Mutates bool
Reason ProxyRefusalReason
Tracking string
}
// ProxyCapabilityError is a machine-identifiable front-door refusal.
type ProxyCapabilityError struct {
Code string
Message string
ExitCode int
Mutates bool
Reason ProxyRefusalReason
}
func (e *ProxyCapabilityError) Error() string { return e.Message }
// errProxiedStoreUnrouted is the backstop for a command that the front door
// permitted and that then asked for a classic store on a proxied-server
// workspace. The proxied topology has no such store — the provider owns the
// connection — so the factory refuses rather than opening the proxied root a
// second time behind the proxy's back, which is the one failure mode every
// slice of this work must not regress.
//
// Reaching this is a routing gap in the command, not a policy decision: the
// registry says the gate permits the path, and permitting a path is not a
// promise that a proxied route exists for it. The owner is therefore whichever
// slice routes the command that landed here, which is why the reason is
// "unimplemented" and no single tracking item fits. It is typed so that a
// caller can classify it; before the registry there was no way to tell this
// apart from a genuine store failure.
func errProxiedStoreUnrouted() error {
return &ProxyCapabilityError{
Code: "proxy.store.unrouted",
Message: "this command has no proxied-server route; bd will not open a proxied-server workspace as a direct store",
ExitCode: 1,
Reason: ProxyReasonUnimplemented,
}
}
func refused(code, message string, reason ProxyRefusalReason, tracking string) proxyCapabilityRule {
return proxyCapabilityRule{
Outcome: ProxyOutcomeRefused, Code: code, Message: message, ExitCode: 1,
Reason: reason, Tracking: tracking,
}
}
func honored() proxyCapabilityRule {
return proxyCapabilityRule{Outcome: ProxyOutcomeHonored, ExitCode: 0}
}
func notApplicable() proxyCapabilityRule { return proxyCapabilityRule{Outcome: ProxyOutcomeNA} }
// ProxyCapabilityKey identifies a command's flag/argument on a topology.
// Command is the command's path below the root ("dep tree", "mol ready"),
// never its cobra leaf name — see commandRegistryPath. Argument is intentionally
// explicit (for example, "--watch"), allowing callers and tests to
// distinguish a command that lacks a flag (N/A) from one that refuses it.
type ProxyCapabilityKey struct {
Command string
Argument string
Mode ProxyMode
Topology ProxyTopology
}
// ProxyCapabilityRow is an inspectable command/argument/topology policy row.
type ProxyCapabilityRow struct {
ProxyCapabilityKey
Rule proxyCapabilityRule
}
// LookupProxyCapabilityFor returns the command/argument-specific rule. An
// absent command row falls back to the topology-wide default.
func LookupProxyCapabilityFor(command, argument string, mode ProxyMode) (proxyCapabilityRule, bool) {
capability := ProxyCapability(argument)
if len(argument) > 2 && argument[:2] == "--" {
capability = ProxyCapability(argument[2:])
}
if commands, ok := proxyCommandCapabilities[command]; ok {
if modes, ok := commands[mode]; ok {
if rule, ok := modes[capability]; ok {
return rule, true
}
}
}
return LookupProxyCapability(mode, capability)
}
// Shared by the mode-wide rule and its per-command overrides, so a command that
// refuses one of these refuses it with the same words and the same reason.
var (
// The cap is refused rather than silently dropped, which is right; the fix
// is threading it through the UOW reader the way `list` already does, so
// the refusal itself is the gap.
maxRowsRefusal = refused("proxy.max_rows.unsupported", "--max-rows / BEADS_MAX_ROWS is not supported in proxied-server mode", ProxyReasonUnimplemented, trackLongTail)
// `list --watch` is routed, so watching is possible over the provider;
// nothing else has been wired to it.
watchRefusal = refused("proxy.watch.unsupported", "watch mode not supported in proxied-server mode", ProxyReasonUnimplemented, trackLongTail)
// --repo routes to another workspace, bypassing the proxied root entirely,
// which is why it is design rather than a gap. `bd create` is the only
// command that registers the flag, so it is the only command this rule can
// actually refuse; every other row for it must be notApplicable(), which is
// what TestProxyCapabilityRowsNameFlagsTheCommandRegisters enforces.
repoRefusal = refused("proxy.repo.unsupported", "--repo is not supported with --proxied-server", ProxyReasonDesign, "")
)
// proxyCapabilityMatrix is the flag-keyed half of the policy; the path-keyed
// half is the registry in capability_registry.go. Reasons follow the same rule
// there and here.
//
// Strict --readonly is the one capability that needs real backend work rather
// than routing: it is a GUARANTEE, the proxied provider carries no read-only
// posture, and the only honest implementation is a read-only SQL principal on
// the backend — which on external topologies is the operator's configuration,
// not bd's. A best-effort version would betray exactly the workflows that ask
// for it, so it is refused by design until that principal exists. --repo is
// design for a simpler reason: it routes to another workspace, bypassing the
// proxied root entirely.
var proxyCapabilityMatrix = map[ProxyMode]map[ProxyCapability]proxyCapabilityRule{
ProxyModeDirect: {
ProxyCapReadonly: honored(), ProxyCapMaxRows: honored(),
ProxyCapWatch: honored(), ProxyCapRepo: honored(),
},
ProxyModeProxied: {
ProxyCapReadonly: refused("proxy.readonly.unsupported", "strict readonly is unavailable for dolt proxied-server backend; refusing to open a store that cannot guarantee mutation-free access", ProxyReasonDesign, "1.4 candidate: read-only SQL principal on the backend"),
ProxyCapMaxRows: maxRowsRefusal,
ProxyCapWatch: watchRefusal,
ProxyCapRepo: repoRefusal,
},
}
// proxyCommandCapabilities overrides the mode-wide default for one command.
// Keys are command paths (commandRegistryPath), so a row lands on the command it
// was written for and on nothing else. The "mol ready" row is a documentation
// pin rather than the guard: path keying is what stops `bd mol ready --gated`
// from inheriting the refusal `bd ready` carries on their shared leaf name
// "ready", and the row records that the command has no --max-rows flag to
// refuse. TestProxyCapabilityPolicyKeysResolveInRealCommandTree keeps the pin
// honest by failing if the path it names stops existing.
//
// A row must describe a flag the command actually registers. `list`'s
// ProxyCapRepo is notApplicable() for that reason and not as a hedge: listCmd
// has no --repo flag (create.go:940 registers the only one), so `bd list --repo`
// dies in cobra as an unknown flag and a refusal row here would be policy no
// command line can reach. TestProxyCapabilityRowsNameFlagsTheCommandRegisters
// enforces both directions of that rule.
var proxyCommandCapabilities = map[string]map[ProxyMode]map[ProxyCapability]proxyCapabilityRule{
"show": {ProxyModeProxied: {ProxyCapWatch: watchRefusal}},
"list": {ProxyModeProxied: {ProxyCapWatch: honored(), ProxyCapMaxRows: honored(), ProxyCapRepo: notApplicable()}},
"dep tree": {ProxyModeProxied: {ProxyCapMaxRows: honored()}},
"ready": {ProxyModeProxied: {ProxyCapMaxRows: maxRowsRefusal}},
"mol ready": {ProxyModeProxied: {ProxyCapMaxRows: notApplicable()}},
"graph": {ProxyModeProxied: {ProxyCapMaxRows: maxRowsRefusal}},
"find-duplicates": {ProxyModeProxied: {ProxyCapMaxRows: maxRowsRefusal}},
}
// proxyCapabilityRows materializes the policy for every supported proxied
// topology. Keeping rows explicit makes matrix audits and front-door tests
// deterministic even though the current provider implementations share rules.
var proxyCapabilityRows = buildProxyCapabilityRows()
func buildProxyCapabilityRows() []ProxyCapabilityRow {
topologies := []ProxyTopology{ProxyTopologyManagedLocal, ProxyTopologyExternalTCP, ProxyTopologyExternalUnix}
var rows []ProxyCapabilityRow
for _, topology := range topologies {
for _, capability := range []ProxyCapability{ProxyCapReadonly, ProxyCapMaxRows, ProxyCapWatch, ProxyCapRepo} {
rule, _ := LookupProxyCapability(ProxyModeProxied, capability)
rows = append(rows, ProxyCapabilityRow{ProxyCapabilityKey{"", string(capability), ProxyModeProxied, topology}, rule})
}
for command, modes := range proxyCommandCapabilities {
for mode, capabilities := range modes {
for capability, rule := range capabilities {
rows = append(rows, ProxyCapabilityRow{ProxyCapabilityKey{command, string(capability), mode, topology}, rule})
}
}
}
}
return rows
}
// LookupProxyCapabilityAt returns a topology-keyed rule. Unknown topology is
// rejected; ProxyTopologyAny applies the topology-independent direct policy.
func LookupProxyCapabilityAt(command, argument string, mode ProxyMode, topology ProxyTopology) (proxyCapabilityRule, bool) {
if topology != ProxyTopologyAny && topology != ProxyTopologyManagedLocal && topology != ProxyTopologyExternalTCP && topology != ProxyTopologyExternalUnix {
return proxyCapabilityRule{}, false
}
if len(argument) > 2 && argument[:2] == "--" {
argument = argument[2:]
}
for _, row := range proxyCapabilityRows {
if row.Command == command && row.Argument == argument && row.Mode == mode && row.Topology == topology {
return row.Rule, true
}
}
if topology == ProxyTopologyAny {
return LookupProxyCapabilityFor(command, argument, mode)
}
return proxyCapabilityRule{}, false
}
// LookupProxyCapability returns the typed rule for a mode/capability pair.
func LookupProxyCapability(mode ProxyMode, capability ProxyCapability) (proxyCapabilityRule, bool) {
rules, ok := proxyCapabilityMatrix[mode]
if !ok {
return proxyCapabilityRule{}, false
}
rule, ok := rules[capability]
return rule, ok
}
// AssertProxyCapability rejects unsupported features before provider setup.
func AssertProxyCapability(mode ProxyMode, capability ProxyCapability) error {
return AssertProxyCommandCapability("", mode, capability)
}
// proxyCapabilityAllowed reports whether an outcome lets the invocation
// proceed. ProxyOutcomeNA means the command does not have the flag at all
// (see ProxyCapabilityKey), which is a fact about the command rather than a
// policy objection: there is nothing to refuse, so it asserts successfully.
func proxyCapabilityAllowed(outcome ProxyCapabilityOutcome) bool {
return outcome == ProxyOutcomeHonored || outcome == ProxyOutcomeDelegated || outcome == ProxyOutcomeNA
}
// proxyCapabilityRuleError renders a non-allowing rule as an error. A rule
// with neither a code nor a message would otherwise produce an error whose
// Error() is the empty string, which the CLI prints as a bare "Error: " with
// exit 1 — the least debuggable failure available — so it falls back to a
// generic message no matter how a future rule is written.
// It builds the typed error through proxyCapabilityErrorFor so a rule's Reason
// reaches the JSON refusal here exactly as it does from the registry half; a
// local struct literal would silently drop it.
func proxyCapabilityRuleError(rule proxyCapabilityRule, capability ProxyCapability, mode ProxyMode) error {
if rule.Code != "" {
if rule.Message == "" {
// rule is a copy, so this fills the fallback in for this render
// only and never edits the policy table.
rule.Message = fmt.Sprintf("%s is not supported in %s mode", capability, mode)
}
return proxyCapabilityErrorFor(rule)
}
if rule.Message != "" {
return fmt.Errorf("%s", rule.Message)
}
return fmt.Errorf("%s is not supported in %s mode", capability, mode)
}
// AssertProxyCommandCapability checks a command-specific capability rule.
// command is a command path (commandRegistryPath), not a cobra leaf name.
func AssertProxyCommandCapability(command string, mode ProxyMode, capability ProxyCapability) error {
if commands, ok := proxyCommandCapabilities[command]; ok {
if modes, ok := commands[mode]; ok {
if rule, ok := modes[capability]; ok {
if proxyCapabilityAllowed(rule.Outcome) {
return nil
}
return proxyCapabilityRuleError(rule, capability, mode)
}
}
}
rule, ok := LookupProxyCapability(mode, capability)
if !ok || !proxyCapabilityAllowed(rule.Outcome) {
return proxyCapabilityRuleError(rule, capability, mode)
}
return nil
}
// validateProxyCapabilitiesBeforeProvider runs refusals that can be decided
// from argv before the proxied provider is opened.
func validateProxyCapabilitiesBeforeProvider(cmd *cobra.Command) error {
if cmd == nil {
return nil
}
path := commandRegistryPath(cmd)
if path == "create" && cmd.Flags().Changed("repo") {
return HandleProxyCapabilityError(AssertProxyCapability(ProxyModeProxied, ProxyCapRepo))
}
if path == "show" {
if watch, _ := cmd.Flags().GetBool("watch"); watch {
return HandleProxyCapabilityError(AssertProxyCommandCapability(path, ProxyModeProxied, ProxyCapWatch))
}
}
if path == "ready" && !readyGatedArm(cmd) {
// --claim is NOT exempt. The proxied ready role cannot enforce a row
// cap on either arm, and ready.go refuses a positive cap on both (see
// its comment above rejectMaxRowsUnderProxiedServer) — so exempting
// the claim here would not have let it through, only downgraded the
// same refusal to an untyped one raised after the provider opened.
// A malformed or negative value is still rejected here, before any
// provider work, which is what the claim path gained.
//
// --gated IS exempt, and the guard sits on the branch rather than
// inside it so the arm skips the resolver too: the direct route never
// resolves a cap before dispatching --gated, so resolving one here
// would make a malformed or negative value fail on the proxied route
// alone. See readyGatedArm for why the arm takes no cap at all.
maxRows, err := resolveMaxRowsQuiet(cmd)
if err != nil {
return err
}
if maxRows > 0 {
return HandleProxyCapabilityError(AssertProxyCommandCapability(path, ProxyModeProxied, ProxyCapMaxRows))
}
}
if path == "graph" || path == "find-duplicates" {
maxRows, err := resolveMaxRowsQuiet(cmd)
if err != nil {
return err
}
if maxRows > 0 {
return HandleProxyCapabilityError(AssertProxyCommandCapability(path, ProxyModeProxied, ProxyCapMaxRows))
}
}
return nil
}