fix(init): bd init --server --external starts no server; a failed bd init --server can be retried (#7674)

* fix(init): admit a retried `bd init --server` over an empty .beads/dolt

A first `bd init --server` that cannot reach its server fails after
creating the local Dolt root, leaving an empty .beads/dolt, no
.local_version witness, and no config.yaml/metadata.json recording the
server choice. The legacy-upgrade guard runs before init writes that
choice, so it saw an embedded-looking workspace with a local Dolt root
and refused every retry as a "legacy Dolt workspace"; no bd command could
repair it.

guardLegacyUpgradeWorkspaceForInit(beadsDir, initSelectsServer) carries
init's already-resolved server intent into the guard. It is consulted
for exactly one decision: an empty, witness-less .beads/dolt is admitted,
the same admission a workspace that records server mode already gets
(#6935). It is deliberately not folded into the workspace's own server
mode, so a non-empty root with an unreadable witness and an embedded
repository beside a non-empty root keep their current outcomes.
guardLegacyUpgradeWorkspace is now the initSelectsServer=false wrapper,
and only init's main guard call passes the flag; the proxied-server
init path keeps the plain wrapper.

Ported from the versioned-beads fork (donnabox/codex/preview3-source-
catchup-46aa), commits bc8d72182a (red) and 5bdfbfe5e2 (green). The
fork's graph_mode refusal in the same function is graph-preview-only
and is not carried here.

Tests: TestLegacyUpgradeGuardForInitAdmitsEmptyDoltRoot and
TestLegacyUpgradeGuardForInitAdmissionStaysNarrow pin the admission and
its narrowness at the guard; TestInitServerFlagAdmitsEmptyDoltRootWithoutConfig
and TestInitServerFlagRetryAfterFailedFirstAttempt run the real binary
against the test Dolt server and fail on main with the legacy refusal.

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(init): `bd init --server --external` must not auto-start a server

`--external` declares the Dolt server managed outside bd ("skip server
startup", per its help), but init builds its dolt.Config by hand with
`AutoStart: initServerMode && BEADS_DOLT_AUTO_START != "0"`, so the flag
never reached the auto-start decision. A `bd init --server --external`
that named no port therefore ran dolt and tried to start a repo-local
sql-server. A named port was already declared external by rule 2c
(#5934), but its failure still advised `bd dolt start`, the one thing
--external says bd must not do, and each route (host:port, socket,
shared server, auto-start pinned off) worded the failure differently.

- AutoStart is now `initServerMode && !externalServer && ...`.
- externalServerUnreachableMessage rewrites only a failed dial
  (*net.OpError with Op "dial") under --external: it names the endpoint
  that was dialed and says bd did not start a server. A dial to port 0
  means no port was named, so that message asks for --server-port or
  BEADS_DOLT_SERVER_PORT and offers no default (GH#2098, GH#2372). Any
  other open failure keeps its own text.

Ported from the versioned-beads fork (donnabox/codex/preview3-source-
catchup-46aa), commits 234ca3d502 and a601a80e77 (red/green), 03a64a1aba
(socket helper rename), and a6ca0536c9 and 397fc4c69e (red/green: no-port
arm and wording). The fork's graph-preview dispatch at the top of init
and its --skip-hooks help text change are graph-only and not carried.
The TestInitExternalProvisionerShape doc comment is corrected: on main
every provisioner cell is a control (a named port is already external),
not a reproduction.

Tests: TestInitServerExternalDeadPortStartsNoServer,
TestInitServerExternalNoPortStartsNoServer and
TestInitExternalUnreachableMessage run the real binary against a dolt
shim that records every launch and fail on main;
TestInitSharedServerExternalDeadPortStillFails,
TestInitServerWithoutNamedPortStillStartsServer and
TestInitExternalProvisionerShape are controls; and
TestExternalServerUnreachableMessage pins which errors are rewritten.

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-19 03:11:14 +00:00 • committed by GitHub
commit 3488dc4536
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 847 additions and 3 deletions

View file

@ -763,6 +763,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- **`bd init --server --external` no longer starts a Dolt server of its own.**
Init builds its store config by hand and turned auto-start on for every
server init, so an `--external` init that named no port launched a
repo-local `dolt sql-server`, although `--external` says the server is
managed outside bd. `--external` now turns auto-start off. When the
external server cannot be reached, init gives one message on every route
(host and port, socket, shared server, auto-start pinned off): it names the
endpoint it dialed, says that bd did not start a server, and no longer
advises `bd dolt start`. With no port named at all, it asks for one
(`--server-port` or `BEADS_DOLT_SERVER_PORT`) instead of offering a default.
- **A failed `bd init --server` can be retried.** A first attempt that could
not reach its server left an empty `.beads/dolt` and nothing on disk that
records the server choice, so the legacy-upgrade guard refused every retry
as a "legacy Dolt workspace" and no bd command could repair it. When init
itself selects server mode, the guard now admits exactly that root: empty,
with no `.local_version` witness. A pre-1.0 witness, or a `.beads/dolt` that
holds anything, is still refused, and commands other than `bd init` are
decided as before.
- **Time-bound filters and the keyset cursor compare the same instant on every
engine, whatever zone they are given in.** The storage filter builder binds
every time bound (`created_*`, `updated_*`, `closed_*`, `started_*`,

View file

@ -891,6 +891,8 @@ go_test(
"init_commit_test.go",
"init_embedded_test.go",
"init_explicit_beads_dir_embedded_test.go",
"init_external_autostart_test.go",
"init_external_message_test.go",
"init_gateway_test.go",
"init_git_bootstrap_routing_test.go",
"init_guard_force_e2e_test.go",
@ -939,6 +941,8 @@ go_test(
"legacy_upgrade_guard_e2e_test.go",
"legacy_upgrade_guard_empty_root_test.go",
"legacy_upgrade_guard_external_server_test.go",
"legacy_upgrade_guard_init_flag_e2e_test.go",
"legacy_upgrade_guard_init_flag_test.go",
"legacy_upgrade_guard_test.go",
"legacy_upgrade_guard_witness_test.go",
"linear_roundtrip_test.go",

View file

@ -5,6 +5,7 @@ import (
"context"
"errors"
"fmt"
"net"
"os"
"os/exec"
"os/user"
@ -226,6 +227,40 @@ func shouldInitSharedGlobalDB(sharedServer, sharedServerMode, gateway bool) bool
return (sharedServer || sharedServerMode) && !gateway
}
// externalServerUnreachableMessage returns the message for an --external init
// whose server could not be dialed, or "" when err is any other failure.
//
// --external declares the server managed outside bd, so init starts none. The
// store's own advice for a dead local server, "bd dolt start", would start the
// very server --external says bd must not, and the store words this failure
// differently per route (shared server, socket, remote host, auto-start pinned
// off). One message serves them all: it names the endpoint that was dialed and
// says that bd did not start a server.
//
// A dial to port 0 is the exception. The store leaves a zero port zero for
// auto-start to fill in, so it means nothing named a port: the address is a
// placeholder, not an endpoint. The message says so and how to name one, and
// offers no default, since on a shared machine whatever listens on a default
// port may belong to another project (GH#2098, GH#2372).
func externalServerUnreachableMessage(err error) string {
var opErr *net.OpError
if !errors.As(err, &opErr) || opErr.Op != "dial" {
return ""
}
if addr, ok := opErr.Addr.(*net.TCPAddr); ok && addr.Port == 0 {
return fmt.Sprintf("Error: failed to open Dolt store: %v\n\n"+
"--external declares the Dolt server externally managed, so bd did not start one, and no port was named for it.\n"+
"Name the server's port with --server-port or BEADS_DOLT_SERVER_PORT.\n", opErr)
}
endpoint := "the configured endpoint"
if opErr.Addr != nil {
endpoint = opErr.Addr.String()
}
return fmt.Sprintf("Error: failed to open Dolt store: %v\n\n"+
"--external declares the Dolt server at %s externally managed, so bd did not start one.\n"+
"Start that server, or point init at the right endpoint.\n", opErr, endpoint)
}
// warnHalfIdentifiedSubstrate reports a substrate carrying one identity marker
// and not the other.
//
@ -970,7 +1005,7 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
// before init's existing-workspace checks so even --force cannot create
// or rewrite state beside a source that has not been preserved.
if beadsDir := resolveInitBeadsDir(); beadsDir != "" {
if err := guardLegacyUpgradeWorkspace(beadsDir); err != nil {
if err := guardLegacyUpgradeWorkspaceForInit(beadsDir, initServerMode); err != nil {
return err
}
}
@ -1554,7 +1589,9 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
}
// Build config. Beads always uses dolt sql-server.
// AutoStart is always enabled during init — we need a server to initialize the database.
// AutoStart is enabled during init — we need a server to initialize the database —
// except under --external: that server is managed outside bd, so bd must not start
// one of its own on the endpoint the caller named.
//
// Port resolution for init: use ONLY project-local sources (env var, port file)
// to prevent cross-project data leakage (GH#2336). DefaultConfig falls through
@ -1602,7 +1639,7 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
ProxiedServer: initProxiedServer,
CreateIfMissing: true, // bd init is the only path that should create databases
OpenedByInit: true, // shapes the identity-mismatch advice (GH#5558)
AutoStart: initServerMode && os.Getenv("BEADS_DOLT_AUTO_START") != "0",
AutoStart: initServerMode && !externalServer && os.Getenv("BEADS_DOLT_AUTO_START") != "0",
ServerTLS: initDoltServerTLSFromEnv(),
}
if serverHost != "" {
@ -1727,6 +1764,12 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
}
return &exitError{Code: 1}
}
if externalServer {
if msg := externalServerUnreachableMessage(err); msg != "" {
fmt.Fprint(os.Stderr, msg)
return &exitError{Code: 1}
}
}
fmt.Fprintf(os.Stderr, "Error: failed to open Dolt store: %v\n", err)
return &exitError{Code: 1}
}

View file

@ -0,0 +1,430 @@
//go:build cgo
package main
import (
"encoding/json"
"errors"
"fmt"
"io"
"net"
"os"
"os/exec"
"path/filepath"
"runtime"
"strconv"
"strings"
"sync"
"testing"
"time"
"github.com/steveyegge/beads/internal/configfile"
)
// `bd init --external` declares that the Dolt server is managed outside bd, so
// init must never start one. These tests own one boundary risk that no lower
// seam can show: init builds its dolt config by hand, so the flag reaches the
// auto-start decision only if init carries it there. They run the real bd
// binary against a dolt shim that records every launch, which makes the
// outcome observable without a real server and leaves nothing running.
// externalInitFixture is one fresh project plus a dolt shim for `bd init`
// attempts. The shim sits first on PATH, records every invocation and fails.
type externalInitFixture struct {
t *testing.T
repoDir string
home string
shimDir string
launches string
}
type externalInitResult struct {
output string // combined stdout and stderr
failed bool // bd exited non-zero
launches string // dolt invocations the shim saw, one per line
}
func newExternalInitFixture(t *testing.T) *externalInitFixture {
t.Helper()
if runtime.GOOS == "windows" {
t.Skip("the dolt shim is a POSIX shell script")
}
f := &externalInitFixture{t: t, repoDir: t.TempDir(), home: t.TempDir(), shimDir: t.TempDir()}
f.launches = filepath.Join(f.shimDir, "invocations")
shim := "#!/bin/sh\nprintf '%s\\n' \"$*\" >> \"$EXTERNAL_INIT_SHIM_LOG\"\nexit 1\n"
if err := os.WriteFile(filepath.Join(f.shimDir, "dolt"), []byte(shim), 0o755); err != nil {
t.Fatal(err)
}
initGitRepo(t, f.repoDir)
return f
}
// run executes bd in the project. autoStart is the value of
// BEADS_DOLT_AUTO_START, or "" to leave it unset: an unpinned environment is
// what most callers run in, so it is the one that matters here.
func (f *externalInitFixture) run(autoStart string, args ...string) externalInitResult {
f.t.Helper()
env := append(envWithoutBeadsStorageSettings(),
"HOME="+f.home,
"XDG_CONFIG_HOME="+filepath.Join(f.home, ".config"),
"BEADS_TEST_IGNORE_REPO_CONFIG=1",
"BD_DISABLE_METRICS=1",
"PATH="+f.shimDir+string(os.PathListSeparator)+os.Getenv("PATH"),
"EXTERNAL_INIT_SHIM_LOG="+f.launches,
)
if autoStart != "" {
env = append(env, "BEADS_DOLT_AUTO_START="+autoStart)
}
out, err := runExternalServerBD(f.t, f.repoDir, env, args...)
var exitErr *exec.ExitError
if err != nil && !errors.As(err, &exitErr) {
f.t.Fatalf("bd %s did not run: %v\n%s", strings.Join(args, " "), err, out)
}
launches, _ := os.ReadFile(f.launches)
return externalInitResult{output: out, failed: err != nil, launches: strings.TrimSpace(string(launches))}
}
// externalEndpoint is the server an --external init is pointed at.
type externalEndpoint struct {
flags []string // --server-host/--server-port, or --server-socket
network string // "tcp" or "unix"
addr string // host:port or the socket path, as bd reports it
}
func tcpEndpoint(port int) externalEndpoint {
return externalEndpoint{
flags: []string{"--server-host", "127.0.0.1", "--server-port", strconv.Itoa(port)},
network: "tcp",
addr: net.JoinHostPort("127.0.0.1", strconv.Itoa(port)),
}
}
func unixEndpoint(path string) externalEndpoint {
return externalEndpoint{flags: []string{"--server-socket", path}, network: "unix", addr: path}
}
// externalInitSocketPath returns an unused unix socket path. Socket paths are
// capped near 104 bytes and t.TempDir() nests too deeply under some runners.
func externalInitSocketPath(t *testing.T) string {
t.Helper()
dir, err := os.MkdirTemp("", "bdx")
if err != nil {
t.Fatal(err)
}
if len(filepath.Join(dir, "dolt.sock")) > 100 {
_ = os.RemoveAll(dir)
if dir, err = os.MkdirTemp("/tmp", "bdx"); err != nil {
t.Fatal(err)
}
}
t.Cleanup(func() { _ = os.RemoveAll(dir) })
return filepath.Join(dir, "dolt.sock")
}
// serveUnixProxy listens on a fresh unix socket and forwards each connection
// to target, so bd sees a reachable server at a socket path. The returned
// func reports how many connections bd made through it.
func serveUnixProxy(t *testing.T, target string) (string, func() int) {
t.Helper()
path := externalInitSocketPath(t)
ln, err := net.Listen("unix", path)
if err != nil {
t.Fatalf("listen on %s: %v", path, err)
}
t.Cleanup(func() { _ = ln.Close() })
var mu sync.Mutex
accepted := 0
go func() {
for {
client, err := ln.Accept()
if err != nil {
return
}
mu.Lock()
accepted++
mu.Unlock()
go func() {
defer client.Close()
upstream, err := net.Dial("tcp", target)
if err != nil {
return
}
defer upstream.Close()
done := make(chan struct{}, 2)
go func() { _, _ = io.Copy(upstream, client); done <- struct{}{} }()
go func() { _, _ = io.Copy(client, upstream); done <- struct{}{} }()
<-done // either side closing ends the session; the deferred closes release the other copy
}()
}
}()
return path, func() int { mu.Lock(); defer mu.Unlock(); return accepted }
}
// requireNoLaunch fails when bd tried to run dolt at all: an externally
// managed server is never started by bd, and the shim is how a start shows.
func requireNoLaunch(t *testing.T, res externalInitResult) {
t.Helper()
if res.launches != "" {
t.Errorf("bd launched dolt although the server is externally managed (dolt %s):\n%s",
strings.ReplaceAll(res.launches, "\n", "; dolt "), res.output)
}
}
// requireExternalUnreachableMessage checks the one wording an --external init
// gives for an endpoint it cannot reach: it names the endpoint, says the server
// is declared external and that bd did not start one, and never advises
// `bd dolt start`, which would start the server --external says bd must not.
func requireExternalUnreachableMessage(t *testing.T, output, endpoint string) {
t.Helper()
for _, want := range []string{endpoint, "externally managed", "did not start"} {
if !strings.Contains(output, want) {
t.Errorf("output does not contain %q:\n%s", want, output)
}
}
if strings.Contains(output, "bd dolt start") {
t.Errorf("output advises `bd dolt start`:\n%s", output)
}
}
func requireNothingListening(t *testing.T, network, addr string) {
t.Helper()
conn, err := net.DialTimeout(network, addr, time.Second)
if err == nil {
_ = conn.Close()
t.Errorf("something accepts connections on %s %s after init", network, addr)
}
}
// requireDoltRootEmpty fails when .beads/dolt holds anything: init leaves at
// most an empty marker directory for an external server, so any entry is a
// server root a local dolt created.
func requireDoltRootEmpty(t *testing.T, repoDir string) {
t.Helper()
entries, err := os.ReadDir(filepath.Join(repoDir, ".beads", "dolt"))
if errors.Is(err, os.ErrNotExist) {
return
}
if err != nil {
t.Fatal(err)
}
if len(entries) > 0 {
names := make([]string, 0, len(entries))
for _, e := range entries {
names = append(names, e.Name())
}
t.Errorf(".beads/dolt holds %v, which init did not put there", names)
}
}
// TestInitServerExternalDeadPortStartsNoServer is the end-to-end boundary for
// --external: a dead endpoint must fail loudly instead of making bd launch a
// dolt of its own on the port the caller named.
func TestInitServerExternalDeadPortStartsNoServer(t *testing.T) {
f := newExternalInitFixture(t)
ep := tcpEndpoint(freeLoopbackPort(t))
res := f.run("", append(append([]string{"init", "--quiet", "--server", "--external"}, ep.flags...),
"--prefix", "x", "--skip-hooks", "--skip-agents")...)
if !res.failed {
t.Errorf("bd init --server --external succeeded against a dead endpoint %s:\n%s", ep.addr, res.output)
}
requireNoLaunch(t, res)
requireExternalUnreachableMessage(t, res.output, ep.addr)
requireNothingListening(t, ep.network, ep.addr)
requireDoltRootEmpty(t, f.repoDir)
}
// TestInitServerExternalNoPortStartsNoServer is the --external boundary that
// rule 2c (#5934) cannot see: the argv and the environment name no port, so
// nothing but the flag declares the server external. A server init in that
// shape launches a repo-local dolt by design (see
// TestInitServerWithoutNamedPortStillStartsServer), so with --external it must
// fail instead, and say that bd did not start one. There is no endpoint to
// name, so the wording is checked without one: the child inherits
// BEADS_TEST_MODE, under which the store dials port 1 rather than leave an
// unnamed port at 0, so the port-0 wording itself is pinned by
// TestExternalServerUnreachableMessage.
func TestInitServerExternalNoPortStartsNoServer(t *testing.T) {
f := newExternalInitFixture(t)
res := f.run("", "init", "--quiet", "--server", "--external", "--prefix", "x", "--skip-hooks", "--skip-agents")
if !res.failed {
t.Errorf("bd init --server --external succeeded with no server named:\n%s", res.output)
}
requireNoLaunch(t, res)
requireDoltRootEmpty(t, f.repoDir)
for _, want := range []string{"externally managed", "did not start"} {
if !strings.Contains(res.output, want) {
t.Errorf("output does not contain %q:\n%s", want, res.output)
}
}
if strings.Contains(res.output, "bd dolt start") {
t.Errorf("output advises `bd dolt start`:\n%s", res.output)
}
}
// TestInitSharedServerExternalDeadPortStillFails pins the sibling route that
// already honors --external: the same dead endpoint under --shared-server
// exits non-zero without launching dolt. Without it the test above could pass
// because every init fails here, not because --server honors the flag.
func TestInitSharedServerExternalDeadPortStillFails(t *testing.T) {
f := newExternalInitFixture(t)
ep := tcpEndpoint(freeLoopbackPort(t))
res := f.run("", append(append([]string{"init", "--quiet", "--shared-server", "--external"}, ep.flags...),
"--prefix", "x", "--skip-hooks", "--skip-agents")...)
if !res.failed {
t.Errorf("bd init --shared-server --external succeeded against a dead endpoint %s:\n%s", ep.addr, res.output)
}
requireNoLaunch(t, res)
}
// TestInitServerWithoutNamedPortStillStartsServer pins the other half of the
// contract: a --server init that names no port is where bd starts a repo-local
// dolt by design, so the no-launch assertions above cannot pass merely because
// nothing can ever launch one. It names no port, in argv or in the environment
// (envWithoutBeadsStorageSettings drops every BEADS_DOLT_* variable): a named
// port is declared external by rule 2c (#5934) with or without --external, so
// it would launch nothing here either way.
func TestInitServerWithoutNamedPortStillStartsServer(t *testing.T) {
f := newExternalInitFixture(t)
res := f.run("", "init", "--quiet", "--server", "--prefix", "x", "--skip-hooks", "--skip-agents")
if res.launches == "" {
t.Errorf("bd init --server naming no port never reached dolt, so auto-start regressed:\n%s", res.output)
}
}
// TestInitExternalUnreachableMessage covers the wording across the routes an
// --external init can take. Every one of them gives the same message, whether
// auto-start is pinned off by the environment, the server is a shared one, or
// the endpoint is a socket.
func TestInitExternalUnreachableMessage(t *testing.T) {
cases := []struct {
name string
mode string
autoStart string
endpoint func(t *testing.T) externalEndpoint
}{
{"server host:port with auto-start pinned off", "--server", "0",
func(t *testing.T) externalEndpoint { return tcpEndpoint(freeLoopbackPort(t)) }},
{"shared-server host:port", "--shared-server", "",
func(t *testing.T) externalEndpoint { return tcpEndpoint(freeLoopbackPort(t)) }},
{"server socket", "--server", "",
func(t *testing.T) externalEndpoint { return unixEndpoint(externalInitSocketPath(t)) }},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
f := newExternalInitFixture(t)
ep := tc.endpoint(t)
res := f.run(tc.autoStart, append(append([]string{"init", "--quiet", tc.mode, "--external"}, ep.flags...),
"--prefix", "x", "--skip-hooks", "--skip-agents")...)
if !res.failed {
t.Fatalf("bd init succeeded against a dead endpoint %s:\n%s", ep.addr, res.output)
}
requireExternalUnreachableMessage(t, res.output, ep.addr)
})
}
}
// TestInitExternalProvisionerShape runs init with the argv a provisioner of an
// externally managed server uses, in both endpoint forms, with auto-start
// unset and pinned off, against a server that is up and one that is not. Every
// cell is a control: a port named with --server-port is already declared
// external by rule 2c (#5934), and a socket is never auto-started, so none of
// them launched dolt before init honored --external either. They pin that the
// provisioner shape keeps launching nothing, keeps failing against a dead
// endpoint, and still records the endpoint it was given. The reachable cells
// need the Dolt test server and skip without it.
func TestInitExternalProvisionerShape(t *testing.T) {
for _, form := range []string{"host-port", "socket"} {
for _, autoStart := range []string{"unset", "0"} {
for _, reachable := range []bool{false, true} {
state := "unreachable"
if reachable {
state = "reachable"
}
t.Run(fmt.Sprintf("%s/auto-start=%s/%s", form, autoStart, state), func(t *testing.T) {
runProvisionerCell(t, form, autoStart, reachable)
})
}
}
}
}
func runProvisionerCell(t *testing.T, form, autoStart string, reachable bool) {
t.Helper()
if reachable {
skipIfNoDolt(t)
}
f := newExternalInitFixture(t)
var ep externalEndpoint
var socketConnections func() int
switch {
case form == "host-port" && reachable:
ep = tcpEndpoint(testDoltServerPort)
case form == "host-port":
ep = tcpEndpoint(freeLoopbackPort(t))
case reachable:
var sock string
sock, socketConnections = serveUnixProxy(t, net.JoinHostPort("127.0.0.1", strconv.Itoa(testDoltServerPort)))
ep = unixEndpoint(sock)
default:
ep = unixEndpoint(externalInitSocketPath(t))
}
database := "provisioned"
if reachable {
database = uniqueTestDBName(t)
t.Cleanup(func() { dropTestDatabase(database, testDoltServerPort) })
}
args := append([]string{"init", "--init-if-missing", "--quiet", "--server", "--external"}, ep.flags...)
args = append(args, "-p", "prov", "--skip-hooks", "--skip-agents", "--database", database, f.repoDir)
pin := ""
if autoStart == "0" {
pin = "0"
}
res := f.run(pin, args...)
requireNoLaunch(t, res)
if !reachable {
if !res.failed {
t.Errorf("bd init succeeded against an unreachable endpoint %s:\n%s", ep.addr, res.output)
}
requireNothingListening(t, ep.network, ep.addr)
return
}
if res.failed {
t.Fatalf("bd init against the reachable server %s failed:\n%s", ep.addr, res.output)
}
requireDoltRootEmpty(t, f.repoDir)
data, err := os.ReadFile(filepath.Join(f.repoDir, ".beads", "metadata.json"))
if err != nil {
t.Fatalf("expected metadata.json after init: %v", err)
}
var meta configfile.Config
if err := json.Unmarshal(data, &meta); err != nil {
t.Fatalf("parse metadata.json: %v\n%s", err, data)
}
if form == "socket" {
if meta.DoltServerSocket != ep.addr {
t.Errorf("metadata.json dolt_server_socket = %q, want the socket init was given, %q", meta.DoltServerSocket, ep.addr)
}
if socketConnections() == 0 {
t.Errorf("bd never connected through the socket %s", ep.addr)
}
return
}
if meta.DoltServerHost != "127.0.0.1" || meta.DoltServerPort != testDoltServerPort {
t.Errorf("metadata.json names %s:%d, want the endpoint init was given, %s", meta.DoltServerHost, meta.DoltServerPort, ep.addr)
}
}

View file

@ -0,0 +1,97 @@
package main
import (
"errors"
"fmt"
"net"
"strings"
"testing"
)
// TestExternalServerUnreachableMessage pins which failures get the --external
// wording. Only a failed dial may: the message claims the server could not be
// reached, so any other open failure (an identity mismatch, a handshake that
// was reset) must keep its own text instead of being reported as "externally
// managed".
func TestExternalServerUnreachableMessage(t *testing.T) {
refused := errors.New("connect: connection refused")
dial := &net.OpError{
Op: "dial",
Net: "tcp",
Addr: &net.TCPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 3307},
Err: refused,
}
tests := []struct {
name string
err error
wantEndpoint string // "" means the error is not rewritten
}{
{"dial error", dial, "127.0.0.1:3307"},
{
// The store wraps the dial error with %w and its own advice.
"dial error wrapped like the store does",
fmt.Errorf("Dolt server unreachable at 127.0.0.1:3307: %w\n\nThe Dolt server may not be running.", dial),
"127.0.0.1:3307",
},
{
"unix socket dial error",
&net.OpError{Op: "dial", Net: "unix", Addr: &net.UnixAddr{Name: "/run/dolt.sock", Net: "unix"}, Err: refused},
"/run/dolt.sock",
},
{
// A name that does not resolve has no address to report.
"dial error without an address",
&net.OpError{Op: "dial", Net: "tcp", Err: errors.New("no such host")},
"the configured endpoint",
},
{"read error after connecting", &net.OpError{Op: "read", Net: "tcp", Err: errors.New("connection reset by peer")}, ""},
{"not a network error", errors.New("project identity mismatch"), ""},
}
// Every rewritten message says the server is declared external and that bd
// did not start one, and never advises `bd dolt start`.
requireDeclaredExternal := func(t *testing.T, got string, wants ...string) {
t.Helper()
for _, want := range append(wants, "externally managed", "did not start") {
if !strings.Contains(got, want) {
t.Errorf("message does not contain %q:\n%s", want, got)
}
}
if strings.Contains(got, "bd dolt start") {
t.Errorf("message advises `bd dolt start`:\n%s", got)
}
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := externalServerUnreachableMessage(tt.err)
if tt.wantEndpoint == "" {
if got != "" {
t.Fatalf("message = %q, want none for an error that is not a failed dial", got)
}
return
}
requireDeclaredExternal(t, got, tt.wantEndpoint)
})
}
// A dial to port 0 is an init that was never told a port: the address is a
// placeholder, not the server's endpoint, so the message must not offer it
// as one. The first line quotes the dialled address, so it is cut out
// before looking.
t.Run("dial error with no port named", func(t *testing.T) {
noPort := &net.OpError{
Op: "dial",
Net: "tcp",
Addr: &net.TCPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0},
Err: refused,
}
got := externalServerUnreachableMessage(noPort)
if got == "" {
t.Fatal("message = none, want the --external wording for a failed dial")
}
requireDeclaredExternal(t, got)
if strings.Contains(strings.ReplaceAll(got, noPort.Error(), ""), ":0") {
t.Errorf("message offers port 0 as the endpoint:\n%s", got)
}
})
}

