Merge pull request #6905 from gastownhall/hotfix/1.3.1-proxied-backup

hotfix/1.3.1: proxied bd backup + purge wisps-plane/live-dependent protection/--limit
This commit is contained in:
Julian Knutsen 2026-09-28 12:39:50 -07:00 • committed by GitHub
commit f5a9402790
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
52 changed files with 4100 additions and 487 deletions

View file

@ -23,6 +23,8 @@ on:
- 'cmd/bd/proxied_server*.go'
- 'cmd/bd/dolt*.go'
- 'cmd/bd/*_proxied_server.go'
- 'cmd/bd/backup*.go'
- 'cmd/bd/purge*.go'
- 'cmd/bd/db_proxy_child.go'
- 'cmd/bd/init*.go'
- 'cmd/bd/proxied_integration_helpers_test.go'
@ -42,6 +44,8 @@ on:
- 'cmd/bd/proxied_server*.go'
- 'cmd/bd/dolt*.go'
- 'cmd/bd/*_proxied_server.go'
- 'cmd/bd/backup*.go'
- 'cmd/bd/purge*.go'
- 'cmd/bd/db_proxy_child.go'
- 'cmd/bd/init*.go'
- 'cmd/bd/proxied_integration_helpers_test.go'
@ -110,7 +114,10 @@ jobs:
TestManagedLocalProxiedDoltStatusReportsLiveTopology \
TestManagedLocalProxiedDoltStartRefusesOverLiveProxy \
TestManagedLocalProxiedDoltStartRefusesWithProxyDown \
TestManagedLocalProxiedDoltLifecycleLeavesOtherTopologiesAlone
TestManagedLocalProxiedDoltLifecycleLeavesOtherTopologiesAlone \
TestManagedLocalProxiedPurgeWispsPlaneRetention \
TestManagedLocalProxiedCapabilityMatrix \
TestManagedLocalProxiedBackupRoundTrip
do
if ! grep -qx "$test_name" <<<"$listed"; then
echo "managed-local lifecycle test $test_name is missing; got: '$listed'" >&2

View file

@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- **`bd backup` works on a proxied-server workspace bd runs the Dolt server
for.** `bd backup init`, `sync`, `remove`, `status` and `restore` are routed
over the proxied provider; before this, a proxied workspace — the default
topology since 1.3.0 — had no backup path at all. `bd backup restore` stops
the proxy and its Dolt child before replacing the database and leaves the
workspace quiescent, so the next command relaunches against the restored
data.
The family stays **refused by design** on a proxied workspace pointed at a
Dolt server bd does not own (an external host, socket, or a beads-team-server
database): `CALL DOLT_BACKUP('add', …)` registers the backup remote on the
*server*, where it is global to every client connected to it, so one
workspace's backup decision would silently become everyone's — the shape
`bd backup`'s own help text already warns about for auto-backup. A `file://`
destination has a second problem on top, since the server resolves that path
on its own filesystem. The refusal keeps the `proxy.backup.unsupported` code
and now carries `"reason": "design"`; a backup story for those deployments
belongs to whoever runs the server. Whether a *remote-scheme* destination
(DoltHub, `aws://`, `gs://`) should eventually be allowed there is recorded as
an open question rather than settled — the server pushes those over the
network from its own environment, which is the same credential question the
next slice has to answer for `dolt push`.
Backups on this topology are **explicit only**. Auto-backup has no
post-command hook on the proxied path, so `backup.enabled=true` does nothing
there; `bd backup status` and `bd backup` help now say so instead of
attributing the OFF to a missing git remote, which was never the reason on a
server topology. Wiring an auto-backup hook through the new routes is left to
a later slice.
- **`bd purge` covers an orchestrator's wisp retention sweep.** Three changes
that together let `bd purge --wisps-plane --older-than 168h --force` replace
a raw `DELETE FROM wisps` retention step:
- **Live-dependent protection, always on.** `bd purge` no longer deletes a
closed bead that a live bead depends on through a `parent-child`,
`tracks` or `blocks` edge — a closed molecule root whose step is still
open, a closed wisp a live convoy tracks, a closed blocker of live work.
"Live" is any status that is not done, including custom statuses. The
held-back count is reported as `live_dependent_skipped` in `--json` (and
on its own line in text output). The protection is on the role
(`issueops.SweepRequest.ProtectLiveDependents`); `bd prune` does not ask
for it.
- **`--wisps-plane`** selects every closed row stored in the wisps table,
including `--no-history` beads, which the default ephemeral selection
leaves to `bd prune`. It works on embedded, server and proxied
workspaces, and because it reaches durable-tier rows it requires
`--older-than` or `--pattern`, like `bd prune`
(`issueops.SweepWispsPlane`).
- **`--older-than` accepts hour and finer durations** (`36h`, `168h`,
`90m`, down to `1s`) on both `bd purge` and `bd prune`. Day values (`7`,
`7d`, `2w`) are unchanged. An `Nh` value used to be converted to whole
days: floored above a day (`36h` swept rows only 24 hours old) and
rounded UP to one day below it (`12h` kept everything younger than 24
hours). Both are now taken exactly, so `bd prune --older-than 12h` now
deletes rows closed 12–24 hours ago that it used to keep. A value too
large to represent (e.g. `213504d`) is now refused instead of silently
wrapping to a tiny age.
- **`--limit N`** caps one `bd purge` run at N beads, oldest-closed first
(`issueops.SweepRequest.Limit`), so a large backlog drains in bounded
transactions; `--json` then adds `remaining` and `has_more`. Loop while
`has_more` is true.
### Changed
- **Proxied-server refusals now say *why* they refuse.** The JSON a refused
command prints gains a `reason` field next to the existing `code`, `error`
and `mutates`: `design` for a refusal that is expected to stay (shared
history, multi-repo routing, destructive admin, strict `--readonly`) and
`unimplemented` for a capability gap with a named owner. Every existing code,
message and exit status is unchanged, and `reason` is absent on refusals that
report a runtime state rather than a policy, so existing consumers are
unaffected. The policy behind it moved into one registry
(`cmd/bd/capability_registry.go`) that every command must appear in.
- **A command with no proxied-server route now fails with a typed error**
(`proxy.store.unrouted`) instead of the bare string `proxy server store
should be uow provider`.
- **`bd backup restore --json` prints a result object on every topology**
(`{"restored": true, "source": "<dir>"}`). It previously printed nothing at
all, which left a caller unable to tell a completed restore from a silently
skipped one. This applies to direct/embedded workspaces too, not only proxied
ones.
- **`bd backup init`, `sync`, `remove` and `restore` no longer print a usage
block after a failure.** They now silence cobra's own error and usage
rendering like the rest of the CLI, so a failure is one error line on stderr
instead of the message followed by `Error: exit code 1` and the full usage
text. Exit statuses are unchanged; this applies on every topology.
- **`bd purge` keeps closed beads a live bead depends on.** A closed bead
that a not-done bead depends on through `parent-child`, `tracks` or
`blocks` is no longer purged (reported as `live_dependent_skipped`), so a
purge that used to delete a closed molecule root under a live step now
leaves it. See the `--wisps-plane` entry under Added.
## [1.3.1] - 2026-09-16
### Changed

View file

