feat(backup): route the backup family over proxied-server, refused by design off-host (proxied-parity S3) (#6584)

* refactor(proxy): one capability registry, with a reason on every refusal

Proxied-server policy lived in three path tables (a maintenance refusal
map, a history classification map, a transform row list), each with its
own lookup and its own front-door validator, plus a flag matrix. Nothing
forced a new command to appear in any of them, so an unclassified
command sailed past the gate and died in the store factory with
`proxy server store should be uow provider`. That — not the table count
— was the root problem.

One table now (cmd/bd/capability_registry.go), and a test that fails
when a runnable command is missing from it. Adding a command is no
longer a place where policy can be forgotten: it is a build failure
until someone decides whether the proxied front door lets it through.

Every refusal carries a Reason: `design` where refusing is correct and
expected to stay (shared history, multi-repo routing, destructive admin,
storage-format surgery, strict --readonly), `unimplemented` where it is
a gap with a named owner. The reason renders in the refusal JSON,
additive to the frozen {code, error, mutates} contract, and is omitted
on refusals that report a runtime state rather than a policy so a
consumer keying on its presence is never told "" by mistake.

The registry also inventories the 57 untyped refusals commands raise
from their own RunE. Those rows are not enforced — converting them
changes observable output and belongs to the slice that owns each
family — but a source scan now keeps the inventory honest in both
directions.

The store-factory backstop is typed as `proxy.store.unrouted`, the
unreachable duplicate readonly refusal in main.go is gone (the proxied
branch above it already returns for the only config that reaches it),
and with it `backendSupportsStrictReadonly`, which had no other caller.

No outcome changes. Every code, message and exit status is identical,
which #6576's five-topology matrix proves: 90/90 cells unchanged
(HONORED 47, REFUSED_TYPED 24 = 4 design + 20 unimplemented, ERROR 12,
WRONG_ANSWER 4, DEGRADED 3), all five topologies exercised, no skips.

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

* refactor(proxy): `migrate hooks` is an unimplemented refusal, not a design one

The registry filed `migrate hooks` under "storage-format and workspace
surgery against a store other clients may be holding open". That rationale
does not describe it: migrate_hooks.go plans and applies GIT HOOK FILE
migration through doctor.PlanHookMigration, on the local filesystem, and
opens no store at all. Left as it was, proxied-local — the default topology
since 1.3.0 — loses the command permanently, because `design` tells every
later slice the refusal is semantic and settled.

It is not settled, but it is also not free to lift, and the difference is
structural rather than semantic. `migrate hooks` appears on none of main.go's
store-init skip lists, so permitting it makes the root pre-run open the
proxied provider before RunE runs. Measured with the row flipped to
permitted, not reasoned about: on a managed-local workspace
`bd migrate hooks --dry-run` started the proxy AND its dolt child — both
pidfiles present — to print a hook plan for five missing hooks, 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 provider-open error is not a lift.

So: Reason=unimplemented with a Tracking item that names the actual work —
put the command on the store-init skip list first, then permit it — which is
S7's, not this slice's. No outcome changes; the row still refuses with the
same code, message and exit status. The registry header now says that
permitting a path costs a provider open, since that is the fact this row
turns on and the one the completeness test cannot see.

Also leaves S7 an explicit instruction on the rows next door. `migrate
issues`, `migrate-personal` and `admin cleanup`/`admin reset` claim `design`
on a topology-blind rationale — "a store other clients may be holding open",
"destructive against a possibly-shared store" — that describes external and
team-server workspaces and does not describe managed-local, which is 1:1 and
bd-owned. They are not reclassified here: the table cannot yet express
"refused, except on managed-local", and narrowing them is semantic work
nobody has done. The comments now say that is why, so the next reader does
not mistake conservatism for a considered verdict.

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

* feat(backup): route the backup family over proxied-server, refuse it by design off-host

A proxied-server workspace had no backup path at all: all five verbs — init,
sync, remove, status, restore — refused. Proxied has been the default topology
since 1.3.0, which made this the highest user-weight gap in the proxied-parity
plan.

The mechanism needed no proxy work. 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 and 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. The work was use
cases, route files and policy rows, and the premise held.

The policy is the interesting half, and it is the first genuinely
topology-differentiated rule in the capability registry. A backup destination
is resolved by the SERVER: `file:///…` names a path on the machine running
dolt. On managed-local that machine and that user are bd's own, because bd
spawned the child. Anywhere else — an external host or socket, or a
beads-team-server database — the URL describes a filesystem bd cannot see, so
honoring the command would either fail at the point of use or, far worse,
report success having written the backup where the operator will never look.
Those shapes stay refused with Reason=design: no plumbing on this side gives bd
a path on somebody else's host.

Team-server is classified by OWNERSHIP, not transport. bts owns the store's
schema and identity whether bd reaches it over a port, a socket, or a child bd
started, and one client registering a server-side backup remote acts on every
client's data — the shape of the storm this command's own help text warns about.

Restore quiesces before it replaces. DOLT_BACKUP('restore') swaps the database
under the server, which is undefined with clients connected, so: the exclusive
workspace gate `bd backup restore` already takes excludes every other gated bd
command (including `bd serve`); this closes the provider the pre-run opened and
shuts the proxy and its dolt child down; it reopens a provider of its own to
run the restore as the only client; then it puts the topology down and reopens
once more to reconcile the project identity and the backup remote — which also
proves the restored database is serviceable. The final shutdown leaves the
workspace quiescent for the next command to relaunch lazily.

Registry rows gain a Topology map and honoredOn(), stated as "refuse, except
here" so a shape nobody thought about — a new transport, or the unknown a
corrupt sidecar produces — inherits the refusal rather than the exemption.
resolveProxiedTopology reads the shape from the workspace and reports unknown
rather than guessing.

`bd backup restore --json` now prints a result object on every topology; it
printed nothing before, which left a caller unable to tell a completed restore
from a skipped one. The four backup subcommands that lacked SilenceUsage/
SilenceErrors no longer follow their error message with "Error: exit code 1"
and a usage block.

Verified by round trip, not by exit codes: TestManagedLocalProxiedBackupRoundTrip
takes a backup on a live managed-local workspace, creates an issue after it,
restores, and asserts the pre-backup issue is back and the post-backup one is
gone, with both pidfiles absent afterwards.
TestProxiedServerBackupRefusedOnExternalTopology pins the typed design refusal
against the shared container and proves a refused command starts nothing and
writes nothing.

Flips four cells of #6576's matrix: `backup status` and `backup sync` go
REFUSED_TYPED/unimplemented -> HONORED and -> ERROR ("no backup destination
configured", the command's own error, same as every direct topology) on
proxied-local, and unimplemented -> design on proxied-external-tcp.

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

* fix(backup): say why proxied backup is refused, and stop calling a cleanup failure a restore failure

Review follow-ups on the proxied backup slice. None of them changes which
commands are honored on which topology; what changes is what the refusal
CLAIMS, and what a restore says when only its teardown failed.

The refusal rationale was true of one destination scheme out of five. It said
"a backup destination is resolved on the server's filesystem, not this
client's" — which describes `file://` and nothing else. resolveDoltBackupURL
passes `https://`, `aws://` and `gs://` straight through, and `bd backup`'s
own help recommends DoltHub by name; for those the server pushes over the
network from its own environment and no filesystem of anybody's is involved.
An operator running `bd backup init https://doltremoteapi.dolthub.com/...` on
an external topology got a permanent verdict explained by a filesystem the
command never touches.

The refusal itself stands, on the reason that is true of every scheme: `CALL
DOLT_BACKUP('add', …)` registers the remote ON THE SERVER, where it is global
to every client connected to it, so one workspace's backup decision becomes
everyone's — the same shape as the auto-backup storm this command's help text
already warns about. The file:// locality problem is now stated as the second,
scheme-specific problem it is. The message keeps its frozen
"<path> is not supported in proxied-server mode" prefix and its
proxy.backup.unsupported code.

The remote-scheme case gets a Tracking item, the way `diff` got "1.4
candidate". The outcome is design; that particular CASE is an open question,
and a design label with no tracking reads as "never" to every later slice.
It is the same server-env credential question S4 has to answer for `dolt
push` on these same topologies. Recorded there too: restore-from-a-remote is
already half-broken in DIRECT mode, because validateBackupRestoreDir stats its
argument, so `bd backup restore https://...` fails everywhere today.

A restore that succeeded and then failed to shut the proxy down reported
"restore failed". The operator's data was back; they were told it was not,
and the obvious next move — run the restore again — was the wrong one.
withQuiescedProxiedProvider now returns teardown failures wrapped in
*proxiedTeardownError instead of flattening them into the operation's error,
and the message the caller renders is split into a function a test can hold
still, because the judgement it encodes (did the data come back) is the point.
Both call sites distinguish now; the second one's "did not reopen" wording was
also wrong for a teardown failure, since it had reopened.

Two smaller things while in here. The guard-rail comment on
newProxiedServerUOWProviderAdopting still said "only two callers legitimately
have no workspace identity to assert" — this slice added a third. That comment
is the register of identity-assertion bypasses, so it now names the third and
why, and says what to do about a fourth. And DirToFileURL was "file://" +
filepath.Abs with no scheme check: it would have turned a DoltHub URL into
file:///cwd/https:/doltremoteapi.dolthub.com/... , a valid-looking URL naming a
directory nobody asked for. Unreachable today, and every caller is a restore
path, which is exactly the capability the tracking item above describes.

CHANGELOG additionally discloses two direct-mode changes this slice makes that
were previously only visible in the diff: `bd backup restore --json` prints a
result object on EVERY topology where it used to print nothing, and the four
backup subcommands that gained SilenceUsage/SilenceErrors no longer follow a
failure with "Error: exit code 1" and a usage block, on every topology.

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

* fix(backup): quiesce failed restore reopens and pin JSON output (bd-obos)

Preserve the primary constructor or operation error while reporting cleanup failures without a successful-restore marker. Exercise a real malformed-backup reopen failure and assert both pidfiles are removed; retain the successful round trip and assert its JSON result.

Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Julian Knutsen

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-09-23 02:16:45 -07:00 • committed by GitHub
commit c69dd3061a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 1545 additions and 115 deletions

View file

@ -76,6 +76,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### 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`.
- **`bd count` supports repeatable `--metadata-field key=value` filters**
([#6023](https://github.com/gastownhall/beads/issues/6023)), so callers can
count the same metadata-scoped set `bd list` returns without fetching every
@ -124,6 +147,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **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 gate check` resolves bead gates whose target lives in a prefix-routed
rig** ([#5859](https://github.com/gastownhall/beads/pull/5859)). After a local

View file

@ -56,7 +56,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() {

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

@ -72,8 +72,9 @@ const (
// 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 (
trackBackup = "proxied-parity S3 (backup/restore family)"
trackVersionCtl = "proxied-parity S4 (dolt commit/push/pull/remote)"
trackSync = "proxied-parity S5 (bd sync)"
trackDegradation = "proxied-parity S6 (doctor, config show, degradations)"
@ -85,12 +86,40 @@ const (
// 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
History HistoryCapabilityClass
Note string
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.
@ -166,6 +195,50 @@ 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{
@ -176,16 +249,37 @@ var proxyCapabilityRegistry = []capabilityRow{
// --- backup / restore ---------------------------------------------------
// CALL DOLT_BACKUP(...) is pure SQL over a connection proxied mode already
// owns, so this family is plumbing, not policy. Locality policy (file://
// URLs naming the server's filesystem on external topologies) is decided
// per topology when S3 lands.
refusedPath("backup", "proxy.backup.unsupported", ProxyReasonUnimplemented, trackBackup).
asParentGroup(),
refusedPath("backup init", "proxy.backup.unsupported", ProxyReasonUnimplemented, trackBackup),
refusedPath("backup sync", "proxy.backup.unsupported", ProxyReasonUnimplemented, trackBackup),
refusedPath("backup remove", "proxy.backup.unsupported", ProxyReasonUnimplemented, trackBackup),
refusedPath("backup status", "proxy.backup.unsupported", ProxyReasonUnimplemented, trackBackup),
refusedPath("backup restore", "proxy.backup.unsupported", ProxyReasonUnimplemented, trackBackup),
// 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
@ -515,7 +609,11 @@ func commandPolicyArgSet(cmd *cobra.Command) string {
// 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.
func validateProxyRegistryBeforeProvider(cmd *cobra.Command) error {
//
// 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
}
@ -532,10 +630,14 @@ func validateProxyRegistryBeforeProvider(cmd *cobra.Command) error {
}
}
row, ok := capabilityRowFor(cmd)
if !ok || row.Rule.Outcome != ProxyOutcomeRefused {
if !ok {
return nil
}
return HandleProxyCapabilityError(proxyCapabilityErrorFor(row.Rule))
rule := row.ruleFor(topology)
if rule.Outcome != ProxyOutcomeRefused {
return nil
}
return HandleProxyCapabilityError(proxyCapabilityErrorFor(rule))
}
func proxyCapabilityErrorFor(rule proxyCapabilityRule) *ProxyCapabilityError {

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 := validateProxyRegistryBeforeProvider(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 { _ = validateProxyRegistryBeforeProvider(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 := validateProxyRegistryBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if path == "dolt remote remove" {
if err != nil {
t.Fatalf("supported %s refused: %v", path, err)
@ -120,7 +120,7 @@ func TestHistoryNestedFrontDoorsRefuseAndSupportedPathsPass(t *testing.T) {
var got map[string]any
// validateProxyRegistryBeforeProvider renders the typed refusal to
// stdout in JSON mode; the command must retain its nested path.
out := captureStdout(t, func() error { _ = validateProxyRegistryBeforeProvider(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 := validateProxyRegistryBeforeProvider(history); err != nil {
if err := validateProxyRegistryBeforeProvider(history, ProxyTopologyManagedLocal); err != nil {
t.Fatalf("history --events supported path refused: %v", err)
}
}

View file

@ -109,38 +109,12 @@ func TestProxyCapabilityRegistryHasNoDuplicateRows(t *testing.T) {
// refusal with no tracking item is a gap nobody owns.
func TestProxyCapabilityRegistryRowInvariants(t *testing.T) {
for _, row := range proxyCapabilityRegistry {
switch row.Rule.Outcome {
case ProxyOutcomeRefused:
if row.Rule.Code == "" || row.Rule.Message == "" || row.Rule.ExitCode != 1 {
t.Errorf("%s: refusal must carry a code, a message and exit 1, got %#v", row.display(), row.Rule)
}
if row.Rule.Mutates {
t.Errorf("%s: a refusal never mutates", row.display())
}
if !strings.HasPrefix(row.Rule.Code, "proxy.") {
t.Errorf("%s: code %q must be in the stable proxy.* namespace", row.display(), row.Rule.Code)
}
case ProxyOutcomeRefusedInRunE:
if row.Rule.Code != "" {
t.Errorf("%s: an untyped RunE refusal has no code; if it has one it belongs in the gate", row.display())
}
case ProxyOutcomeHonored:
if row.Rule.Reason != "" {
t.Errorf("%s: Reason explains a refusal; an honored row must not carry one", row.display())
}
default:
t.Errorf("%s: unexpected outcome %q", row.display(), row.Rule.Outcome)
}
refusal := row.Rule.Outcome == ProxyOutcomeRefused || row.Rule.Outcome == ProxyOutcomeRefusedInRunE
if refusal {
switch row.Rule.Reason {
case ProxyReasonDesign, ProxyReasonUnimplemented:
default:
t.Errorf("%s: refusal must declare Reason design or unimplemented, got %q", row.display(), row.Rule.Reason)
}
if row.Rule.Reason == ProxyReasonUnimplemented && row.Rule.Tracking == "" {
t.Errorf("%s: an unimplemented refusal needs a Tracking item naming who closes it", row.display())
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 {
@ -152,6 +126,46 @@ func TestProxyCapabilityRegistryRowInvariants(t *testing.T) {
}
}
// 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").
@ -271,6 +285,16 @@ func TestProxyCapabilityRegistryReasonsAreAssignedIndividually(t *testing.T) {
"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{}
@ -364,7 +388,7 @@ func TestProxyRefusalJSONCarriesReason(t *testing.T) {
cmd := &cobra.Command{Use: tc.path}
root.AddCommand(cmd)
out := captureStdout(t, func() error {
_ = validateProxyRegistryBeforeProvider(cmd)
_ = validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
return nil
})
for _, want := range []string{

View file

@ -76,7 +76,7 @@ func TestProxyTransformCapabilityRows(t *testing.T) {
t.Fatalf("typed refusal = %#v", typed)
}
}
if err := validateProxyRegistryBeforeProvider(cmd); tc.outcome == ProxyOutcomeHonored && err != nil {
if err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); tc.outcome == ProxyOutcomeHonored && err != nil {
t.Fatalf("honored transform refused: %v", err)
}
})
@ -86,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 := validateProxyRegistryBeforeProvider(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 := validateProxyRegistryBeforeProvider(cmd); err != nil {
if err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal); err != nil {
t.Fatalf("dry-run auto-merge refused: %v", err)
}
}
@ -104,7 +104,7 @@ func TestProxyTransformRefusalRendering(t *testing.T) {
jsonOutput = false
var textErr string
stderr := captureStderr(t, func() {
err := validateProxyRegistryBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if code, ok := exitCodeFromError(err); !ok || code != 1 {
t.Fatalf("exit = %v, want 1", err)
}
@ -116,7 +116,7 @@ func TestProxyTransformRefusalRendering(t *testing.T) {
jsonOutput = true
stdout := captureStdout(t, func() error {
_ = validateProxyRegistryBeforeProvider(cmd)
_ = validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
return nil
})
var envelope map[string]any
@ -164,7 +164,7 @@ func TestProxyTransformRefusalHasNoProviderOrFileMutation(t *testing.T) {
t.Cleanup(func() { uowProvider = oldProvider })
cmd := transformTestCommand("supersede")
err := validateProxyRegistryBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if err == nil {
t.Fatal("expected transform refusal")
}

View file

@ -1273,18 +1273,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. 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 := validateProxyRegistryBeforeProvider(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() {
@ -1491,7 +1491,7 @@ var rootCmd = &cobra.Command{
if err := validateProxyCapabilitiesBeforeProvider(cmd); err != nil {
return err
}
if err := validateProxyRegistryBeforeProvider(cmd); err != nil {
if err := validateProxyRegistryBeforeProvider(cmd, resolveProxiedTopology(beadsDir)); err != nil {
return err
}
}

View file

@ -25,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 (
@ -36,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.

View file

@ -69,6 +69,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
@ -81,7 +86,7 @@ func TestProxyMaintenanceNestedPathsRefuseBeforeProvider(t *testing.T) {
root.AddCommand(parent)
parent.AddCommand(child)
out := captureStdout(t, func() error {
_ = validateProxyRegistryBeforeProvider(child)
_ = validateProxyRegistryBeforeProvider(child, ProxyTopologyExternalTCP)
return nil
})
if !strings.Contains(out, `"code":`) {
@ -101,7 +106,7 @@ func TestProxyFormulaSwarmMergeSlotRefusals(t *testing.T) {
cmd.AddCommand(child)
cmd = child
}
err := validateProxyRegistryBeforeProvider(cmd)
err := validateProxyRegistryBeforeProvider(cmd, ProxyTopologyManagedLocal)
if err == nil {
t.Fatalf("%s unexpectedly allowed", path)
}
@ -162,7 +167,7 @@ func TestProxyWorkflowRefusalContractAndNoMutation(t *testing.T) {
oldDidWrite := commandDidWrite.Load()
commandDidWrite.Store(false)
t.Cleanup(func() { commandDidWrite.Store(oldDidWrite) })
out := captureStdout(t, func() error { _ = validateProxyRegistryBeforeProvider(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)
@ -199,7 +204,7 @@ func TestProxyMaintenanceRefusalLeavesFilesUntouched(t *testing.T) {
oldProvider := uowProvider
uowProvider = nil
t.Cleanup(func() { uowProvider = oldProvider })
err := validateProxyRegistryBeforeProvider(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

@ -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

@ -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