View file

@ -24,6 +24,19 @@ import (
// SQLite files, and the bounded local version witness; storage internals stay
// behind the driver boundary.
func guardLegacyUpgradeWorkspace(beadsDir string) error {
return guardLegacyUpgradeWorkspaceForInit(beadsDir, false)
}
// guardLegacyUpgradeWorkspaceForInit is guardLegacyUpgradeWorkspace for a caller
// that has already resolved server intent from a source the workspace does not
// yet record: `bd init --server`, whose flag is the only place that choice lives
// until init has written it. The guard cannot see the flag, so initSelectsServer
// carries it in. It is consulted for exactly one thing, the empty-root admission
// below, and is deliberately not folded into the workspace's own server mode:
// that would also move a non-empty root with an unreadable witness onto the
// warn-and-open arm, and an embedded repository beside a non-empty .beads/dolt
// onto the refusing one.
func guardLegacyUpgradeWorkspaceForInit(beadsDir string, initSelectsServer bool) error {
if beadsDir == "" {
return nil
}
@ -75,6 +88,15 @@ func guardLegacyUpgradeWorkspace(beadsDir string) error {
// did not.
return nil
}
if initSelectsServer && !present && isEmptyDirectory(filepath.Join(beadsDir, "dolt")) {
// Init has already chosen a server, so this is the empty root the
// serverMode arm below admits for a workspace that records the choice: it
// holds no Dolt data a legacy release could have left, and bd makes it
// itself on use, so a retry after a first attempt that could not reach a
// server finds exactly this. A present witness, a root holding any entry,
// and every caller that does not pass the flag are decided as before.
return nil
}
if serverMode {
if !present && isEmptyDirectory(filepath.Join(beadsDir, "dolt")) {
// An empty .beads/dolt holds no Dolt data, so no legacy release

View file

@ -0,0 +1,87 @@
//go:build cgo
package main
import (
"os"
"path/filepath"
"slices"
"strconv"
"testing"
)
// TestInitServerFlagAdmitsEmptyDoltRootWithoutConfig reproduces the retry shape
// with nothing on disk that records the server choice: an empty .beads/dolt and
// neither config.yaml nor metadata.json, so the --server flag is the only place
// the intent lives. The legacy guard used to refuse that init as a legacy Dolt
// workspace, so the workspace was never created and no bd command could repair
// it.
func TestInitServerFlagAdmitsEmptyDoltRootWithoutConfig(t *testing.T) {
skipIfNoDolt(t)
env := externalServerTestEnv(t)
repoDir := t.TempDir()
initGitRepo(t, repoDir)
beadsDir := filepath.Join(repoDir, ".beads")
if err := os.MkdirAll(filepath.Join(beadsDir, "dolt"), 0o700); err != nil {
t.Fatal(err)
}
database := uniqueTestDBName(t)
t.Cleanup(func() { dropTestDatabase(database, testDoltServerPort) })
out, err := runExternalServerBD(t, repoDir, env, externalServerInitArgs(database)...)
if err != nil {
t.Fatalf("bd init --server over an empty .beads/dolt failed: %v\n%s", err, out)
}
assertCurrentVersionWitness(t, beadsDir)
}
// TestInitServerFlagRetryAfterFailedFirstAttempt replays the reported sequence: a
// first `bd init --server` that cannot reach a server fails after creating the
// local Dolt root, leaving an empty .beads/dolt and no witness, and the same
// command run again once the server is up must succeed instead of being refused
// as a legacy workspace over the root the first attempt made itself.
func TestInitServerFlagRetryAfterFailedFirstAttempt(t *testing.T) {
skipIfNoDolt(t)
env := externalServerTestEnv(t)
// The first attempt has to fail without starting a server of its own: one
// that started and then failed would leave a populated .beads/dolt, which
// the guard refuses by design. externalServerTestEnv pins
// BEADS_DOLT_AUTO_START=0 for exactly that, which keeps the attempt
// deterministic even once init's separate --external handling stops trying
// to start a per-project server. Fail here, naming the reason, if a change to
// that helper drops it.
if !slices.Contains(env, "BEADS_DOLT_AUTO_START=0") {
t.Fatal("externalServerTestEnv must set BEADS_DOLT_AUTO_START=0: the failed first attempt must not start a server of its own")
}
repoDir := t.TempDir()
initGitRepo(t, repoDir)
beadsDir := filepath.Join(repoDir, ".beads")
database := uniqueTestDBName(t)
t.Cleanup(func() { dropTestDatabase(database, testDoltServerPort) })
out, err := runExternalServerBD(t, repoDir, env,
externalServerInitArgs(database, "--server-port", strconv.Itoa(freeLoopbackPort(t)))...)
if err == nil {
t.Fatalf("precondition: bd init --server against an unreachable server succeeded:\n%s", out)
}
// The retry only has something to fix if the failed attempt left exactly
// this. Any other leftover is a finding about init, not a reason to loosen
// what follows.
entries, readErr := os.ReadDir(filepath.Join(beadsDir, "dolt"))
if readErr != nil || len(entries) != 0 {
t.Fatalf("precondition: the failed first attempt should leave an empty .beads/dolt, found %d entries (err %v)", len(entries), readErr)
}
if _, statErr := os.Stat(filepath.Join(beadsDir, localVersionFile)); !os.IsNotExist(statErr) {
t.Fatalf("precondition: the failed first attempt should leave no %s (stat err %v)", localVersionFile, statErr)
}
out, err = runExternalServerBD(t, repoDir, env, externalServerInitArgs(database)...)
if err != nil {
t.Fatalf("retrying bd init --server over the empty .beads/dolt the first attempt left failed: %v\n%s", err, out)
}
assertCurrentVersionWitness(t, beadsDir)
}

View file

@ -0,0 +1,143 @@
package main
import (
"fmt"
"os"
"path/filepath"
"testing"
)
// TestLegacyUpgradeGuardForInitAdmitsEmptyDoltRoot pins the one thing init's own
// intent unlocks. `bd init --server` resolves server mode from the flag, a source
// the workspace does not record until init has written it. A retry over the empty
// .beads/dolt that a failed first attempt leaves behind therefore looks like an
// embedded workspace with a local Dolt root, and the guard refuses it. Told what
// init already knows, the guard gives that root the admission a config-selected
// server workspace gets. Asked without it, in either form, it still refuses, so
// the admission cannot pass vacuously.
func TestLegacyUpgradeGuardForInitAdmitsEmptyDoltRoot(t *testing.T) {
warnings := captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, "", "", "")
if err := guardLegacyUpgradeWorkspaceForInit(beadsDir, true); err != nil {
t.Fatalf("guardLegacyUpgradeWorkspaceForInit(dir, true) = %v, want nil", err)
}
if warnings.Len() != 0 {
t.Fatalf("guard warned about an absent witness: %q", warnings.String())
}
if err := guardLegacyUpgradeWorkspaceForInit(beadsDir, false); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspaceForInit(dir, false) = %v, want migration refusal", err)
}
if err := guardLegacyUpgradeWorkspace(beadsDir); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspace(dir) = %v, want migration refusal", err)
}
}
// TestLegacyUpgradeGuardForInitAdmissionStaysNarrow proves init's intent relaxes
// nothing beyond an empty, witness-less .beads/dolt. With it set, anything that
// could be legacy data still refuses, and the outcomes a broader reading of the
// flag would move (treating it as if the workspace itself selected server mode)
// stay where they are.
func TestLegacyUpgradeGuardForInitAdmissionStaysNarrow(t *testing.T) {
for _, entry := range []string{"beads", ".dolt", "stray-file", "symlink"} {
t.Run("root holding "+entry, func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, "", "", "")
path := filepath.Join(beadsDir, "dolt", entry)
var err error
switch entry {
case "stray-file":
err = os.WriteFile(path, nil, 0o600)
case "symlink":
if err = os.Symlink(t.TempDir(), path); err != nil {
t.Skipf("symlink capability unavailable: %v", err)
}
default:
err = os.Mkdir(path, 0o700)
}
if err != nil {
t.Fatal(err)
}
if err := guardLegacyUpgradeWorkspaceForInit(beadsDir, true); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspaceForInit(dir, true) = %v, want migration refusal", err)
}
})
}
for _, version := range []string{"0.49.6", "0.62.0"} {
t.Run("pre-1.0 witness "+version, func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, "", "", version)
if err := guardLegacyUpgradeWorkspaceForInit(beadsDir, true); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspaceForInit(dir, true) = %v, want migration refusal", err)
}
})
}
t.Run("blank witness over a non-empty root", func(t *testing.T) {
warnings := captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, "", "", "")
if err := os.Mkdir(filepath.Join(beadsDir, "dolt", "beads"), 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(beadsDir, localVersionFile), []byte("\n"), 0o600); err != nil {
t.Fatal(err)
}
// A workspace that selects server mode itself warns and opens over an
// unreadable witness. Init's intent must not move this root onto that arm.
if err := guardLegacyUpgradeWorkspaceForInit(beadsDir, true); !isLegacyUpgradeRefusal(err) {
t.Fatalf("guardLegacyUpgradeWorkspaceForInit(dir, true) = %v, want migration refusal", err)
}
if warnings.Len() != 0 {
t.Fatalf("guard took the unreadable-witness arm: %q", warnings.String())
}
})
t.Run("symlinked dolt root", func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, "", "", "")
root := filepath.Join(beadsDir, "dolt")
if err := os.Remove(root); err != nil {
t.Fatal(err)
}
if err := os.Symlink(t.TempDir(), root); err != nil {
t.Skipf("symlink capability unavailable: %v", err)
}
// hasLegacyDoltRoot does not follow a symlink, so the guard never takes
// such a root for a local Dolt root and it never reaches the empty-root
// admission. Init's intent has to leave its outcome exactly where every
// other caller finds it.
want := fmt.Sprint(guardLegacyUpgradeWorkspace(beadsDir))
if got := fmt.Sprint(guardLegacyUpgradeWorkspaceForInit(beadsDir, true)); got != want {
t.Fatalf("guardLegacyUpgradeWorkspaceForInit(dir, true) = %s, want %s (unchanged by init's intent)", got, want)
}
})
t.Run("embedded repository beside a non-empty root", func(t *testing.T) {
captureLegacyUpgradeWarnings(t)
beadsDir := writeEmptyDoltRootServerWorkspace(t, "", "", "")
repo := filepath.Join(beadsDir, "embeddeddolt", "beads", ".dolt")
if err := os.MkdirAll(repo, 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(repo, "repo-entry"), []byte("opaque"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(beadsDir, "dolt", "stray-file"), nil, 0o600); err != nil {
t.Fatal(err)
}
// An embedded repository admits the workspace before server intent is
// consulted at all. Folding init's intent into the workspace's own mode
// would send this one to the refusing arm.
for _, initSelectsServer := range []bool{false, true} {
if err := guardLegacyUpgradeWorkspaceForInit(beadsDir, initSelectsServer); err != nil {
t.Fatalf("guardLegacyUpgradeWorkspaceForInit(dir, %t) = %v, want nil", initSelectsServer, err)
}
}
})
}