@ -637,6 +637,11 @@ var roleContractCases = []roleContract{
RunSweeperEmptyMatchIsZeroAndNil,
RunSweeperRecordsExactlyOneHistoryEntry,
RunSweeperDoesNotMutateTheCallerRequest,
RunSweeperWispsPlaneClearsTheWholeWispsTable,
RunSweeperWispsPlaneRequiresAFilter,
RunSweeperProtectsLiveDependents,
RunSweeperProtectsLiveDependentsAcrossPlanes,
RunSweeperLimitTakesTheOldestClosedFirst,
),
roleCases("TreeWalker", "TreeWalker()", oncePerRole,

View file

@ -89,6 +89,11 @@ type SweeperFixture struct {
// by hand. A nil Exec means "this backend cannot seed raw rows", and the
// case that needs it SKIPS with that reason rather than passing quietly.
Exec func(ctx context.Context, statements []SQLStatement) error
// AddDependencies wires edges between seeded rows, filled from the
// backend's DependencyEditor role so each adapter routes an edge to the
// dependency table of its source's plane itself. The live-dependent case
// needs it; a nil hook SKIPS that case with the reason.
AddDependencies func(ctx context.Context, req publicops.AddDependenciesRequest) error
}
// sweeperClosedAt is the stamp every seeded candidate carries, and
@ -345,7 +350,7 @@ func RunSweeperDryRunChangesNothing(t *testing.T, ctx context.Context, fixture S
IDPattern: sweeperPattern(fixture, "dry"),
}
preview := sweeperSweep(t, ctx, fixture, sweeperWithDryRun(request, true))
preview := sweeperSweep(t, ctx, fixture, sweeperAsDryRun(request))
if !preview.DryRun {
t.Error("preview.DryRun = false; the result must echo the request it answered")
}
@ -356,7 +361,7 @@ func RunSweeperDryRunChangesNothing(t *testing.T, ctx context.Context, fixture S
// A second preview: a dry run that had deleted anything reports a smaller
// number here.
if again := sweeperSweep(t, ctx, fixture, sweeperWithDryRun(request, true)); again.Swept != preview.Swept {
if again := sweeperSweep(t, ctx, fixture, sweeperAsDryRun(request)); again.Swept != preview.Swept {
t.Fatalf("second preview Swept = %d, first = %d: the first preview changed the store", again.Swept, preview.Swept)
}
@ -556,7 +561,7 @@ func RunSweeperRecordsExactlyOneHistoryEntry(t *testing.T, ctx context.Context,
}
before := sweeperHistory(t, ctx, fixture)
sweeperSweep(t, ctx, fixture, sweeperWithDryRun(request, true))
sweeperSweep(t, ctx, fixture, sweeperAsDryRun(request))
if after := sweeperHistory(t, ctx, fixture); after != before {
t.Errorf("history went %d -> %d across a DRY RUN, want no entry at all", before, after)
}
@ -609,6 +614,230 @@ func RunSweeperDoesNotMutateTheCallerRequest(t *testing.T, ctx context.Context,
}
}
// RunSweeperWispsPlaneClearsTheWholeWispsTable pins issueops.SweepWispsPlane:
// the selection is the wisps TABLE, so a closed no-history bead — durable-tier,
// and left alone by SweepEphemeral (RunSweeperLeavesNoHistoryBeadsToTheDurableTier)
// — goes with the closed ephemeral wisp, while a closed issues-plane row the
// same pattern admits stays.
func RunSweeperWispsPlaneClearsTheWholeWispsTable(t *testing.T, ctx context.Context, fixture SweeperFixture) {
t.Helper()
wisp := sweeperSeedClosedIssue(t, ctx, fixture, "plane", true)
durable := sweeperSeedClosedIssue(t, ctx, fixture, "plane", false)
noHistory := sweeperIssue(fixture, "plane", "nohist", false)
noHistory.NoHistory = true
if err := fixture.CreateWisp(ctx, noHistory, "sweeper-seed"); err != nil {
t.Fatalf("seeding %s: %v", noHistory.ID, err)
}
pinned := sweeperSeed(t, ctx, fixture, sweeperIssue(fixture, "plane", "pinned", true), func(issue *types.Issue) {
issue.Pinned = true
})
request := publicops.SweepRequest{
Tier: publicops.SweepWispsPlane,
IDPattern: sweeperPattern(fixture, "plane"),
ClosedBefore: &sweeperCutoff,
}
preview := sweeperSweep(t, ctx, fixture, sweeperAsDryRun(request))
if preview.Swept != 2 {
t.Fatalf("dry-run Swept = %d, want 2 (the ephemeral wisp and the no-history bead)", preview.Swept)
}
sweeperAssertWispRows(t, ctx, fixture, 3, wisp, noHistory.ID, pinned)
result := sweeperSweep(t, ctx, fixture, request)
if result.Swept != 2 {
t.Errorf("Swept = %d, want 2 (the ephemeral wisp and the no-history bead)", result.Swept)
}
if result.Skipped.Pinned != 1 {
t.Errorf("Skipped.Pinned = %d, want 1 — the plane selector does not override pinning", result.Skipped.Pinned)
}
sweeperAssertWispRows(t, ctx, fixture, 0, wisp, noHistory.ID)
sweeperAssertWispRows(t, ctx, fixture, 1, pinned)
sweeperAssertIssueRows(t, ctx, fixture, 1, durable)
}
// RunSweeperWispsPlaneRequiresAFilter pins that the wisps-plane tier carries
// the durable tier's require-a-filter gate: it reaches no-history beads, which
// are durable-tier. The refusal is asserted with its effect, as the durable
// case does.
func RunSweeperWispsPlaneRequiresAFilter(t *testing.T, ctx context.Context, fixture SweeperFixture) {
t.Helper()
id := sweeperSeedClosedIssue(t, ctx, fixture, "planegate", true)
result, err := fixture.Sweeper.Sweep(ctx, publicops.SweepRequest{Tier: publicops.SweepWispsPlane})
if !errors.Is(err, publicops.ErrValidation) {
t.Fatalf("Sweep(wisps-plane, no cutoff, no pattern) error = %v, want ErrValidation", err)
}
if result.Swept != 0 {
t.Errorf("refused sweep reported Swept = %d, want 0", result.Swept)
}
sweeperAssertWispRows(t, ctx, fixture, 1, id)
}
// RunSweeperProtectsLiveDependents pins issueops.SweepRequest.ProtectLiveDependents:
// a closed row a LIVE row depends on through parent-child, tracks or blocks is
// held back and counted, while a closed row reached only by a non-structural
// edge, or only by a dependent that is itself closed, is swept.
//
// The live sources carry three different not-done statuses (open,
// in_progress, hooked), because "live" is the not-done set and not "open".
// It runs on the wisps-plane tier with a cutoff — the request an
// orchestrator's retention sweep sends — after proving on a dry run that the
// same rows ARE candidates without the protection.
func RunSweeperProtectsLiveDependents(t *testing.T, ctx context.Context, fixture SweeperFixture) {
t.Helper()
if fixture.AddDependencies == nil {
t.Skip("fixture has no AddDependencies hook; cannot wire the edges this case needs")
}
live := func(name string, status types.Status) string {
issue := sweeperIssue(fixture, "live", name, true)
issue.Status = status
issue.ClosedAt = nil
return sweeperSeed(t, ctx, fixture, issue, nil)
}
closed := func(name string) string {
return sweeperSeed(t, ctx, fixture, sweeperIssue(fixture, "live", name, true), nil)
}
parent := closed("parent")
openChild := live("child-open", types.StatusOpen)
tracked := closed("tracked")
convoy := live("convoy", types.StatusInProgress)
blocker := closed("blocker")
hooked := live("hooked", types.StatusHooked)
related := closed("related")
relater := live("relater", types.StatusOpen)
doneParent := closed("done-parent")
doneChild := closed("done-child")
if err := fixture.AddDependencies(ctx, publicops.AddDependenciesRequest{
Actor: "sweeper-seed",
Edges: []publicops.DependencyEdge{
{IssueID: openChild, DependsOnID: parent, Type: publicops.DepParentChild},
{IssueID: convoy, DependsOnID: tracked, Type: publicops.DepTracks},
{IssueID: hooked, DependsOnID: blocker, Type: publicops.DepBlocks},
{IssueID: relater, DependsOnID: related, Type: publicops.DepRelated},
{IssueID: doneChild, DependsOnID: doneParent, Type: publicops.DepParentChild},
},
}); err != nil {
t.Fatalf("wiring dependencies: %v", err)
}
request := publicops.SweepRequest{
Tier: publicops.SweepWispsPlane,
IDPattern: sweeperPattern(fixture, "live"),
ClosedBefore: &sweeperCutoff,
}
unprotected := sweeperSweep(t, ctx, fixture, sweeperAsDryRun(request))
if unprotected.Swept != 6 || unprotected.Skipped.LiveDependent != 0 {
t.Fatalf("unprotected dry run: Swept = %d, LiveDependent = %d; want 6 and 0 — "+
"the protection must be asked for", unprotected.Swept, unprotected.Skipped.LiveDependent)
}
request.ProtectLiveDependents = true
result := sweeperSweep(t, ctx, fixture, request)
if result.Skipped.LiveDependent != 3 {
t.Errorf("Skipped.LiveDependent = %d, want 3 (the parent, the tracked bead and the blocker)",
result.Skipped.LiveDependent)
}
if result.Swept != 3 {
t.Errorf("Swept = %d, want 3 (the related-only bead and the closed parent/child pair)", result.Swept)
}
sweeperAssertWispRows(t, ctx, fixture, 3, parent, tracked, blocker)
sweeperAssertWispRows(t, ctx, fixture, 0, related, doneParent, doneChild)
sweeperAssertWispRows(t, ctx, fixture, 4, openChild, convoy, hooked, relater)
}
// RunSweeperProtectsLiveDependentsAcrossPlanes pins that the live-dependent
// protection reads BOTH dependency tables: a closed wisp that a live DURABLE
// (issues-table) bead depends on through parent-child, tracks or blocks is
// kept, whatever not-done status the durable source carries.
func RunSweeperProtectsLiveDependentsAcrossPlanes(t *testing.T, ctx context.Context, fixture SweeperFixture) {
t.Helper()
if fixture.AddDependencies == nil {
t.Skip("fixture has no AddDependencies hook; cannot wire the edges this case needs")
}
durableLive := func(name string, status types.Status) string {
issue := sweeperIssue(fixture, "xplane", name, false)
issue.Status = status
issue.ClosedAt = nil
return sweeperSeed(t, ctx, fixture, issue, nil)
}
closedWisp := func(name string) string {
return sweeperSeed(t, ctx, fixture, sweeperIssue(fixture, "xplane", name, true), nil)
}
parent := closedWisp("parent")
tracked := closedWisp("tracked")
blocker := closedWisp("blocker")
loose := closedWisp("loose")
child := durableLive("child", types.StatusOpen)
convoy := durableLive("convoy", types.StatusInProgress)
waiter := durableLive("waiter", types.StatusDeferred)
if err := fixture.AddDependencies(ctx, publicops.AddDependenciesRequest{
Actor: "sweeper-seed",
Edges: []publicops.DependencyEdge{
{IssueID: child, DependsOnID: parent, Type: publicops.DepParentChild},
{IssueID: convoy, DependsOnID: tracked, Type: publicops.DepTracks},
{IssueID: waiter, DependsOnID: blocker, Type: publicops.DepBlocks},
},
}); err != nil {
t.Fatalf("wiring cross-plane dependencies: %v", err)
}
result := sweeperSweep(t, ctx, fixture, publicops.SweepRequest{
Tier: publicops.SweepWispsPlane,
IDPattern: sweeperPattern(fixture, "xplane"),
ClosedBefore: &sweeperCutoff,
ProtectLiveDependents: true,
})
if result.Skipped.LiveDependent != 3 || result.Swept != 1 {
t.Errorf("Swept = %d, LiveDependent = %d; want 1 (the unlinked wisp) and 3", result.Swept, result.Skipped.LiveDependent)
}
sweeperAssertWispRows(t, ctx, fixture, 3, parent, tracked, blocker)
sweeperAssertWispRows(t, ctx, fixture, 0, loose)
sweeperAssertIssueRows(t, ctx, fixture, 3, child, convoy, waiter)
}
// RunSweeperLimitTakesTheOldestClosedFirst pins issueops.SweepRequest.Limit:
// one call deletes at most Limit rows, oldest closed_at first, and reports the
// rest as Remaining; the next call picks up where it stopped.
func RunSweeperLimitTakesTheOldestClosedFirst(t *testing.T, ctx context.Context, fixture SweeperFixture) {
t.Helper()
seed := func(name string, closed time.Time) string {
return sweeperSeed(t, ctx, fixture, sweeperIssue(fixture, "limit", name, true), func(issue *types.Issue) {
issue.ClosedAt = &closed
})
}
newest := seed("newest", sweeperClosedAt)
middle := seed("middle", sweeperClosedAt.Add(-24*time.Hour))
oldest := seed("oldest", sweeperClosedAt.Add(-48*time.Hour))
request := publicops.SweepRequest{
Tier: publicops.SweepEphemeral,
IDPattern: sweeperPattern(fixture, "limit"),
Limit: 2,
}
first := sweeperSweep(t, ctx, fixture, request)
if first.Swept != 2 || first.Remaining != 1 {
t.Fatalf("first limited sweep: Swept = %d, Remaining = %d; want 2 and 1", first.Swept, first.Remaining)
}
sweeperAssertWispRows(t, ctx, fixture, 0, oldest, middle)
sweeperAssertWispRows(t, ctx, fixture, 1, newest)
second := sweeperSweep(t, ctx, fixture, request)
if second.Swept != 1 || second.Remaining != 0 {
t.Fatalf("second limited sweep: Swept = %d, Remaining = %d; want 1 and 0", second.Swept, second.Remaining)
}
sweeperAssertWispRows(t, ctx, fixture, 0, newest)
if _, err := fixture.Sweeper.Sweep(ctx, publicops.SweepRequest{
Tier: publicops.SweepEphemeral, IDPattern: sweeperPattern(fixture, "limit"), Limit: -1,
}); !errors.Is(err, publicops.ErrValidation) {
t.Fatalf("negative Limit error = %v, want ErrValidation", err)
}
}
// --- fixture helpers -------------------------------------------------------
// sweeperPattern is the glob that scopes one case's ids: a sweep is asked of a
@ -664,8 +893,8 @@ func sweeperSeedOpen(t *testing.T, ctx context.Context, fixture SweeperFixture,
return sweeperSeed(t, ctx, fixture, issue, nil)
}
func sweeperWithDryRun(request publicops.SweepRequest, dryRun bool) publicops.SweepRequest {
request.DryRun = dryRun
func sweeperAsDryRun(request publicops.SweepRequest) publicops.SweepRequest {
request.DryRun = true
return request
}

View file

@ -40,7 +40,12 @@ Auto-backup default:
dir and full-sync the whole database — a self-amplifying storm. To back up
a shared server, run 'bd backup' explicitly (or set backup.enabled=true and
coordinate destinations). 'bd config get backup.enabled' shows the effective
value and its source.`,
value and its source.
On a proxied-server workspace that opt-in does not apply: auto-backup has
no post-command hook on that path, so backup.enabled=true is inert there.
The five backup verbs above are honored on a managed-local proxied server —
run 'bd backup sync' explicitly to back one up.`,
GroupID: "sync",
}
@ -56,7 +61,9 @@ func newBackupStatusCommand(sizeDatabase backupSizeFunc) *cobra.Command {
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("backup status is not supported in proxied-server mode")
if err := requireLocalProxiedBackup("backup status"); err != nil {
return err
}
}
evt := metrics.NewCommandEvent("backup-status")
defer func() {
@ -124,14 +131,9 @@ func newBackupStatusCommand(sizeDatabase backupSizeFunc) *cobra.Command {
// Show config (effective values with source)
enabled := isBackupAutoEnabled()
interval := config.GetDuration("backup.interval")
enabledSource := config.GetValueSource("backup.enabled")
enabledNote := ""
if enabledSource == config.SourceDefault {
if enabled {
enabledNote = " (auto: git remote detected)"
} else {
enabledNote = " (auto: no git remote)"
}
if note := backupAutoStatusNote(enabled); note != "" {
enabledNote = " (" + note + ")"
}
fmt.Printf("\nConfig: enabled=%v%s interval=%s\n",
enabled, enabledNote, interval)

View file

@ -40,6 +40,43 @@ func isBackupAutoEnabled() bool {
return primeHasGitRemote()
}
// backupAutoStatusNote returns the parenthetical `bd backup status`
// prints after the effective backup.enabled value, or "" when the value
// speaks for itself. Callers pass the value isBackupAutoEnabled()
// already computed so the note cannot disagree with the number beside
// it — and so status does not re-run the git-remote probe.
//
// The note narrates the reason the decision actually used. Proxied-server
// is checked first and ignores the config source, because on that topology
// auto-backup cannot run at all whatever backup.enabled says: the proxied
// arm of PersistentPostRunE never calls runPostRunAutoBackup (main.go), so
// an explicit backup.enabled=true is inert and reporting a bare
// "enabled=true" would send the operator away believing backups happen.
// The five backup verbs are honored on managed-local (the only proxied
// shape that reaches this line — every other one is refused by
// requireLocalProxiedBackup), so `bd backup sync` is the real answer there.
//
// Every other sql-server shape keeps its post-run hook, so there the
// default is merely off — the reason `bd config get backup.enabled`
// already reports for the same condition. Before this arm existed, status
// attributed that OFF to a missing git remote, which is untrue: server
// mode short-circuits isBackupAutoEnabled whether or not a remote exists.
func backupAutoStatusNote(enabled bool) string {
if usesProxiedServer() {
return "auto-backup does not run on proxied-server; use 'bd backup sync'"
}
if config.GetValueSource("backup.enabled") != config.SourceDefault {
return ""
}
if usesSQLServer() {
return "auto: off in sql-server mode"
}
if enabled {
return "auto: git remote detected"
}
return "auto: no git remote"
}
// clientServerShareFilesystem reports whether the configured Dolt
// server runs on a filesystem the bd client can also see — i.e.
// whether a file:// URL constructed on the client is meaningful to

View file

@ -123,6 +123,145 @@ func TestIsBackupAutoEnabled(t *testing.T) {
}
}
// TestBackupAutoStatusNote pins the reason `bd backup status` prints beside
// the effective backup.enabled value against the reason isBackupAutoEnabled
// actually used — the two are computed in different files and drifted apart
// once already.
//
// The regression this locks down arrived with the proxied-parity S3 slice
// (PR #6584): honoring the backup family on managed-local made `bd backup
// status` reachable on a proxied server for the first time, where it rendered
// the embedded-mode footnote "(auto: no git remote)". On any sql-server shape
// the value is false because usesSQLServer() short-circuits, whether or not a
// remote exists, so that reason was simply untrue; and on proxied specifically
// even an explicit backup.enabled=true changes nothing, because the proxied
// arm of PersistentPostRunE never calls runPostRunAutoBackup.
//
// Cannot be parallel: mutates the proxiedServerMode global, primeHasGitRemote
// and env vars.
func TestBackupAutoStatusNote(t *testing.T) {
tests := []struct {
name string
envVal string // "\x00" = not set, otherwise explicit backup.enabled
hasRemote bool
sharedServer bool // BEADS_DOLT_SHARED_SERVER=1 → usesSQLServer() true
proxied bool // proxiedServerMode → usesProxiedServer() true
wantEnabled bool
wantNote string
}{
{
name: "embedded default + git remote → unchanged",
envVal: "\x00",
hasRemote: true,
wantEnabled: true,
wantNote: "auto: git remote detected",
},
{
name: "embedded default + no git remote → unchanged",
envVal: "\x00",
hasRemote: false,
wantEnabled: false,
wantNote: "auto: no git remote",
},
{
name: "embedded explicit → no note, the source explains it",
envVal: "true",
hasRemote: false,
wantEnabled: true,
wantNote: "",
},
{
// Pre-fix this case printed "auto: no git remote" even with a
// remote configured: server mode, not the remote, is the reason.
name: "sql-server default + git remote → server mode, not the remote",
envVal: "\x00",
hasRemote: true,
sharedServer: true,
wantEnabled: false,
wantNote: "auto: off in sql-server mode",
},
{
// Non-proxied server mode keeps its post-run hook, so an explicit
// opt-in really does work there and needs no caveat.
name: "sql-server explicit opt-in → no note",
envVal: "true",
hasRemote: false,
sharedServer: true,
wantEnabled: true,
wantNote: "",
},
{
name: "proxied default → names the missing hook, not the remote",
envVal: "\x00",
hasRemote: true,
proxied: true,
wantEnabled: false,
wantNote: "auto-backup does not run on proxied-server; use 'bd backup sync'",
},
{
// The dead opt-in: enabled=true with nothing to run it. The note
// must survive an explicit source here, or status reports a bare
// "enabled=true" and the operator believes backups are happening.
name: "proxied explicit opt-in → still inert, still annotated",
envVal: "true",
hasRemote: false,
proxied: true,
wantEnabled: true,
wantNote: "auto-backup does not run on proxied-server; use 'bd backup sync'",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// Same isolation as TestIsBackupAutoEnabled: a leaked BEADS_DIR or
// a cwd inside the repo tree lets Initialize() load an ambient
// config.yaml whose explicit backup.enabled wins over the computed
// default these cases assert on (be-yjp4z).
t.Chdir(t.TempDir())
t.Setenv("BEADS_DIR", "")
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
orig := primeHasGitRemote
primeHasGitRemote = func() bool { return tt.hasRemote }
t.Cleanup(func() { primeHasGitRemote = orig })
origProxied := proxiedServerMode
proxiedServerMode = tt.proxied
t.Cleanup(func() { proxiedServerMode = origProxied })
if tt.sharedServer {
t.Setenv("BEADS_DOLT_SHARED_SERVER", "1")
} else {
os.Unsetenv("BEADS_DOLT_SHARED_SERVER")
t.Cleanup(func() { os.Unsetenv("BEADS_DOLT_SHARED_SERVER") })
}
if tt.envVal == "\x00" {
os.Unsetenv("BD_BACKUP_ENABLED")
t.Cleanup(func() { os.Unsetenv("BD_BACKUP_ENABLED") })
} else {
t.Setenv("BD_BACKUP_ENABLED", tt.envVal)
}
config.ResetForTesting()
t.Cleanup(func() { config.ResetForTesting() })
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
// Take the value the way backup status does, so the note is pinned
// against the number it is printed beside rather than a literal.
enabled := isBackupAutoEnabled()
if enabled != tt.wantEnabled {
t.Fatalf("isBackupAutoEnabled() = %v, want %v", enabled, tt.wantEnabled)
}
if got := backupAutoStatusNote(enabled); got != tt.wantNote {
t.Errorf("backupAutoStatusNote(%v) = %q, want %q", enabled, got, tt.wantNote)
}
})
}
}
// TestClientServerShareFilesystem_GH3523 pins the gating logic that
// suppresses auto-backup's file:// register when the Dolt server
// runs on a different filesystem from the client. Pre-fix every

View file

@ -46,10 +46,13 @@ DoltHub (recommended for cloud backup):
After adding, run 'bd backup sync' to push your data.`,
Args: cobra.ExactArgs(1),
// As on `backup status`: the failures here are configuration and I/O
// errors, not usage errors, and cobra's default prints the message, then
// "Error: exit code 1", then the whole usage block — three things where one
// was wanted, and on --json it lands after the JSON object.
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("backup init is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("backup-init")
defer func() {
if c := metrics.Global(); c != nil {
@ -60,6 +63,10 @@ After adding, run 'bd backup sync' to push your data.`,
ctx := rootCtx
rawPath := args[0]
if usesProxiedServer() {
return runBackupInitProxied(ctx, rawPath)
}
if store == nil {
return fmt.Errorf("no store available")
}
@ -124,10 +131,9 @@ backup location configured with 'bd backup init'.
The backup is atomic — if the sync fails, the previous backup state is preserved.
Run 'bd backup init <path>' first to configure a destination.`,
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("backup sync is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("backup-sync")
defer func() {
if c := metrics.Global(); c != nil {
@ -136,6 +142,9 @@ Run 'bd backup init <path>' first to configure a destination.`,
}()
ctx := rootCtx
if usesProxiedServer() {
return runBackupSyncProxied(ctx)
}
if store == nil {
return fmt.Errorf("no store available")
}
@ -358,7 +367,14 @@ func showDoltBackupStatusJSON() map[string]interface{} {
// doltBackupSize returns the active database size when the current store
// instance can measure its storage locally. Unsupported backends preserve the
// optional status-field contract instead of failing the command.
//
// Proxied mode has no store to ask — the provider owns the connection — so the
// fork lives here, where "which backend measures this database" is already the
// question being answered.
func doltBackupSize(ctx context.Context) (int64, bool, error) {
if usesProxiedServer() {
return doltBackupSizeProxied(ctx)
}
if store == nil {
return 0, false, fmt.Errorf("no storage backend is open")
}
@ -405,11 +421,10 @@ var backupRemoveCmd = &cobra.Command{
This unregisters the backup remote from Dolt and removes the local
backup configuration. The backup data at the destination is not deleted.`,
Aliases: []string{"rm"},
Aliases: []string{"rm"},
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("backup remove is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("backup-remove")
defer func() {
if c := metrics.Global(); c != nil {
@ -418,6 +433,9 @@ backup configuration. The backup data at the destination is not deleted.`,
}()
ctx := rootCtx
if usesProxiedServer() {
return runBackupRemoveProxied(ctx)
}
if store == nil {
return fmt.Errorf("no store available")
}

View file

@ -0,0 +1,107 @@
//go:build cgo
package main
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage/dbproxy/proxy"
"github.com/steveyegge/beads/internal/storage/dbproxy/server"
)
// TestProxiedServerBackupRefusedOnExternalTopology is the other half of slice
// S3: the backup family is honored on managed-local and refused BY DESIGN
// against a Dolt server bd does not own.
//
// The refusal matters more than the capability. `CALL DOLT_BACKUP('add', …)`
// registers the remote on the server, where it is global to every client of
// that server, so one workspace's backup decision becomes everyone's. With a
// file:/// destination there is a second problem on top: the server resolves
// that path on its own filesystem, so honoring it here would either fail at the
// point of use or write the backup to a directory on the server's host that the
// operator asking for it will never look in. The second outcome is worse than
// any refusal.
//
// Named TestProxiedServer* so .github/scripts/proxied-test-shard.sh runs it in
// the external lane, which is the only one with an external Dolt server.
func TestProxiedServerBackupRefusedOnExternalTopology(t *testing.T) {
requireProxiedServerEnv(t)
bd := buildEmbeddedBD(t)
p := newSharedProxiedProject(t, bd, "bkext")
dest := filepath.Join(t.TempDir(), "dolt-backup")
// Refusals are decided before the provider is constructed, so take the
// topology down first: a pidfile appearing during one of these commands
// would mean the refusal came too late to have cost nothing.
if err := proxy.Shutdown(p.proxyRoot); err != nil {
t.Logf("proxy.Shutdown(%s) before the refusal probes: %v", p.proxyRoot, err)
}
for _, tc := range []struct {
name string
args []string
}{
{"status", []string{"backup", "status"}},
{"init", []string{"backup", "init", dest}},
{"sync", []string{"backup", "sync"}},
{"remove", []string{"backup", "remove"}},
{"restore", []string{"backup", "restore", dest}},
} {
t.Run(tc.name, func(t *testing.T) {
args := append([]string{"--json"}, tc.args...)
out, err := bdProxiedRun(t, bd, p.dir, args...)
if err == nil {
t.Fatalf("bd %s succeeded on an external proxied topology:\n%s",
strings.Join(tc.args, " "), out)
}
var refusal struct {
Code string `json:"code"`
Error string `json:"error"`
Mutates bool `json:"mutates"`
Reason string `json:"reason"`
}
start := strings.Index(string(out), "{")
if start < 0 {
t.Fatalf("no typed refusal JSON:\n%s", out)
}
if err := json.Unmarshal(out[start:], &refusal); err != nil {
t.Fatalf("parse refusal JSON: %v\n%s", err, out)
}
if refusal.Code != "proxy.backup.unsupported" {
t.Errorf("code = %q, want proxy.backup.unsupported", refusal.Code)
}
if refusal.Mutates {
t.Errorf("refusal reported mutates=true")
}
// design, not unimplemented: no later slice is going to lift this.
if refusal.Reason != string(ProxyReasonDesign) {
t.Errorf("reason = %q, want design", refusal.Reason)
}
// The reason has to be the one that is true of every destination
// scheme. "resolved on the server's filesystem" is a file://
// property, and `bd backup init` also takes https/aws/gs.
if !strings.Contains(refusal.Error, "the backup remote is registered on the server, where it is global to every client") {
t.Errorf("refusal message does not say why: %q", refusal.Error)
}
// Nothing was started and nothing was written: the refusal is free.
for _, name := range []string{proxy.PIDFileName, server.PIDFileName} {
if _, err := os.Stat(filepath.Join(p.proxyRoot, name)); err == nil {
t.Errorf("a refused backup command started the topology (%s)", name)
}
}
if _, err := os.Stat(filepath.Join(p.beadsDir, "dolt-backup.json")); err == nil {
t.Errorf("a refused backup command wrote the local backup config")
}
if _, err := os.Stat(dest); err == nil {
t.Errorf("a refused backup command created %s", dest)
}
})
}
}

View file

@ -0,0 +1,208 @@
//go:build cgo && unix
package main
import (
"context"
"encoding/json"
"os"
"path/filepath"
"slices"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/storage/dbproxy/proxy"
"github.com/steveyegge/beads/internal/storage/dbproxy/server"
"github.com/steveyegge/beads/internal/storage/versioncontrolops"
)
// TestManagedLocalProxiedBackupRoundTrip is the claim slice S3 makes: a
// managed-local proxied workspace can take a Dolt-native backup and get its
// data back from it.
//
// It is deliberately a ROUND TRIP rather than a pair of exit-code assertions.
// A backup command that reports success without producing a restorable
// artifact is the failure that matters here, and the only way to rule it out is
// to restore the artifact and look at the issues that come back: the issue
// created BEFORE the backup must survive, and the one created AFTER it must be
// gone. Both directions are load-bearing — a restore that changed nothing would
// pass the first check alone.
//
// Named TestManagedLocalProxied* so the proxied-local smoke lane
// (.github/workflows/proxied-local-smoke.yml) runs it; that lane is the only
// one that sets BEADS_TEST_PROXIED_LOCAL.
func TestManagedLocalProxiedBackupRoundTrip(t *testing.T) {
requireManagedLocalProxiedEnv(t)
bd := buildEmbeddedBD(t)
p := bdManagedLocalInit(t, bd, "bkrt", 5*time.Minute)
before := bdProxiedCreate(t, bd, p.dir, "survives the restore", "-p", "1")
// Status first: it is the read-only probe that proves the route exists at
// all, and it must answer with a real measured size rather than the
// "optional field omitted" the external topologies produce.
status := readProxiedBackupStatus(t, bd, p)
if status.Dolt.Configured {
t.Fatalf("fresh workspace reports a configured backup: %+v", status.Dolt)
}
if status.DatabaseSize.Bytes <= 0 {
t.Fatalf("backup status measured no database: %+v", status.DatabaseSize)
}
dest := filepath.Join(t.TempDir(), "dolt-backup")
if out, err := bdProxiedRun(t, bd, p.dir, "backup", "init", dest); err != nil {
t.Fatalf("bd backup init %s: %v\n%s", dest, err, out)
}
if out, err := bdProxiedRun(t, bd, p.dir, "backup", "sync"); err != nil {
t.Fatalf("bd backup sync: %v\n%s", err, out)
}
// A Dolt backup is a chunk store with a manifest; an empty directory here
// would mean the command reported a success it did not perform.
if _, err := os.Stat(filepath.Join(dest, "manifest")); err != nil {
t.Fatalf("backup sync produced no manifest at %s: %v", dest, err)
}
after := bdProxiedCreate(t, bd, p.dir, "must not survive the restore", "-p", "1")
out, err := bdProxiedRun(t, bd, p.dir, "backup", "restore", dest, "--force", "--json")
if err != nil {
t.Fatalf("bd backup restore %s --force: %v\n%s", dest, err, out)
}
var result struct {
Restored bool `json:"restored"`
Source string `json:"source"`
}
if err := json.Unmarshal(out, &result); err != nil {
t.Fatalf("parse restore JSON: %v\n%s", err, out)
}
if !result.Restored || result.Source != dest {
t.Fatalf("unexpected restore result: %+v; want restored=true, source=%s", result, dest)
}
// The restore quiesces the topology and leaves it down, so the next command
// relaunches against the restored data. Assert that rather than assume it:
// a restore that ran with the old server still up would be the undefined
// case this design exists to avoid.
for _, name := range []string{proxy.PIDFileName, server.PIDFileName} {
if _, err := os.Stat(filepath.Join(p.proxyRoot, name)); err == nil {
t.Fatalf("restore left %s in place; the topology should be quiescent afterwards", name)
}
}
issues := bdProxiedListJSON(t, bd, p)
var ids []string
for _, issue := range issues {
ids = append(ids, issue.ID)
}
if !slices.Contains(ids, before.ID) {
t.Fatalf("restore lost the issue the backup contained (%s); got %v", before.ID, ids)
}
if slices.Contains(ids, after.ID) {
t.Fatalf("restore did not replace the database: %s was created after the backup and is still here; got %v",
after.ID, ids)
}
// The restore registers its source as the backup destination, so a plain
// `bd backup sync` works straight afterwards with no second init.
restored := readProxiedBackupStatus(t, bd, p)
if !restored.Dolt.Configured || !strings.HasSuffix(restored.Dolt.BackupURL, dest) {
t.Fatalf("restore did not register %s as the backup destination: %+v", dest, restored.Dolt)
}
if out, err := bdProxiedRun(t, bd, p.dir, "backup", "sync"); err != nil {
t.Fatalf("bd backup sync after restore: %v\n%s", err, out)
}
if out, err := bdProxiedRun(t, bd, p.dir, "backup", "remove"); err != nil {
t.Fatalf("bd backup remove: %v\n%s", err, out)
}
removed := readProxiedBackupStatus(t, bd, p)
if removed.Dolt.Configured {
t.Fatalf("backup remove left the destination configured: %+v", removed.Dolt)
}
// Removing the destination unregisters the remote; it does not delete the
// backup, which is what makes `bd backup remove` safe to run.
if _, err := os.Stat(filepath.Join(dest, "manifest")); err != nil {
t.Fatalf("backup remove deleted the backup data at %s: %v", dest, err)
}
if out, err := bdProxiedRun(t, bd, p.dir, "backup", "sync"); err == nil {
t.Fatalf("bd backup sync succeeded with no destination configured:\n%s", out)
}
}
// A backup with a malformed migration table can replace the database but fail
// the following provider construction at schema initialization. That failure must
// still leave both processes down, even though no provider was returned.
func TestManagedLocalProxiedBackupRestoreReopenFailure(t *testing.T) {
requireManagedLocalProxiedEnv(t)
bd := buildEmbeddedBD(t)
p := bdManagedLocalInit(t, bd, "bkrf", 5*time.Minute)
dest := filepath.Join(t.TempDir(), "malformed-backup")
if out, err := bdProxiedRun(t, bd, p.dir, "backup", "init", dest); err != nil {
t.Fatalf("backup init: %v\n%s", err, out)
}
// Damage the migration table in the backup, then repair the live table so
// the command's initial provider can open normally. Only its post-restore
// constructor will see the malformed table and fail after starting Dolt.
held := openHeldManagedProxiedConn(t, bd, p)
ctx := context.Background()
if _, err := held.Conn.ExecContext(ctx, "ALTER TABLE schema_migrations RENAME COLUMN version TO broken_version"); err != nil {
t.Fatalf("damage migration table: %v", err)
}
if _, err := held.Conn.ExecContext(ctx, "CALL DOLT_COMMIT('-Am', 'Simulate a malformed migration table in the backup')"); err != nil {
t.Fatalf("commit malformed migration table: %v", err)
}
if err := versioncontrolops.BackupSync(ctx, held.Conn, proxiedBackupTargetName); err != nil {
t.Fatalf("back up malformed schema: %v", err)
}
if _, err := held.Conn.ExecContext(ctx, "ALTER TABLE schema_migrations RENAME COLUMN broken_version TO version"); err != nil {
t.Fatalf("repair live migration table: %v", err)
}
held.Release()
out, err := bdProxiedRun(t, bd, p.dir, "backup", "restore", dest, "--force")
if err == nil {
t.Fatalf("restore unexpectedly reopened a malformed schema:\n%s", out)
}
if !strings.Contains(string(out), "the restored database did not reopen") || !strings.Contains(string(out), "schema") {
t.Fatalf("expected post-restore schema initialization failure, got:\n%s", out)
}
if strings.Contains(string(out), "restored and reconciled") {
t.Fatalf("failed reopen reported successful reconciliation:\n%s", out)
}
for _, name := range []string{proxy.PIDFileName, server.PIDFileName} {
if _, err := os.Stat(filepath.Join(p.proxyRoot, name)); !os.IsNotExist(err) {
t.Errorf("failed reopen should remove %s; stat error: %v", name, err)
}
}
}
type proxiedBackupStatus struct {
Dolt struct {
Configured bool `json:"configured"`
BackupURL string `json:"backup_url"`
BackupName string `json:"backup_name"`
} `json:"dolt"`
DatabaseSize struct {
Bytes int64 `json:"bytes"`
} `json:"database_size"`
}
func readProxiedBackupStatus(t *testing.T, bd string, p proxiedProject) proxiedBackupStatus {
t.Helper()
out, err := bdProxiedRun(t, bd, p.dir, "backup", "status", "--json")
if err != nil {
t.Fatalf("bd backup status --json: %v\n%s", err, out)
}
start := strings.Index(string(out), "{")
if start < 0 {
t.Fatalf("bd backup status --json produced no JSON:\n%s", out)
}
var status proxiedBackupStatus
if err := json.Unmarshal(out[start:], &status); err != nil {
t.Fatalf("parse backup status JSON: %v\n%s", err, out)
}
return status
}

View file

@ -0,0 +1,285 @@
package main
import (
"encoding/json"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/configfile"
)
// TestProxiedRestoreFailureMessage pins the one distinction the operator acts
// on: whether the data came back. A teardown failure happens after the step
// succeeded, so reporting it as "restore failed" is not a wording nit — it
// tells someone whose database IS restored to restore it again.
func TestProxiedRestoreFailureMessage(t *testing.T) {
boom := errors.New("proxy shutdown: connection refused")
for _, tc := range []struct {
name string
afterReconcile bool
err error
wantContains []string
wantMissing []string
}{
{
name: "restore itself failed",
err: errors.New("DOLT_BACKUP: no such backup"),
// No claim that anything was restored.
wantContains: []string{"restore failed", "no such backup"},
wantMissing: []string{"the data is restored"},
},
{
name: "restore succeeded, teardown failed",
err: &proxiedTeardownError{err: boom},
wantContains: []string{"the data is restored", "bd dolt stop --force", "bd backup init"},
wantMissing: []string{"restore failed"},
},
{
name: "reconcile failed for real",
afterReconcile: true,
err: errors.New("open provider: schema is behind"),
wantContains: []string{"the restored database did not reopen", "schema is behind"},
wantMissing: []string{"restore failed"},
},
{
name: "reconcile succeeded, teardown failed",
afterReconcile: true,
err: &proxiedTeardownError{err: boom},
wantContains: []string{"the data is restored and reconciled", "bd dolt stop --force"},
// Nothing left to re-register: the reconcile already ran.
wantMissing: []string{"restore failed", "bd backup init"},
},
} {
t.Run(tc.name, func(t *testing.T) {
got := proxiedRestoreFailureMessage("/tmp/backup", tc.afterReconcile, tc.err)
for _, want := range tc.wantContains {
if !strings.Contains(got, want) {
t.Errorf("message %q does not contain %q", got, want)
}
}
for _, unwanted := range tc.wantMissing {
if strings.Contains(got, unwanted) {
t.Errorf("message %q must not contain %q", got, unwanted)
}
}
})
}
}
// backupFamilyPaths is every registry path the backup family owns. Keeping the
// list in one place is what makes "the whole family moves together" an
// assertion rather than a convention.
var backupFamilyPaths = []string{
"backup", "backup init", "backup sync", "backup remove", "backup status", "backup restore",
}
// TestProxiedBackupHonoredOnlyOnManagedLocal is the locality policy.
//
// A Dolt backup destination is resolved by the SERVER: CALL DOLT_BACKUP('add',
// name, 'file:///…') names a path on the machine running dolt, not on the
// machine running bd. On managed-local that is the same machine and the same
// user, because bd spawned the child itself. On every other proxied shape it is
// somebody else's filesystem, so honoring the command would either fail at the
// point of use or — much worse — succeed and write the backup somewhere the
// operator cannot see. That is why these stay refused with Reason=design.
func TestProxiedBackupHonoredOnlyOnManagedLocal(t *testing.T) {
for _, path := range backupFamilyPaths {
row, ok := LookupCapabilityRow(path, "")
if !ok {
t.Fatalf("%q has no registry row", path)
}
if got := row.ruleFor(ProxyTopologyManagedLocal); got.Outcome != ProxyOutcomeHonored {
t.Errorf("%q on managed-local: outcome %q, want honored", path, got.Outcome)
}
for _, topology := range []ProxyTopology{
ProxyTopologyExternalTCP, ProxyTopologyExternalUnix,
ProxyTopologyTeamServer, ProxyTopologyUnknown,
} {
got := row.ruleFor(topology)
if got.Outcome != ProxyOutcomeRefused {
t.Errorf("%q on %s: outcome %q, want refused", path, topology, got.Outcome)
}
if got.Reason != ProxyReasonDesign {
t.Errorf("%q on %s: reason %q, want design", path, topology, got.Reason)
}
if got.Code != "proxy.backup.unsupported" {
t.Errorf("%q on %s: code %q, want the frozen proxy.backup.unsupported", path, topology, got.Code)
}
if !strings.Contains(got.Message, "is not supported in proxied-server mode") {
t.Errorf("%q on %s: message %q dropped the frozen prefix", path, topology, got.Message)
}
}
}
}
// TestProxiedBackupGateRefusesByTopology exercises the gate itself rather than
// the table, so a row that is right while the validator ignores the topology
// still fails.
func TestProxiedBackupGateRefusesByTopology(t *testing.T) {
newBackupCmd := func(sub string) *cobra.Command {
root := &cobra.Command{Use: "bd"}
parent := &cobra.Command{Use: "backup"}
child := &cobra.Command{Use: sub}
parent.AddCommand(child)
root.AddCommand(parent)
return child
}
for _, sub := range []string{"init", "sync", "remove", "status", "restore"} {
t.Run(sub, func(t *testing.T) {
if err := validateProxyRegistryBeforeProvider(newBackupCmd(sub), ProxyTopologyManagedLocal); err != nil {
t.Fatalf("managed-local: gate refused %q: %v", sub, err)
}
err := validateProxyRegistryBeforeProvider(newBackupCmd(sub), ProxyTopologyExternalTCP)
if err == nil {
t.Fatalf("external-tcp: gate permitted %q", sub)
}
})
}
}
// TestProxiedBackupRefusalJSONCarriesDesignReason pins what a consumer sees.
// The three frozen fields are unchanged and reason now says "design", which is
// the difference that matters: this refusal is not waiting on a later slice.
func TestProxiedBackupRefusalJSONCarriesDesignReason(t *testing.T) {
t.Setenv("BD_JSON_ENVELOPE", "")
oldJSON := jsonOutput
jsonOutput = true
t.Cleanup(func() { jsonOutput = oldJSON })
root := &cobra.Command{Use: "bd"}
parent := &cobra.Command{Use: "backup"}
child := &cobra.Command{Use: "sync"}
parent.AddCommand(child)
root.AddCommand(parent)
out := captureStdout(t, func() error {
_ = validateProxyRegistryBeforeProvider(child, ProxyTopologyExternalTCP)
return nil
})
for _, want := range []string{
`"code": "proxy.backup.unsupported"`,
`"mutates": false`,
`"reason": "design"`,
} {
if !strings.Contains(out, want) {
t.Fatalf("refusal JSON missing %s:\n%s", want, out)
}
}
}
// TestResolveProxiedTopology covers the resolution the gate depends on. The
// team-server case is the one worth reading twice: ownership beats transport,
// because a bts-managed database is somebody else's store whether bd reaches it
// over a socket, a port, or a child it spawned itself.
func TestResolveProxiedTopology(t *testing.T) {
for _, tc := range []struct {
name string
cfg configfile.Config
sidecar *configfile.ProxiedServerClientInfo
rawCfg string // when set, written verbatim instead of cfg
rawCar string // when set, written verbatim instead of sidecar
want ProxyTopology
}{
{
name: "managed local has no external block",
cfg: configfile.Config{DoltMode: configfile.DoltModeProxiedServer},
sidecar: &configfile.ProxiedServerClientInfo{},
want: ProxyTopologyManagedLocal,
},
{
name: "no sidecar at all is still managed local",
cfg: configfile.Config{DoltMode: configfile.DoltModeProxiedServer},
sidecar: nil,
want: ProxyTopologyManagedLocal,
},
{
name: "external host and port",
cfg: configfile.Config{DoltMode: configfile.DoltModeProxiedServer},
sidecar: &configfile.ProxiedServerClientInfo{
External: &configfile.ExternalDoltConfig{Host: "db.example.com", Port: 3306},
},
want: ProxyTopologyExternalTCP,
},
{
name: "external unix socket",
cfg: configfile.Config{DoltMode: configfile.DoltModeProxiedServer},
sidecar: &configfile.ProxiedServerClientInfo{
External: &configfile.ExternalDoltConfig{Socket: "/var/run/dolt.sock"},
},
want: ProxyTopologyExternalUnix,
},
{
name: "team server beats the transport",
cfg: configfile.Config{DoltMode: configfile.DoltModeProxiedServer, DoltTeamServer: true},
sidecar: &configfile.ProxiedServerClientInfo{
External: &configfile.ExternalDoltConfig{Host: "bts.example.com", Port: 3306},
},
want: ProxyTopologyTeamServer,
},
{
name: "team server on a local child is still team server",
cfg: configfile.Config{DoltMode: configfile.DoltModeProxiedServer, DoltTeamServer: true},
sidecar: &configfile.ProxiedServerClientInfo{},
want: ProxyTopologyTeamServer,
},
{
name: "unreadable sidecar fails closed",
cfg: configfile.Config{DoltMode: configfile.DoltModeProxiedServer},
rawCar: "{ not json",
want: ProxyTopologyUnknown,
},
{
name: "unreadable workspace config fails closed",
rawCfg: "{ not json",
want: ProxyTopologyUnknown,
},
} {
t.Run(tc.name, func(t *testing.T) {
beadsDir := filepath.Join(t.TempDir(), ".beads")
if err := os.MkdirAll(beadsDir, 0o750); err != nil {
t.Fatal(err)
}
switch {
case tc.rawCfg != "":
writeTestFile(t, configfile.ConfigPath(beadsDir), tc.rawCfg)
default:
cfg := tc.cfg
cfg.Backend = configfile.BackendDolt
data, err := json.Marshal(cfg)
if err != nil {
t.Fatal(err)
}
writeTestFile(t, configfile.ConfigPath(beadsDir), string(data))
}
switch {
case tc.rawCar != "":
writeTestFile(t, configfile.ProxiedServerClientInfoPath(beadsDir), tc.rawCar)
case tc.sidecar != nil:
data, err := json.Marshal(tc.sidecar)
if err != nil {
t.Fatal(err)
}
writeTestFile(t, configfile.ProxiedServerClientInfoPath(beadsDir), string(data))
}
if got := resolveProxiedTopology(beadsDir); got != tc.want {
t.Fatalf("resolveProxiedTopology = %q, want %q", got, tc.want)
}
})
}
}
func writeTestFile(t *testing.T, path, body string) {
t.Helper()
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
t.Fatal(err)
}
}

View file

@ -0,0 +1,477 @@
package main
import (
"context"
"database/sql"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"time"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/dbproxy/proxy"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/storage/uow"
"github.com/steveyegge/beads/internal/storage/versioncontrolops"
)
// Dolt-native backup over the proxied-server provider.
//
// The mechanism needed no proxy work at all: CALL DOLT_BACKUP(...) is ordinary
// SQL, RunNonTx already hands out a raw pinned connection (the seam `compact
// --dolt` and `gc` run on), the UOW DSN sets a connect timeout but no read
// deadline, and an active connection keeps the idle reaper from arming — so a
// backup that takes minutes is safe from both the driver and the 30s reaper.
//
// What the family DID need is the locality policy, which lives in the registry
// (see capability_registry.go's backup rows) because it is what the front door
// enforces. The guard below repeats it at the route because these functions are
// reachable from RunE, and a route that trusts the gate is one refactor away
// from writing a backup onto a host it does not own.
//
// None of these routes touch commandDidWrite or commandDidExplicitDoltCommit.
// Those two drive the post-run Dolt auto-commit, which is an embedded/direct
// concern — PersistentPostRunE's proxied branch never reads them — and the
// other proxied routes leave them alone for the same reason.
// proxiedBackupTargetName is the Dolt backup remote bd registers. Same name the
// direct path uses, so a workspace that changes topology still finds its
// destination.
const proxiedBackupTargetName = defaultDoltBackupName
// requireLocalProxiedBackup re-checks the locality policy at the route.
// Defense in depth, not a second policy: the rule and its wording come from the
// same registry row the pre-provider gate consults, so the two cannot drift.
func requireLocalProxiedBackup(path string) error {
row, ok := LookupCapabilityRow(path, "")
if !ok {
// Unreachable: TestProxyCapabilityRegistryCoversCommandTree fails the
// build for a backup path with no row. Refuse rather than guess.
return HandleErrorRespectJSON("%s has no proxied-server capability row", path)
}
rule := row.ruleFor(resolveProxiedTopology(beads.FindBeadsDir()))
if rule.Outcome == ProxyOutcomeHonored {
return nil
}
return HandleProxyCapabilityError(proxyCapabilityErrorFor(rule))
}
// proxiedActiveDatabase asks the server which database the provider opened,
// rather than re-deriving it from the workspace config. The provider already
// resolved that question (metadata.json, then --database/--db), and a second
// ladder here would be a second answer waiting to disagree with it.
func proxiedActiveDatabase(ctx context.Context) (string, error) {
var database string
err := runProxiedNonTx(ctx, func(ctx context.Context, conn *sql.Conn) error {
var name sql.NullString
if err := conn.QueryRowContext(ctx, "SELECT DATABASE()").Scan(&name); err != nil {
return fmt.Errorf("resolve active database: %w", err)
}
if !name.Valid || name.String == "" {
return fmt.Errorf("the proxied connection has no database selected")
}
database = name.String
return nil
})
return database, err
}
// runBackupInitProxied registers the backup destination, mirroring the direct
// path's conflict handling: Dolt refuses a second remote at an address another
// one already holds, and a re-init to a new path has to replace the old entry
// rather than fail.
func runBackupInitProxied(ctx context.Context, rawPath string) error {
if err := requireLocalProxiedBackup("backup init"); err != nil {
return err
}
backupURL := resolveDoltBackupURL(rawPath)
err := runProxiedNonTx(ctx, func(ctx context.Context, conn *sql.Conn) error {
addErr := versioncontrolops.BackupAdd(ctx, conn, proxiedBackupTargetName, backupURL)
if addErr == nil {
return nil
}
switch {
case strings.Contains(addErr.Error(), "already exists"):
// Same name, different URL: replace it.
_ = versioncontrolops.BackupRemove(ctx, conn, proxiedBackupTargetName)
case versioncontrolops.ExtractAddressConflictName(addErr) != "":
// A different name (auto-export registers "backup_export") already
// points at this URL; take the address over.
_ = versioncontrolops.BackupRemove(ctx, conn, versioncontrolops.ExtractAddressConflictName(addErr))
default:
return addErr
}
return versioncontrolops.BackupAdd(ctx, conn, proxiedBackupTargetName, backupURL)
})
if err != nil {
return HandleErrorRespectJSON("failed to add backup destination: %v", err)
}
if err := saveDoltBackupConfig(backupURL); err != nil {
fmt.Fprintf(os.Stderr, "Warning: backup registered but failed to save config: %v\n", err)
}
if jsonOutput {
return outputJSON(map[string]interface{}{
"backup_url": backupURL,
"backup_name": proxiedBackupTargetName,
"initialized": true,
})
}
fmt.Printf("Backup destination configured: %s\n", backupURL)
fmt.Println("Run 'bd backup sync' to push your data.")
return nil
}
// runBackupSyncProxied pushes the database to the configured destination.
func runBackupSyncProxied(ctx context.Context) error {
if err := requireLocalProxiedBackup("backup sync"); err != nil {
return err
}
start := time.Now()
err := runProxiedNonTx(ctx, func(ctx context.Context, conn *sql.Conn) error {
if err := commitWorkingSetBeforeBackup(ctx, conn); err != nil {
// Same posture as the direct path: a failed pre-backup commit
// means the backup may miss the newest writes, which is worth
// saying out loud and is not worth refusing to back up over.
fmt.Fprintf(os.Stderr, "Warning: failed to commit pending changes: %v\n", err)
}
return versioncontrolops.BackupSync(ctx, conn, proxiedBackupTargetName)
})
if err != nil {
if strings.Contains(err.Error(), "no backup") || strings.Contains(err.Error(), "not found") {
return HandleErrorRespectJSON("no backup destination configured. Run 'bd backup init <path>' first")
}
return HandleErrorRespectJSON("backup sync failed: %v", err)
}
elapsed := time.Since(start)
if err := updateDoltBackupState(elapsed); err != nil {
fmt.Fprintf(os.Stderr, "Warning: backup synced but failed to update state: %v\n", err)
}
if jsonOutput {
return outputJSON(map[string]interface{}{
"synced": true,
"duration": elapsed.String(),
})
}
fmt.Printf("Backup synced in %s\n", elapsed.Round(time.Millisecond))
return nil
}
// commitWorkingSetBeforeBackup is the proxied twin of the direct path's
// "bd: pre-backup commit". DOLT_BACKUP syncs COMMITTED history, so anything
// still in the working set would silently be missing from the backup.
//
// It is normally a no-op: every proxied write transaction ends in
// DOLT_COMMIT('-Am') (uow doltServerTx.Commit), so the working set is already
// clean. The pending check is what keeps this from minting an empty commit on
// every sync — Dolt rejects those server-side and logs each one.
func commitWorkingSetBeforeBackup(ctx context.Context, conn *sql.Conn) error {
pending, err := issueops.HasPendingChanges(ctx, conn)
if err != nil {
return fmt.Errorf("check pending changes: %w", err)
}
if !pending {
return nil
}
if _, err := conn.ExecContext(ctx, "CALL DOLT_COMMIT('-Am', ?)", "bd: pre-backup commit"); err != nil {
if issueops.IsNothingToCommitError(err) {
return nil
}
return err
}
return nil
}
// runBackupRemoveProxied unregisters the destination and drops the local
// sidecars. The backup data itself is left alone, as in direct mode.
func runBackupRemoveProxied(ctx context.Context) error {
if err := requireLocalProxiedBackup("backup remove"); err != nil {
return err
}
err := runProxiedNonTx(ctx, func(ctx context.Context, conn *sql.Conn) error {
if err := versioncontrolops.BackupRemove(ctx, conn, proxiedBackupTargetName); err != nil {
return err
}
// auto-export may have registered a second remote at the same URL.
_ = versioncontrolops.BackupRemove(ctx, conn, "backup_export")
return nil
})
if err != nil {
if strings.Contains(err.Error(), "not found") || strings.Contains(err.Error(), "no backup") {
return HandleErrorRespectJSON("no backup destination configured")
}
return HandleErrorRespectJSON("failed to remove backup: %v", err)
}
if path, err := doltBackupConfigPath(); err == nil {
_ = os.Remove(path)
}
if path, err := doltBackupStatePath(); err == nil {
_ = os.Remove(path)
}
if jsonOutput {
return outputJSON(map[string]interface{}{"removed": true})
}
fmt.Println("Backup destination removed.")
return nil
}
// doltBackupSizeProxied measures the managed-local database on disk, which is
// what `bd backup status` reports on every other topology that can answer.
//
// It reads the directory rather than asking Dolt because that is what the
// direct stores do (DoltStore.ActiveDatabaseSize measures
// localActiveDatabaseDir), so the number means the same thing in both modes.
// The database NAME still comes from the server, so the directory measured is
// the one this connection is actually using.
func doltBackupSizeProxied(ctx context.Context) (int64, bool, error) {
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return 0, false, nil
}
root, err := resolveProxiedServerRootPath(beadsDir)
if err != nil {
return 0, false, nil
}
database, err := proxiedActiveDatabase(ctx)
if err != nil {
return 0, false, err
}
dir := filepath.Join(root, database)
if _, err := os.Stat(dir); err != nil {
// No local directory means nothing bd can measure; the status contract
// treats size as optional rather than failing the command.
return 0, false, nil
}
size, err := storage.MeasureDirectorySize(ctx, dir)
if err != nil {
return 0, false, fmt.Errorf("measure active database directory %q: %w", dir, err)
}
return size, true, nil
}
// runBackupRestoreProxied restores the database from a Dolt backup, quiescing
// the topology first.
//
// DOLT_BACKUP('restore') REPLACES the database under the server. Doing that
// while clients hold connections to it is undefined, so the restore runs with
// bd as the only client and nothing else pointed at the store:
//
// 1. `bd backup restore` already holds the workspace and physical-root gates
// EXCLUSIVELY (commandNeedsExclusiveGate), so no other gated bd command —
// including `bd serve` — is using this workspace.
// 2. This function closes the provider the root pre-run opened and shuts the
// proxy and its dolt child down, so no connection survives into the
// replace.
// 3. It reopens a provider of its own, which relaunches the topology with
// exactly one client, and runs the restore on that.
// 4. It shuts the topology down again and reopens once more to finish: the
// reopen proves the restored database is serviceable, and it is where the
// project identity and the backup remote are reconciled. A connection
// pinned across the replace would be reading a database that no longer
// exists underneath it.
//
// The final shutdown leaves the workspace quiescent, so the next bd command
// relaunches lazily against the restored data.
func runBackupRestoreProxied(ctx context.Context, dir string, force bool) error {
if err := requireLocalProxiedBackup("backup restore"); err != nil {
return err
}
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return HandleErrorRespectJSON("%s", activeWorkspaceNotFoundError())
}
root, err := resolveProxiedServerRootPath(beadsDir)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
backupURL, err := versioncontrolops.DirToFileURL(dir)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
// Ask the live provider which database to replace before taking it away.
database, err := proxiedActiveDatabase(ctx)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
if err := quiesceProxiedTopology(ctx, root); err != nil {
return HandleErrorRespectJSON("%v", err)
}
if err := withQuiescedProxiedProvider(ctx, beadsDir, database, root, func(ctx context.Context, conn *sql.Conn) error {
return versioncontrolops.BackupRestore(ctx, conn, backupURL, database, force)
}); err != nil {
return HandleErrorRespectJSON("%s", proxiedRestoreFailureMessage(dir, false, err))
}
if err := withQuiescedProxiedProvider(ctx, beadsDir, database, root, func(ctx context.Context, conn *sql.Conn) error {
return reconcileRestoredProxiedWorkspace(ctx, conn, beadsDir, dir, force)
}); err != nil {
return HandleErrorRespectJSON("%s", proxiedRestoreFailureMessage(dir, true, err))
}
return nil
}
// proxiedRestoreFailureMessage renders what the operator is told when one of
// the two quiesced steps fails.
//
// The distinction it makes is the only one that matters here: DID THE DATA COME
// BACK. A teardown failure happens after the step succeeded, so saying "restore
// failed" would be false, and the obvious response to it — run the restore
// again — is the wrong one. Split out from the call sites so that judgement is
// something a test can hold still (TestProxiedRestoreFailureMessage).
//
// afterReconcile distinguishes the two steps, because a teardown failure costs
// the operator different follow-up work either side of the reconcile: before
// it, the backup destination has not been re-registered yet.
func proxiedRestoreFailureMessage(dir string, afterReconcile bool, err error) string {
var teardown *proxiedTeardownError
if errors.As(err, &teardown) {
if afterReconcile {
return fmt.Sprintf("restored from %s, but shutting the proxied server down afterwards failed: %v; "+
"the data is restored and reconciled — run 'bd dolt stop --force' before the next command", dir, teardown)
}
return fmt.Sprintf("restored from %s, but shutting the proxied server down afterwards failed: %v; "+
"the data is restored — run 'bd dolt stop --force', then 'bd backup init %s' to re-register the "+
"backup destination, which this run did not reach", dir, teardown, dir)
}
if afterReconcile {
return fmt.Sprintf("restored from %s, but the restored database did not reopen: %v", dir, err)
}
return fmt.Sprintf("restore failed: %v", err)
}
// quiesceProxiedTopology drops this process's provider and stops the proxy and
// its dolt child, so nothing holds the database that is about to be replaced.
func quiesceProxiedTopology(ctx context.Context, root string) error {
if uowProvider != nil {
if err := uowProvider.Close(ctx); err != nil {
return fmt.Errorf("close the proxied provider before restoring: %w", err)
}
uowProvider = nil
}
if err := proxy.Shutdown(root); err != nil {
return fmt.Errorf("stop the proxied server before restoring: %w; "+
"run 'bd dolt stop --force' and retry", err)
}
return nil
}
// proxiedTeardownError marks a failure that happened AFTER the operation
// succeeded, while putting the topology back down. It exists so the caller can
// tell the two apart in what it prints. Flattening them is what made a restore
// that completed and then failed to shut the proxy down report "restore
// failed": the operator is told their data did not come back when it did, and
// the obvious response — run the restore again — is the wrong one.
type proxiedTeardownError struct{ err error }
func (e *proxiedTeardownError) Error() string { return e.err.Error() }
func (e *proxiedTeardownError) Unwrap() error { return e.err }
// withQuiescedProxiedProvider relaunches the topology for one operation and
// puts it back down afterwards, so each step either side of the replace runs on
// a connection that was opened after it.
//
// The provider ADOPTS whatever identity the database carries: a restore is
// precisely the operation after which the workspace's recorded project id and
// the database's may legitimately differ, and asserting the old one would
// refuse the connection that is supposed to reconcile them. That makes this the
// third caller of newProxiedServerUOWProviderAdopting; its doc comment is the
// register of identity-assertion bypasses and names this one.
//
// A teardown failure is returned wrapped in *proxiedTeardownError, and only
// when the operation itself succeeded. If opening or running the operation
// failed, preserve that error and append any cleanup failure without the
// success marker. Shutdown is attempted even if construction fails after
// starting the topology but before returning a provider.
func withQuiescedProxiedProvider(ctx context.Context, beadsDir, database, root string, fn func(context.Context, *sql.Conn) error) (err error) {
var provider uow.UnitOfWorkProvider
defer func() {
var closeErr error
if provider != nil {
closeErr = provider.Close(ctx)
}
stopErr := proxy.Shutdown(root)
if teardownErr := errors.Join(closeErr, stopErr); teardownErr != nil {
if err != nil {
err = errors.Join(err, fmt.Errorf("shut down the proxied server after failure: %w", teardownErr))
} else {
err = &proxiedTeardownError{err: teardownErr}
}
}
}()
provider, err = newProxiedServerUOWProviderAdopting(ctx, beadsDir, database)
if err != nil {
return err
}
maintenance, ok := provider.(uow.MaintenanceProvider)
if !ok {
return fmt.Errorf("the proxied provider does not support maintenance operations")
}
return maintenance.RunNonTx(ctx, fn)
}
// reconcileRestoredProxiedWorkspace is the post-restore bookkeeping, mirroring
// the direct path: adopt the restored database's project identity when the
// restore overwrote one, and register the restore source as the backup
// destination so `bd backup sync` works without a separate init.
//
// Both are best-effort with a warning, as in direct mode. The restore itself
// has already succeeded by this point, and failing the command over bookkeeping
// would tell the operator their data did not come back when it did.
func reconcileRestoredProxiedWorkspace(ctx context.Context, conn *sql.Conn, beadsDir, dir string, force bool) error {
if force {
if err := syncProjectIDFromProxiedDB(ctx, conn, beadsDir); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to sync project ID after restore: %v\n", err)
}
}
backupURL := resolveDoltBackupURL(dir)
_ = versioncontrolops.BackupRemove(ctx, conn, proxiedBackupTargetName)
if err := versioncontrolops.BackupAdd(ctx, conn, proxiedBackupTargetName, backupURL); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to register backup remote: %v\n", err)
return nil
}
if err := saveDoltBackupConfig(backupURL); err != nil {
fmt.Fprintf(os.Stderr, "Warning: backup registered but failed to save config: %v\n", err)
}
return nil
}
// syncProjectIDFromProxiedDB copies the restored database's _project_id into
// metadata.json, so the identity check does not reject later connections. The
// direct path reads it through the store; there is no store in proxied mode, so
// it goes through the same issueops accessor the store itself uses rather than
// a second copy of the query.
func syncProjectIDFromProxiedDB(ctx context.Context, conn *sql.Conn, beadsDir string) error {
dbID, err := issueops.GetMetadataInTx(ctx, conn, "_project_id")
if err != nil || dbID == "" {
return err
}
cfg, err := configfile.Load(beadsDir)
if err != nil {
return err
}
if cfg == nil || cfg.ProjectID == dbID {
return nil
}
cfg.ProjectID = dbID
return cfg.Save(beadsDir)
}

View file

@ -30,11 +30,10 @@ Use --force to overwrite an existing database with the backup contents.
The database must already be initialized (run 'bd init' first if needed).
To initialize and restore in one step, use: bd init && bd backup restore`,
Args: cobra.MaximumNArgs(1),
Args: cobra.MaximumNArgs(1),
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("backup restore is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("backup-restore")
defer func() {
if c := metrics.Global(); c != nil {
@ -61,14 +60,24 @@ To initialize and restore in one step, use: bd init && bd backup restore`,
force, _ := cmd.Flags().GetBool("force")
if err := runBackupRestore(ctx, store, dir, force); err != nil {
if usesProxiedServer() {
if err := runBackupRestoreProxied(ctx, dir, force); err != nil {
return err
}
} else if err := runBackupRestore(ctx, store, dir, force); err != nil {
return err
}
if !jsonOutput {
fmt.Printf("%s Restore complete\n", ui.RenderPass("✓"))
// One success report for both topologies. Under --json this used to
// print nothing at all, which left a caller unable to tell a completed
// restore from a silently skipped one.
if jsonOutput {
return outputJSON(map[string]interface{}{
"restored": true,
"source": dir,
})
}
fmt.Printf("%s Restore complete\n", ui.RenderPass("✓"))
return nil
},
}

View file

@ -10,6 +10,7 @@ import (
"testing"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/configfile"
)
func TestBackupStatusSizeErrorRespectsOutputMode(t *testing.T) {
@ -159,25 +160,62 @@ func TestBackupStatusIncludesAvailableDatabaseSize(t *testing.T) {
})
}
func TestBackupStatusProxiedGuardDoesNotMeasureSize(t *testing.T) {
prepareBackupStatusTest(t)
proxiedServerMode = true
called := false
sizeDatabase := func(context.Context) (int64, bool, error) {
called = true
return 1, true, nil
}
// TestBackupStatusProxiedGuardFollowsLocality replaces a test that asserted a
// blanket proxied refusal. Since slice S3 the guard is scoped to locality: bd
// owns the dolt process on a managed-local workspace and can honor the command
// there, while an external one is still refused — and a refused command must
// not go on to measure anything, because the directory it would measure belongs
// to a server on another host.
func TestBackupStatusProxiedGuardFollowsLocality(t *testing.T) {
for _, tc := range []struct {
name string
sidecar string
wantMeasure bool
}{
{
name: "external topology is refused without measuring",
sidecar: `{"external":{"host":"db.example.com","port":3306}}`,
wantMeasure: false,
},
{
name: "managed local is honored and measures",
sidecar: `{}`,
wantMeasure: true,
},
} {
t.Run(tc.name, func(t *testing.T) {
beadsDir := prepareBackupStatusTest(t)
proxiedServerMode = true
if err := os.WriteFile(configfile.ProxiedServerClientInfoPath(beadsDir), []byte(tc.sidecar), 0o600); err != nil {
t.Fatalf("write proxied sidecar: %v", err)
}
cmd := newBackupStatusTestRoot(sizeDatabase)
cmd.SetArgs([]string{"backup", "status"})
_, _, err := executeBackupStatusCommand(t, cmd)
assertExitCode(t, err, 1)
if called {
t.Fatal("proxied-server guard called database size provider")
measured := false
sizeDatabase := func(context.Context) (int64, bool, error) {
measured = true
return 1, true, nil
}
cmd := newBackupStatusTestRoot(sizeDatabase)
cmd.SetArgs([]string{"backup", "status"})
_, _, err := executeBackupStatusCommand(t, cmd)
if tc.wantMeasure {
if err != nil {
t.Fatalf("backup status on managed-local: %v", err)
}
} else {
assertExitCode(t, err, 1)
}
if measured != tc.wantMeasure {
t.Fatalf("size provider called = %v, want %v", measured, tc.wantMeasure)
}
})
}
}
func prepareBackupStatusTest(t *testing.T) {
// prepareBackupStatusTest builds a throwaway workspace and returns its .beads
// directory, so a caller can drop workspace files (the proxied sidecar) into it.
func prepareBackupStatusTest(t *testing.T) string {
t.Helper()
beadsDir := filepath.Join(t.TempDir(), ".beads")
@ -198,6 +236,7 @@ func prepareBackupStatusTest(t *testing.T) {
proxiedServerMode = oldProxiedServerMode
resetCommandContext()
})
return beadsDir
}
func newBackupStatusTestRoot(sizeDatabase backupSizeFunc) *cobra.Command {

View file

@ -0,0 +1,671 @@
package main
import (
"sort"
"strings"
"github.com/spf13/cobra"
"github.com/spf13/pflag"
)
// The proxied-server capability registry: one table for every command path.
//
// Before this file the policy lived in three separate tables — a maintenance
// refusal map, a history classification map, and a transform row list — each
// with its own lookup and its own front-door validator. Nothing forced a new
// command to appear in any of them, so an unclassified command sailed past the
// gate and died deep in the store factory with an untyped error. The fix is not
// a fourth table: it is one table plus a test that fails when a command is
// missing from it (TestProxyCapabilityRegistryCoversCommandTree).
//
// WHAT A ROW MEANS. Outcome describes what the PRE-PROVIDER GATE does with the
// path on a proxied-server workspace, nothing more:
//
// ProxyOutcomeRefused the gate refuses with a typed ProxyCapabilityError
// before any workspace side effect
// ProxyOutcomeRefusedInRunE the gate lets the path through and the command
// refuses inside its own RunE with an untyped
// string; recorded here so the untyped surface is
// inventoried rather than invisible. Not enforced.
// ProxyOutcomeHonored the gate lets the path through. It does NOT
// promise a proxied route exists: a permitted
// command with no route still fails at the store
// factory with proxy.store.unrouted.
//
// Permitting a path also COSTS something, and the cost is invisible from this
// table: unless the command is on one of main.go's store-init skip lists, the
// root pre-run opens the proxied provider before RunE runs — which starts the
// proxy and its dolt child, creates the database and migrates the schema. For a
// command that genuinely uses the store that is the point. For a store-free one
// it is pure side effect, and on a workspace whose topology cannot be resolved
// it turns a clean typed refusal into a provider-open error. So "this command
// touches no store" is an argument for permitting it only once the command is
// also off the store-init path; see the `migrate hooks` row. Nothing here
// asserts that, and TestProxyCapabilityRegistryCoversCommandTree cannot see it.
//
// REASON is the load-bearing field. "design" means refusing is correct and is
// expected to stay that way — the semantics are undefined or unsafe against a
// backend that may be shared. "unimplemented" means the refusal is a capability
// gap with a named slice that closes it, and Tracking says which. Every later
// slice measures itself by turning "unimplemented" rows into honored ones; the
// count of remaining "unimplemented" rows is the completion signal for the whole
// proxied-parity effort. Assign the field row by row, from the command's actual
// semantics — a bulk assignment would destroy the only information it carries.
//
// The reason also renders in the refusal JSON, additive to the frozen
// {code, error, mutates} contract (see buildJSONCapabilityError). Codes are
// frozen; messages are informative-only.
// ProxyRefusalReason distinguishes a deliberate policy refusal from a
// not-yet-built one.
type ProxyRefusalReason string
const (
// ProxyReasonDesign: the command is refused on purpose and is expected to
// stay refused. Lifting it would need a semantic decision, not plumbing.
ProxyReasonDesign ProxyRefusalReason = "design"
// ProxyReasonUnimplemented: the command could work over the proxied
// provider; nobody has routed it yet. Tracking names the work item.
ProxyReasonUnimplemented ProxyRefusalReason = "unimplemented"
)
// Tracking values name the plan-of-record work item for an unimplemented
// refusal. These are the slices of the proxied-parity plan; a row gets a GitHub
// issue or bead ID instead once one is filed for it.
// S3 has no entry: it landed, and its rows carry Reason=design rather than a
// tracking item.
const (
trackVersionCtl = "proxied-parity S4 (dolt commit/push/pull/remote)"
trackSync = "proxied-parity S5 (bd sync)"
trackDegradation = "proxied-parity S6 (doctor, config show, degradations)"
trackLongTail = "proxied-parity S7 (long-tail policy pass)"
)
// capabilityRow is one command-path policy row. ArgSet is the sorted set of
// execution-altering flags that were set (for example "--auto-merge --dry-run"),
// empty for the bare path; a row keyed on an ArgSet wins over the bare row, which
// is how `duplicates --auto-merge --dry-run` stays honored while
// `duplicates --auto-merge` is refused.
//
// Topology overrides Rule on the proxied shapes named in it and is empty for
// every row whose answer is the same everywhere — which is all of them but the
// backup family. See honoredOn.
type capabilityRow struct {
Path string
ArgSet string
Rule proxyCapabilityRule
Topology map[ProxyTopology]proxyCapabilityRule
History HistoryCapabilityClass
Note string
}
// ruleFor resolves the row's policy on one proxied topology.
func (r capabilityRow) ruleFor(topology ProxyTopology) proxyCapabilityRule {
if rule, ok := r.Topology[topology]; ok {
return rule
}
return r.Rule
}
// honoredOn narrows a refusal to the shapes where it is actually true: the row
// goes on refusing everywhere except the topologies named here.
//
// The direction is deliberate. A row states its refusal first and then lists
// the exceptions, so a shape nobody thought about — a new transport, or the
// unknown a corrupt sidecar produces — inherits the refusal rather than the
// exemption.
func (r capabilityRow) honoredOn(topologies ...ProxyTopology) capabilityRow {
r.Topology = make(map[ProxyTopology]proxyCapabilityRule, len(topologies))
for _, topology := range topologies {
r.Topology[topology] = proxyCapabilityRule{Outcome: ProxyOutcomeHonored}
}
return r
}
// display renders the row's key the way its refusal message names it.
func (r capabilityRow) display() string {
if r.ArgSet == "" {
return r.Path
}
return r.Path + " " + r.ArgSet
}
func (r capabilityRow) withHistory(class HistoryCapabilityClass) capabilityRow {
r.History = class
return r
}
// asParentGroup marks a row whose path is a command GROUP. Cobra answers a
// non-runnable parent with its help text before PersistentPreRunE, so the gate
// never sees it; the row is kept because it is the parent every child row
// inherits its code from, and because a parent that later gains a Run must not
// silently become permitted.
func (r capabilityRow) asParentGroup() capabilityRow {
r.Note = "parent group: cobra shows help instead of reaching the gate"
return r
}
func (r capabilityRow) withMessage(message string) capabilityRow {
r.Rule.Message = message
return r
}
// refusedPath builds a typed front-door refusal for a bare command path.
func refusedPath(path, code string, reason ProxyRefusalReason, tracking string) capabilityRow {
return refusedArgs(path, "", code, reason, tracking)
}
// refusedArgs builds a typed front-door refusal keyed on a flag set.
func refusedArgs(path, argSet, code string, reason ProxyRefusalReason, tracking string) capabilityRow {
row := capabilityRow{Path: path, ArgSet: argSet}
row.Rule = proxyCapabilityRule{
Outcome: ProxyOutcomeRefused,
Code: code,
Message: row.display() + " is not supported in proxied-server mode",
ExitCode: 1,
Reason: reason,
Tracking: tracking,
}
return row
}
// refusedInRunE records a command that the gate permits and that then refuses
// itself with an untyped string from RunE. The row carries no message: the
// string lives in the command, and duplicating it here would rot. The scan in
// TestProxyCapabilityRegistryCoversInlineRefusals keeps the two in step.
//
// The reason is always "unimplemented" and the owner is always the long-tail
// slice, because an untyped string inside RunE is not a considered policy
// statement: a refusal decided on purpose belongs in the gate, typed, where a
// consumer can read it. Anything here is a family nobody has routed yet.
func refusedInRunE(path, site string) capabilityRow {
return capabilityRow{
Path: path,
Rule: proxyCapabilityRule{
Outcome: ProxyOutcomeRefusedInRunE, ExitCode: 1,
Reason: ProxyReasonUnimplemented, Tracking: trackLongTail,
},
Note: "untyped refusal in " + site,
}
}
// permitted records that the gate lets a path through. See the header: this is
// a statement about the gate, not a promise that a proxied route exists.
func permitted(path string) capabilityRow {
return capabilityRow{Path: path, Rule: proxyCapabilityRule{Outcome: ProxyOutcomeHonored}}
}
// backupRefusal builds one backup-family row: honored where bd owns the Dolt
// server, refused by design everywhere else. The code stays
// proxy.backup.unsupported — consumers have been keying on it since 1.3.0 and
// the refusal it names has not changed, only its reason and its scope — and the
// message keeps the frozen "<path> is not supported in proxied-server mode"
// prefix, with the reason appended.
//
// The message leads with SERVER-GLOBAL STATE rather than with the filesystem,
// because only the filesystem half is scheme-specific. `bd backup init` accepts
// https/aws/gs as well as file:// (resolveDoltBackupURL) and the help text
// recommends DoltHub; for those a server-side push over the network with the
// server's own credentials is a coherent thing to ask for, and "the destination
// is on the server's disk" says nothing about it. What is true of every scheme
// is that `CALL DOLT_BACKUP('add', …)` registers the remote ON THE SERVER,
// where it is global to every client of that server — one workspace's backup
// decision silently becomes everyone's, which is the shape of the auto-backup
// storm this command's own help text warns about.
//
// backupRemoteSchemeTracking is why these rows carry a Tracking item despite
// being Reason=design: the outcome is settled, the remote-scheme CASE is not.
func backupRefusal(path string) capabilityRow {
return refusedPath(path, "proxy.backup.unsupported", ProxyReasonDesign, backupRemoteSchemeTracking).
withMessage(path + " is not supported in proxied-server mode against a Dolt server bd does not own: " +
"the backup remote is registered on the server, where it is global to every client, " +
"and a file:// destination names a filesystem this client cannot see").
honoredOn(ProxyTopologyManagedLocal)
}
// backupRemoteSchemeTracking records the one part of the backup refusal that is
// a question rather than a verdict, so refusing the family off-host does not
// silently foreclose it. A remote-scheme destination (DoltHub, aws://, gs://)
// needs no filesystem bd can see — the server pushes it over the network from
// its own environment, which is exactly the credential story S4 has to settle
// for `dolt push` on these same topologies. Whether a per-client backup remote
// on a shared server is ever acceptable is the open part; the plumbing is not.
//
// Note also that the DoltHub story is already half-built in DIRECT mode:
// `bd backup init https://…` and `bd backup sync` work, but
// `bd backup restore https://…` does not, because validateBackupRestoreDir
// os.Stats its argument and rejects anything that is not an existing directory
// on every topology. Pre-existing, not something this slice changed.
const backupRemoteSchemeTracking = "open question, not a verdict: remote-scheme (DoltHub/aws/gs) backup on a server " +
"bd does not own — revisit with S4, which settles the same server-env credential question for dolt push"
// proxyCapabilityRegistry is the whole path-keyed policy. Rows for permitted
// paths are appended from proxyPermittedPaths by init.
var proxyCapabilityRegistry = []capabilityRow{
// --- doctor -------------------------------------------------------------
// Diagnosis needs no version-control surface; the checks simply have no
// proxied dual yet. S6 splits them into client-local and store-backed.
refusedPath("doctor", "proxy.doctor.unsupported", ProxyReasonUnimplemented, trackDegradation),
// --- backup / restore ---------------------------------------------------
// CALL DOLT_BACKUP(...) is pure SQL over a connection proxied mode already
// owns, so routing this family needed no proxy work at all — see
// backup_proxied_server.go.
//
// What it did need is the ownership policy, which is the first genuinely
// topology-differentiated rule in this table. A backup remote belongs to the
// SERVER, not to the client that asked for it: `CALL DOLT_BACKUP('add', …)`
// registers it in the server's own configuration, where it is global to
// every client connected to that server. On managed-local "every client" is
// this workspace, because bd spawned the child itself. Anywhere else one
// operator's backup decision silently becomes everyone's — the same shape as
// the auto-backup storm this command's help text already warns about, and
// the reason team-server is the sharpest case: bts owns the store.
//
// A file:// destination adds a second, scheme-specific problem on top: it
// names a path on the machine running dolt, so off-host the command either
// fails at the point of use or, far worse, reports success having written
// the backup somewhere the operator will never look for it.
//
// Hence: honored on managed-local, refused by design everywhere else. The
// OUTCOME is design — server-global state is not something plumbing on this
// side can make per-client, and a backup story for those shapes belongs to
// whoever runs the server. The remote-scheme case (DoltHub, aws://, gs://,
// which resolveDoltBackupURL accepts and backup.go recommends) is the part
// that is a question rather than a verdict, and it is not silently
// foreclosed: see backupRemoteSchemeTracking, which every row below carries.
backupRefusal("backup").asParentGroup(),
backupRefusal("backup init"),
backupRefusal("backup sync"),
backupRefusal("backup remove"),
backupRefusal("backup status"),
backupRefusal("backup restore"),
// --- version control over a shared history ------------------------------
// Refused by design: these mutate or traverse a history that several
// clients share through one connection, and the per-client semantics
// (whose working set? whose branch head?) are undefined. `diff` is the one
// plausible 1.4 candidate, via the dolt_diff system tables.
refusedPath("branch", "proxy.branch.unsupported", ProxyReasonDesign, "").
withHistory(HistoryDirectOnly),
refusedPath("diff", "proxy.diff.unsupported", ProxyReasonDesign, "1.4 candidate: dolt_diff system tables"),
refusedPath("flatten", "proxy.flatten.unsupported", ProxyReasonDesign, "").
withHistory(HistoryDirectOnly),
refusedPath("conflicts", "proxy.conflicts.unsupported", ProxyReasonDesign, "").
withHistory(HistoryDirectOnly).
asParentGroup(),
refusedPath("conflicts list", "proxy.conflicts.unsupported", ProxyReasonDesign, ""),
refusedPath("conflicts show", "proxy.conflicts.unsupported", ProxyReasonDesign, ""),
refusedPath("conflicts resolve", "proxy.conflicts.unsupported", ProxyReasonDesign, ""),
refusedPath("vc", "proxy.vc.unsupported", ProxyReasonDesign, "").
withHistory(HistoryDirectOnly).
asParentGroup(),
refusedPath("vc merge", "proxy.vc.unsupported", ProxyReasonDesign, ""),
refusedPath("vc commit", "proxy.vc.unsupported", ProxyReasonDesign, ""),
refusedPath("vc status", "proxy.vc.unsupported", ProxyReasonDesign, ""),
refusedPath("federation", "proxy.federation.unsupported", ProxyReasonDesign, "").
withHistory(HistoryDirectOnly).
asParentGroup(),
refusedPath("federation sync", "proxy.federation.unsupported", ProxyReasonDesign, ""),
refusedPath("federation status", "proxy.federation.unsupported", ProxyReasonDesign, ""),
refusedPath("federation add-peer", "proxy.federation.unsupported", ProxyReasonDesign, ""),
refusedPath("federation remove-peer", "proxy.federation.unsupported", ProxyReasonDesign, ""),
refusedPath("federation list-peers", "proxy.federation.unsupported", ProxyReasonDesign, ""),
// --- multi-repo routing -------------------------------------------------
// Routing to another workspace bypasses the proxied root entirely, which is
// the same reason --repo is N/A mode-wide.
refusedPath("repo", "proxy.repo.unsupported", ProxyReasonDesign, "").
withHistory(HistoryDirectOnly).
asParentGroup(),
refusedPath("repo add", "proxy.repo.unsupported", ProxyReasonDesign, ""),
refusedPath("repo remove", "proxy.repo.unsupported", ProxyReasonDesign, ""),
refusedPath("repo list", "proxy.repo.unsupported", ProxyReasonDesign, ""),
refusedPath("repo sync", "proxy.repo.unsupported", ProxyReasonDesign, ""),
// --- dolt version-control verbs -----------------------------------------
// CALL DOLT_PUSH/DOLT_PULL/DOLT_COMMIT are SQL procedures and the generic
// repository that wraps them is already written; these need a use case and
// a route, not proxy work. `dolt remote remove` is already routed, which is
// the precedent.
refusedPath("dolt commit", "proxy.dolt_commit.unsupported", ProxyReasonUnimplemented, trackVersionCtl).
withHistory(HistoryDirectOnly),
refusedPath("dolt push", "proxy.dolt_push.unsupported", ProxyReasonUnimplemented, trackVersionCtl).
withHistory(HistoryDirectOnly),
refusedPath("dolt pull", "proxy.dolt_pull.unsupported", ProxyReasonUnimplemented, trackVersionCtl).
withHistory(HistoryDirectOnly),
refusedPath("dolt remote", "proxy.dolt_remote.unsupported", ProxyReasonUnimplemented, trackVersionCtl).
withHistory(HistoryDirectOnly).
asParentGroup(),
refusedPath("dolt remote add", "proxy.dolt_remote.unsupported", ProxyReasonUnimplemented, trackVersionCtl).
withHistory(HistoryDirectOnly),
refusedPath("dolt remote list", "proxy.dolt_remote.unsupported", ProxyReasonUnimplemented, trackVersionCtl).
withHistory(HistoryDirectOnly),
refusedPath("dolt remote reset-data", "proxy.dolt_remote.unsupported", ProxyReasonUnimplemented, trackVersionCtl).
withHistory(HistoryDirectOnly),
refusedPath("sync", "proxy.sync.unsupported", ProxyReasonUnimplemented, trackSync).
withHistory(HistoryDirectOnly),
// --- migration and workspace surgery ------------------------------------
// Storage-format and workspace surgery against a store other clients may be
// holding open. `migrate schema` is the exception and is already routed:
// the provider open runs it under the migration gate.
//
// S7 MUST RE-EXAMINE THE ROWS BELOW PER TOPOLOGY. "A store other clients may
// be holding open" describes external and team-server workspaces; it does
// not describe managed-local, which is 1:1 and bd-owned — bd spawned the
// dolt child itself. A row cannot yet say "refused, except on managed-local"
// (S3's backup locality policy is the slice that adds per-topology rules),
// so the blanket refusal is the only thing this table can express today.
// These rows keep it because nobody has done the semantic work to narrow
// them, not because the work has been done and come out this way.
refusedPath("migrate", "proxy.migrate.unsupported", ProxyReasonDesign, ""),
refusedPath("migrate sync", "proxy.migrate.unsupported", ProxyReasonDesign, ""),
// `migrate hooks` is the one row in this block the surgery rationale never
// described: it plans and applies GIT HOOK FILE migration (migrate_hooks.go
// -> doctor.PlanHookMigration) on the local filesystem and opens no store at
// all. It is refused for a structural reason instead — the command is wired
// into the store-opening path it does not need. It is on none of main.go's
// store-init skip lists, so permitting it makes the root pre-run open the
// proxied provider before RunE ever runs. Measured, not assumed: with this
// row flipped to permitted, `bd migrate hooks --dry-run` on a managed-local
// workspace started the proxy AND its dolt child (both pidfiles present) to
// print a hook plan, and on a workspace with an unreadable sidecar it exited
// 1 with "failed to open uow provider: corrupt proxied-server sidecar ..."
// where it had cleanly refused before. Trading a typed refusal for a
// connection error is not a lift. The honest fix is to take the command off
// the store path first, which is S7's job, not this slice's.
refusedPath("migrate hooks", "proxy.migrate.unsupported", ProxyReasonUnimplemented,
trackLongTail+" (specifically: put `migrate hooks` on main.go's store-init skip list, then permit it)"),
refusedPath("migrate issues", "proxy.migrate.unsupported", ProxyReasonDesign, ""),
refusedPath("migrate-issues", "proxy.migrate.unsupported", ProxyReasonDesign, ""),
refusedPath("migrate-personal", "proxy.migrate.unsupported", ProxyReasonDesign, ""),
// --- destructive admin --------------------------------------------------
// Same topology-blind rationale as the migrate block above, and the same
// instruction to S7: "destructive against a possibly-shared store" is a
// claim about external and team-server shapes. On managed-local the store is
// this workspace's alone, and `bd admin reset` there is no more shared than
// it is in embedded mode, where it is honored. Re-examine per topology.
refusedPath("admin cleanup", "proxy.admin.unsupported", ProxyReasonDesign, ""),
refusedPath("admin reset", "proxy.admin.unsupported", ProxyReasonDesign, ""),
// --- issue compaction ---------------------------------------------------
// `bd admin compact` without --dolt is the description-rewriting pass; only
// the --dolt arm has a proxied route (runCompactDoltProxiedServer). The
// --dolt arm is decided by flag VALUE, so the gate keeps a value-aware
// branch for it and lands here when the flag is off.
refusedPath("admin compact", "proxy.compact.unsupported", ProxyReasonUnimplemented, trackLongTail).
withMessage("only 'compact --dolt' is supported in proxied-server mode"),
// `bd restore` recovers a COMPACTED ISSUE's original text, not a backup —
// the backup verb is `bd backup restore`. Its snapshot read is ordinary
// CRUD; only its fallback path (reconstructing from Dolt history when no
// snapshot was archived) touches version control.
refusedPath("restore", "proxy.restore.unsupported", ProxyReasonUnimplemented, trackLongTail),
// --- gates, formulas, swarm, merge slots --------------------------------
// Ordinary CRUD over a store with no version-control surface. They stay
// refused because nothing downstream has asked for them, which is this
// codebase's standing rule for lifting a refusal — not because the proxied
// topology makes them wrong.
refusedPath("gate discover", "proxy.gate.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("cook", "proxy.formula.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("ship", "proxy.formula.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("swarm create", "proxy.swarm.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("swarm list", "proxy.swarm.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("merge-slot create", "proxy.merge_slot.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("merge-slot check", "proxy.merge_slot.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("merge-slot acquire", "proxy.merge_slot.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("merge-slot release", "proxy.merge_slot.unsupported", ProxyReasonUnimplemented, trackLongTail),
// --- transforms ---------------------------------------------------------
// ID rewrites walk every reference in the store. They need a routed
// multi-statement transaction, which the UOW can express; nobody has
// written it. The arg-set rows are what let the read-only preview of a
// duplicate merge stay honored while the merge itself is refused.
refusedPath("rename", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("rename-prefix", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedArgs("rename-prefix", "--dry-run", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedArgs("rename-prefix", "--repair", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedArgs("rename-prefix", "--dry-run --repair", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("duplicate", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedArgs("duplicate", "--of", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedPath("supersede", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedArgs("supersede", "--with", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
refusedArgs("duplicates", "--auto-merge", "proxy.transform.unsupported", ProxyReasonUnimplemented, trackLongTail),
// The dry run reports what the merge WOULD do without writing anything, so
// it rides the read path plain `duplicates` already uses.
{Path: "duplicates", ArgSet: "--auto-merge --dry-run", Rule: proxyCapabilityRule{Outcome: ProxyOutcomeHonored}},
// --- routed history -----------------------------------------------------
// The two paths that already have a proxied route, recorded so the class is
// asserted rather than remembered.
permitted("history").withHistory(HistoryProxySupported),
permitted("dolt remote remove").withHistory(HistoryProxySupported),
// --- untyped refusals inside RunE ---------------------------------------
// The gate permits these paths and the command refuses itself with a bare
// string, so a JSON consumer gets no code and no mutates flag. They are
// listed to inventory that surface, not to enforce it: converting them to
// typed refusals changes observable output and belongs to the slice that
// owns each family. Tracker verbs are ordinary store reads plus a network
// call; nothing about the proxied topology makes them wrong.
refusedInRunE("ado status", "ado.go"),
refusedInRunE("ado projects", "ado.go"),
refusedInRunE("ado sync", "ado.go"),
refusedInRunE("github status", "github.go"),
refusedInRunE("github repos", "github.go"),
refusedInRunE("github sync", "github.go"),
refusedInRunE("gitlab status", "gitlab.go"),
refusedInRunE("gitlab projects", "gitlab.go"),
refusedInRunE("gitlab sync", "gitlab.go"),
refusedInRunE("notion status", "notion.go"),
refusedInRunE("notion init", "notion.go"),
refusedInRunE("notion connect", "notion.go"),
refusedInRunE("notion sync", "notion.go"),
refusedInRunE("create-form", "create_form.go"),
}
// proxyPermittedPaths lists every command path the proxied front door lets
// through. It exists so that a command added without a policy decision fails
// TestProxyCapabilityRegistryCoversCommandTree instead of shipping — the whole
// point of the registry. Being listed here says the GATE permits the path; a
// permitted command with no proxied route still fails at the store factory with
// proxy.store.unrouted.
var proxyPermittedPaths = []string{
// issue CRUD and queries
"assign", "batch", "blocked", "children", "close", "comment", "count", "create",
"defer", "delete", "duplicates", "edit", "export", "find-duplicates", "forget",
"gc", "graph", "graph check", "heartbeat", "import", "info", "lint", "link",
"list", "note", "orphans", "priority", "promote", "prune", "purge", "q", "query",
"ready", "recompute-blocked", "reclaim", "reopen", "search", "set-state", "show",
"stale", "status", "statuses", "tag", "types", "unclaim", "undefer", "update",
// comments, dependencies, labels, key-value
"comments", "comments add", "comments list",
"dep", "dep add", "dep cycles", "dep list", "dep relate", "dep remove", "dep tree", "dep unrelate",
"kv clear", "kv get", "kv list", "kv set",
"label add", "label list", "label list-all", "label propagate", "label remove",
// molecules, epics, todos, state
"epic close-eligible", "epic status",
"mol bond", "mol burn", "mol current", "mol distill", "mol last-activity", "mol pour",
"mol progress", "mol ready", "mol seed", "mol show", "mol squash", "mol stale",
"mol wisp", "mol wisp create", "mol wisp gc", "mol wisp list",
"state", "state list", "todo", "todo add", "todo done", "todo list",
// gates, rules, provenance, audit, upgrade review
"audit label", "audit record",
"gate add-waiter", "gate check", "gate create", "gate list", "gate resolve", "gate show",
"provenance by-ref", "provenance log", "provenance record",
"rules audit", "rules compact",
"upgrade ack", "upgrade review", "upgrade status",
// workspace lifecycle and configuration
"bootstrap", "config apply", "config drift", "config get", "config list", "config set",
"config set-many", "config show", "config unset", "config validate", "context",
"init", "init-safety", "onboard", "preflight", "quickstart", "schema", "setup", "where",
"version", "worktree create", "worktree info", "worktree list", "worktree remove",
// storage, history and migration paths that are already routed or store-free
"compact", "events export", "events prune", "events tail",
"dolt clean-databases", "dolt killall", "dolt set", "dolt show", "dolt status",
"dolt start", "dolt stop", "dolt test",
"migrate from-proxied-server-to-server", "migrate from-proxied-server-to-shared-server",
"migrate from-server-to-proxied-server", "migrate from-shared-server-to-proxied-server",
"migrate legacy-sqlite", "migrate schema",
// formulas (parser-only), agent memory, swarm reads
"formula convert", "formula list", "formula schema", "formula show",
"mail", "memories", "ping", "prime", "recall", "remember",
"swarm status", "swarm validate",
// human-in-the-loop queue
"human", "human dismiss", "human list", "human respond", "human stats",
// trackers: the verbs with no proxied refusal of any kind
"ado pull", "ado push", "github pull", "github push", "gitlab pull", "gitlab push",
"jira pull", "jira push", "jira status", "jira sync",
"linear pull", "linear push", "linear status", "linear sync", "linear teams",
"notion pull", "notion push",
// hooks, metrics, serving and internal entry points
"hooks install", "hooks list", "hooks run", "hooks uninstall",
"metrics", "metrics example", "metrics off", "metrics on",
"serve", "sql",
"codex-hook", "cursor-hook", "db-proxy-child", "send-metrics",
}
func init() {
for _, path := range proxyPermittedPaths {
proxyCapabilityRegistry = append(proxyCapabilityRegistry, permitted(path))
}
proxyCapabilityIndex = make(map[string]capabilityRow, len(proxyCapabilityRegistry))
for _, row := range proxyCapabilityRegistry {
proxyCapabilityIndex[capabilityKey(row.Path, row.ArgSet)] = row
}
}
// proxyCapabilityIndex is proxyCapabilityRegistry keyed for lookup. Duplicate
// keys are rejected by TestProxyCapabilityRegistryHasNoDuplicateRows rather
// than by a panic here: a typo must fail the build, not every bd invocation.
var proxyCapabilityIndex map[string]capabilityRow
func capabilityKey(path, argSet string) string { return path + "\x00" + argSet }
// LookupCapabilityRow returns the row for an exact path/arg-set key.
func LookupCapabilityRow(path, argSet string) (capabilityRow, bool) {
row, ok := proxyCapabilityIndex[capabilityKey(path, argSet)]
return row, ok
}
// capabilityRowFor resolves a command to its row, preferring the row keyed on
// the flags the invocation actually set over the bare path.
//
// The fallback to the bare row is what lets one table serve both halves of the
// old policy: a path row refuses whatever flags were passed unless a more
// specific row says otherwise, so `backup sync --dry-run` is still refused by
// the `backup sync` row. The predecessor of the arg-set half matched exactly or
// not at all, which meant an unlisted flag combination on a refused path
// slipped through; no such combination exists among the commands that carry
// these flags, so nothing changes today, and the fallback is why none can
// appear later.
func capabilityRowFor(cmd *cobra.Command) (capabilityRow, bool) {
path := commandRegistryPath(cmd)
if argSet := commandPolicyArgSet(cmd); argSet != "" {
if row, ok := LookupCapabilityRow(path, argSet); ok {
return row, true
}
}
return LookupCapabilityRow(path, "")
}
// commandRegistryPath is the registry key for a command: its full path with the
// root name removed, for example "dolt remote add".
func commandRegistryPath(cmd *cobra.Command) string {
return strings.TrimSpace(strings.TrimPrefix(cmd.CommandPath(), cmd.Root().Name()))
}
// proxyPolicyArgFlags are the flags that take part in a capability key. Only
// flags that alter a command's execution belong here: output, tracing and other
// inherited root flags must never bypass a refusal by changing the key.
var proxyPolicyArgFlags = map[string]bool{
"auto-merge": true, "dry-run": true, "repair": true, "of": true, "with": true,
}
// commandPolicyArgSet renders the set flags that take part in the key, sorted so
// the key does not depend on the order the user typed them.
func commandPolicyArgSet(cmd *cobra.Command) string {
var args []string
cmd.Flags().Visit(func(f *pflag.Flag) {
if proxyPolicyArgFlags[f.Name] {
args = append(args, "--"+f.Name)
}
})
sort.Strings(args)
return strings.Join(args, " ")
}
// validateProxyRegistryBeforeProvider is the path-keyed half of the proxied
// front door: it rejects direct-only commands before migrations, auto-start or
// provider construction, so a refusal leaves the workspace untouched. The
// flag-keyed half is validateProxyCapabilitiesBeforeProvider.
//
// topology is the workspace's proxied shape (resolveProxiedTopology). It is a
// parameter rather than a lookup inside so the gate can be exercised for every
// shape without a workspace on disk.
func validateProxyRegistryBeforeProvider(cmd *cobra.Command, topology ProxyTopology) error {
if cmd == nil {
return nil
}
// `compact` is the one rule that a flag VALUE decides rather than a flag's
// presence, so it cannot be expressed as an arg-set row. `bd compact` and
// `bd rules compact` have no --dolt flag at all and are never refused here;
// `bd admin compact --dolt` has a proxied route and falls through to it.
if cmd.Name() == "compact" {
if cmd.Flags().Lookup("dolt") == nil {
return nil
}
if dolt, _ := cmd.Flags().GetBool("dolt"); dolt {
return nil
}
}
row, ok := capabilityRowFor(cmd)
if !ok {
return nil
}
rule := row.ruleFor(topology)
if rule.Outcome != ProxyOutcomeRefused {
return nil
}
return HandleProxyCapabilityError(proxyCapabilityErrorFor(rule))
}
func proxyCapabilityErrorFor(rule proxyCapabilityRule) *ProxyCapabilityError {
return &ProxyCapabilityError{
Code: rule.Code,
Message: rule.Message,
ExitCode: rule.ExitCode,
Mutates: rule.Mutates,
Reason: rule.Reason,
}
}
// HistoryCapabilityClass classifies history/version-control commands on the
// proxied topology without coupling them to a particular backend engine.
type HistoryCapabilityClass string
const (
HistoryProxySupported HistoryCapabilityClass = "proxy-supported"
HistoryDirectOnly HistoryCapabilityClass = "direct-only"
)
// LookupHistoryCapability classifies an exact command path. Paths with no
// history classification are intentionally absent so callers cannot
// accidentally advertise support.
func LookupHistoryCapability(commandPath string) (HistoryCapabilityClass, bool) {
row, ok := LookupCapabilityRow(commandPath, "")
if !ok || row.History == "" {
return "", false
}
return row.History, true
}

View file

@ -31,7 +31,7 @@ func TestSyncRefusesBeforeProvider(t *testing.T) {
root := &cobra.Command{Use: "bd"}
cmd := &cobra.Command{Use: "sync"}
root.AddCommand(cmd)
err := validateProxyMaintenanceBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if err == nil {
t.Fatalf("sync refusal = %#v", err)
}
@ -71,7 +71,7 @@ func TestHistoryDirectOnlyRefusalContract(t *testing.T) {
}
uowProvider = nil
jsonOutput = true
out := captureStdout(t, func() error { _ = validateProxyMaintenanceBeforeProvider(cmd); return nil })
out := captureStdout(t, func() error { _ = validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); return nil })
var got map[string]any
want := expected[path]
if err := json.Unmarshal([]byte(out), &got); err != nil || got["code"] != want.code || got["error"] != want.message || got["mutates"] != false {
@ -104,7 +104,7 @@ func TestHistoryNestedFrontDoorsRefuseAndSupportedPathsPass(t *testing.T) {
cmd.AddCommand(child)
cmd = child
}
err := validateProxyMaintenanceBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if path == "dolt remote remove" {
if err != nil {
t.Fatalf("supported %s refused: %v", path, err)
@ -118,9 +118,9 @@ func TestHistoryNestedFrontDoorsRefuseAndSupportedPathsPass(t *testing.T) {
t.Fatalf("%s exit=%v, want 1", path, err)
}
var got map[string]any
// validateProxyMaintenanceBeforeProvider renders the typed refusal to
// validateProxyRegistryBeforeProvider renders the typed refusal to
// stdout in JSON mode; the command must retain its nested path.
out := captureStdout(t, func() error { _ = validateProxyMaintenanceBeforeProvider(cmd); return nil })
out := captureStdout(t, func() error { _ = validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); return nil })
if err := json.Unmarshal([]byte(out), &got); err != nil {
t.Fatalf("%s refusal JSON: %v (%q)", path, err, out)
}
@ -132,7 +132,7 @@ func TestHistoryNestedFrontDoorsRefuseAndSupportedPathsPass(t *testing.T) {
root := &cobra.Command{Use: "bd"}
history := &cobra.Command{Use: "history"}
root.AddCommand(history)
if err := validateProxyMaintenanceBeforeProvider(history); err != nil {
if err := validateProxyRegistryBeforeProvider(history, ProxyTopologyManagedLocal); err != nil {
t.Fatalf("history --events supported path refused: %v", err)
}
}

View file

@ -0,0 +1,423 @@
package main
import (
"errors"
"os"
"path/filepath"
"regexp"
"sort"
"strings"
"testing"
"github.com/spf13/cobra"
)
// cobraBuiltinCommands are added to the tree by cobra itself, not by bd, and
// only once something calls Execute — which another test in this package does
// (completions_test.go runs __complete). Without this set the completeness test
// below would pass or fail depending on test ORDER, which is the worst possible
// property for a policy gate.
var cobraBuiltinCommands = map[string]bool{
"help": true, "completion": true, "__complete": true, "__completeNoDesc": true,
}
// walkCommandPaths returns every command path in the tree, with the runnable
// ones flagged. Runnable is the property that matters: cobra returns ErrHelp
// for a non-runnable parent before PersistentPreRunE, so a group command never
// reaches the capability gate at all.
func walkCommandPaths(root *cobra.Command) map[string]bool {
paths := map[string]bool{}
var walk func(c *cobra.Command)
walk = func(c *cobra.Command) {
if cobraBuiltinCommands[c.Name()] {
return
}
if path := commandRegistryPath(c); path != "" {
paths[path] = c.Runnable()
}
for _, sub := range c.Commands() {
walk(sub)
}
}
walk(root)
return paths
}
// TestProxyCapabilityRegistryCoversCommandTree is the reason this registry
// exists. Every command that can actually run must state what the proxied front
// door does with it. A new command with no row fails here, at build time, rather
// than shipping and dying in the store factory with an untyped error — which is
// how every scattered refusal in this codebase got there.
//
// Adding a row is not a formality: choose the outcome deliberately.
// - the command works over the proxied provider, or never opens a store at
// all => add its path to proxyPermittedPaths
// - the command must not run on a shared/proxied store => add a refusedPath
// row with Reason=design and say why in a comment
// - the command could work but nobody has routed it => add a refusedPath row
// with Reason=unimplemented and a Tracking item
func TestProxyCapabilityRegistryCoversCommandTree(t *testing.T) {
var missing []string
for path, runnable := range walkCommandPaths(rootCmd) {
if !runnable {
continue
}
if _, ok := LookupCapabilityRow(path, ""); !ok {
missing = append(missing, path)
}
}
sort.Strings(missing)
if len(missing) > 0 {
t.Fatalf("%d command(s) have no proxied-server capability row:\n %s\n\n"+
"Add each to cmd/bd/capability_registry.go: proxyPermittedPaths if the proxied "+
"front door should let it through, or a refusedPath row with a Reason if it should not.",
len(missing), strings.Join(missing, "\n "))
}
}
// TestProxyCapabilityRegistryHasNoStaleRows is the other direction: a row whose
// command no longer exists is policy for nothing, and would hide the renamed
// command's own missing row behind a green test.
func TestProxyCapabilityRegistryHasNoStaleRows(t *testing.T) {
tree := walkCommandPaths(rootCmd)
var stale []string
for _, row := range proxyCapabilityRegistry {
if _, ok := tree[row.Path]; !ok {
stale = append(stale, row.display())
}
}
sort.Strings(stale)
if len(stale) > 0 {
t.Fatalf("registry rows for commands that do not exist:\n %s", strings.Join(stale, "\n "))
}
}
func TestProxyCapabilityRegistryHasNoDuplicateRows(t *testing.T) {
seen := map[string]bool{}
for _, row := range proxyCapabilityRegistry {
key := capabilityKey(row.Path, row.ArgSet)
if seen[key] {
t.Errorf("duplicate registry row for %q: one of them is dead and the lookup silently picks the last", row.display())
}
seen[key] = true
}
}
// TestProxyCapabilityRegistryRowInvariants pins the contract every row must
// satisfy. The Reason rules are the load-bearing ones: a refusal with no reason
// is exactly the tribal knowledge this registry replaces, and an unimplemented
// refusal with no tracking item is a gap nobody owns.
func TestProxyCapabilityRegistryRowInvariants(t *testing.T) {
for _, row := range proxyCapabilityRegistry {
assertCapabilityRuleInvariants(t, row.display(), row.Rule)
for topology, rule := range row.Topology {
assertCapabilityRuleInvariants(t, row.display()+" on "+string(topology), rule)
if topology == ProxyTopologyUnknown {
t.Errorf("%s: a row must not name the unknown topology; unknown exists so an unclassifiable "+
"workspace INHERITS the refusal, and exempting it would invert that", row.display())
}
}
if row.History == HistoryDirectOnly && row.Rule.Outcome != ProxyOutcomeRefused {
t.Errorf("%s: classified direct-only but the gate does not refuse it", row.display())
}
if row.History == HistoryProxySupported && row.Rule.Outcome != ProxyOutcomeHonored {
t.Errorf("%s: classified proxy-supported but the gate refuses it", row.display())
}
}
}
// assertCapabilityRuleInvariants checks one rule — a row's default or one of
// its per-topology overrides. Both have to satisfy the same contract: a
// topology override is policy a consumer sees, not a footnote.
func assertCapabilityRuleInvariants(t *testing.T, where string, rule proxyCapabilityRule) {
t.Helper()
switch rule.Outcome {
case ProxyOutcomeRefused:
if rule.Code == "" || rule.Message == "" || rule.ExitCode != 1 {
t.Errorf("%s: refusal must carry a code, a message and exit 1, got %#v", where, rule)
}
if rule.Mutates {
t.Errorf("%s: a refusal never mutates", where)
}
if !strings.HasPrefix(rule.Code, "proxy.") {
t.Errorf("%s: code %q must be in the stable proxy.* namespace", where, rule.Code)
}
case ProxyOutcomeRefusedInRunE:
if rule.Code != "" {
t.Errorf("%s: an untyped RunE refusal has no code; if it has one it belongs in the gate", where)
}
case ProxyOutcomeHonored:
if rule.Reason != "" {
t.Errorf("%s: Reason explains a refusal; an honored row must not carry one", where)
}
default:
t.Errorf("%s: unexpected outcome %q", where, rule.Outcome)
}
if rule.Outcome == ProxyOutcomeRefused || rule.Outcome == ProxyOutcomeRefusedInRunE {
switch rule.Reason {
case ProxyReasonDesign, ProxyReasonUnimplemented:
default:
t.Errorf("%s: refusal must declare Reason design or unimplemented, got %q", where, rule.Reason)
}
if rule.Reason == ProxyReasonUnimplemented && rule.Tracking == "" {
t.Errorf("%s: an unimplemented refusal needs a Tracking item naming who closes it", where)
}
}
}
// inlineProxiedRefusal matches the untyped refusals commands raise from their
// own RunE, e.g. HandleErrorRespectJSON("gitlab sync is not supported in
// proxied-server mode").
var inlineProxiedRefusal = regexp.MustCompile(`HandleErrorRespectJSON\("([^"]*proxied-server mode)"\)`)
// inlineProxiedMessages classifies the messages that do not name their command
// path in the standard "<path> is not supported ..." shape. A path maps the
// message to its registry row; an empty string records a message that mentions
// proxied mode without being a capability refusal at all. Keeping both explicit
// is what lets the scan below be exhaustive rather than best-effort.
var inlineProxiedMessages = map[string]string{
"only 'compact --dolt' is supported in proxied-server mode": "admin compact",
// Not a refusal: --database is the flag that only MAKES SENSE on a proxied
// workspace, so this fires on the direct topologies.
"--database (or a --db value naming a database) is only supported in proxied-server mode": "",
}
// TestProxyCapabilityRegistryCoversInlineRefusals scans the package for
// refusals raised inside RunE and requires each one to resolve to a registry
// row. Those strings are the untyped half of the refusal surface — no code, no
// mutates flag, nothing a JSON consumer can classify — and before the registry
// they were discoverable only by grep.
//
// The scan runs in both directions on purpose: a new inline refusal must be
// registered, and a ProxyOutcomeRefusedInRunE row whose string has been deleted
// must be flipped to its new outcome by the slice that deleted it.
func TestProxyCapabilityRegistryCoversInlineRefusals(t *testing.T) {
entries, err := os.ReadDir(".")
if err != nil {
t.Fatalf("read package dir: %v", err)
}
found := map[string]string{} // registry path -> file it was found in
for _, entry := range entries {
name := entry.Name()
if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
continue
}
src, err := os.ReadFile(filepath.Clean(name))
if err != nil {
t.Fatalf("read %s: %v", name, err)
}
for _, match := range inlineProxiedRefusal.FindAllStringSubmatch(string(src), -1) {
message := match[1]
path, ok := inlineRefusalPath(message)
if !ok {
t.Errorf("%s: %q mentions proxied-server mode but does not name a command path; "+
"add it to inlineProxiedMessages so it can be checked against the registry "+
"(map it to \"\" if it is not a capability refusal)", name, message)
continue
}
if path == "" {
continue // documented non-refusal
}
found[path] = name
}
}
for path, file := range found {
argSet := ""
if base, args, split := strings.Cut(path, " --"); split {
argSet = "--" + args
path = base
}
row, ok := LookupCapabilityRow(path, argSet)
if !ok {
t.Errorf("%s refuses %q inside RunE with no registry row; the front door and the command disagree about what bd supports",
file, strings.TrimSpace(path+" "+argSet))
continue
}
if row.Rule.Outcome == ProxyOutcomeHonored {
t.Errorf("%s refuses %q inside RunE, but the registry says the front door honors it", file, row.display())
}
}
for _, row := range proxyCapabilityRegistry {
if row.Rule.Outcome != ProxyOutcomeRefusedInRunE {
continue
}
if _, ok := found[row.Path]; !ok {
t.Errorf("%s is recorded as an untyped RunE refusal but no such refusal exists in the package any more (%s); "+
"flip the row to its new outcome", row.display(), row.Note)
}
}
}
func inlineRefusalPath(message string) (string, bool) {
if path, ok := inlineProxiedMessages[message]; ok {
return path, true
}
path, ok := strings.CutSuffix(message, " is not supported in proxied-server mode")
if !ok {
return "", false
}
// conflicts.go says "bd conflicts ..."; the registry keys on the path.
return strings.TrimPrefix(path, "bd "), true
}
// TestProxyCapabilityRegistryReasonsAreAssignedIndividually guards the one way
// this registry could become useless while staying green: reasons assigned in
// bulk. Every later slice reads these to decide what is left to do, so both
// values have to be genuinely represented, and the design refusals — the claim
// a reviewer will challenge — are listed here by name.
func TestProxyCapabilityRegistryReasonsAreAssignedIndividually(t *testing.T) {
wantDesign := map[string]bool{
"branch": true, "diff": true, "flatten": true,
"conflicts": true, "conflicts list": true, "conflicts show": true, "conflicts resolve": true,
"vc": true, "vc merge": true, "vc commit": true, "vc status": true,
"federation": true, "federation sync": true, "federation status": true,
"federation add-peer": true, "federation remove-peer": true, "federation list-peers": true,
"repo": true, "repo add": true, "repo remove": true, "repo list": true, "repo sync": true,
// `migrate hooks` is deliberately NOT here: it migrates git hook files
// and opens no store, so the surgery rationale the rest of this block
// rests on does not describe it. Its refusal is structural — the
// command is on none of main.go's store-init skip lists — which makes
// it unimplemented with a tracking item, not design.
"migrate": true, "migrate sync": true, "migrate issues": true,
"migrate-issues": true, "migrate-personal": true,
"admin cleanup": true, "admin reset": true,
// The backup family's DEFAULT rule is the design refusal; managed-local
// overrides it to honored (TestProxiedBackupHonoredOnlyOnManagedLocal).
// It is design because a backup remote is registered on the SERVER,
// where it is global to every client of that server — true of every
// destination scheme, unlike the filesystem half, which is a file://
// property only. These rows carry a Tracking item anyway
// (backupRemoteSchemeTracking): the outcome is settled, the
// remote-scheme case is an open question and must not read as closed.
"backup": true, "backup init": true, "backup sync": true,
"backup remove": true, "backup status": true, "backup restore": true,
}
gotDesign := map[string]bool{}
unimplemented := 0
for _, row := range proxyCapabilityRegistry {
switch row.Rule.Reason {
case ProxyReasonDesign:
gotDesign[row.display()] = true
case ProxyReasonUnimplemented:
unimplemented++
}
}
for path := range wantDesign {
if !gotDesign[path] {
t.Errorf("%q is no longer refused by design; if that is intended, update this test and say why in the PR", path)
}
}
for path := range gotDesign {
if !wantDesign[path] {
t.Errorf("%q claims Reason=design and is not in the reviewed list; a design refusal is a semantic claim that needs review", path)
}
}
if unimplemented == 0 {
t.Error("no unimplemented refusals left — either the work is done or the reasons were bulk-assigned")
}
}
// TestProxyCapabilityArgSetFallsBackToBarePath pins the lookup rule that lets
// one table carry both the path policy and the flag policy: a flag combination
// with no row of its own inherits the bare path's verdict rather than escaping
// it. Written against the real command tree so it exercises the flags these
// commands actually declare.
func TestProxyCapabilityArgSetFallsBackToBarePath(t *testing.T) {
for _, tc := range []struct {
path string
flags []string
want ProxyCapabilityOutcome
wantMsg string
}{
// Covered by an explicit row: the message names the flags.
{"rename-prefix", []string{"dry-run"}, ProxyOutcomeRefused, "rename-prefix --dry-run is not supported in proxied-server mode"},
// No row for this combination: it inherits the refused bare row rather
// than slipping past the gate.
{"rename-prefix", []string{"dry-run", "auto-merge"}, ProxyOutcomeRefused, "rename-prefix is not supported in proxied-server mode"},
// Inheriting an honored bare row is equally load-bearing: this is the
// read-only preview and it must keep working.
{"duplicates", []string{"dry-run"}, ProxyOutcomeHonored, ""},
} {
t.Run(tc.path+" "+strings.Join(tc.flags, " "), func(t *testing.T) {
root := &cobra.Command{Use: "bd"}
cmd := &cobra.Command{Use: tc.path}
root.AddCommand(cmd)
for _, flag := range tc.flags {
cmd.Flags().Bool(flag, false, "")
if err := cmd.Flags().Set(flag, "true"); err != nil {
t.Fatal(err)
}
}
row, ok := capabilityRowFor(cmd)
if !ok {
t.Fatalf("no row resolved for %q with %v", tc.path, tc.flags)
}
if row.Rule.Outcome != tc.want || row.Rule.Message != tc.wantMsg {
t.Fatalf("row = outcome %q message %q, want %q / %q",
row.Rule.Outcome, row.Rule.Message, tc.want, tc.wantMsg)
}
})
}
}
// TestProxyRefusalJSONCarriesReason pins the additive half of the JSON
// contract. {code, error, mutates} is frozen and parsed downstream; reason is
// new, and it must appear without disturbing the three fields that were already
// there.
func TestProxyRefusalJSONCarriesReason(t *testing.T) {
t.Setenv("BD_JSON_ENVELOPE", "")
oldJSON := jsonOutput
jsonOutput = true
t.Cleanup(func() { jsonOutput = oldJSON })
for _, tc := range []struct {
path, code string
reason ProxyRefusalReason
}{
{"branch", "proxy.branch.unsupported", ProxyReasonDesign},
{"sync", "proxy.sync.unsupported", ProxyReasonUnimplemented},
} {
t.Run(tc.path, func(t *testing.T) {
root := &cobra.Command{Use: "bd"}
cmd := &cobra.Command{Use: tc.path}
root.AddCommand(cmd)
out := captureStdout(t, func() error {
_ = validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
return nil
})
for _, want := range []string{
`"code": "` + tc.code + `"`,
`"error": "` + tc.path + ` is not supported in proxied-server mode"`,
`"mutates": false`,
`"reason": "` + string(tc.reason) + `"`,
} {
if !strings.Contains(out, want) {
t.Fatalf("refusal JSON missing %s:\n%s", want, out)
}
}
})
}
}
// TestProxiedStoreUnroutedIsTyped covers the backstop: a permitted command with
// no proxied route used to die with a bare string that no consumer could tell
// from a real store failure.
func TestProxiedStoreUnroutedIsTyped(t *testing.T) {
var typed *ProxyCapabilityError
err := errProxiedStoreUnrouted()
if !errors.As(err, &typed) {
t.Fatalf("store backstop error = %#v, want *ProxyCapabilityError", err)
}
if typed.Code != "proxy.store.unrouted" || typed.ExitCode != 1 || typed.Mutates {
t.Fatalf("store backstop = %#v", typed)
}
if typed.Reason != ProxyReasonUnimplemented {
t.Fatalf("store backstop reason = %q, want unimplemented", typed.Reason)
}
}

View file

@ -58,24 +58,25 @@ func TestProxyTransformCapabilityRows(t *testing.T) {
}
}
}
row, ok := lookupTransformCapability(cmd)
row, ok := capabilityRowFor(cmd)
if !ok {
t.Fatalf("lookup(%q, %q) missing row", tc.path, tc.argument)
}
if row.Path != tc.path || row.Argument != tc.argument || row.Outcome != tc.outcome {
if row.Path != tc.path || row.ArgSet != tc.argument || row.Rule.Outcome != tc.outcome {
t.Fatalf("row = %#v, want path=%q argument=%q outcome=%q", row, tc.path, tc.argument, tc.outcome)
}
if tc.outcome == ProxyOutcomeRefused {
if row.Code != tc.code || row.Message != tc.message || row.ExitCode != tc.exit || row.Mutates != tc.mutates {
t.Fatalf("refusal fields = code=%q message=%q exit=%d mutates=%t", row.Code, row.Message, row.ExitCode, row.Mutates)
if row.Rule.Code != tc.code || row.Rule.Message != tc.message || row.Rule.ExitCode != tc.exit || row.Rule.Mutates != tc.mutates {
t.Fatalf("refusal fields = code=%q message=%q exit=%d mutates=%t",
row.Rule.Code, row.Rule.Message, row.Rule.ExitCode, row.Rule.Mutates)
}
typed := transformCapabilityError(row)
var typed error = proxyCapabilityErrorFor(row.Rule)
var got *ProxyCapabilityError
if !errors.As(typed, &got) || got.Code != tc.code || got.ExitCode != 1 || got.Mutates {
t.Fatalf("typed refusal = %#v", typed)
}
}
if err := validateProxyTransformBeforeProvider(cmd); tc.outcome == ProxyOutcomeHonored && err != nil {
if err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); tc.outcome == ProxyOutcomeHonored && err != nil {
t.Fatalf("honored transform refused: %v", err)
}
})
@ -85,11 +86,11 @@ func TestProxyTransformCapabilityRows(t *testing.T) {
func TestProxyDuplicatesAutoMergeDryRunMatrix(t *testing.T) {
cmd := transformTestCommand("duplicates", "auto-merge", "dry-run")
_ = cmd.Flags().Set("auto-merge", "true")
if err := validateProxyTransformBeforeProvider(cmd); err == nil {
if err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); err == nil {
t.Fatalf("non-dry auto-merge error = %v", err)
}
_ = cmd.Flags().Set("dry-run", "true")
if err := validateProxyTransformBeforeProvider(cmd); err != nil {
if err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); err != nil {
t.Fatalf("dry-run auto-merge refused: %v", err)
}
}
@ -103,7 +104,7 @@ func TestProxyTransformRefusalRendering(t *testing.T) {
jsonOutput = false
var textErr string
stderr := captureStderr(t, func() {
err := validateProxyTransformBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if code, ok := exitCodeFromError(err); !ok || code != 1 {
t.Fatalf("exit = %v, want 1", err)
}
@ -115,7 +116,7 @@ func TestProxyTransformRefusalRendering(t *testing.T) {
jsonOutput = true
stdout := captureStdout(t, func() error {
_ = validateProxyTransformBeforeProvider(cmd)
_ = validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
return nil
})
var envelope map[string]any
@ -140,8 +141,8 @@ func TestProxyTransformMatcherIgnoresInheritedOutputFlags(t *testing.T) {
if err := root.PersistentFlags().Set("json", "true"); err != nil {
t.Fatal(err)
}
row, ok := lookupTransformCapability(cmd)
if !ok || row.Argument != "--auto-merge" || row.Outcome != ProxyOutcomeRefused {
row, ok := capabilityRowFor(cmd)
if !ok || row.ArgSet != "--auto-merge" || row.Rule.Outcome != ProxyOutcomeRefused {
t.Fatalf("row with inherited --json = %#v, ok=%v", row, ok)
}
}
@ -163,7 +164,7 @@ func TestProxyTransformRefusalHasNoProviderOrFileMutation(t *testing.T) {
t.Cleanup(func() { uowProvider = oldProvider })
cmd := transformTestCommand("supersede")
err := validateProxyTransformBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if err == nil {
t.Fatal("expected transform refusal")
}

View file

@ -76,8 +76,16 @@ func buildJSONError(message, hint string) interface{} {
return inner
}
// buildJSONCapabilityError renders a typed refusal. {code, error, mutates} is a
// frozen contract that downstream consumers parse; `reason` is additive and
// appears only on refusals that came from the capability registry, which is why
// it is omitted rather than emitted empty — a consumer that keys on its presence
// must not be told "" by a runtime state error that has no policy reason.
func buildJSONCapabilityError(e *ProxyCapabilityError) interface{} {
inner := map[string]interface{}{"error": e.Message, "code": e.Code, "mutates": e.Mutates}
if e.Reason != "" {
inner["reason"] = string(e.Reason)
}
if jsonEnvelopeEnabled() {
return map[string]interface{}{"schema_version": JSONSchemaVersion, "data": inner}
}

View file

@ -1,28 +0,0 @@
package main
// HistoryCapabilityClass classifies history/version-control commands on the
// proxied topology without coupling them to a particular backend engine.
type HistoryCapabilityClass string
const (
HistoryProxySupported HistoryCapabilityClass = "proxy-supported"
HistoryProxyAPI HistoryCapabilityClass = "proxy-api"
HistoryDirectOnly HistoryCapabilityClass = "direct-only"
)
var historyCapabilityMatrix = map[string]HistoryCapabilityClass{
"history": HistoryProxySupported,
"branch": HistoryDirectOnly, "conflicts": HistoryDirectOnly, "repo": HistoryDirectOnly,
"federation": HistoryDirectOnly, "vc": HistoryDirectOnly, "flatten": HistoryDirectOnly,
"dolt push": HistoryDirectOnly, "dolt pull": HistoryDirectOnly, "dolt commit": HistoryDirectOnly,
"dolt remote": HistoryDirectOnly, "dolt remote add": HistoryDirectOnly, "dolt remote list": HistoryDirectOnly,
"dolt remote reset-data": HistoryDirectOnly, "dolt remote remove": HistoryProxySupported,
"sync": HistoryDirectOnly,
}
// LookupHistoryCapability classifies an exact command path. Unknown paths are
// intentionally absent so callers cannot accidentally advertise support.
func LookupHistoryCapability(commandPath string) (HistoryCapabilityClass, bool) {
c, ok := historyCapabilityMatrix[commandPath]
return c, ok
}

View file

@ -229,13 +229,6 @@ func effectiveRootStorePolicy(cmdName string, strictReadonly bool) rootStorePoli
}
}
// backendSupportsStrictReadonly reports whether the live backend path can open
// without provisioning or lifecycle changes. Unsupported SQL backends are
// rejected earlier by validateConfiguredBackend; proxied Dolt remains writable-only.
func backendSupportsStrictReadonly(cfg *configfile.Config) bool {
return cfg == nil || !cfg.IsDoltProxiedServerMode()
}
// runsPostCommandMaintenance reports whether PersistentPostRunE should run the
// post-command maintenance net — Dolt auto-commit, the tip-metadata commit,
// auto-backup, auto-export and auto-push.
@ -1292,18 +1285,18 @@ var rootCmd = &cobra.Command{
fmt.Fprintf(os.Stderr, "warning: %v\n", err)
}
}
if beadsDir == "" {
beadsDir = beads.FindBeadsDir()
}
if cmdName == "doctor" && usesProxiedServer() {
// Refuse only on a real refusal. validateProxyMaintenance...
// Refuse only on a real refusal. The registry validator
// returns nil for doctor subcommands, and returning early on
// that would skip the legacy-store guard and autocommit-mode
// resolution every other skipsStoreInit command still runs.
if err := validateProxyMaintenanceBeforeProvider(cmd); err != nil {
if err := validateProxyRegistryBeforeProvider(cmd, resolveProxiedTopology(beadsDir)); err != nil {
return err
}
}
if beadsDir == "" {
beadsDir = beads.FindBeadsDir()
}
if err := guardLegacyNoStoreCommand(cmd, beadsDir); err != nil {
isMigrationCommand := false
for current := cmd; current != nil; current = current.Parent() {
@ -1504,14 +1497,13 @@ var rootCmd = &cobra.Command{
}
// Reject proxy capability combinations before any workspace side effect
// (version tracking, migration, auto-start, or provider construction).
// Two validators, one for each half of the policy: flag-keyed rules and
// the path-keyed capability registry.
if cfg != nil && cfg.IsDoltProxiedServerMode() {
if err := validateProxyCapabilitiesBeforeProvider(cmd); err != nil {
return err
}
if err := validateProxyMaintenanceBeforeProvider(cmd); err != nil {
return err
}
if err := validateProxyTransformBeforeProvider(cmd); err != nil {
if err := validateProxyRegistryBeforeProvider(cmd, resolveProxiedTopology(beadsDir)); err != nil {
return err
}
}
@ -1522,9 +1514,6 @@ var rootCmd = &cobra.Command{
if readonlyMode && cfg != nil && cfg.IsDoltProxiedServerMode() {
return HandleProxyCapabilityError(AssertProxyCapability(ProxyModeProxied, ProxyCapReadonly))
}
if readonlyMode && !backendSupportsStrictReadonly(cfg) {
return HandleError("strict readonly is unavailable for dolt proxied-server backend; refusing to open a store that cannot guarantee mutation-free access")
}
// Set actor for audit trail
actor = getActorWithGit()

View file

@ -199,12 +199,17 @@ func migrateFault(phase migratePhase) error {
return nil
}
// externalMigrationRefusal is a policy refusal rather than a registry row: it
// depends on the workspace's endpoint, not on which command was typed. The
// reason is design because someone else owns that endpoint and its schema —
// no amount of plumbing on this side makes migrating it bd's business.
func externalMigrationRefusal(message string) error {
return HandleProxyCapabilityError(&ProxyCapabilityError{
Code: "proxy.migrate.external_endpoint",
Message: message,
ExitCode: 1,
Mutates: false,
Reason: ProxyReasonDesign,
})
}

View file

@ -2,7 +2,6 @@ package main
import (
"fmt"
"strings"
"github.com/spf13/cobra"
)
@ -26,10 +25,11 @@ const (
ProxyModeProxied ProxyMode = "proxied-server"
)
// ProxyTopology distinguishes the provider deployment shape. Capability
// policy is currently identical across proxied shapes, but retaining this
// dimension prevents an external TCP server from being conflated with a local
// managed one as more surfaces are added.
// 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 (
@ -37,6 +37,17 @@ const (
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.
@ -47,17 +58,24 @@ const (
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.
// 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.
@ -66,12 +84,39 @@ type ProxyCapabilityError struct {
Message string
ExitCode int
Mutates bool
Reason ProxyRefusalReason
}
func (e *ProxyCapabilityError) Error() string { return e.Message }
func refused(code, message string) proxyCapabilityRule {
return proxyCapabilityRule{Outcome: ProxyOutcomeRefused, Code: code, Message: message, ExitCode: 1}
// 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 {
@ -97,104 +142,6 @@ type ProxyCapabilityRow struct {
Rule proxyCapabilityRule
}
var proxyMaintenanceRefusals = map[string]proxyCapabilityRule{
"doctor": refused("proxy.doctor.unsupported", "doctor is not supported in proxied-server mode"),
"backup": refused("proxy.backup.unsupported", "backup is not supported in proxied-server mode"),
"restore": refused("proxy.restore.unsupported", "restore is not supported in proxied-server mode"),
"diff": refused("proxy.diff.unsupported", "diff is not supported in proxied-server mode"),
"flatten": refused("proxy.flatten.unsupported", "flatten is not supported in proxied-server mode"),
"migrate": refused("proxy.migrate.unsupported", "migrate is not supported in proxied-server mode"),
"migrate-personal": refused("proxy.migrate.unsupported", "migrate-personal is not supported in proxied-server mode"),
"branch": refused("proxy.branch.unsupported", "branch is not supported in proxied-server mode"),
"conflicts": refused("proxy.conflicts.unsupported", "conflicts is not supported in proxied-server mode"),
"vc": refused("proxy.vc.unsupported", "vc is not supported in proxied-server mode"),
"federation": refused("proxy.federation.unsupported", "federation is not supported in proxied-server mode"),
"repo": refused("proxy.repo.unsupported", "repo is not supported in proxied-server mode"),
// Wording matches the long-standing compact.go refusal this pre-provider
// gate now short-circuits, so the user-facing message does not change.
"compact": refused("proxy.compact.unsupported", "only 'compact --dolt' is supported in proxied-server mode"),
"backup init": refused("proxy.backup.unsupported", "backup init is not supported in proxied-server mode"),
"backup sync": refused("proxy.backup.unsupported", "backup sync is not supported in proxied-server mode"),
"backup remove": refused("proxy.backup.unsupported", "backup remove is not supported in proxied-server mode"),
"backup status": refused("proxy.backup.unsupported", "backup status is not supported in proxied-server mode"),
"backup restore": refused("proxy.backup.unsupported", "backup restore is not supported in proxied-server mode"),
"migrate sync": refused("proxy.migrate.unsupported", "migrate sync is not supported in proxied-server mode"),
"migrate-issues": refused("proxy.migrate.unsupported", "migrate-issues is not supported in proxied-server mode"),
"gate discover": refused("proxy.gate.unsupported", "gate discover is not supported in proxied-server mode"),
"admin cleanup": refused("proxy.admin.unsupported", "admin cleanup is not supported in proxied-server mode"),
"admin reset": refused("proxy.admin.unsupported", "admin reset is not supported in proxied-server mode"),
"dolt push": refused("proxy.dolt_push.unsupported", "dolt push is not supported in proxied-server mode"),
"dolt pull": refused("proxy.dolt_pull.unsupported", "dolt pull is not supported in proxied-server mode"),
"dolt commit": refused("proxy.dolt_commit.unsupported", "dolt commit is not supported in proxied-server mode"),
"dolt remote": refused("proxy.dolt_remote.unsupported", "dolt remote is not supported in proxied-server mode"),
"dolt remote add": refused("proxy.dolt_remote.unsupported", "dolt remote add is not supported in proxied-server mode"),
"dolt remote list": refused("proxy.dolt_remote.unsupported", "dolt remote list is not supported in proxied-server mode"),
"cook": refused("proxy.formula.unsupported", "cook is not supported in proxied-server mode"),
"ship": refused("proxy.formula.unsupported", "ship is not supported in proxied-server mode"),
"swarm create": refused("proxy.swarm.unsupported", "swarm create is not supported in proxied-server mode"),
"swarm list": refused("proxy.swarm.unsupported", "swarm list is not supported in proxied-server mode"),
"merge-slot create": refused("proxy.merge_slot.unsupported", "merge-slot create is not supported in proxied-server mode"),
"merge-slot check": refused("proxy.merge_slot.unsupported", "merge-slot check is not supported in proxied-server mode"),
"merge-slot acquire": refused("proxy.merge_slot.unsupported", "merge-slot acquire is not supported in proxied-server mode"),
"merge-slot release": refused("proxy.merge_slot.unsupported", "merge-slot release is not supported in proxied-server mode"),
"dolt remote reset-data": refused("proxy.dolt_remote.unsupported", "dolt remote reset-data is not supported in proxied-server mode"),
"sync": refused("proxy.sync.unsupported", "sync is not supported in proxied-server mode"),
}
func init() {
for parent, children := range map[string][]string{
"vc": {"merge", "commit", "status"},
"federation": {"sync", "status", "add-peer", "remove-peer", "list-peers"},
"repo": {"add", "remove", "list", "sync"},
"conflicts": {"list", "show", "resolve"},
"migrate": {"hooks", "issues"},
} {
rule := proxyMaintenanceRefusals[parent]
for _, child := range children {
path := parent + " " + child
proxyMaintenanceRefusals[path] = refused(rule.Code, path+" is not supported in proxied-server mode")
}
}
}
// validateProxyMaintenanceBeforeProvider rejects known direct-only commands
// before migrations, auto-start, or provider construction.
func validateProxyMaintenanceBeforeProvider(cmd *cobra.Command) error {
if cmd == nil {
return nil
}
name := cmd.Name()
path := strings.TrimSpace(strings.TrimPrefix(cmd.CommandPath(), cmd.Root().Name()))
if name == "compact" {
if cmd.Flags().Lookup("dolt") == nil {
return nil // root `bd compact` is the Dolt history command
}
dolt, _ := cmd.Flags().GetBool("dolt")
if dolt {
return nil
}
rule := proxyMaintenanceRefusals["compact"]
return HandleProxyCapabilityError(&ProxyCapabilityError{Code: rule.Code, Message: rule.Message, ExitCode: rule.ExitCode})
}
if rule, ok := proxyMaintenanceRefusals[path]; ok {
return HandleProxyCapabilityError(&ProxyCapabilityError{Code: rule.Code, Message: rule.Message, ExitCode: rule.ExitCode})
}
if class, ok := LookupHistoryCapability(path); ok && class == HistoryDirectOnly {
rule := refused("proxy.history.unsupported", path+" is not supported in proxied-server mode")
if specific, found := proxyMaintenanceRefusals[path]; found {
rule = specific
}
return HandleProxyCapabilityError(&ProxyCapabilityError{Code: rule.Code, Message: rule.Message, ExitCode: rule.ExitCode, Mutates: rule.Mutates})
}
if strings.Contains(path, " ") {
return nil
}
if rule, ok := proxyMaintenanceRefusals[name]; ok {
return HandleProxyCapabilityError(&ProxyCapabilityError{Code: rule.Code, Message: rule.Message, ExitCode: rule.ExitCode})
}
return nil
}
// 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) {
@ -212,26 +159,50 @@ func LookupProxyCapabilityFor(command, argument string, mode ProxyMode) (proxyCa
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)
)
// 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"),
ProxyCapMaxRows: refused("proxy.max_rows.unsupported", "--max-rows / BEADS_MAX_ROWS is not supported in proxied-server mode"),
ProxyCapWatch: refused("proxy.watch.unsupported", "watch mode not supported in proxied-server mode"),
ProxyCapRepo: refused("proxy.repo.unsupported", "--repo is not supported with --proxied-server"),
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: refused("proxy.repo.unsupported", "--repo is not supported with --proxied-server", ProxyReasonDesign, ""),
},
}
var proxyCommandCapabilities = map[string]map[ProxyMode]map[ProxyCapability]proxyCapabilityRule{
"show": {ProxyModeProxied: {ProxyCapWatch: refused("proxy.watch.unsupported", "watch mode not supported in proxied-server mode")}},
"show": {ProxyModeProxied: {ProxyCapWatch: watchRefusal}},
"list": {ProxyModeProxied: {ProxyCapWatch: honored(), ProxyCapMaxRows: honored(), ProxyCapRepo: notApplicable()}},
"dep tree": {ProxyModeProxied: {ProxyCapMaxRows: honored()}},
"ready": {ProxyModeProxied: {ProxyCapMaxRows: refused("proxy.max_rows.unsupported", "--max-rows / BEADS_MAX_ROWS is not supported in proxied-server mode")}},
"graph": {ProxyModeProxied: {ProxyCapMaxRows: refused("proxy.max_rows.unsupported", "--max-rows / BEADS_MAX_ROWS is not supported in proxied-server mode")}},
"find-duplicates": {ProxyModeProxied: {ProxyCapMaxRows: refused("proxy.max_rows.unsupported", "--max-rows / BEADS_MAX_ROWS is not supported in proxied-server mode")}},
"ready": {ProxyModeProxied: {ProxyCapMaxRows: maxRowsRefusal}},
"graph": {ProxyModeProxied: {ProxyCapMaxRows: maxRowsRefusal}},
"find-duplicates": {ProxyModeProxied: {ProxyCapMaxRows: maxRowsRefusal}},
}
// proxyCapabilityRows materializes the policy for every supported proxied
@ -305,7 +276,7 @@ func AssertProxyCommandCapability(command string, mode ProxyMode, capability Pro
return nil
}
if rule.Code != "" {
return &ProxyCapabilityError{Code: rule.Code, Message: rule.Message, ExitCode: rule.ExitCode, Mutates: rule.Mutates}
return proxyCapabilityErrorFor(rule)
}
return fmt.Errorf("%s", rule.Message)
}
@ -314,7 +285,7 @@ func AssertProxyCommandCapability(command string, mode ProxyMode, capability Pro
rule, ok := LookupProxyCapability(mode, capability)
if !ok || (rule.Outcome != ProxyOutcomeHonored && rule.Outcome != ProxyOutcomeDelegated) {
if rule.Code != "" {
return &ProxyCapabilityError{Code: rule.Code, Message: rule.Message, ExitCode: rule.ExitCode, Mutates: rule.Mutates}
return proxyCapabilityErrorFor(rule)
}
if rule.Message != "" {
return fmt.Errorf("%s", rule.Message)

View file

@ -17,12 +17,12 @@ import (
// #6575 proxied data-behind guidance is written against: the consent command
// that guidance prescribes is NOT refused at the proxied front door.
//
// The refusal table keys on the full command path. It has rows for the bare
// `migrate` verb and for `migrate hooks` / `migrate issues` / `migrate sync`,
// but none for `migrate schema` — so that path falls through
// validateProxyMaintenanceBeforeProvider's multi-word arm to `bd migrate
// schema`'s own proxied arm, which reports the migration the provider open
// already applied under this verb's consent.
// The capability registry keys on the full command path. It refuses the bare
// `migrate` verb and `migrate hooks` / `migrate issues` / `migrate sync`, but
// permits `migrate schema` — so that path passes
// validateProxyRegistryBeforeProvider to `bd migrate schema`'s own proxied
// arm, which reports the migration the provider open already applied under
// this verb's consent.
//
// An earlier revision of that guidance asserted the opposite on three runtime
// surfaces and nothing failed, because no test called this function with this
@ -51,7 +51,7 @@ func TestProxyMaintenanceAllowsTheSharedConsentVerb(t *testing.T) {
var allowErr error
out := captureStdout(t, func() error {
allowErr = validateProxyMaintenanceBeforeProvider(target)
allowErr = validateProxyRegistryBeforeProvider(target, ProxyTopologyManagedLocal)
return nil
})
if allowErr != nil {
@ -70,7 +70,7 @@ func TestProxyMaintenanceAllowsTheSharedConsentVerb(t *testing.T) {
}
var bareErr error
refusal := captureStdout(t, func() error {
bareErr = validateProxyMaintenanceBeforeProvider(bare)
bareErr = validateProxyRegistryBeforeProvider(bare, ProxyTopologyManagedLocal)
return nil
})
if bareErr == nil {
@ -139,6 +139,11 @@ func TestProxyCapabilityCommandRows(t *testing.T) {
}
}
// TestProxyMaintenanceNestedPathsRefuseBeforeProvider proves the gate resolves
// a PARENT+CHILD path, which is where a nested command used to slip through.
// It runs on external-tcp because that is the topology on which every path
// listed here still refuses: the backup family is honored on managed-local
// since slice S3, and asserting a refusal there would be asserting the bug.
func TestProxyMaintenanceNestedPathsRefuseBeforeProvider(t *testing.T) {
oldJSON := jsonOutput
jsonOutput = true
@ -151,7 +156,7 @@ func TestProxyMaintenanceNestedPathsRefuseBeforeProvider(t *testing.T) {
root.AddCommand(parent)
parent.AddCommand(child)
out := captureStdout(t, func() error {
_ = validateProxyMaintenanceBeforeProvider(child)
_ = validateProxyRegistryBeforeProvider(child, ProxyTopologyExternalTCP)
return nil
})
if !strings.Contains(out, `"code":`) {
@ -171,7 +176,7 @@ func TestProxyFormulaSwarmMergeSlotRefusals(t *testing.T) {
cmd.AddCommand(child)
cmd = child
}
err := validateProxyMaintenanceBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if err == nil {
t.Fatalf("%s unexpectedly allowed", path)
}
@ -209,7 +214,7 @@ func TestProxyWorkflowRefusalContractAndNoMutation(t *testing.T) {
if !ok || row.Code != tc.code || row.Message != tc.message || row.ExitCode != 1 || row.Mutates {
t.Fatalf("row = %#v, ok=%v", row, ok)
}
var typed *ProxyCapabilityError = &ProxyCapabilityError{Code: row.Code, Message: row.Message, ExitCode: row.ExitCode, Mutates: row.Mutates}
typed := proxyCapabilityErrorFor(row)
if typed.Code != tc.code || typed.Message != tc.message || typed.ExitCode != 1 || typed.Mutates {
t.Fatalf("typed refusal = %#v", typed)
}
@ -232,7 +237,7 @@ func TestProxyWorkflowRefusalContractAndNoMutation(t *testing.T) {
oldDidWrite := commandDidWrite.Load()
commandDidWrite.Store(false)
t.Cleanup(func() { commandDidWrite.Store(oldDidWrite) })
out := captureStdout(t, func() error { _ = validateProxyMaintenanceBeforeProvider(cmd); return nil })
out := captureStdout(t, func() error { _ = validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); return nil })
var got map[string]any
if err := json.Unmarshal([]byte(out), &got); err != nil || got["code"] != tc.code || got["error"] != tc.message {
t.Fatalf("JSON refusal = %q (%v)", out, err)
@ -251,8 +256,8 @@ func TestProxyWorkflowRefusalContractAndNoMutation(t *testing.T) {
}
func lookupProxyMaintenanceRuleForTest(path string) (proxyCapabilityRule, bool) {
rule, ok := proxyMaintenanceRefusals[path]
return rule, ok
row, ok := LookupCapabilityRow(path, "")
return row.Rule, ok
}
func TestProxyMaintenanceRefusalLeavesFilesUntouched(t *testing.T) {
@ -269,7 +274,7 @@ func TestProxyMaintenanceRefusalLeavesFilesUntouched(t *testing.T) {
oldProvider := uowProvider
uowProvider = nil
t.Cleanup(func() { uowProvider = oldProvider })
err := validateProxyMaintenanceBeforeProvider(hooks)
err := validateProxyRegistryBeforeProvider(hooks, ProxyTopologyManagedLocal)
if err == nil {
t.Fatal("expected typed maintenance refusal")
}

54
cmd/bd/proxy_topology.go Normal file
View file

@ -0,0 +1,54 @@
package main
import (
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/configfile"
)
// resolveProxiedTopology reports which proxied-server SHAPE a workspace is, for
// the capability rows whose answer depends on it.
//
// The shapes are ordered by how much of the store bd owns, and the first one
// that matches wins:
//
// team-server the database belongs to beads-team-server, which owns its
// schema and identity. Ownership beats transport — a
// bts-managed database is somebody else's store even when the
// dolt process happens to be local.
// external-* an operator's Dolt server that bd only connects to. The
// sidecar's External block is what records it, and the socket
// field is what separates the two transports.
// managed-local no External block: bd spawned this dolt sql-server itself,
// under this user, on this filesystem.
//
// A workspace bd cannot read is reported as unknown rather than guessed at.
// Every topology-keyed row treats unknown as refused, so a corrupt sidecar
// costs a capability instead of buying one; the provider open that follows
// fails on the same file with a much better message than this function could
// produce, so this is a policy decision, not the error path.
func resolveProxiedTopology(beadsDir string) ProxyTopology {
if beadsDir == "" {
beadsDir = beads.FindBeadsDir()
}
if beadsDir == "" {
return ProxyTopologyUnknown
}
cfg, err := configfile.Load(beadsDir)
if err != nil {
return ProxyTopologyUnknown
}
if cfg != nil && cfg.IsTeamServerManaged() {
return ProxyTopologyTeamServer
}
info, err := configfile.LoadProxiedServerClientInfo(beadsDir)
if err != nil {
return ProxyTopologyUnknown
}
if info == nil || info.External == nil {
return ProxyTopologyManagedLocal
}
if info.External.Socket != "" {
return ProxyTopologyExternalUnix
}
return ProxyTopologyExternalTCP
}

View file

@ -73,7 +73,7 @@ func init() {
pruneCmd.Flags().BoolP("force", "f", false, "Actually prune (without this, shows preview)")
pruneCmd.Flags().Bool("ignore-references", false, "Delete closed beads even when referenced by open beads (use with care; see --help for details)")
pruneCmd.Flags().Bool("dry-run", false, "Preview what would be pruned with stats")
pruneCmd.Flags().String("older-than", "", "Only prune beads closed more than N ago (e.g., 30d, 2w, 60)")
pruneCmd.Flags().String("older-than", "", "Only prune beads closed more than N ago (e.g., 30d, 2w, 60, 36h)")
pruneCmd.Flags().String("pattern", "", "Only prune beads matching ID glob pattern (e.g., 'gm-old-*')")
rootCmd.AddCommand(pruneCmd)
}

View file

@ -2,6 +2,7 @@ package main
import (
"fmt"
"math"
"strconv"
"strings"
"time"
@ -36,6 +37,12 @@ type purgeScope struct {
// is not done. `bd prune` asks unless --ignore-references; `bd purge`
// never does, because a wisp's citations are as transient as the wisp.
protectReferenced bool
// protectLiveDependents asks the role to skip candidates a live bead
// depends on through a parent-child, tracks or blocks edge. `bd purge`
// always asks: deleting a closed wisp whose child, tracker or blocked bead
// is still live cuts that live work loose from its root, and there is no
// retention reason to want that — a deliberate removal is `bd delete`.
protectLiveDependents bool
// reportsReferences publishes the reference-skip keys under --json. It is
// separate from protectReferenced because `bd prune --ignore-references`
// still publishes them, as zeroes, which is the shipped shape.
@ -52,7 +59,21 @@ Closed ephemeral beads (wisps, transient molecules) accumulate rapidly and
have no value once closed. This command removes them to reclaim storage.
Deletes: issues, dependencies, labels, events, and comments for matching beads.
Skips: pinned beads (protected).
Skips: pinned beads, and closed beads a live bead still depends on through a
parent-child, tracks or blocks edge (a closed molecule root whose step is open,
a closed bead a live convoy tracks). Live means any status that is not done.
--wisps-plane selects by storage plane instead: every closed row stored in the
wisps table, including --no-history beads, which the default ephemeral
selection leaves to ` + "`bd prune`" + `. It reaches durable-tier rows, so it requires
--older-than or --pattern, like ` + "`bd prune`" + `.
--limit N caps one run at N beads, oldest-closed first, so a large backlog can
be drained in bounded transactions; --json then reports "remaining" and
"has_more". Loop while has_more is true.
--older-than takes days (7, 7d), weeks (2w) or a duration with hour precision
(36h, 168h, 90m).
To delete closed non-ephemeral beads (regular tasks, features, bugs, etc.)
use ` + "`bd prune`" + ` instead.
@ -65,6 +86,9 @@ EXAMPLES:
bd purge --force # Delete all closed ephemeral beads
bd purge --older-than 7d --force # Only purge items closed 7+ days ago
bd purge --pattern "*-wisp-*" # Only purge matching ID pattern
bd purge --older-than 36h --force # Hour precision: closed 36+ hours ago
bd purge --wisps-plane --older-than 168h --force
# Every closed wisps-table row, incl. no-history
bd purge --dry-run # Detailed preview with stats`,
SilenceUsage: true,
SilenceErrors: true,
@ -76,14 +100,20 @@ EXAMPLES:
}
}()
return runPurgeOrPrune(cmd, purgeScope{
cmdName: "purge",
pastTense: "purged",
countKey: "purged_count",
dryRunCountKey: "purge_count",
subjectNoun: "closed ephemeral bead",
tier: issueops.SweepEphemeral,
})
scope := purgeScope{
cmdName: "purge",
pastTense: "purged",
countKey: "purged_count",
dryRunCountKey: "purge_count",
subjectNoun: "closed ephemeral bead",
tier: issueops.SweepEphemeral,
protectLiveDependents: true,
}
if wispsPlane, _ := cmd.Flags().GetBool("wisps-plane"); wispsPlane {
scope.subjectNoun = "closed wisps-plane bead"
scope.tier = issueops.SweepWispsPlane
}
return runPurgeOrPrune(cmd, scope)
},
}
@ -110,6 +140,11 @@ func runPurgeOrPrune(cmd *cobra.Command, scope purgeScope) error {
dryRun, _ := cmd.Flags().GetBool("dry-run")
olderThan, _ := cmd.Flags().GetString("older-than")
pattern, _ := cmd.Flags().GetString("pattern")
// Only `bd purge` defines --limit; GetInt on an undefined flag is 0, "no cap".
limit, _ := cmd.Flags().GetInt("limit")
if limit < 0 {
return HandleErrorRespectJSON("invalid --limit value %d: must be 0 (no limit) or positive", limit)
}
// The ROLE refuses an unfiltered durable sweep — that guard is
// workapi.ValidateSweepRequest, below every front door. This branch is here
@ -117,30 +152,36 @@ func runPurgeOrPrune(cmd *cobra.Command, scope purgeScope) error {
// flags a person who typed `bd prune --force` has to reach for. The contract
// case RunSweeperRefusesAnUnfilteredDurableSweep proves the guard survives
// this branch being deleted.
if scope.tier == issueops.SweepDurable && olderThan == "" && pattern == "" {
if scope.tier != issueops.SweepEphemeral && olderThan == "" && pattern == "" {
command := scope.cmdName
if scope.tier == issueops.SweepWispsPlane {
command += " --wisps-plane"
}
return HandleErrorWithHint(
fmt.Sprintf("bd %s requires --older-than or --pattern", scope.cmdName),
fmt.Sprintf("bd %s requires --older-than or --pattern", command),
"Protects against accidental bulk deletion. Use `--pattern '*'` to\n"+
" include all closed beads in this scope, or `--older-than 1d`\n"+
" / `--pattern '<glob>'` to narrow the deletion.")
}
request := issueops.SweepRequest{
Actor: actor,
Tier: scope.tier,
IDPattern: pattern,
ProtectReferenced: scope.protectReferenced,
Actor: actor,
Tier: scope.tier,
IDPattern: pattern,
ProtectReferenced: scope.protectReferenced,
ProtectLiveDependents: scope.protectLiveDependents,
Limit: limit,
// A --dry-run and an UNCONFIRMED run ask the role the same question —
// "what would this do" — so both send DryRun. --force is this
// command's confirmation, not a request field.
DryRun: dryRun || !force,
}
if olderThan != "" {
days, err := parseHumanDuration(olderThan)
age, err := parseOlderThan(olderThan)
if err != nil {
return HandleErrorRespectJSON("invalid --older-than value %q: %v", olderThan, err)
}
cutoff := time.Now().UTC().AddDate(0, 0, -days)
cutoff := time.Now().UTC().Add(-age)
request.ClosedBefore = &cutoff
}
@ -165,16 +206,16 @@ func runPurgeOrPrune(cmd *cobra.Command, scope purgeScope) error {
switch {
case result.Swept == 0:
return emitSweepEmpty(scope, olderThan, pattern, result)
return emitSweepEmpty(scope, olderThan, pattern, limit, result)
case dryRun:
return emitSweepDryRun(scope, result)
return emitSweepDryRun(scope, limit, result)
case !force:
return emitSweepConfirm(scope, olderThan, pattern, result)
}
commandDidWrite.Store(true)
commandMayEmptyJSONLExport.Store(true)
return emitSweepResult(scope, result)
return emitSweepResult(scope, limit, result)
}
// warnSweepDefenseSkips reports the candidates the role's own recheck threw
@ -208,12 +249,40 @@ func addReferenceStats(scope purgeScope, stats map[string]interface{}, result is
}
}
func emitSweepEmpty(scope purgeScope, olderThan, pattern string, result issueops.SweepResult) error {
// addLimitStats reports what --limit left for the next run. It is attached
// only when the caller asked for a limit, so the unlimited shape is unchanged.
func addLimitStats(stats map[string]interface{}, limit int, result issueops.SweepResult) {
if limit <= 0 {
return
}
stats["remaining"] = result.Remaining
stats["has_more"] = result.Remaining > 0
}
// printLimitNote tells a text reader that --limit left rows behind.
func printLimitNote(result issueops.SweepResult) {
if result.Remaining > 0 {
fmt.Printf(" Remaining (over --limit): %d — run again to continue\n", result.Remaining)
}
}
// addLiveDependentStats attaches the live-dependent skip count to a --json
// payload when the protection held anything back, the way pinned_skipped is
// reported.
func addLiveDependentStats(stats map[string]interface{}, result issueops.SweepResult) {
if result.Skipped.LiveDependent > 0 {
stats["live_dependent_skipped"] = result.Skipped.LiveDependent
}
}
func emitSweepEmpty(scope purgeScope, olderThan, pattern string, limit int, result issueops.SweepResult) error {
if jsonOutput {
stats := map[string]interface{}{
scope.countKey: 0,
"message": fmt.Sprintf("No %ss to %s", scope.subjectNoun, scope.cmdName),
}
addLiveDependentStats(stats, result)
addLimitStats(stats, limit, result)
addReferenceStats(scope, stats, result)
return outputJSON(stats)
}
@ -225,6 +294,10 @@ func emitSweepEmpty(scope purgeScope, olderThan, pattern string, result issueops
msg += fmt.Sprintf(" (matching %q)", pattern)
}
fmt.Println(msg)
if result.Skipped.LiveDependent > 0 {
fmt.Println(ui.MutedStyle.Render(fmt.Sprintf(
" (%d closed bead(s) protected by live dependents)", result.Skipped.LiveDependent)))
}
if result.Skipped.Referenced > 0 {
fmt.Println(ui.MutedStyle.Render(fmt.Sprintf(
" (%d closed bead(s) protected by open-bead references — use --ignore-references to override)",
@ -233,7 +306,7 @@ func emitSweepEmpty(scope purgeScope, olderThan, pattern string, result issueops
return nil
}
func emitSweepDryRun(scope purgeScope, result issueops.SweepResult) error {
func emitSweepDryRun(scope purgeScope, limit int, result issueops.SweepResult) error {
if jsonOutput {
stats := map[string]interface{}{
"dry_run": true,
@ -245,6 +318,8 @@ func emitSweepDryRun(scope purgeScope, result issueops.SweepResult) error {
if result.Skipped.Pinned > 0 {
stats["pinned_skipped"] = result.Skipped.Pinned
}
addLiveDependentStats(stats, result)
addLimitStats(stats, limit, result)
addReferenceStats(scope, stats, result)
return outputJSON(stats)
}
@ -255,6 +330,9 @@ func emitSweepDryRun(scope purgeScope, result issueops.SweepResult) error {
if result.Skipped.Pinned > 0 {
fmt.Printf(" Pinned (skipped): %d\n", result.Skipped.Pinned)
}
if result.Skipped.LiveDependent > 0 {
fmt.Printf(" Live dependent (skipped): %d\n", result.Skipped.LiveDependent)
}
if result.Skipped.Referenced > 0 {
fmt.Printf(" %s %d\n", ui.MutedStyle.Render("Referenced (skipped):"), result.Skipped.Referenced)
sample := result.ReferencedIDs
@ -271,6 +349,7 @@ func emitSweepDryRun(scope purgeScope, result issueops.SweepResult) error {
}
fmt.Printf(" %s %s%s\n", ui.MutedStyle.Render("Referenced IDs (sample):"), strings.Join(idStrs, ", "), suffix)
}
printLimitNote(result)
fmt.Printf("\n(Dry-run mode — no changes made)\n")
return nil
}
@ -280,10 +359,16 @@ func emitSweepConfirm(scope purgeScope, olderThan, pattern string, result issueo
if result.Skipped.Pinned > 0 {
fmt.Printf("Skipping %d pinned bead(s)\n", result.Skipped.Pinned)
}
if result.Skipped.LiveDependent > 0 {
fmt.Printf("Skipping %d bead(s) a live bead depends on\n", result.Skipped.LiveDependent)
}
if result.Skipped.Referenced > 0 {
fmt.Println(ui.MutedStyle.Render(fmt.Sprintf("Skipping %d referenced bead(s)", result.Skipped.Referenced)))
}
hint := fmt.Sprintf("bd %s --force", scope.cmdName)
if scope.tier == issueops.SweepWispsPlane {
hint += " --wisps-plane"
}
if olderThan != "" {
hint += " --older-than " + olderThan
}
@ -295,7 +380,7 @@ func emitSweepConfirm(scope purgeScope, olderThan, pattern string, result issueo
fmt.Sprintf("Use --force to confirm or --dry-run to preview.\n %s", hint))
}
func emitSweepResult(scope purgeScope, result issueops.SweepResult) error {
func emitSweepResult(scope purgeScope, limit int, result issueops.SweepResult) error {
if jsonOutput {
stats := map[string]interface{}{
scope.countKey: result.Swept,
@ -306,6 +391,8 @@ func emitSweepResult(scope purgeScope, result issueops.SweepResult) error {
if result.Skipped.Pinned > 0 {
stats["pinned_skipped"] = result.Skipped.Pinned
}
addLiveDependentStats(stats, result)
addLimitStats(stats, limit, result)
addReferenceStats(scope, stats, result)
return outputJSON(stats)
}
@ -316,9 +403,13 @@ func emitSweepResult(scope purgeScope, result issueops.SweepResult) error {
if result.Skipped.Pinned > 0 {
fmt.Printf(" Pinned (skipped): %d\n", result.Skipped.Pinned)
}
if result.Skipped.LiveDependent > 0 {
fmt.Printf(" Live dependent (skipped): %d\n", result.Skipped.LiveDependent)
}
if result.Skipped.Referenced > 0 {
fmt.Printf(" %s %d\n", ui.MutedStyle.Render("Referenced (skipped):"), result.Skipped.Referenced)
}
printLimitNote(result)
return nil
}
@ -329,53 +420,77 @@ func capitalize(s string) string {
return strings.ToUpper(s[:1]) + s[1:]
}
// parseHumanDuration parses a human-friendly duration string into days.
// Accepts: "7d", "30d", "24h", "2w", or just a number (treated as days).
func parseHumanDuration(s string) (int, error) {
// parseOlderThan parses an --older-than value into an age.
//
// Day-denominated values keep the meaning they always had: a bare number is
// days ("7"), and "7d" / "2w" are days and weeks. Anything else is a Go
// duration with hour precision or finer — "36h", "168h", "90m", "1h30m" — and
// is taken exactly; "Nh" used to be floored to whole days, which made "36h"
// sweep rows only 24 hours old. The suffix letters are case-insensitive, as
// they always were. The age must be positive.
func parseOlderThan(s string) (time.Duration, error) {
s = strings.TrimSpace(s)
if s == "" {
return 0, fmt.Errorf("empty duration")
}
// Plain number = days
if days, err := strconv.Atoi(s); err == nil {
if days <= 0 {
return 0, fmt.Errorf("duration must be positive")
}
return days, nil
return daysAge(int64(days))
}
// Parse suffix
unit := s[len(s)-1]
numStr := s[:len(s)-1]
num, err := strconv.Atoi(numStr)
if err != nil {
return 0, fmt.Errorf("invalid number %q", numStr)
switch unit {
case 'd', 'D', 'w', 'W':
num, err := strconv.Atoi(s[:len(s)-1])
if err != nil {
return 0, fmt.Errorf("invalid number %q", s[:len(s)-1])
}
days := int64(num)
if unit == 'w' || unit == 'W' {
if days > maxOlderThanDays/7 || days < -maxOlderThanDays/7 {
return 0, errOlderThanRange
}
days *= 7
}
return daysAge(days)
}
if num <= 0 {
age, err := time.ParseDuration(strings.ToLower(s))
if err != nil {
// time.ParseDuration refuses an out-of-range value ("9999999h") the
// same way it refuses a malformed one, so neither can wrap around.
return 0, fmt.Errorf("invalid or out-of-range duration %q (use a number of days, Nd, Nw, or a duration such as 36h or 90m)", s)
}
return positiveAge(age)
}
// maxOlderThanDays is the largest day count a time.Duration can hold. A larger
// value used to overflow silently — 213504d wrapped to 25 minutes — which on a
// destructive command selected nearly everything instead of nothing.
const maxOlderThanDays = math.MaxInt64 / int64(24*time.Hour)
var errOlderThanRange = fmt.Errorf("duration out of range (at most %d days)", maxOlderThanDays)
func daysAge(days int64) (time.Duration, error) {
if days > maxOlderThanDays {
return 0, errOlderThanRange
}
return positiveAge(time.Duration(days) * 24 * time.Hour)
}
func positiveAge(age time.Duration) (time.Duration, error) {
if age <= 0 {
return 0, fmt.Errorf("duration must be positive")
}
switch unit {
case 'h', 'H':
days := num / 24
if days == 0 {
days = 1 // minimum 1 day
}
return days, nil
case 'd', 'D':
return num, nil
case 'w', 'W':
return num * 7, nil
default:
return 0, fmt.Errorf("unknown unit %q (use h, d, or w)", string(unit))
}
return age, nil
}
func init() {
purgeCmd.Flags().BoolP("force", "f", false, "Actually purge (without this, shows preview)")
purgeCmd.Flags().Bool("dry-run", false, "Preview what would be purged with stats")
purgeCmd.Flags().String("older-than", "", "Only purge beads closed more than N ago (e.g., 7d, 2w, 30)")
purgeCmd.Flags().String("older-than", "", "Only purge beads closed more than N ago (e.g., 7d, 2w, 30, 36h)")
purgeCmd.Flags().Int("limit", 0, "Purge at most N beads this run, oldest-closed first (0 = no limit); --json reports remaining/has_more")
purgeCmd.Flags().Bool("wisps-plane", false, "Select every closed row in the wisps table, including --no-history beads (requires --older-than or --pattern)")
purgeCmd.Flags().String("pattern", "", "Only purge beads matching ID glob pattern (e.g., *-wisp-*)")
rootCmd.AddCommand(purgeCmd)
}

View file

@ -1,40 +1,68 @@
package main
import "testing"
import (
"testing"
"time"
)
func TestParseHumanDuration(t *testing.T) {
// TestParseOlderThan pins --older-than on both `bd purge` and `bd prune`.
// Day-denominated values keep their meaning; hour (and finer) values are taken
// exactly rather than floored to whole days — "36h" used to become 24h and
// sweep rows younger than the caller asked for.
func TestParseOlderThan(t *testing.T) {
const day = 24 * time.Hour
tests := []struct {
input string
want int
want time.Duration
wantErr bool
}{
{"7", 7, false},
{"30", 30, false},
{"7d", 7, false},
{"30d", 30, false},
{"2w", 14, false},
{"1w", 7, false},
{"48h", 2, false},
{"12h", 1, false}, // rounds up to 1 day minimum
{"7D", 7, false},
{"2W", 14, false},
// Unchanged day semantics.
{"7", 7 * day, false},
{"30", 30 * day, false},
{"7d", 7 * day, false},
{"30d", 30 * day, false},
{"2w", 14 * day, false},
{"1w", 7 * day, false},
{"7D", 7 * day, false},
{"2W", 14 * day, false},
// Hour precision, no longer floored to days.
{"48h", 48 * time.Hour, false},
{"168h", 7 * day, false},
{"36h", 36 * time.Hour, false},
{"12h", 12 * time.Hour, false},
{"36H", 36 * time.Hour, false},
{"90m", 90 * time.Minute, false},
{"1h30m", 90 * time.Minute, false},
// Refusals.
{"", 0, true},
{"0", 0, true},
{"-1", 0, true},
{"0d", 0, true},
{"0h", 0, true},
{"-36h", 0, true},
{"abc", 0, true},
{"7x", 0, true},
{"d", 0, true},
// Out of range must be refused, never wrapped: 213504d used to
// overflow to 25m26s and select almost every closed row.
{"213504d", 0, true},
{"213504", 0, true},
{"30501w", 0, true},
{"106752d", 0, true},
{"9223372036854775807d", 0, true},
{"99999999999h", 0, true},
// The largest representable day count still parses.
{"106751d", 106751 * day, false},
}
for _, tt := range tests {
t.Run(tt.input, func(t *testing.T) {
got, err := parseHumanDuration(tt.input)
got, err := parseOlderThan(tt.input)
if (err != nil) != tt.wantErr {
t.Errorf("parseHumanDuration(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
return
t.Fatalf("parseOlderThan(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
}
if got != tt.want {
t.Errorf("parseHumanDuration(%q) = %d, want %d", tt.input, got, tt.want)
t.Errorf("parseOlderThan(%q) = %s, want %s", tt.input, got, tt.want)
}
})
}

View file

@ -0,0 +1,207 @@
//go:build cgo
package main
import (
"encoding/json"
"os"
"os/exec"
"strings"
"testing"
"time"
)
// purgeScenarioRunner drives one storage mode for the purge retention
// scenario. run never fatals: several steps assert a refusal.
type purgeScenarioRunner struct {
mode string
run func(t *testing.T, args ...string) (stdout, stderr string, err error)
}
func (r purgeScenarioRunner) must(t *testing.T, args ...string) string {
t.Helper()
stdout, stderr, err := r.run(t, args...)
if err != nil {
t.Fatalf("%s: bd %s failed: %v\nstdout:\n%s\nstderr:\n%s",
r.mode, strings.Join(args, " "), err, stdout, stderr)
}
return stdout
}
func (r purgeScenarioRunner) create(t *testing.T, title string, args ...string) string {
t.Helper()
id := strings.TrimSpace(r.must(t, append([]string{"create", title, "--silent"}, args...)...))
if id == "" {
t.Fatalf("%s: bd create %q printed no id", r.mode, title)
}
return id
}
func (r purgeScenarioRunner) exists(t *testing.T, id string) bool {
t.Helper()
_, _, err := r.run(t, "show", id)
return err == nil
}
// purgeJSON runs a purge that must succeed and decodes its --json object.
func (r purgeScenarioRunner) purgeJSON(t *testing.T, args ...string) map[string]any {
t.Helper()
out := r.must(t, append(append([]string{"purge"}, args...), "--json")...)
start := strings.Index(out, "{")
if start < 0 {
t.Fatalf("%s: bd purge %s --json printed no object:\n%s", r.mode, strings.Join(args, " "), out)
}
var result map[string]any
if err := json.Unmarshal([]byte(out[start:]), &result); err != nil {
t.Fatalf("%s: parse purge JSON: %v\n%s", r.mode, err, out)
}
return result
}
func jsonCount(result map[string]any, key string) int {
n, _ := result[key].(float64)
return int(n)
}
// runPurgeRetentionScenario is the retention sweep an orchestrator runs over
// the wisps plane — `bd purge --wisps-plane --older-than <age> --force` — and
// the three things it has to get right:
//
// - the wisps PLANE is the selection, so a closed --no-history bead goes
// with the closed ephemeral wisp while a closed durable bead stays;
// - a closed wisp a live wisp depends on (parent-child, tracks) is kept and
// counted, on the default purge as much as the plane one;
// - --older-than has sub-day precision: rows closed seconds ago are swept
// by "1s" and kept by "36h" (which used to be floored to 24h), and an
// out-of-range value is refused rather than wrapped;
// - --limit drains a backlog in bounded runs, reporting remaining/has_more.
func runPurgeRetentionScenario(t *testing.T, r purgeScenarioRunner) {
t.Helper()
wisp := r.create(t, "closed wisp", "--ephemeral")
noHistory := r.create(t, "closed no-history bead", "--no-history")
durable := r.create(t, "closed durable bead")
parent := r.create(t, "closed molecule root", "--ephemeral")
child := r.create(t, "open step", "--ephemeral")
r.must(t, "dep", "add", child, parent, "--type", "parent-child")
tracked := r.create(t, "closed tracked wisp", "--ephemeral")
convoy := r.create(t, "live convoy", "--ephemeral")
r.must(t, "dep", "add", convoy, tracked, "--type", "tracks")
r.must(t, "update", convoy, "--status", "in_progress")
r.must(t, "close", wisp, noHistory, durable, tracked)
r.must(t, "close", parent, "--force")
// Everything above closed within the last few seconds. closed_at is
// stored at second precision, so wait comfortably past one second before
// asking "--older-than 1s" for it.
time.Sleep(2500 * time.Millisecond)
// The plane selector reaches durable-tier rows, so it takes the durable
// tier's require-a-filter gate.
if stdout, stderr, err := r.run(t, "purge", "--wisps-plane", "--force"); err == nil ||
!strings.Contains(stdout+stderr, "requires --older-than or --pattern") {
t.Fatalf("%s: unfiltered purge --wisps-plane: err=%v\n%s%s", r.mode, err, stdout, stderr)
}
// Hour precision: nothing here is 36 hours old.
if got := r.purgeJSON(t, "--wisps-plane", "--older-than", "36h", "--dry-run"); jsonCount(got, "purge_count") != 0 {
t.Fatalf("%s: --older-than 36h selected rows closed seconds ago: %v", r.mode, got)
}
preview := r.purgeJSON(t, "--wisps-plane", "--older-than", "1s", "--dry-run")
if jsonCount(preview, "purge_count") != 2 || jsonCount(preview, "live_dependent_skipped") != 2 {
t.Fatalf("%s: dry run = %v; want purge_count 2 (wisp + no-history) and live_dependent_skipped 2 (root + tracked)",
r.mode, preview)
}
// --limit drains in bounded runs and says whether more remain.
first := r.purgeJSON(t, "--wisps-plane", "--older-than", "1s", "--limit", "1", "--force")
if jsonCount(first, "purged_count") != 1 || jsonCount(first, "remaining") != 1 || first["has_more"] != true {
t.Fatalf("%s: purge --limit 1 = %v; want purged_count 1, remaining 1, has_more true", r.mode, first)
}
result := r.purgeJSON(t, "--wisps-plane", "--older-than", "1s", "--limit", "1", "--force")
if jsonCount(result, "purged_count") != 1 || jsonCount(result, "live_dependent_skipped") != 2 ||
jsonCount(result, "remaining") != 0 || result["has_more"] != false {
t.Fatalf("%s: second purge --limit 1 = %v; want purged_count 1, live_dependent_skipped 2, remaining 0, has_more false",
r.mode, result)
}
if stdout, stderr, err := r.run(t, "purge", "--limit", "-1", "--force"); err == nil {
t.Fatalf("%s: purge --limit -1 succeeded:\n%s%s", r.mode, stdout, stderr)
}
if stdout, stderr, err := r.run(t, "purge", "--older-than", "213504d", "--force"); err == nil ||
!strings.Contains(stdout+stderr, "out of range") {
t.Fatalf("%s: purge --older-than 213504d must refuse as out of range: err=%v\n%s%s", r.mode, err, stdout, stderr)
}
for id, want := range map[string]bool{
wisp: false, noHistory: false,
parent: true, child: true, tracked: true, convoy: true, durable: true,
} {
if got := r.exists(t, id); got != want {
t.Errorf("%s: after purge --wisps-plane, %s exists = %v, want %v", r.mode, id, got, want)
}
}
// The default (ephemeral-tier) purge protects live dependents too, and
// still leaves no-history beads alone.
root2 := r.create(t, "second closed root", "--ephemeral")
step2 := r.create(t, "second open step", "--ephemeral")
r.must(t, "dep", "add", step2, root2, "--type", "parent-child")
r.must(t, "close", root2, "--force")
noHistory2 := r.create(t, "second no-history bead", "--no-history")
r.must(t, "close", noHistory2)
plain := r.purgeJSON(t, "--force")
if jsonCount(plain, "live_dependent_skipped") < 1 {
t.Errorf("%s: default purge reported no live-dependent skip: %v", r.mode, plain)
}
if !r.exists(t, root2) {
t.Errorf("%s: default purge deleted %s, whose step %s is still open", r.mode, root2, step2)
}
if !r.exists(t, noHistory2) {
t.Errorf("%s: default purge deleted no-history bead %s; only --wisps-plane selects it", r.mode, noHistory2)
}
}
func embeddedPurgeScenarioRunner(bd, dir string) purgeScenarioRunner {
return purgeScenarioRunner{
mode: "embedded",
run: func(t *testing.T, args ...string) (string, string, error) {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
cmd.Env = bdEnv(dir)
stdout, stderr, err := runCommandBuffers(t, cmd)
return stdout.String(), stderr.String(), err
},
}
}
func proxiedPurgeScenarioRunner(bd string, p proxiedProject) purgeScenarioRunner {
return purgeScenarioRunner{
mode: "proxied",
run: func(t *testing.T, args ...string) (string, string, error) {
t.Helper()
return bdProxiedRunBuffers(t, bd, p.dir, args...)
},
}
}
func TestEmbeddedPurgeWispsPlaneRetention(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "pwp")
runPurgeRetentionScenario(t, embeddedPurgeScenarioRunner(bd, dir))
}
func TestProxiedServerPurgeWispsPlaneRetention(t *testing.T) {
requireSharedProxiedServer(t)
t.Parallel()
bd := buildEmbeddedBD(t)
p := newSharedProxiedProject(t, bd, "pwx")
runPurgeRetentionScenario(t, proxiedPurgeScenarioRunner(bd, p))
}

View file

@ -0,0 +1,19 @@
//go:build cgo && unix
package main
import (
"testing"
"time"
)
// TestManagedLocalProxiedPurgeWispsPlaneRetention runs the purge retention
// scenario on the managed-local proxied topology, the default for a proxied
// workspace bd starts the Dolt server for. Named TestManagedLocalProxied* so
// the proxied-local smoke lane runs it.
func TestManagedLocalProxiedPurgeWispsPlaneRetention(t *testing.T) {
requireManagedLocalProxiedEnv(t)
bd := buildEmbeddedBD(t)
p := bdManagedLocalInit(t, bd, "pwl", 5*time.Minute)
runPurgeRetentionScenario(t, proxiedPurgeScenarioRunner(bd, p))
}

View file

@ -68,26 +68,6 @@ func TestEffectiveRootStorePolicy(t *testing.T) {
}
}
func TestStrictReadonlyBackendSupport(t *testing.T) {
tests := []struct {
name string
cfg *configfile.Config
want bool
}{
{name: "fresh embedded default", cfg: nil, want: true},
{name: "dolt server", cfg: &configfile.Config{Backend: configfile.BackendDolt, DoltMode: configfile.DoltModeServer}, want: true},
{name: "proxied server", cfg: &configfile.Config{Backend: configfile.BackendDolt, DoltMode: configfile.DoltModeProxiedServer}, want: false},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
if got := backendSupportsStrictReadonly(tc.cfg); got != tc.want {
t.Fatalf("backendSupportsStrictReadonly() = %v, want %v", got, tc.want)
}
})
}
}
type strictReadonlyPostRunStore struct {
storage.DoltStorage
metadataWrites int

View file

@ -603,7 +603,7 @@ func serveDatabaseSource(beadsDir string) (serveDatabase, error) {
// the server, which no client can discover before connecting. bd already
// answers this question the same way one layer down, where a backend that
// cannot guarantee mutation-free access is turned away rather than opened
// anyway (backendSupportsStrictReadonly, cmd/bd/main.go).
// anyway (the proxy.readonly.unsupported refusal in cmd/bd/main.go).
//
// The value is read from the global rather than a flag lookup because
// `readonly` is also a config key, and PersistentPreRunE has already folded

View file

@ -70,9 +70,7 @@ func newRegisteredBackendStore(ctx context.Context, name, beadsDir string, readO
func newDoltStore(ctx context.Context, cfg *dolt.Config) (s storage.DoltStorage, err error) {
defer func() { s, err = activateEventsJournalStore(cfg.BeadsDir, s, err) }()
if cfg.ProxiedServer {
// TODO: this should not be a store
// it should be a uow provider
return nil, fmt.Errorf("proxy server store should be uow provider")
return nil, errProxiedStoreUnrouted()
}
if cfg.ServerMode {
return dolt.New(ctx, cfg)
@ -172,13 +170,7 @@ func newDoltStoreFromConfig(ctx context.Context, beadsDir string) (s storage.Dol
return backend.Open(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store should be uow provider")
// return newProxiedServerStore(ctx, &dolt.Config{
// BeadsDir: beadsDir,
// Database: cfg.GetDoltDatabase(),
// ProxiedServer: true,
// })
return nil, errProxiedStoreUnrouted()
}
if cfg != nil && cfg.IsDoltServerMode() {
return dolt.NewFromConfig(ctx, beadsDir)
@ -280,14 +272,7 @@ func openNonMutatingStoreFromConfig(ctx context.Context, beadsDir string, previe
return backend.OpenReadOnly(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store needs to be uow provider")
// return newProxiedServerStore(ctx, &dolt.Config{
// BeadsDir: beadsDir,
// Database: cfg.GetDoltDatabase(),
// ProxiedServer: true,
// ReadOnly: true,
// })
return nil, errProxiedStoreUnrouted()
}
if cfg != nil && cfg.IsDoltServerMode() {
return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{ReadOnly: true})

View file

@ -50,9 +50,7 @@ func newRegisteredBackendStore(ctx context.Context, name, beadsDir string, readO
func newDoltStore(ctx context.Context, cfg *dolt.Config) (s storage.DoltStorage, err error) {
defer func() { s, err = activateEventsJournalStore(cfg.BeadsDir, s, err) }()
if cfg.ProxiedServer {
// TODO: this should not be a store
// it should be a uow provider
return nil, fmt.Errorf("proxy server store should be uow provider")
return nil, errProxiedStoreUnrouted()
}
if !cfg.ServerMode {
return nil, fmt.Errorf("%s", nocgoEmbeddedErrMsg)
@ -83,13 +81,7 @@ func newDoltStoreFromConfig(ctx context.Context, beadsDir string) (s storage.Dol
return backend.Open(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store should be uow provider")
// return newProxiedServerStore(ctx, &dolt.Config{
// BeadsDir: beadsDir,
// Database: cfg.GetDoltDatabase(),
// ProxiedServer: true,
// })
return nil, errProxiedStoreUnrouted()
}
if cfg != nil && cfg.IsDoltServerMode() {
return dolt.NewFromConfig(ctx, beadsDir)
@ -114,14 +106,7 @@ func newReadOnlyStoreFromConfig(ctx context.Context, beadsDir string) (storage.D
return backend.OpenReadOnly(ctx, beadsDir)
}
if cfg != nil && cfg.IsDoltProxiedServerMode() {
// TODO: this needs to be uow provider
return nil, fmt.Errorf("proxy server store needs to be uow provider")
// return newProxiedServerStore(ctx, &dolt.Config{
// BeadsDir: beadsDir,
// Database: cfg.GetDoltDatabase(),
// ProxiedServer: true,
// ReadOnly: true,
// })
return nil, errProxiedStoreUnrouted()
}
if cfg != nil && cfg.IsDoltServerMode() {
return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{ReadOnly: true})

View file

@ -274,10 +274,16 @@ var capabilityProbes = []probe{
direct: expectation{
outcome: outcomeHonored, substr: `"configured"`, reason: reasonNA,
},
// Refused by design where bd does not own the server (#6584): the
// backup remote is registered on the server, global to every client.
proxied: expectation{
outcome: outcomeRefusedTyped, code: "proxy.backup.unsupported",
substr: "backup status is not supported in proxied-server mode",
reason: reasonUnimplemented,
reason: reasonDesign,
},
// Honored on managed-local, where bd spawned the Dolt child (#6584).
override: map[string]expectation{
topoProxiedLocal: {outcome: outcomeHonored, substr: `"configured"`, reason: reasonNA},
},
},
{
@ -289,7 +295,13 @@ var capabilityProbes = []probe{
proxied: expectation{
outcome: outcomeRefusedTyped, code: "proxy.backup.unsupported",
substr: "backup sync is not supported in proxied-server mode",
reason: reasonUnimplemented,
reason: reasonDesign,
},
// Honored on managed-local (#6584): it reaches the command, which
// fails on its own merits with no destination configured — the same
// answer every direct topology gives.
override: map[string]expectation{
topoProxiedLocal: {outcome: outcomeError, substr: "no backup destination configured", reason: reasonNA},
},
},
@ -464,7 +476,7 @@ var deliberatelyNotProbed = map[string]string{
"restore": "`bd restore` restores an ISSUE, not a backup; the backup verb is `bd backup restore`, which is already " +
"covered by the backup rows. Probing it adds a row that says nothing about the backup family.",
"backup restore": "would need a real backup destination to distinguish a topology refusal from a missing-backup error. " +
"Covered indirectly by `backup status` / `backup sync`; revisit in slice S3 when the family gains a proxied route.",
"Covered indirectly by `backup status` / `backup sync`, and directly by TestManagedLocalProxiedBackupRoundTrip since slice S3 (#6584).",
}
// ---------------------------------------------------------------------------

View file

@ -1,90 +0,0 @@
package main
import (
"sort"
"strings"
"github.com/spf13/cobra"
"github.com/spf13/pflag"
)
type TransformCapability struct {
Path string
Argument string
Outcome ProxyCapabilityOutcome
Code string
Message string
ExitCode int
Mutates bool
}
var transformCapabilityRows = []TransformCapability{
transformRefused("rename"),
transformRefused("rename-prefix"),
transformRefusedWithArgs("rename-prefix", "--dry-run"),
transformRefusedWithArgs("rename-prefix", "--repair"),
transformRefusedWithArgs("rename-prefix", "--dry-run --repair"),
transformRefused("duplicate"),
transformRefusedWithArgs("duplicate", "--of"),
transformRefused("supersede"),
transformRefusedWithArgs("supersede", "--with"),
{Path: "duplicates", Outcome: ProxyOutcomeHonored},
transformRefusedWithArgs("duplicates", "--auto-merge"),
{Path: "duplicates", Argument: "--auto-merge --dry-run", Outcome: ProxyOutcomeHonored},
}
func transformRefused(path string) TransformCapability {
return transformRefusedWithArgs(path, "")
}
func transformRefusedWithArgs(path, argument string) TransformCapability {
displayPath := path
if argument != "" {
displayPath += " " + argument
}
return TransformCapability{
Path: path, Argument: argument, Outcome: ProxyOutcomeRefused,
Code: "proxy.transform.unsupported", Message: displayPath + " is not supported in proxied-server mode", ExitCode: 1,
}
}
func transformCapabilityError(row TransformCapability) *ProxyCapabilityError {
return &ProxyCapabilityError{Code: row.Code, Message: row.Message, ExitCode: row.ExitCode, Mutates: row.Mutates}
}
func lookupTransformCapability(cmd *cobra.Command) (TransformCapability, bool) {
path := cmd.CommandPath()
path = strings.TrimSpace(strings.TrimPrefix(path, cmd.Root().Name()))
var args []string
cmd.Flags().Visit(func(f *pflag.Flag) {
if transformPolicyFlags[f.Name] {
args = append(args, "--"+f.Name)
}
})
sort.Strings(args)
arg := strings.Join(args, " ")
for _, row := range transformCapabilityRows {
if row.Path == path && row.Argument == arg {
return row, true
}
}
return TransformCapability{}, false
}
// Only flags that alter a transform's execution belong in the capability key.
// Output, tracing, and other inherited root flags must not bypass a refusal.
var transformPolicyFlags = map[string]bool{
"auto-merge": true, "dry-run": true, "repair": true, "of": true, "with": true,
}
func validateProxyTransformBeforeProvider(cmd *cobra.Command) error {
if cmd == nil {
return nil
}
if row, ok := lookupTransformCapability(cmd); ok {
if row.Outcome == ProxyOutcomeRefused {
return HandleProxyCapabilityError(transformCapabilityError(row))
}
}
return nil
}

View file

@ -171,11 +171,24 @@ func newProxiedServerUOWProvider(ctx context.Context, beadsDir, databaseOverride
return openProxiedServerUOWProvider(ctx, beadsDir, databaseOverride, assertWorkspaceIdentity, opts...)
}
// newProxiedServerUOWProviderAdopting skips that assertion. Only two callers
// legitimately have no workspace identity to assert: `bd init --team-server`,
// which ADOPTS the identity the shared database already carries (asserting the
// locally-minted placeholder would reject every correct init), and server-wide
// database maintenance, which is not scoped to one project's database.
// newProxiedServerUOWProviderAdopting skips that assertion. Three callers
// legitimately have no workspace identity to assert:
//
// - `bd init --team-server`, which ADOPTS the identity the shared database
// already carries (asserting the locally-minted placeholder would reject
// every correct init);
// - server-wide database maintenance, which is not scoped to one project's
// database;
// - withQuiescedProxiedProvider (backup_proxied_server.go), the post-restore
// reopen. A restore is precisely the operation after which the workspace's
// recorded project id and the database's may legitimately differ, and it is
// the connection whose job is to reconcile them — asserting the pre-restore
// identity would refuse the one open that can fix the mismatch. The full
// reasoning is at that function's doc comment.
//
// Anything else reaching this constructor is bypassing an identity assertion
// that exists to stop a workspace writing into another project's database. Add
// a fourth entry here, with its reason, or use newProxiedServerUOWProvider.
func newProxiedServerUOWProviderAdopting(ctx context.Context, beadsDir, databaseOverride string, opts ...uow.ProviderOption) (uow.UnitOfWorkProvider, error) {
return openProxiedServerUOWProvider(ctx, beadsDir, databaseOverride, adoptWorkspaceIdentity, opts...)
}

View file

@ -35,6 +35,21 @@ func TestSweeperContract(t *testing.T) {
t.Run("TreatsALegacyTypedWispAsEphemeralTier", func(t *testing.T) {
conformance.RunSweeperTreatsALegacyTypedWispAsEphemeralTier(t, ctx, fixture)
})
t.Run("WispsPlaneClearsTheWholeWispsTable", func(t *testing.T) {
conformance.RunSweeperWispsPlaneClearsTheWholeWispsTable(t, ctx, fixture)
})
t.Run("WispsPlaneRequiresAFilter", func(t *testing.T) {
conformance.RunSweeperWispsPlaneRequiresAFilter(t, ctx, fixture)
})
t.Run("ProtectsLiveDependents", func(t *testing.T) {
conformance.RunSweeperProtectsLiveDependents(t, ctx, fixture)
})
t.Run("ProtectsLiveDependentsAcrossPlanes", func(t *testing.T) {
conformance.RunSweeperProtectsLiveDependentsAcrossPlanes(t, ctx, fixture)
})
t.Run("LimitTakesTheOldestClosedFirst", func(t *testing.T) {
conformance.RunSweeperLimitTakesTheOldestClosedFirst(t, ctx, fixture)
})
t.Run("LeavesNoHistoryBeadsToTheDurableTier", func(t *testing.T) {
conformance.RunSweeperLeavesNoHistoryBeadsToTheDurableTier(t, ctx, fixture)
})
@ -98,6 +113,16 @@ func newDoltSweeperFixture(t *testing.T, prefix string) (conformance.SweeperFixt
}
return nil
},
AddDependencies: func(ctx context.Context, req issueops.AddDependenciesRequest) error {
// Through the DependencyEditor ROLE, which routes each edge to its
// source plane's dependency table itself.
editor, err := store.DependencyEditor()
if err != nil {
return err
}
_, err = editor.AddDependencies(ctx, req)
return err
},
AddComment: func(ctx context.Context, issueID, author, text string) error {
// Through the Commenter ROLE, which resolves the plane itself, so
// the case can cite from a wisp's comment without knowing how this

View file

@ -933,6 +933,13 @@ func (r *issueSQLRepositoryImpl) SearchAcrossIssuesAndWispsWithCounts(ctx contex
return r.searchAcrossIssuesAndWispsWithCounts(ctx, query, filter)
}
// SearchWispsPlane runs the shared wisps-plane search body on this
// repository's transaction, so the unit-of-work provider and the two store
// backends read the plane through one function.
func (r *issueSQLRepositoryImpl) SearchWispsPlane(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error) {
return issueops.SearchWispsPlaneInTx(ctx, r.runner, query, filter)
}
func (r *issueSQLRepositoryImpl) SearchIssueIDs(ctx context.Context, query string, filter types.IssueFilter) ([]string, error) {
return issueops.SearchIssueIDsInTx(ctx, r.runner, query, filter)
}

View file

@ -72,6 +72,10 @@ type IssueSQLRepository interface {
SearchAcrossIssuesAndWisps(ctx context.Context, query string, filter types.IssueFilter) (SearchPage, error)
SearchAcrossIssuesAndWispsWithCounts(ctx context.Context, query string, filter types.IssueFilter) (SearchCountsPage, error)
SearchIssueIDs(ctx context.Context, query string, filter types.IssueFilter) ([]string, error)
// SearchWispsPlane searches the wisps table ALONE, whatever each row's
// ephemeral, no_history or wisp_type values, and never the issues table
// (issueops.SearchWispsPlaneInTx).
SearchWispsPlane(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error)
GetReadyWork(ctx context.Context, filter types.WorkFilter) (SearchPage, error)
GetReadyWorkWithCounts(ctx context.Context, filter types.WorkFilter) (SearchCountsPage, error)
GetDescendants(ctx context.Context, rootID string, filter types.IssueFilter) ([]*types.Issue, error)
@ -308,6 +312,10 @@ type IssueUseCase interface {
SearchIssues(ctx context.Context, query string, filter types.IssueFilter) (SearchPage, error)
SearchIssuesWithCounts(ctx context.Context, query string, filter types.IssueFilter) (SearchCountsPage, error)
SearchIssueIDs(ctx context.Context, query string, filter types.IssueFilter) ([]string, error)
// SearchWispsPlane searches the wisps table ALONE, whatever each row's
// ephemeral, no_history or wisp_type values, and never the issues table
// (issueops.SearchWispsPlaneInTx).
SearchWispsPlane(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error)
GetReadyWork(ctx context.Context, filter types.WorkFilter) (SearchPage, error)
GetReadyWorkWithCounts(ctx context.Context, filter types.WorkFilter) (SearchCountsPage, error)
GetDescendants(ctx context.Context, rootID string, filter types.IssueFilter) ([]*types.Issue, error)
@ -843,6 +851,14 @@ func (u *issueUseCaseImpl) SearchIssues(ctx context.Context, query string, filte
return out, nil
}
func (u *issueUseCaseImpl) SearchWispsPlane(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error) {
out, err := u.issueRepo.SearchWispsPlane(ctx, query, filter)
if err != nil {
return nil, fmt.Errorf("SearchWispsPlane: %w", err)
}
return out, nil
}
func (u *issueUseCaseImpl) SearchIssueIDs(ctx context.Context, query string, filter types.IssueFilter) ([]string, error) {
out, err := u.issueRepo.SearchIssueIDs(ctx, query, filter)
if err != nil {

View file

@ -40,6 +40,21 @@ func TestSweeperContract(t *testing.T) {
t.Run("TreatsALegacyTypedWispAsEphemeralTier", func(t *testing.T) {
conformance.RunSweeperTreatsALegacyTypedWispAsEphemeralTier(t, ctx, fixture)
})
t.Run("WispsPlaneClearsTheWholeWispsTable", func(t *testing.T) {
conformance.RunSweeperWispsPlaneClearsTheWholeWispsTable(t, ctx, fixture)
})
t.Run("WispsPlaneRequiresAFilter", func(t *testing.T) {
conformance.RunSweeperWispsPlaneRequiresAFilter(t, ctx, fixture)
})
t.Run("ProtectsLiveDependents", func(t *testing.T) {
conformance.RunSweeperProtectsLiveDependents(t, ctx, fixture)
})
t.Run("ProtectsLiveDependentsAcrossPlanes", func(t *testing.T) {
conformance.RunSweeperProtectsLiveDependentsAcrossPlanes(t, ctx, fixture)
})
t.Run("LimitTakesTheOldestClosedFirst", func(t *testing.T) {
conformance.RunSweeperLimitTakesTheOldestClosedFirst(t, ctx, fixture)
})
t.Run("LeavesNoHistoryBeadsToTheDurableTier", func(t *testing.T) {
conformance.RunSweeperLeavesNoHistoryBeadsToTheDurableTier(t, ctx, fixture)
})
@ -99,6 +114,16 @@ func newEmbeddedSweeperFixture(t *testing.T, te *testEnv, prefix string) conform
}
return nil
},
AddDependencies: func(ctx context.Context, req issueops.AddDependenciesRequest) error {
// Through the DependencyEditor ROLE, which routes each edge to its
// source plane's dependency table itself.
editor, err := te.store.DependencyEditor()
if err != nil {
return err
}
_, err = editor.AddDependencies(ctx, req)
return err
},
AddComment: func(ctx context.Context, issueID, author, text string) error {
// Through the Commenter ROLE, which resolves the plane itself, so
// the case can cite from a wisp's comment without knowing how this

View file

@ -32,6 +32,35 @@ func SearchIssueIDsInTx(ctx context.Context, tx DBTX, query string, filter types
return searchInTx(ctx, tx, query, filter, idProjection)
}
// SearchWispsPlaneInTx searches the wisps plane ALONE: every row stored in
// the wisps table, whatever its ephemeral, no_history or wisp_type values, and
// never the issues table.
//
// It is not SearchIssuesInTx with Ephemeral=true. That filter adds an
// "ephemeral = 1" clause, which drops the no-history rows stored beside the
// wisps, and it falls back to the issues table when the wisps plane is empty.
// This answers "what is in the wisps table" — the unit
// issueops.SweepWispsPlane selects by — and a database with no wisps table
// answers with nothing.
func SearchWispsPlaneInTx(ctx context.Context, tx DBTX, query string, filter types.IssueFilter) ([]*types.Issue, error) {
proj := issueProjection
if filter.Lite {
proj = issueLiteProjection
}
results, err := searchTableInTxT(ctx, tx, query, filter, WispsFilterTables, proj)
if err != nil {
if missingOptionalWispTable(err) {
return nil, nil
}
return nil, fmt.Errorf("search wisps plane: %w", err)
}
results = trimToSearchLimit(results, filter.Limit)
if err := EnforceMaxRowsCap(len(results), filter.MaxRows, filter.MaxRowsSource); err != nil {
return nil, err
}
return results, nil
}
// searchProjection describes how to project, scan, and dedup search results.
// Adding a narrow-projection variant means adding a new projection literal —
// not a parallel top-level function or wisp-merge wrapper, which is how the

View file

@ -31,7 +31,11 @@ import (
func SweepInTx(ctx context.Context, tx *sql.Tx, req publicops.SweepRequest) (publicops.SweepResult, error) {
result := publicops.SweepResult{DryRun: req.DryRun}
candidates, err := SearchIssuesInTx(ctx, tx, "", workapi.BuildSweepCandidateFilter(req))
search := SearchIssuesInTx
if workapi.SweepSearchesWispsPlaneOnly(req) {
search = SearchWispsPlaneInTx
}
candidates, err := search(ctx, tx, "", workapi.BuildSweepCandidateFilter(req))
if err != nil {
return publicops.SweepResult{}, fmt.Errorf("listing sweep candidates: %w", err)
}
@ -39,6 +43,14 @@ func SweepInTx(ctx context.Context, tx *sql.Tx, req publicops.SweepRequest) (pub
kept, skips := workapi.FilterSweepCandidates(candidates, req.IDPattern, req.ClosedBefore)
result.Skipped = skips
if req.ProtectLiveDependents {
protected, err := sweepLiveDependentsInTx(ctx, tx, kept)
if err != nil {
return publicops.SweepResult{}, err
}
kept, result.Skipped.LiveDependent = workapi.PartitionSweepLiveDependents(kept, protected)
}
if req.ProtectReferenced {
referenced, err := sweepReferencedInTx(ctx, tx, kept)
if err != nil {
@ -49,6 +61,8 @@ func SweepInTx(ctx context.Context, tx *sql.Tx, req publicops.SweepRequest) (pub
result.Skipped.Referenced = count
}
kept, result.Remaining = workapi.LimitSweepCandidates(kept, req.Limit)
if len(kept) == 0 {
return result, nil
}
@ -73,6 +87,46 @@ func SweepInTx(ctx context.Context, tx *sql.Tx, req publicops.SweepRequest) (pub
return result, nil
}
// sweepLiveDependentsInTx returns which of the candidates a live row depends
// on through a protecting edge (issueops.SweepRequest.ProtectLiveDependents),
// on the SAME transaction the candidates came off. Edges are read from both
// dependency tables, and the sources' statuses from both planes.
//
// Reading the custom statuses is required for the reason sweepReferencedInTx
// gives: a missed custom active status would under-protect.
func sweepLiveDependentsInTx(ctx context.Context, tx *sql.Tx, candidates []*types.Issue) (map[string]bool, error) {
if len(candidates) == 0 {
return nil, nil
}
ids := make([]string, len(candidates))
for i, issue := range candidates {
ids[i] = issue.ID
}
incoming, err := GetDependentRecordsForIssuesInTx(ctx, tx, ids)
if err != nil {
return nil, fmt.Errorf("reading dependents for live-dependent protection: %w", err)
}
sources := workapi.SweepLiveDependentSources(incoming)
if len(sources) == 0 {
return nil, nil
}
custom, err := ResolveCustomStatusesDetailedInTx(ctx, tx)
if err != nil {
return nil, fmt.Errorf("reading custom statuses for live-dependent protection: %w", err)
}
liveRows, err := SearchIssuesInTx(ctx, tx, "", workapi.BuildSweepLiveDependentScanFilter(sources, custom))
if err != nil {
return nil, fmt.Errorf("reading dependent statuses for live-dependent protection: %w", err)
}
live := make(map[string]bool, len(liveRows))
for _, issue := range liveRows {
if issue != nil {
live[issue.ID] = true
}
}
return workapi.SweepLiveDependentTargets(incoming, live), nil
}
// sweepReferencedInTx returns which of the candidates are cited by a row that
// is not done, reading the not-done set and its comments on the SAME
// transaction the candidates came off.

View file

@ -159,6 +159,7 @@ func TestRecordingIssueUseCaseCoversItsSurface(t *testing.T) {
"PreviewDeleteWisp": reads,
"SearchIssueIDs": reads,
"SearchIssues": reads,
"SearchWispsPlane": reads,
"SearchIssuesWithCounts": reads,
"DeleteIssue": deletes,
"DeleteIssues": deletes,

View file

@ -4,6 +4,7 @@ import (
"context"
"fmt"
"github.com/steveyegge/beads/internal/storage/dberrors"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/workapi"
@ -76,14 +77,22 @@ func (s *sweeper) Sweep(ctx context.Context, req publicops.SweepRequest) (public
func sweepInUOW(ctx context.Context, uw UnitOfWork, req publicops.SweepRequest) (publicops.SweepResult, error) {
result := publicops.SweepResult{DryRun: req.DryRun}
page, err := uw.IssueUseCase().SearchIssues(ctx, "", workapi.BuildSweepCandidateFilter(req))
candidates, err := sweepCandidatesInUOW(ctx, uw, req)
if err != nil {
return publicops.SweepResult{}, fmt.Errorf("listing sweep candidates: %w", err)
}
kept, skips := workapi.FilterSweepCandidates(page.Items, req.IDPattern, req.ClosedBefore)
kept, skips := workapi.FilterSweepCandidates(candidates, req.IDPattern, req.ClosedBefore)
result.Skipped = skips
if req.ProtectLiveDependents {
protected, err := sweepLiveDependentsInUOW(ctx, uw, kept)
if err != nil {
return publicops.SweepResult{}, err
}
kept, result.Skipped.LiveDependent = workapi.PartitionSweepLiveDependents(kept, protected)
}
if req.ProtectReferenced {
referenced, err := sweepReferencedInUOW(ctx, uw, kept)
if err != nil {
@ -94,6 +103,8 @@ func sweepInUOW(ctx context.Context, uw UnitOfWork, req publicops.SweepRequest)
result.Skipped.Referenced = count
}
kept, result.Remaining = workapi.LimitSweepCandidates(kept, req.Limit)
if len(kept) == 0 {
return result, nil
}
@ -116,6 +127,73 @@ func sweepInUOW(ctx context.Context, uw UnitOfWork, req publicops.SweepRequest)
return result, nil
}
// sweepCandidatesInUOW reads the request's candidate rows: the wisps table
// alone for the wisps-plane tier, a tier query across both planes otherwise.
func sweepCandidatesInUOW(ctx context.Context, uw UnitOfWork, req publicops.SweepRequest) ([]*types.Issue, error) {
filter := workapi.BuildSweepCandidateFilter(req)
if workapi.SweepSearchesWispsPlaneOnly(req) {
return uw.IssueUseCase().SearchWispsPlane(ctx, "", filter)
}
page, err := uw.IssueUseCase().SearchIssues(ctx, "", filter)
if err != nil {
return nil, err
}
return page.Items, nil
}
// sweepLiveDependentsInUOW returns which of the candidates a live row depends
// on through a protecting edge, on the unit of work the candidates came off.
//
// Edges are read from BOTH dependency tables: a wisp's edges live in
// wisp_dependencies and an issue's in dependencies, and the source of an edge
// pointing at a candidate can be either. The sources' statuses are then read
// across both planes by SearchIssues.
func sweepLiveDependentsInUOW(ctx context.Context, uw UnitOfWork, candidates []*types.Issue) (map[string]bool, error) {
if len(candidates) == 0 {
return nil, nil
}
ids := make([]string, len(candidates))
for i, issue := range candidates {
ids[i] = issue.ID
}
edges := domain.DepListFilter{Types: publicops.SweepLiveDependentEdgeTypes, Direction: domain.DepDirectionIn}
durable, err := uw.DependencyUseCase().ListByIssueIDs(ctx, ids, edges)
if err != nil {
return nil, fmt.Errorf("reading dependents for live-dependent protection: %w", err)
}
wisp, err := uw.DependencyUseCase().ListByWispIDs(ctx, ids, edges)
if err != nil && !dberrors.IsTableNotExist(err) {
return nil, fmt.Errorf("reading wisp dependents for live-dependent protection: %w", err)
}
incoming := make(map[string][]*types.Dependency, len(durable.Incoming)+len(wisp.Incoming))
for target, deps := range durable.Incoming {
incoming[target] = append(incoming[target], deps...)
}
for target, deps := range wisp.Incoming {
incoming[target] = append(incoming[target], deps...)
}
sources := workapi.SweepLiveDependentSources(incoming)
if len(sources) == 0 {
return nil, nil
}
custom, err := uw.ConfigUseCase().GetCustomStatuses(ctx)
if err != nil {
return nil, fmt.Errorf("reading custom statuses for live-dependent protection: %w", err)
}
page, err := uw.IssueUseCase().SearchIssues(ctx, "", workapi.BuildSweepLiveDependentScanFilter(sources, custom))
if err != nil {
return nil, fmt.Errorf("reading dependent statuses for live-dependent protection: %w", err)
}
live := make(map[string]bool, len(page.Items))
for _, issue := range page.Items {
if issue != nil {
live[issue.ID] = true
}
}
return workapi.SweepLiveDependentTargets(incoming, live), nil
}
// sweepReferencedInUOW returns which of the candidates a not-done row cites,
// reading the not-done set and its comments on the same unit of work the
// candidates came off. Comments are read for the whole not-done set in ONE

View file

@ -35,6 +35,21 @@ func TestSweeperContract(t *testing.T) {
t.Run("TreatsALegacyTypedWispAsEphemeralTier", func(t *testing.T) {
conformance.RunSweeperTreatsALegacyTypedWispAsEphemeralTier(t, ctx, fixture)
})
t.Run("WispsPlaneClearsTheWholeWispsTable", func(t *testing.T) {
conformance.RunSweeperWispsPlaneClearsTheWholeWispsTable(t, ctx, fixture)
})
t.Run("WispsPlaneRequiresAFilter", func(t *testing.T) {
conformance.RunSweeperWispsPlaneRequiresAFilter(t, ctx, fixture)
})
t.Run("ProtectsLiveDependents", func(t *testing.T) {
conformance.RunSweeperProtectsLiveDependents(t, ctx, fixture)
})
t.Run("ProtectsLiveDependentsAcrossPlanes", func(t *testing.T) {
conformance.RunSweeperProtectsLiveDependentsAcrossPlanes(t, ctx, fixture)
})
t.Run("LimitTakesTheOldestClosedFirst", func(t *testing.T) {
conformance.RunSweeperLimitTakesTheOldestClosedFirst(t, ctx, fixture)
})
t.Run("LeavesNoHistoryBeadsToTheDurableTier", func(t *testing.T) {
conformance.RunSweeperLeavesNoHistoryBeadsToTheDurableTier(t, ctx, fixture)
})
@ -98,6 +113,20 @@ func newUOWSweeperFixture(t *testing.T, ctx context.Context, prefix string) conf
return "seed legacy sweep rows", nil
})
},
AddDependencies: func(ctx context.Context, req issueops.AddDependenciesRequest) error {
// Through the DependencyEditor ROLE, which routes each edge to its
// source plane's dependency table itself.
ds, ok := provider.(DependencyEditorSource)
if !ok {
return fmt.Errorf("provider %T does not offer the DependencyEditor accessor", provider)
}
editor, err := ds.DependencyEditor()
if err != nil {
return err
}
_, err = editor.AddDependencies(ctx, req)
return err
},
AddComment: func(ctx context.Context, issueID, author, text string) error {
// Through the Commenter ROLE, which resolves the plane itself, so
// the case can cite from a wisp's comment without knowing how this

View file

@ -48,7 +48,20 @@ func BackupRestore(ctx context.Context, db DBConn, url, dbName string, force boo
}
// DirToFileURL resolves dir to an absolute path and returns a file:// URL.
//
// An input that already carries a scheme is rejected rather than prefixed.
// filepath.Abs would happily turn "https://doltremoteapi.dolthub.com/u/r" into
// "file:///cwd/https:/doltremoteapi.dolthub.com/u/r" — a syntactically valid
// URL naming a local directory that does not exist, which DOLT_BACKUP would
// then fail on, or worse create. No caller can reach that today (`bd backup
// restore` os.Stats its argument first, so a URL never gets here), but every
// caller is a restore path and restore-from-a-remote is an open capability
// question — see backupRemoteSchemeTracking in cmd/bd/capability_registry.go.
// Whoever closes it should get an error here, not a mangled path.
func DirToFileURL(dir string) (string, error) {
if scheme, _, found := strings.Cut(dir, "://"); found {
return "", fmt.Errorf("%q is a %s URL, not a directory: this path takes a local directory to turn into a file:// URL", dir, scheme)
}
abs, err := filepath.Abs(dir)
if err != nil {
return "", fmt.Errorf("resolve absolute path: %w", err)

View file

@ -2,9 +2,38 @@ package versioncontrolops
import (
"fmt"
"strings"
"testing"
)
// TestDirToFileURLRejectsSchemes pins the guard that stops a URL being turned
// into a bogus local path. filepath.Abs treats "https://host/repo" as a
// relative path, so without the check this helper would hand DOLT_BACKUP
// "file:///cwd/https:/host/repo" and the failure would name a directory nobody
// asked for. No caller can reach it today — `bd backup restore` stats its
// argument first — but every caller is a restore path, and restore-from-a-remote
// is the open capability that would reach it.
func TestDirToFileURLRejectsSchemes(t *testing.T) {
for _, dir := range []string{
"https://doltremoteapi.dolthub.com/user/repo",
"file:///already/a/url",
"aws://bucket/key",
"gs://bucket/key",
} {
if got, err := DirToFileURL(dir); err == nil {
t.Errorf("DirToFileURL(%q) = %q, want an error naming the scheme", dir, got)
}
}
got, err := DirToFileURL("backups/nightly")
if err != nil {
t.Fatalf("DirToFileURL on a plain relative dir: %v", err)
}
if !strings.HasPrefix(got, "file://") || strings.Contains(got, "://backups") {
t.Fatalf("DirToFileURL(%q) = %q", "backups/nightly", got)
}
}
func TestExtractAddressConflictName(t *testing.T) {
tests := []struct {
name string

View file

@ -29,13 +29,13 @@ import (
// by calling the role. See issueops.SweepRequest.
func ValidateSweepRequest(in issueops.SweepRequest) error {
switch in.Tier {
case issueops.SweepEphemeral, issueops.SweepDurable:
case issueops.SweepEphemeral, issueops.SweepDurable, issueops.SweepWispsPlane:
case "":
return fmt.Errorf("%w: sweep requires a tier (%q or %q), and has no default",
issueops.ErrValidation, issueops.SweepEphemeral, issueops.SweepDurable)
return fmt.Errorf("%w: sweep requires a tier (%q, %q or %q), and has no default",
issueops.ErrValidation, issueops.SweepEphemeral, issueops.SweepDurable, issueops.SweepWispsPlane)
default:
return fmt.Errorf("%w: %q is not a sweep tier; use %q or %q",
issueops.ErrValidation, in.Tier, issueops.SweepEphemeral, issueops.SweepDurable)
return fmt.Errorf("%w: %q is not a sweep tier; use %q, %q or %q",
issueops.ErrValidation, in.Tier, issueops.SweepEphemeral, issueops.SweepDurable, issueops.SweepWispsPlane)
}
if in.IDPattern != "" {
// filepath.Match reports a malformed pattern on any subject, so one
@ -47,14 +47,32 @@ func ValidateSweepRequest(in issueops.SweepRequest) error {
issueops.ErrValidation, in.IDPattern, err)
}
}
if in.Tier == issueops.SweepDurable && in.ClosedBefore == nil && in.IDPattern == "" {
return fmt.Errorf("%w: a durable sweep requires a closed-before cutoff or an id pattern; "+
if in.Limit < 0 {
return fmt.Errorf("%w: sweep limit %d is negative; use 0 for no limit", issueops.ErrValidation, in.Limit)
}
if sweepRequiresFilter(in.Tier) && in.ClosedBefore == nil && in.IDPattern == "" {
return fmt.Errorf("%w: a %s sweep requires a closed-before cutoff or an id pattern; "+
"pass the pattern \"*\" to sweep every closed issue deliberately",
issueops.ErrValidation)
issueops.ErrValidation, in.Tier)
}
return nil
}
// sweepRequiresFilter reports whether a tier reaches durable-tier rows and so
// carries the require-a-filter gate. The wisps plane does: it holds no-history
// beads (issueops.SweepWispsPlane).
func sweepRequiresFilter(tier issueops.SweepTier) bool {
return tier == issueops.SweepDurable || tier == issueops.SweepWispsPlane
}
// SweepSearchesWispsPlaneOnly reports whether a request's candidates come from
// the wisps table alone (issueops.SweepWispsPlane) rather than from a tier
// query merged across both planes. Every Sweeper implementation branches on
// this one answer, so the plane a tier reads is decided in one place.
func SweepSearchesWispsPlaneOnly(in issueops.SweepRequest) bool {
return in.Tier == issueops.SweepWispsPlane
}
// BuildSweepCandidateFilter turns a sweep request into the storage-level
// filter that selects its CANDIDATES: the closed rows of one tier, bounded by
// the cutoff.
@ -66,8 +84,21 @@ func ValidateSweepRequest(in issueops.SweepRequest) error {
//
// Call ValidateSweepRequest first; this builder assumes a validated request
// and does not re-refuse one.
//
// For SweepWispsPlane the filter carries NO tier constraint: the plane is the
// selection, and the implementation applies it by searching the wisps table
// alone (SweepSearchesWispsPlaneOnly). Every closed row there is a candidate,
// whatever its ephemeral, no_history or wisp_type values.
func BuildSweepCandidateFilter(in issueops.SweepRequest) types.IssueFilter {
closed := types.StatusClosed
if SweepSearchesWispsPlaneOnly(in) {
filter := types.IssueFilter{Status: &closed}
if in.ClosedBefore != nil {
cutoff := *in.ClosedBefore
filter.ClosedBefore = &cutoff
}
return filter
}
ephemeral := in.Tier == issueops.SweepEphemeral
// EphemeralTier, not Ephemeral: the tier owns typed wisps whether or not
// their minting set the ephemeral flag (older creators set wisp_type but
@ -271,3 +302,91 @@ func PartitionSweepReferenced(candidates []*types.Issue, referenced map[string]b
}
return kept, referencedCount, sample
}
// BuildSweepLiveDependentScanFilter selects which of a candidate set's
// dependents are LIVE for issueops.SweepRequest.ProtectLiveDependents: the
// named sources, restricted to the not-done statuses. It is the same status
// vocabulary the reference scan asks, so "live" means one thing in a sweep.
func BuildSweepLiveDependentScanFilter(dependentIDs []string, custom []types.CustomStatus) types.IssueFilter {
return types.IssueFilter{IDs: dependentIDs, Statuses: NotDoneStatusesForSweep(custom)}
}
// SweepLiveDependentSources returns the ids of the rows that depend on a
// candidate through a protecting edge (issueops.SweepLiveDependentEdgeTypes),
// given the edges pointing at the candidates keyed by target. The result is
// sorted and de-duplicated, so the follow-up status read is deterministic.
func SweepLiveDependentSources(incoming map[string][]*types.Dependency) []string {
seen := make(map[string]bool)
for _, deps := range incoming {
for _, dep := range deps {
if dep != nil && isSweepProtectingEdge(dep.Type) {
seen[dep.IssueID] = true
}
}
}
ids := make([]string, 0, len(seen))
for id := range seen {
ids = append(ids, id)
}
sort.Strings(ids)
return ids
}
// SweepLiveDependentTargets returns the candidates a live row depends on: the
// targets of protecting edges whose source is in live.
func SweepLiveDependentTargets(incoming map[string][]*types.Dependency, live map[string]bool) map[string]bool {
protected := make(map[string]bool)
for target, deps := range incoming {
for _, dep := range deps {
if dep != nil && isSweepProtectingEdge(dep.Type) && live[dep.IssueID] {
protected[target] = true
break
}
}
}
return protected
}
func isSweepProtectingEdge(t types.DependencyType) bool {
for _, protecting := range issueops.SweepLiveDependentEdgeTypes {
if t == protecting {
return true
}
}
return false
}
// PartitionSweepLiveDependents splits candidates into the ones no live row
// depends on and a count of the ones some live row does, preserving candidate
// order.
func PartitionSweepLiveDependents(candidates []*types.Issue, protected map[string]bool) (kept []*types.Issue, protectedCount int) {
kept = make([]*types.Issue, 0, len(candidates))
for _, issue := range candidates {
if protected[issue.ID] {
protectedCount++
continue
}
kept = append(kept, issue)
}
return kept, protectedCount
}
// LimitSweepCandidates applies issueops.SweepRequest.Limit to the candidates
// that survived every protection: the oldest-closed first (closed_at
// ascending, then id, so two runs over one snapshot pick the same rows), at
// most limit of them. It returns the kept rows and how many were left behind.
// A non-positive limit keeps everything. The input slice is not reordered.
func LimitSweepCandidates(candidates []*types.Issue, limit int) (kept []*types.Issue, remaining int) {
if limit <= 0 || len(candidates) <= limit {
return candidates, 0
}
ordered := append([]*types.Issue(nil), candidates...)
sort.SliceStable(ordered, func(i, j int) bool {
a, b := ordered[i], ordered[j]
if a.ClosedAt != nil && b.ClosedAt != nil && !a.ClosedAt.Equal(*b.ClosedAt) {
return a.ClosedAt.Before(*b.ClosedAt)
}
return a.ID < b.ID
})
return ordered[:limit], len(ordered) - limit
}

View file

@ -353,3 +353,119 @@ func sweepCandidateIDs(issues []*types.Issue) []string {
}
return ids
}
func TestValidateSweepRequestGatesTheWispsPlane(t *testing.T) {
cutoff := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
if err := ValidateSweepRequest(issueops.SweepRequest{Tier: issueops.SweepWispsPlane}); !errors.Is(err, issueops.ErrValidation) {
t.Fatalf("unfiltered wisps-plane sweep error = %v, want ErrValidation: it reaches no-history (durable-tier) rows", err)
}
for _, req := range []issueops.SweepRequest{
{Tier: issueops.SweepWispsPlane, ClosedBefore: &cutoff},
{Tier: issueops.SweepWispsPlane, IDPattern: "*"},
} {
if err := ValidateSweepRequest(req); err != nil {
t.Errorf("ValidateSweepRequest(%+v) = %v, want nil", req, err)
}
}
}
func TestBuildSweepCandidateFilterForTheWispsPlaneHasNoTierConstraint(t *testing.T) {
cutoff := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
req := issueops.SweepRequest{Tier: issueops.SweepWispsPlane, ClosedBefore: &cutoff}
if !SweepSearchesWispsPlaneOnly(req) {
t.Fatal("SweepSearchesWispsPlaneOnly(wisps-plane) = false; the plane IS the selection")
}
filter := BuildSweepCandidateFilter(req)
if filter.Status == nil || *filter.Status != types.StatusClosed {
t.Fatalf("Status = %v, want closed", filter.Status)
}
if filter.EphemeralTier != nil || filter.Ephemeral != nil {
t.Fatalf("wisps-plane filter carries a flag constraint (EphemeralTier=%v, Ephemeral=%v); "+
"that would drop no-history rows", filter.EphemeralTier, filter.Ephemeral)
}
if filter.ClosedBefore == nil || !filter.ClosedBefore.Equal(cutoff) || filter.ClosedBefore == &cutoff {
t.Fatalf("ClosedBefore = %v, want a copy of %v", filter.ClosedBefore, cutoff)
}
for _, tier := range []issueops.SweepTier{issueops.SweepEphemeral, issueops.SweepDurable} {
if SweepSearchesWispsPlaneOnly(issueops.SweepRequest{Tier: tier}) {
t.Errorf("SweepSearchesWispsPlaneOnly(%s) = true; tier queries merge both planes", tier)
}
}
}
func TestSweepLiveDependentsCountOnlyProtectingEdgesFromLiveSources(t *testing.T) {
dep := func(source, target string, typ types.DependencyType) *types.Dependency {
return &types.Dependency{IssueID: source, DependsOnID: target, Type: typ}
}
incoming := map[string][]*types.Dependency{
"root": {dep("step-open", "root", types.DepParentChild), dep("step-done", "root", types.DepParentChild)},
"tracked": {dep("convoy", "tracked", types.DepTracks)},
"gate": {dep("waiter", "gate", types.DepBlocks)},
"linked": {dep("reader", "linked", types.DepRelated)},
"orphan": {dep("step-done", "orphan", types.DepParentChild), nil},
}
sources := SweepLiveDependentSources(incoming)
if want := []string{"convoy", "step-done", "step-open", "waiter"}; strings.Join(sources, ",") != strings.Join(want, ",") {
t.Fatalf("SweepLiveDependentSources = %v, want %v (sorted, protecting edges only)", sources, want)
}
live := map[string]bool{"step-open": true, "convoy": true, "waiter": true, "reader": true}
protected := SweepLiveDependentTargets(incoming, live)
for _, id := range []string{"root", "tracked", "gate"} {
if !protected[id] {
t.Errorf("%s not protected; a live source depends on it through a protecting edge", id)
}
}
for _, id := range []string{"linked", "orphan"} {
if protected[id] {
t.Errorf("%s protected; its only live source is a non-protecting edge or none is live", id)
}
}
candidates := []*types.Issue{{ID: "root"}, {ID: "linked"}, {ID: "tracked"}, {ID: "orphan"}}
kept, count := PartitionSweepLiveDependents(candidates, protected)
if count != 2 || len(kept) != 2 || kept[0].ID != "linked" || kept[1].ID != "orphan" {
t.Fatalf("PartitionSweepLiveDependents = %d kept %v, count %d; want [linked orphan] and 2", len(kept), kept, count)
}
}
func TestValidateSweepRequestRefusesANegativeLimit(t *testing.T) {
err := ValidateSweepRequest(issueops.SweepRequest{Tier: issueops.SweepEphemeral, Limit: -1})
if !errors.Is(err, issueops.ErrValidation) {
t.Fatalf("negative Limit error = %v, want ErrValidation", err)
}
if err := ValidateSweepRequest(issueops.SweepRequest{Tier: issueops.SweepEphemeral, Limit: 0}); err != nil {
t.Fatalf("zero Limit (no cap) error = %v, want nil", err)
}
}
func TestLimitSweepCandidatesTakesTheOldestClosedFirst(t *testing.T) {
at := func(day int) *time.Time {
ts := time.Date(2026, 1, day, 0, 0, 0, 0, time.UTC)
return &ts
}
candidates := []*types.Issue{
{ID: "c", ClosedAt: at(3)},
{ID: "b2", ClosedAt: at(1)},
{ID: "a", ClosedAt: at(2)},
{ID: "b1", ClosedAt: at(1)},
}
kept, remaining := LimitSweepCandidates(candidates, 3)
var got []string
for _, issue := range kept {
got = append(got, issue.ID)
}
if strings.Join(got, ",") != "b1,b2,a" || remaining != 1 {
t.Fatalf("LimitSweepCandidates(3) = %v, remaining %d; want [b1 b2 a] (closed_at, then id) and 1", got, remaining)
}
if candidates[0].ID != "c" {
t.Fatal("LimitSweepCandidates reordered the caller's slice")
}
for _, limit := range []int{0, 4, 10} {
if kept, remaining := LimitSweepCandidates(candidates, limit); len(kept) != 4 || remaining != 0 {
t.Errorf("LimitSweepCandidates(%d) kept %d, remaining %d; want all 4 and 0", limit, len(kept), remaining)
}
}
}

View file

@ -29,6 +29,7 @@ const (
DepDiscoveredFrom = types.DepDiscoveredFrom
DepRepliesTo = types.DepRepliesTo
DepWaitsFor = types.DepWaitsFor
DepTracks = types.DepTracks
)
// DependencyEdge is one directed edge: IssueID depends on DependsOnID, with

View file

@ -27,6 +27,21 @@ const (
// it — carries the require-a-filter refusal SweepRequest.ClosedBefore
// describes.
SweepDurable SweepTier = "durable"
// SweepWispsPlane clears CLOSED rows by STORAGE PLANE rather than by
// tier: every closed row stored in the wisps table, whatever its flags —
// ephemeral wisps and no-history beads alike. `bd purge --wisps-plane`.
//
// It is the one tier that is NOT disjoint from the other two, and that is
// the point of it. A no-history bead lives in the wisps plane but is
// durable-tier (it is not ephemeral and carries no wisp_type), so neither
// SweepEphemeral nor SweepDurable can say "the wisps table" — the unit an
// orchestrator's retention policy is written in. Conversely a legacy
// typed wisp stored in the issues table is ephemeral-tier and NOT in this
// plane.
//
// Because it reaches durable-tier rows, it carries the durable tier's
// require-a-filter gate (SweepRequest.ClosedBefore).
SweepWispsPlane SweepTier = "wisps-plane"
)
// SweepRequest describes one bulk clearance of closed rows: which tier, which
@ -68,6 +83,9 @@ type SweepRequest struct {
// says so with IDPattern "*", which is a deliberate keystroke rather than
// an omitted one.
//
// SweepWispsPlane carries the same gate, because the wisps plane holds
// no-history beads, which are durable-tier.
//
// The EPHEMERAL tier carries no such gate: an unfiltered sweep of closed
// wisps is the ordinary use of `bd purge`, and the tier is transient by
// definition.
@ -108,6 +126,33 @@ type SweepRequest struct {
// `bd purge` does not, because a wisp's citations are as transient as the
// wisp.
ProtectReferenced bool
// ProtectLiveDependents skips candidates that a LIVE row depends on
// through a structural edge — a closed parent whose child is still open,
// a closed bead a live convoy tracks, a closed blocker of a live bead —
// so a sweep never deletes the root, container or gate of work that is
// still in progress.
//
// WHICH EDGES are SweepLiveDependentEdgeTypes: parent-child, tracks and
// blocks, from either plane's dependency table. Other edge types (related,
// discovered-from, ...) are links rather than structure and do not protect.
//
// WHICH ROWS ARE LIVE is the same not-done set ProtectReferenced asks: the
// built-in active statuses (open, in_progress, blocked, deferred, pinned,
// hooked) plus every configured custom status whose category is not
// "done", with the same REQUIRED read of the custom statuses.
//
// Unlike ProtectReferenced it is a stored-edge lookup, not a text scan, so
// it costs one read of the edges pointing at the candidates and one of
// their sources. `bd purge` always asks for it; `bd prune` does not.
ProtectLiveDependents bool
// Limit, when positive, caps how many rows ONE sweep deletes, taking the
// OLDEST-CLOSED first (closed_at ascending, then id). The rest are left
// for the next call and counted in SweepResult.Remaining, so a caller can
// drain a large backlog in bounded transactions instead of one that grows
// with the backlog and can outlive the caller's deadline. It applies after
// every protection, so it caps rows that would actually go. Zero means no
// cap; a negative value is ErrValidation.
Limit int
// DryRun reports what the sweep WOULD do and deletes nothing. The result
// is otherwise the same result — the same counts, the same skips, the same
// refusals — computed against the same snapshot the real sweep would have
@ -132,6 +177,9 @@ type SweepSkips struct {
// 0 when that field is false; a caller that reads a 0 without having asked
// for the protection has learned nothing about whether rows are cited.
Referenced int
// LiveDependent counts candidates skipped by ProtectLiveDependents, under
// the same always-0-when-not-asked rule as Referenced.
LiveDependent int
// NotClosed, UnknownClosedAt and ClosedAtOrAfterCutoff count candidates
// the tier's own query returned and the sweep rechecked and rejected: a
// status that is not closed, a closed row with no closed_at stamp at all,
@ -173,6 +221,10 @@ type SweepResult struct {
Events int
// Skipped reports the candidates the sweep held back and why.
Skipped SweepSkips
// Remaining is how many rows the sweep WOULD also have deleted but left
// because of SweepRequest.Limit. Zero when there is no limit or the
// backlog fit; a caller loops while it is non-zero.
Remaining int
// ReferencedIDs is a BOUNDED SAMPLE of the ids Skipped.Referenced counts —
// at most SweepReferencedSampleLimit of them, in the order the candidate
// query returned them. It is a sample and not the set: a caller that needs
@ -184,6 +236,11 @@ type SweepResult struct {
ReferencedIDs []string
}
// SweepLiveDependentEdgeTypes are the edge types through which a live row
// protects a closed candidate under SweepRequest.ProtectLiveDependents. It is
// published so a caller can state the same policy without copying the list.
var SweepLiveDependentEdgeTypes = []DependencyType{DepParentChild, DepTracks, DepBlocks}
// SweepReferencedSampleLimit bounds SweepResult.ReferencedIDs. It is published
// so a caller can tell a truncated sample from a complete one by comparing the
// slice's length against it, rather than against a number copied out of an
@ -255,17 +312,20 @@ type Sweeper interface {
//
// THE ORDER THE NARROWING HAPPENS IN IS PART OF THE ANSWER, because the
// skip counters are counted along the way: the tier's closed rows, then
// IDPattern, then the pinned and closed_at rechecks, then the reference
// protection. A pinned row excluded by the pattern is therefore NOT
// counted in Skipped.Pinned — it was never a candidate — and the counters
// describe the set the request actually reached.
// IDPattern, then the pinned and closed_at rechecks, then the
// live-dependent protection, then the reference protection, then Limit
// (oldest-closed first). A pinned row
// excluded by the pattern is therefore NOT counted in Skipped.Pinned — it
// was never a candidate — and the counters describe the set the request
// actually reached.
//
// REFUSALS, all ErrValidation and all before anything is read:
//
// - an unset or unrecognized Tier;
// - a SweepDurable request with neither ClosedBefore nor IDPattern (see
// SweepRequest.ClosedBefore for why this lives here);
// - an IDPattern that is not a well-formed glob.
// - a SweepDurable or SweepWispsPlane request with neither ClosedBefore
// nor IDPattern (see SweepRequest.ClosedBefore for why this lives here);
// - an IDPattern that is not a well-formed glob;
// - a negative Limit.
//
// A REQUEST THAT MATCHES NOTHING IS A ZERO RESULT AND A NIL ERROR, not a
// not-found: an empty set of closed rows is the steady state of a swept