feat(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188)

* feat(backends): registry Remote + optional OpenWith(ctx, dir, OpenOptions)

Slice S1: backends.Backend gains Remote bool and an optional
OpenWith(ctx, beadsDir, OpenOptions{Credential, HTTPClient, UserAgent}) so a
registered extension backend can honor a per-open credential instead of
dialing with a process-global client — the motivating case is one embedder
process serving many workspaces with distinct credentials. Open keeps
working unmodified for every existing backend: Backend.OpenWithOptions calls
OpenWith when present, otherwise falls back to Open and ignores
HTTPClient/UserAgent, but refuses (ErrCredentialWithoutOpenWith) rather than
silently dropping a non-nil Credential.

Public beads.OpenBestAvailableWith(ctx, beadsDir, opts) carries this through
the SDK surface (mirrored in beads_nocgo.go and aliased in backend/backend.go
and beads.go); OpenBestAvailable is now that call with a zero OpenOptions,
identical to its prior behavior for Dolt, embedded Dolt, and every registered
backend. The plain-Dolt path (no registered backend) applies the same
Credential refusal, since Dolt has no per-open credential seam either.

doltserver.ResolvePhysicalRoots now checks backends.IsRemote(cfg.GetBackend())
before every Dolt-mode branch, including the shared-server check (which reads
only env/config.yaml and never consults cfg) — without this ordering, a global
BEADS_DOLT_SHARED_SERVER=1 would hijack a remote-backend workspace into
reporting a bogus local Dolt root it will never open.

Tests: backends_test new file open_with_test.go covers OpenWithOptions
dispatch/back-compat/Credential refusal and Remote/IsRemote; root package
open_backend_selection_test.go adds a fake OpenWith registrant proving
dispatch and option pass-through through OpenBestAvailableWith, zero-options
back-compat for every path (registered w/ and w/o OpenWith, plain Dolt), and
the Credential-without-OpenWith refusal on both paths; doltserver
physical_root_test.go adds the registered-remote-backend case including the
shared-server-override ordering regression test. Verified under both cgo and
nocgo builds. Live-mutated each new guard (the Credential refusal, the
OpenWith dispatch, the ResolvePhysicalRoots remote-backend case, and the
plain-Dolt Credential refusal) one at a time and confirmed RED before
reverting to GREEN.

No HTTP client code added; that is a later slice.

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

* fixup(backends): address Opus review findings on OpenWith (M1-M3, L1-L2)

- M1: frame cmd/bd store-open errors for remote backends as unreachable
  server failures instead of Dolt-shaped "failed to open database"
  advice (openStoreErrorMessage, backendNameForErrorFraming), with tests.
- M2: rewrite the OpenBestAvailable/OpenBestAvailableWith back-compat
  subtest to assert fixed expected outcomes (error identity/message,
  returned store behavior) now that the two functions are identical,
  instead of comparing them to each other.
- M3: document and enforce the OpenWith contract: an implementation that
  receives a non-nil Credential it cannot type-assert to its expected
  type must refuse with the new ErrUnsupportedCredential sentinel,
  verified with a fake registrant.
- L1: document that a nil OpenOptions.Credential means the backend's
  default/ambient auth, and that multi-tenant embedders must pass a
  non-nil Credential (RequireCredential deferred to S2).
- L2: fail closed on HTTPClient/UserAgent passed to a backend without
  OpenWith, mirroring the existing Credential refusal, via new
  ErrHTTPClientWithoutOpenWith/ErrUserAgentWithoutOpenWith sentinels.

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

* build(bazel): auto-sync BUILD files

Applied from the bazel-sync-patch artifact of https://github.com/gastownhall/beads/actions/runs/37195230844
(`make bazel-sync`: gazelle, tools/bazel/go_srcs.py, bazel mod tidy).
Only BUILD.bazel, MODULE.bazel and MODULE.bazel.lock are ever pushed; see
scripts/bazel-autofix-push.sh.

* fix(backends): keep the store-open error chain through the remote framing

Maintainer review fixes for the adopted PR (iteration 1).

openStoreErrorMessage returned a string, so ensureStoreActiveWithContext
rebuilt its error from text (%s) where base wrapped the open error with %w,
and the chain ended at the CLI's framing. Prime tells a store-open timeout
apart from a generic "storage unavailable" only through
errors.Is(err, context.DeadlineExceeded) on what ensureStoreActiveWithContext
returns (cmd/bd/prime.go), so the flattening silently downgraded that
diagnostic for every backend, Dolt included, not just the new Remote ones.

Replace the helper with openStoreError, which returns an error wrapping err
with %w on both arms. The message text is unchanged: "failed to open
database: <err>" for Dolt and any registered backend that is not Remote,
"failed to reach remote backend %q: <err>" for a Remote one. direct_mode.go
wraps the result with %w ahead of its Hint line; main.go keeps printing it
through HandleError("%v", ...), which only formats.

Tests:

- TestOpenStoreErrorFramesRemoteBackends (renamed from
  TestOpenStoreErrorMessageFramesRemoteBackends) now also asserts errors.Is
  on every arm, and the exact original text for the non-Remote arms.
- TestEnsureStoreActiveKeepsOpenErrorChain drives the real
  ensureStoreActiveWithContext against a registered backend whose open
  outlives its context, for a local and a Remote backend, and requires
  errors.Is(err, context.DeadlineExceeded) plus the framing prefix and the
  Hint line.
- TestFormatMemoriesForPrimeTimesOutOpeningRegisteredBackend is the
  unstubbed twin of TestFormatMemoriesForPrimeTimesOutOpeningStore and
  requires the timeout banner, not the "storage unavailable" one.

Measured at this head: turning direct_mode.go's outer %w into %v reddens
both chain-test rows and the prime test; turning the helper's %w into %v
reddens the framing test as well.

Non-gating cleanup in the same area:

- beads_cgo.go, beads_nocgo.go: OpenBestAvailableWith's doc and dispatch
  comments said only a non-nil Credential is refused. The code also refuses
  a non-nil HTTPClient and a non-empty UserAgent, each with its own
  ErrXWithoutOpenWith sentinel.
- internal/doltserver/physical_root.go: the Mode doc lists "remote-backend",
  and the RemoteBackend doc covers a registered Remote backend as well as a
  Dolt server on a non-local host.
- open_backend_selection_test.go: the plain-Dolt refusal test is a table
  over Credential, HTTPClient and UserAgent (renamed
  TestOpenBestAvailableWithRefusesPerOpenOptionsOnPlainDolt). Disabling the
  nocgo HTTPClient arm or the cgo UserAgent arm reddens only that row. The
  zero-options test's comment had the delegation backwards and pointed at
  beads.go; OpenBestAvailable delegates to OpenBestAvailableWith in
  beads_cgo.go and beads_nocgo.go.

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

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
This commit is contained in:
Julian Knutsen 2026-10-04 09:34:36 -07:00 • committed by GitHub
commit 2f1e8be3ca
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 1170 additions and 9 deletions

View file

@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- `backends.Backend` gains an optional `OpenWith(ctx, beadsDir, OpenOptions)`
and a `Remote bool` field for a registered extension backend (for example
an HTTP client registrant). `OpenOptions{Credential, HTTPClient,
UserAgent}` carries per-open injections — the motivating case is a single
embedder process serving many workspaces with distinct credentials against
a backend whose dialer would otherwise be process-global. `Open` keeps
working unmodified: a backend with no `OpenWith` falls back to it and
ignores `HTTPClient`/`UserAgent`, but refuses rather than silently drops a
non-nil `Credential`. The public SDK gains `beads.OpenBestAvailableWith`
(and the `backend` package's matching aliases); `beads.OpenBestAvailable`
is now that function called with a zero `OpenOptions`, with identical
behavior for every existing backend. `doltserver.ResolvePhysicalRoots` now
recognizes a registered remote backend (`backends.IsRemote`) before any
Dolt-mode check, so a remote-backend workspace is never misclassified as
having a local Dolt root to gate.
### Changed
- `bd preflight --fix --json` no longer returns a `Version sync` fix result:

View file

@ -140,6 +140,37 @@ type VCStatus = storage.Status
// store. See the field docs on the aliased struct.
type Backend = backends.Backend
// OpenOptions carries per-open injections (Credential, HTTPClient,
// UserAgent) that Backend.OpenWith may use. See the field docs on the
// aliased struct.
type OpenOptions = backends.OpenOptions
// Credential is the opaque per-open credential marker OpenOptions.Credential
// carries. A backend that needs one declares its own narrower interface and
// type-asserts the value its OpenWith receives. See the aliased type's docs.
type Credential = backends.Credential
// ErrCredentialWithoutOpenWith is returned by Backend.OpenWithOptions when
// OpenOptions.Credential is set but the backend has no OpenWith to honor it.
var ErrCredentialWithoutOpenWith = backends.ErrCredentialWithoutOpenWith
// ErrHTTPClientWithoutOpenWith is returned by Backend.OpenWithOptions when
// OpenOptions.HTTPClient is set but the backend has no OpenWith to honor it.
// Same fail-closed family as ErrCredentialWithoutOpenWith.
var ErrHTTPClientWithoutOpenWith = backends.ErrHTTPClientWithoutOpenWith
// ErrUserAgentWithoutOpenWith is returned by Backend.OpenWithOptions when
// OpenOptions.UserAgent is set but the backend has no OpenWith to honor it.
// Same fail-closed family as ErrCredentialWithoutOpenWith.
var ErrUserAgentWithoutOpenWith = backends.ErrUserAgentWithoutOpenWith
// ErrUnsupportedCredential is the typed refusal an OpenWith implementation
// MUST return (directly or wrapped, so errors.Is still matches) when it
// receives a non-nil Credential that does not type-assert to the narrower
// credential interface that backend's OpenWith expects. See the aliased
// error's docs in internal/storage/backends for the full contract.
var ErrUnsupportedCredential = backends.ErrUnsupportedCredential
// Register adds a backend under name. It is process-start wiring: call it
// once during initialization (typically from a registrant package's init that
// the embedding binary blank-imports), before any concurrent store access.
@ -171,6 +202,12 @@ func WorkspaceIsBeadsDir(name string) bool {
return backends.WorkspaceIsBeadsDir(name)
}
// IsRemote reports whether name is a registered backend that is a pure
// network client of a bd serve with no local database (see Backend.Remote).
func IsRemote(name string) bool {
return backends.IsRemote(name)
}
// Iter is the streaming-read cursor returned by the Iter* methods.
type Iter[T any] = storage.Iter[T]

View file

@ -24,6 +24,7 @@ import (
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/doltserver"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/storage/schema"
@ -37,6 +38,53 @@ import (
// safe to repeat.
type Storage = beads.Storage
// OpenOptions carries per-open injections (Credential, HTTPClient,
// UserAgent) for OpenBestAvailableWith. A registered backend's OpenWith may
// use these; Dolt and embedded Dolt have no per-open seam and never see
// them — instead, a non-nil Credential, non-nil HTTPClient, or non-empty
// UserAgent is always refused rather than silently dropped (see
// OpenBestAvailableWith). A nil Credential means "use the backend's own
// default authentication, which may include ambient environment state
// (env vars, a config file, a logged-in CLI session, ...)"; a multi-tenant
// embedder (one process serving many workspaces, such as gc, Gas City) MUST
// pass a non-nil Credential for every open, since ambient auth cannot
// distinguish one tenant's workspace from another's.
type OpenOptions = backends.OpenOptions
// Credential is the opaque per-open credential marker OpenOptions.Credential
// carries. See backends.Credential for the full contract: this package
// assigns it no methods and performs no assertions against it, so an
// embedder (for example gc, Gas City) can carry a per-workspace credential
// through OpenBestAvailableWith without this package knowing its shape.
type Credential = backends.Credential
// ErrCredentialWithoutOpenWith is returned by OpenBestAvailableWith when
// opts.Credential is set but nothing can honor it: either a registered
// backend has no OpenWith, or no backend is registered at all and the
// workspace is plain Dolt, which has no per-open credential seam. It is
// aliased here, not just in internal/storage/backends, because that package
// is unimportable outside this module: an embedder checking this error with
// errors.Is must do it through the public beads package.
var ErrCredentialWithoutOpenWith = backends.ErrCredentialWithoutOpenWith
// ErrHTTPClientWithoutOpenWith is returned by OpenBestAvailableWith when
// opts.HTTPClient is set but nothing can honor it. Same fail-closed family
// and aliasing rationale as ErrCredentialWithoutOpenWith.
var ErrHTTPClientWithoutOpenWith = backends.ErrHTTPClientWithoutOpenWith
// ErrUserAgentWithoutOpenWith is returned by OpenBestAvailableWith when
// opts.UserAgent is set but nothing can honor it. Same fail-closed family
// and aliasing rationale as ErrCredentialWithoutOpenWith.
var ErrUserAgentWithoutOpenWith = backends.ErrUserAgentWithoutOpenWith
// ErrUnsupportedCredential is the typed refusal a registered backend's
// OpenWith returns (directly or wrapped) when opts.Credential is non-nil but
// does not match the concrete credential type that backend's OpenWith
// expects. See backends.ErrUnsupportedCredential for the full contract.
// Aliased here for the same reason as ErrCredentialWithoutOpenWith: callers
// outside this module cannot import internal/storage/backends directly.
var ErrUnsupportedCredential = backends.ErrUnsupportedCredential
// configuredBackendUnavailable is the public open path's fail-closed refusal for
// metadata naming a removed or unrecognized backend. beadsDir and cfg let the
// refusal detect an already-present Dolt database and name the exact

View file

@ -22,7 +22,30 @@ import (
// The returned Storage must be closed when no longer needed.
//
// beadsDir is the path to the .beads directory.
//
// OpenBestAvailable is OpenBestAvailableWith with a zero OpenOptions; see that
// function for per-open injections into a registered backend.
func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {
return OpenBestAvailableWith(ctx, beadsDir, OpenOptions{})
}
// OpenBestAvailableWith is OpenBestAvailable plus per-open injections
// (Credential, HTTPClient, UserAgent) for a registered backend that
// implements Backend.OpenWith. It exists for an embedder whose single
// process serves many workspaces with distinct credentials (gc, Gas City is
// the motivating case) against a backend whose dialer would otherwise be
// process-global, making per-workspace credentials impossible through plain
// OpenBestAvailable.
//
// A zero OpenOptions behaves IDENTICALLY to OpenBestAvailable for every
// backend, registered or not: Dolt and embedded Dolt have no OpenWith and
// never see opts; a registered backend without OpenWith falls back to its
// Open exactly as OpenBestAvailable always has. The one exception across
// every path is a non-nil opts.Credential, non-nil opts.HTTPClient, or
// non-empty opts.UserAgent with nothing able to honor it — that is always a
// typed refusal (the matching ErrXWithoutOpenWith sentinel), never a silent
// open with the field ignored.
func OpenBestAvailableWith(ctx context.Context, beadsDir string, opts OpenOptions) (Storage, error) {
cfg, err := configfile.Load(beadsDir)
if err != nil {
return nil, fmt.Errorf("loading storage metadata: %w", err)
@ -36,9 +59,28 @@ func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {
// Dispatch to a registered extension backend before any Dolt path, mirroring
// the CLI store factories so SDK callers get the backend they registered
// instead of a silently-opened embedded Dolt store.
// instead of a silently-opened embedded Dolt store. OpenWithOptions calls
// OpenWith when the backend has one, else falls back to Open — except a
// non-nil Credential, non-nil HTTPClient, or non-empty UserAgent, which it
// refuses rather than silently drops.
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.Open(ctx, beadsDir)
return backend.OpenWithOptions(ctx, beadsDir, opts)
}
// No registered backend claims this workspace: it is plain Dolt
// (embedded or server), which has no per-open seam at all. Silently
// dropping a caller-supplied Credential, HTTPClient, or UserAgent here
// would be the same silent-loss hazard OpenWithOptions refuses for a
// registered backend without OpenWith (L2: fail closed on all three,
// not just Credential).
if opts.Credential != nil {
return nil, fmt.Errorf("beads: OpenOptions.Credential is not supported for backend %q (Dolt has no per-open credential seam): %w", cfg.GetBackend(), backends.ErrCredentialWithoutOpenWith)
}
if opts.HTTPClient != nil {
return nil, fmt.Errorf("beads: OpenOptions.HTTPClient is not supported for backend %q (Dolt has no per-open transport seam): %w", cfg.GetBackend(), backends.ErrHTTPClientWithoutOpenWith)
}
if opts.UserAgent != "" {
return nil, fmt.Errorf("beads: OpenOptions.UserAgent is not supported for backend %q (Dolt has no per-open transport seam): %w", cfg.GetBackend(), backends.ErrUserAgentWithoutOpenWith)
}
if cfg.IsDoltServerMode() {

View file

@ -16,7 +16,22 @@ import (
// supported; embedded Dolt returns an error directing the user to server mode.
//
// beadsDir is the path to the .beads directory.
//
// OpenBestAvailable is OpenBestAvailableWith with a zero OpenOptions; see that
// function for per-open injections into a registered backend. Mirrors the
// cgo build exactly for every path: a registered backend dispatches through
// OpenWithOptions regardless of CGO, so this build's only Dolt-specific
// difference from beads_cgo.go is the embedded-Dolt arm.
func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {
return OpenBestAvailableWith(ctx, beadsDir, OpenOptions{})
}
// OpenBestAvailableWith is OpenBestAvailable plus per-open injections
// (Credential, HTTPClient, UserAgent) for a registered backend that
// implements Backend.OpenWith. See the cgo build's doc comment for the full
// rationale; behavior here is identical except that embedded Dolt is
// unavailable without CGO.
func OpenBestAvailableWith(ctx context.Context, beadsDir string, opts OpenOptions) (Storage, error) {
cfg, err := configfile.Load(beadsDir)
if err != nil {
return nil, fmt.Errorf("loading storage metadata: %w", err)
@ -30,9 +45,28 @@ func OpenBestAvailable(ctx context.Context, beadsDir string) (Storage, error) {
// Dispatch to a registered extension backend before any Dolt path, mirroring
// the CLI store factories so SDK callers get the backend they registered
// instead of the embedded-Dolt-requires-CGO error.
// instead of the embedded-Dolt-requires-CGO error. OpenWithOptions calls
// OpenWith when the backend has one, else falls back to Open — except a
// non-nil Credential, non-nil HTTPClient, or non-empty UserAgent, which it
// refuses rather than silently drops.
if backend, ok := backends.Lookup(cfg.GetBackend()); ok {
return backend.Open(ctx, beadsDir)
return backend.OpenWithOptions(ctx, beadsDir, opts)
}
// No registered backend claims this workspace: it is plain Dolt (server
// mode is the only option without CGO), which has no per-open seam at
// all. Silently dropping a caller-supplied Credential, HTTPClient, or
// UserAgent here would be the same silent-loss hazard OpenWithOptions
// refuses for a registered backend without OpenWith (L2: fail closed on
// all three, not just Credential).
if opts.Credential != nil {
return nil, fmt.Errorf("beads: OpenOptions.Credential is not supported for backend %q (Dolt has no per-open credential seam): %w", cfg.GetBackend(), backends.ErrCredentialWithoutOpenWith)
}
if opts.HTTPClient != nil {
return nil, fmt.Errorf("beads: OpenOptions.HTTPClient is not supported for backend %q (Dolt has no per-open transport seam): %w", cfg.GetBackend(), backends.ErrHTTPClientWithoutOpenWith)
}
if opts.UserAgent != "" {
return nil, fmt.Errorf("beads: OpenOptions.UserAgent is not supported for backend %q (Dolt has no per-open transport seam): %w", cfg.GetBackend(), backends.ErrUserAgentWithoutOpenWith)
}
if cfg.IsDoltServerMode() {

View file

@ -3,7 +3,10 @@ package main
import (
"context"
"errors"
"fmt"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage"
@ -29,6 +32,42 @@ func registerContractBackend(t *testing.T, name string) {
t.Cleanup(func() { backends.Deregister(name) })
}
// registerContractRemoteBackend is registerContractBackend plus Remote: true,
// for tests of the IsRemote-aware store-open error framing.
func registerContractRemoteBackend(t *testing.T, name string) {
t.Helper()
backends.Register(name, backends.Backend{
Open: func(context.Context, string) (storage.DoltStorage, error) {
return nil, errRegistryReadWrite
},
OpenReadOnly: func(context.Context, string) (storage.DoltStorage, error) {
return nil, errRegistryReadOnly
},
WorkspaceIsBeadsDir: true,
Remote: true,
})
t.Cleanup(func() { backends.Deregister(name) })
}
// registerContractBlockingBackend registers a backend whose opens block until
// ctx is done and then fail with an error wrapping ctx.Err() — the shape of a
// dial that never completes — so a test can see whether a store-open timeout
// survives the CLI's error framing.
func registerContractBlockingBackend(t *testing.T, name string, remote bool) {
t.Helper()
open := func(ctx context.Context, _ string) (storage.DoltStorage, error) {
<-ctx.Done()
return nil, fmt.Errorf("dial contract backend: %w", ctx.Err())
}
backends.Register(name, backends.Backend{
Open: open,
OpenReadOnly: open,
WorkspaceIsBeadsDir: true,
Remote: remote,
})
t.Cleanup(func() { backends.Deregister(name) })
}
func writeContractBackendConfig(t *testing.T, backend string) string {
t.Helper()
beadsDir := t.TempDir()
@ -83,3 +122,108 @@ func TestOSSRegistersNoRemovedBackends(t *testing.T) {
}
}
}
// TestOpenStoreErrorFramesRemoteBackends is the M1 fix: a registered Remote
// backend's open failure must not be announced as "failed to open database" —
// there is no database, only a network client that could not reach or was
// refused by its remote server — while every other backend (Dolt, or a
// registered backend that is not Remote) keeps the original wording so this
// is additive. Every framing must keep the underlying error in the chain.
func TestOpenStoreErrorFramesRemoteBackends(t *testing.T) {
const remoteName = "contract-remote-error"
const localName = "contract-local-error"
registerContractRemoteBackend(t, remoteName)
registerContractBackend(t, localName)
underlying := errors.New("dial tcp 127.0.0.1:1: connect: connection refused")
got := openStoreError(remoteName, underlying)
msg := got.Error()
if !strings.Contains(msg, "remote backend") || !strings.Contains(msg, remoteName) {
t.Errorf("remote backend message = %q, want it to name the remote backend", msg)
}
if strings.Contains(msg, "failed to open database") {
t.Errorf("remote backend message = %q, want no Dolt-shaped \"failed to open database\" framing", msg)
}
if !strings.Contains(msg, underlying.Error()) {
t.Errorf("remote backend message = %q, want it to include the underlying error %v", msg, underlying)
}
if !errors.Is(got, underlying) {
t.Errorf("remote backend error = %v, want it to wrap the underlying error %v", got, underlying)
}
for _, name := range []string{localName, configfile.BackendDolt, "unregistered"} {
got := openStoreError(name, underlying)
if want := "failed to open database: " + underlying.Error(); got.Error() != want {
t.Errorf("backend %q message = %q, want the original framing %q", name, got, want)
}
if !errors.Is(got, underlying) {
t.Errorf("backend %q error = %v, want it to wrap the underlying error %v", name, got, underlying)
}
}
}
// TestEnsureStoreActiveKeepsOpenErrorChain drives the real
// ensureStoreActiveWithContext (prime's stubbed timeout test cannot see its
// framing) against a registered backend whose open outlives its context. The
// remote-aware framing must still wrap the open error: prime tells a
// store-open timeout apart from a generic "storage unavailable" only through
// errors.Is(err, context.DeadlineExceeded), so a framing that flattens the
// chain into text silently downgrades that diagnostic for every backend.
func TestEnsureStoreActiveKeepsOpenErrorChain(t *testing.T) {
tests := []struct {
name string
backend string
remote bool
wantPrefix string
}{
{
name: "local",
backend: "contract-open-chain-local",
wantPrefix: "failed to open database: ",
},
{
name: "remote",
backend: "contract-open-chain-remote",
remote: true,
wantPrefix: `failed to reach remote backend "contract-open-chain-remote": `,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
registerContractBlockingBackend(t, tt.backend, tt.remote)
t.Setenv("BEADS_DIR", writeContractBackendConfig(t, tt.backend))
oldStore, oldStoreActive := store, storeActive
store, storeActive = nil, false
t.Cleanup(func() { store, storeActive = oldStore, oldStoreActive })
ctx, cancel := context.WithTimeout(t.Context(), 50*time.Millisecond)
defer cancel()
err := ensureStoreActiveWithContext(ctx)
if !errors.Is(err, context.DeadlineExceeded) {
t.Fatalf("ensureStoreActiveWithContext() error = %v, want it to wrap context.DeadlineExceeded", err)
}
if msg := err.Error(); !strings.HasPrefix(msg, tt.wantPrefix) || !strings.Contains(msg, "\nHint: ") {
t.Errorf("ensureStoreActiveWithContext() error = %q, want prefix %q and a Hint line", msg, tt.wantPrefix)
}
})
}
}
// TestBackendNameForErrorFramingReadsMetadata covers direct mode's path to
// openStoreError: it has no cfg in scope at the open call site, so it must
// load metadata.json itself to learn the configured backend name.
func TestBackendNameForErrorFramingReadsMetadata(t *testing.T) {
const name = "contract-error-framing-metadata"
registerContractRemoteBackend(t, name)
beadsDir := writeContractBackendConfig(t, name)
if got := backendNameForErrorFraming(beadsDir); got != name {
t.Errorf("backendNameForErrorFraming(%q) = %q, want %q", beadsDir, got, name)
}
// A directory with no metadata.json at all must degrade to "" (plain
// Dolt framing) rather than erroring.
if got := backendNameForErrorFraming(t.TempDir()); got != "" {
t.Errorf("backendNameForErrorFraming(no metadata.json) = %q, want \"\"", got)
}
}

View file

@ -61,6 +61,39 @@ func normalizeLoadedConfig(cfg *configfile.Config) *configfile.Config {
return cfg
}
// openStoreError frames a failed store-open for the operator. A registered
// remote backend (backends.IsRemote) is a pure network client of a bd serve
// with no local database: "failed to open database" misnames the failure, and
// the "database"-shaped diagnostics the generic path otherwise invites
// (checking .dolt/ files, a wrong data directory, ...) are the wrong advice
// for what is really a dial, auth, or protocol failure against a remote
// server. Every other backend — Dolt, or a registered backend that isn't
// Remote — keeps the original, unqualified wording. Both framings wrap err
// with %w, so errors.Is/errors.As consumers (prime's context.DeadlineExceeded
// check, for one) see the same chain as before: only a Remote backend's
// message text changes, which is what keeps this additive rather than a
// behavior change for any existing workspace.
func openStoreError(backendName string, err error) error {
if backends.IsRemote(backendName) {
return fmt.Errorf("failed to reach remote backend %q: %w", backendName, err)
}
return fmt.Errorf("failed to open database: %w", err)
}
// backendNameForErrorFraming best-effort loads metadata.json to learn which
// backend a failed open was for, so a caller that does not already have cfg
// in scope (for example direct mode's single-shot store-open) can still give
// openStoreError the name it needs. A failure to even read the config
// degrades to "" — openStoreError's default, Dolt-shaped framing — rather
// than compounding one error with another.
func backendNameForErrorFraming(beadsDir string) string {
cfg, err := configfile.Load(beadsDir)
if err != nil || cfg == nil {
return ""
}
return cfg.GetBackend()
}
func loadDoltBackendConfig(beadsDir string) (*configfile.Config, error) {
cfg, err := configfile.Load(beadsDir)
if err != nil {

View file

@ -48,7 +48,7 @@ func ensureStoreActiveWithContext(ctx context.Context) error {
// based on metadata.json configuration and build tags
store, err := newDoltStoreFromConfig(ctx, beadsDir)
if err != nil {
return fmt.Errorf("failed to open database: %w\nHint: %s", err, diagHint())
return fmt.Errorf("%w\nHint: %s", openStoreError(backendNameForErrorFraming(beadsDir), err), diagHint())
}
// Update the database path for compatibility with code that expects it

View file

@ -2060,7 +2060,7 @@ var rootCmd = &cobra.Command{
if renderTypedOpenError(err) {
return SilentExit()
}
return HandleError("failed to open database: %v", err)
return HandleError("%v", openStoreError(cfg.GetBackend(), err))
}
// Mark store as active for flush goroutine safety

View file

@ -493,6 +493,38 @@ func TestFormatMemoriesForPrimeTimesOutOpeningStore(t *testing.T) {
}
}
// TestFormatMemoriesForPrimeTimesOutOpeningRegisteredBackend is the unstubbed
// twin of TestFormatMemoriesForPrimeTimesOutOpeningStore, which replaces
// ensureStoreActiveForPrime and so cannot see how the real open frames its
// error. Here the real open dials a registered remote backend that outlives
// BEADS_PRIME_TIMEOUT, and the timeout banner must still win over the generic
// "storage unavailable" one.
func TestFormatMemoriesForPrimeTimesOutOpeningRegisteredBackend(t *testing.T) {
const backend = "contract-prime-open-timeout"
registerContractBlockingBackend(t, backend, true)
t.Setenv("BEADS_DIR", writeContractBackendConfig(t, backend))
t.Setenv(primeStoreTimeoutEnv, "50ms")
oldStore := store
oldStoreActive := storeActive
oldEnsure := ensureStoreActiveForPrime
oldProxied := proxiedServerMode
store = nil
storeActive = false
ensureStoreActiveForPrime = ensureStoreActiveWithContext
proxiedServerMode = false
t.Cleanup(func() {
store = oldStore
storeActive = oldStoreActive
ensureStoreActiveForPrime = oldEnsure
proxiedServerMode = oldProxied
})
out := formatMemoriesForPrime(false)
if !strings.Contains(out, "timed out after 50ms") {
t.Fatalf("expected the store-open timeout banner in prime memory output, got %q", out)
}
}
// stubPrimeStoreOpen points prime's lazy store open at the given error and
// clears the ambient store, so a test drives formatMemoriesForPrime through a
// chosen failure edge. proxiedServerMode is forced off so the classic route is

View file

@ -37,6 +37,7 @@ go_library(
"//internal/githooksenv",
"//internal/gittraceenv",
"//internal/lockfile",
"//internal/storage/backends",
"//internal/storage/doltutil",
"@com_github_dolthub_dolt_go//libraries/doltcore/servercfg",
"@com_github_dolthub_dolt_go//libraries/utils/filesys",
@ -88,6 +89,8 @@ go_test(
"//internal/config",
"//internal/configfile",
"//internal/githooksenv",
"//internal/storage",
"//internal/storage/backends",
"@com_github_dolthub_dolt_go//libraries/doltcore/servercfg",
] + select({
"@rules_go//go/platform:aix": [

View file

@ -7,6 +7,7 @@ import (
"strings"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/storage/backends"
)
// PhysicalRoots describes the local physical database root(s) a store open
@ -29,14 +30,17 @@ type PhysicalRoots struct {
// the workspace gate applies.
Roots []string
// Mode is the connection mode the open path will actually use:
// "embedded" | "server" | "shared-server" | "proxied-server".
// "embedded" | "server" | "shared-server" | "proxied-server" |
// "remote-backend" (a registered backend that backends.IsRemote).
Mode string
// Provenance is a one-line human explanation of how Mode and Roots
// were decided, for busy/diagnostic messages ("why is bd gating that
// directory?").
Provenance string
// RemoteBackend is true when the backend is a server on a non-local
// host: workspace gate only, no physical gate.
// RemoteBackend is true when bd opens no local files for the workspace:
// either a Dolt server on a non-local host (Mode "server") or a
// registered remote backend (backends.IsRemote, Mode "remote-backend")
// that owns its own connection. Workspace gate only, no physical gate.
RemoteBackend bool
}
@ -206,6 +210,12 @@ func isRemoteServerHost(host string) bool {
// Mode decision (ordering is significant and each step cites the CLI
// behavior it mirrors):
//
// 0. registered remote backend: backends.IsRemote(cfg.GetBackend()) wins
// outright, before every Dolt-mode check below — including
// IsSharedServerMode, which reads only process env/config.yaml and does
// not consult cfg, so it would otherwise misclassify a remote-backend
// workspace under an active global shared-server setting. RemoteBackend
// = true, no local roots: the backend owns its own connection, not bd.
// 1. proxied-server: metadata dolt_mode=proxied-server wins outright —
// main.go routes proxied workspaces to the proxy provider before the
// shared-server rescue, which explicitly excludes ProxiedServer. Root
@ -275,6 +285,20 @@ func ResolvePhysicalRoots(beadsDir string) (PhysicalRoots, error) {
}
switch {
case cfg != nil && backends.IsRemote(cfg.GetBackend()):
// A registered remote backend (for example the http client) is a
// pure network client with no local database: bd opens no local
// files for it, so there is nothing physical to gate here, only the
// workspace gate applies. This must be checked before every Dolt
// mode branch below — IsSharedServerMode in particular reads only
// process env/config.yaml and does not consult cfg at all, so
// without this case a global shared-server setting would hijack a
// remote-backend workspace into reporting a bogus Dolt root it will
// never open.
pr.Mode = "remote-backend"
pr.RemoteBackend = true
pr.Provenance = fmt.Sprintf("metadata.json backend=%q is a registered remote backend; no local physical root", cfg.GetBackend())
case cfg != nil && cfg.IsDoltProxiedServerMode():
pr.Mode = "proxied-server"
root, perr := ResolveProxiedServerRootPath(abs)

View file

@ -1,9 +1,14 @@
package doltserver
import (
"context"
"errors"
"os"
"path/filepath"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
)
// resetPhysicalRootEnv neutralizes every env var ResolvePhysicalRoots (and
@ -174,6 +179,89 @@ func TestResolvePhysicalRootsRemoteServer(t *testing.T) {
}
}
// errFixtureBackendOpen is a sentinel so fixture backend Open/OpenReadOnly
// hooks never need to touch a real store.
var errFixtureBackendOpen = errors.New("fixture backend open")
// registerFixtureRemoteBackend registers a Remote backend under name so
// ResolvePhysicalRoots tests can prove it classifies a registered remote
// backend's workspace correctly instead of falling through to the embedded
// Dolt default.
func registerFixtureRemoteBackend(t *testing.T, name string) {
t.Helper()
open := func(context.Context, string) (storage.DoltStorage, error) {
return nil, errFixtureBackendOpen
}
backends.Register(name, backends.Backend{
Open: open,
OpenReadOnly: open,
Remote: true,
})
t.Cleanup(func() { backends.Deregister(name) })
}
// TestResolvePhysicalRootsRegisteredRemoteBackend covers the gap DESIGN.txt
// calls out: a registered remote backend (Backend.Remote) has no local
// database, but before this fix ResolvePhysicalRoots had no case for it at
// all and fell all the way through to the "embedded" default, reporting a
// bogus beadsDir/embeddeddolt root that backend never opens and bd never
// creates for it.
func TestResolvePhysicalRootsRegisteredRemoteBackend(t *testing.T) {
resetPhysicalRootEnv(t)
const name = "fixture-remote"
registerFixtureRemoteBackend(t, name)
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"backend":"`+name+`"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
if pr.Mode != "remote-backend" {
t.Errorf("Mode = %q, want remote-backend", pr.Mode)
}
if !pr.RemoteBackend {
t.Error("RemoteBackend = false, want true for a registered Remote backend")
}
if len(pr.Roots) != 0 {
t.Errorf("Roots = %v, want none for a registered remote backend", pr.Roots)
}
if pr.Provenance == "" {
t.Error("Provenance is empty; every decision must explain itself")
}
}
// TestResolvePhysicalRootsRegisteredRemoteBackendOverridesSharedServerEnv
// proves the ordering fix: IsSharedServerMode reads only process
// env/config.yaml and does not consult cfg at all, so without checking
// backends.IsRemote FIRST, an operator's global BEADS_DOLT_SHARED_SERVER=1
// would hijack a registered-remote-backend workspace into reporting a Dolt
// shared-server root it will never open.
func TestResolvePhysicalRootsRegisteredRemoteBackendOverridesSharedServerEnv(t *testing.T) {
resetPhysicalRootEnv(t)
t.Setenv("BEADS_DOLT_SHARED_SERVER", "1")
const name = "fixture-remote-shared"
registerFixtureRemoteBackend(t, name)
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"backend":"`+name+`"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
if pr.Mode != "remote-backend" {
t.Errorf("Mode = %q, want remote-backend even with BEADS_DOLT_SHARED_SERVER=1 set", pr.Mode)
}
if !pr.RemoteBackend {
t.Error("RemoteBackend = false, want true")
}
if len(pr.Roots) != 0 {
t.Errorf("Roots = %v, want none", pr.Roots)
}
}
func TestResolvePhysicalRootsSharedServerWinsOverMetadata(t *testing.T) {
resetPhysicalRootEnv(t)
beadsDir := newTestBeadsDir(t)

View file

@ -17,6 +17,7 @@ go_test(
"backends_test.go",
"classification_deregister_test.go",
"classification_test.go",
"open_with_test.go",
],
deps = [
":backends",

View file

@ -23,13 +23,108 @@ package backends
import (
"context"
"errors"
"fmt"
"net/http"
"sync"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backendnames"
)
// Credential is a per-open credential injection a backend's OpenWith may use
// to authenticate to a remote server on behalf of one specific workspace. This
// package assigns it no methods beyond the marker below and performs no type
// assertions against it: it is deliberately opaque so a generic embedder
// (for example gc, Gas City — one process serving many workspaces, called
// "cities") can carry a per-workspace credential through OpenOptions without
// this package, or the embedder, needing to know the concrete shape a future
// backend expects. A backend that needs a credential declares its own
// narrower interface in its own package and type-asserts the value its
// OpenWith receives.
//
// BackendCredential is a zero-cost marker method: every concrete credential
// type implements it (trivially, as a no-op), so passing an arbitrary value
// that was never meant to be a credential is a compile error instead of a
// silently accepted `any`.
type Credential interface {
BackendCredential()
}
// OpenOptions carries per-open injections a backend's OpenWith may use. Open
// has no seam for any of these — it is the process-global, back-compat path.
// The zero value is the back-compat case: every field absent reproduces Open's
// existing behavior exactly, for every backend, registered or not.
type OpenOptions struct {
// Credential authenticates this specific open to a remote backend's
// target. Nil means "use the backend's own default authentication" —
// which, for most backends, means whatever ambient environment (env
// vars, a config file, a logged-in CLI session, ...) the backend's
// default auth already reads. That ambient fallback is the right
// default for a single-tenant CLI process, but it is almost never what
// a multi-tenant embedder (for example gc, Gas City — one process
// serving many workspaces, called "cities") wants: ambient env is
// process-global, so it cannot distinguish one tenant's workspace from
// another's. A multi-tenant embedder MUST pass a non-nil Credential for
// every open; relying on the nil/ambient default in that setting risks
// one tenant's request being silently authenticated as another's. A
// backend with no OpenWith to honor a non-nil Credential refuses rather
// than silently opening unauthenticated: see OpenWithOptions. (S1 does
// not add a RequireCredential knob to enforce the multi-tenant rule
// mechanically — that is deferred to S2.)
Credential Credential
// HTTPClient overrides the *http.Client (and therefore any RoundTripper)
// a remote backend's OpenWith dials with. Nil means "use the backend's
// default client." A backend with no OpenWith to honor a non-nil
// HTTPClient refuses rather than silently ignoring the override and
// dialing with its default client anyway: see OpenWithOptions. A caller
// that asked for a specific transport (a proxy, a custom TLS config, a
// test double, ...) must be told that request was not honored, not have
// it silently dropped — the dial still "succeeding" against the wrong
// transport can be worse than a loud refusal.
HTTPClient *http.Client
// UserAgent overrides the User-Agent string a remote backend's OpenWith
// sends. Empty means "use the backend's default." Refused the same way
// HTTPClient is when the backend has no OpenWith.
UserAgent string
}
// ErrCredentialWithoutOpenWith is returned by Backend.OpenWithOptions when
// OpenOptions.Credential is set but the backend has no OpenWith to honor it.
// Dispatch refuses rather than silently falling back to Open and dropping the
// credential on the floor — a backend that cannot authenticate a per-open
// credential must say so, not open anonymously.
var ErrCredentialWithoutOpenWith = errors.New("backends: OpenOptions.Credential is set but the backend has no OpenWith to honor it; refusing to silently open without authenticating")
// ErrHTTPClientWithoutOpenWith is returned by Backend.OpenWithOptions when
// OpenOptions.HTTPClient is set but the backend has no OpenWith to honor it.
// Same fail-closed family as ErrCredentialWithoutOpenWith: a caller that
// asked for a specific transport must be told it was not honored, not have
// the request silently ignored in favor of the backend's default client.
var ErrHTTPClientWithoutOpenWith = errors.New("backends: OpenOptions.HTTPClient is set but the backend has no OpenWith to honor it; refusing to silently ignore the requested transport")
// ErrUserAgentWithoutOpenWith is returned by Backend.OpenWithOptions when
// OpenOptions.UserAgent is set but the backend has no OpenWith to honor it.
// Same fail-closed family as ErrCredentialWithoutOpenWith.
var ErrUserAgentWithoutOpenWith = errors.New("backends: OpenOptions.UserAgent is set but the backend has no OpenWith to honor it; refusing to silently ignore the requested User-Agent")
// ErrUnsupportedCredential is the typed refusal an OpenWith implementation
// MUST return — directly, or wrapped with backend-specific detail so that
// errors.Is(err, ErrUnsupportedCredential) still holds — when it receives a
// non-nil OpenOptions.Credential that does not type-assert to whatever
// narrower credential interface that backend's OpenWith expects. Credential
// is deliberately opaque at this package's level (see Credential's doc
// comment): this package performs no type assertion against it, so the
// assertion and the refusal-on-mismatch are entirely each OpenWith
// implementation's responsibility. Silently ignoring a Credential of the
// wrong type and opening with default/ambient auth instead would be worse
// than a refusal: it looks like the caller's credential was honored when it
// was not. A fake/test registrant's OpenWith is expected to demonstrate this
// contract the same way a production one must.
var ErrUnsupportedCredential = errors.New("backends: OpenOptions.Credential does not implement the credential type this backend's OpenWith expects")
// Backend describes a registered storage backend.
type Backend struct {
// Open opens the workspace store read-write.
@ -41,6 +136,66 @@ type Backend struct {
// WorkspaceIsBeadsDir means metadata.json and the remote store are enough
// to identify the workspace; no separately discoverable local DB exists.
WorkspaceIsBeadsDir bool
// Remote marks a backend that is a pure network client of a bd serve with
// no database of its own (for example an http client backend). It is
// narrower than WorkspaceIsBeadsDir, which a database-backed registrant
// (for example Postgres) can also set: Postgres opens a database, so its
// open failures ARE database failures, while a Remote backend's open
// failure is a connection failure that "failed to open database" would
// misname, and it has no local physical root for doltserver's
// ResolvePhysicalRoots to gate. cmd/bd reads this to frame the
// store-open error for the active backend.
Remote bool
// OpenWith opens the workspace store read-write, honoring per-open opts
// (Credential, HTTPClient, UserAgent). It exists for a backend whose
// dialer would otherwise be process-global, so it cannot support
// multiple credentialed callers sharing one process — exactly the shape
// an embedder like gc (Gas City, one process serving many workspaces)
// needs for per-workspace credentials. Optional: nil means this backend
// has no per-open seam, and OpenWithOptions falls back to Open — but
// only for a zero OpenOptions; a non-nil Credential, non-nil HTTPClient,
// or non-empty UserAgent is refused rather than silently dropped (see
// OpenWithOptions). A backend that sets OpenWith should make Open behave
// as OpenWith would with a zero OpenOptions, since OpenWithOptions calls
// Open directly whenever OpenWith is nil, and existing callers of Open
// never go through OpenWith at all.
//
// Contract for implementations: opts.Credential is typed only as the
// opaque Credential marker interface (see its doc comment); an OpenWith
// that expects a narrower, backend-specific credential type MUST type-
// assert and, on a non-nil Credential that fails the assertion, refuse
// with ErrUnsupportedCredential (directly, or wrapped so errors.Is still
// matches) rather than silently falling back to default/ambient auth.
// Opening unauthenticated when the caller supplied a credential — even
// one of the wrong shape — would look like the credential was honored
// when it was not.
OpenWith func(ctx context.Context, beadsDir string, opts OpenOptions) (storage.DoltStorage, error)
}
// OpenWithOptions opens beadsDir through this backend, honoring opts. It
// calls OpenWith when the backend implements it. Otherwise it fails closed:
// a zero OpenOptions falls back to the required Open, but a non-nil
// Credential, non-nil HTTPClient, or non-empty UserAgent is never silently
// dropped — with no OpenWith to honor it, OpenWithOptions returns the
// matching ErrXWithoutOpenWith sentinel instead of opening with the field
// ignored. A zero OpenOptions always reaches plain Open, so this is a strict
// superset of calling Open directly.
func (b Backend) OpenWithOptions(ctx context.Context, beadsDir string, opts OpenOptions) (storage.DoltStorage, error) {
if b.OpenWith != nil {
return b.OpenWith(ctx, beadsDir, opts)
}
if opts.Credential != nil {
return nil, ErrCredentialWithoutOpenWith
}
if opts.HTTPClient != nil {
return nil, ErrHTTPClientWithoutOpenWith
}
if opts.UserAgent != "" {
return nil, ErrUserAgentWithoutOpenWith
}
return b.Open(ctx, beadsDir)
}
var (
@ -109,3 +264,17 @@ func WorkspaceIsBeadsDir(name string) bool {
backend, ok := registry[name]
return ok && backend.WorkspaceIsBeadsDir
}
// IsRemote reports whether name is a registered backend that is a pure
// network client of a bd serve with no local database (see Backend.Remote).
// cmd/bd uses it to frame a store-open failure: a remote backend has no
// database, so the "failed to open database" prefix would name something
// that does not exist. doltserver.ResolvePhysicalRoots uses it to recognize
// that a registered remote backend has no local physical root to gate,
// instead of falling through to the embedded-Dolt default.
func IsRemote(name string) bool {
mu.RLock()
defer mu.RUnlock()
backend, ok := registry[name]
return ok && backend.Remote
}

View file

@ -0,0 +1,259 @@
package backends_test
import (
"context"
"errors"
"fmt"
"net/http"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
)
// fixtureCredential is a minimal backends.Credential implementation for
// tests: a bare marker with no fields, since this package never inspects a
// Credential's shape.
type fixtureCredential struct{}
func (fixtureCredential) BackendCredential() {}
var errFixtureOpenWith = errors.New("fixture backend OpenWith")
// openWithCapturingBackend returns a Backend whose OpenWith records the
// beadsDir and opts it was called with (via the returned pointers) and a
// plain Open that errors if dispatch ever falls back to it despite OpenWith
// being set — proving OpenWithOptions prefers OpenWith when present.
func openWithCapturingBackend(gotBeadsDir *string, gotOpts *backends.OpenOptions, calls *int) backends.Backend {
open := func(context.Context, string) (storage.DoltStorage, error) {
return nil, errors.New("fixture: Open called despite backend having OpenWith")
}
return backends.Backend{
Open: open,
OpenReadOnly: open,
OpenWith: func(_ context.Context, beadsDir string, opts backends.OpenOptions) (storage.DoltStorage, error) {
*calls++
*gotBeadsDir = beadsDir
*gotOpts = opts
return nil, errFixtureOpenWith
},
}
}
func TestBackendOpenWithOptionsPrefersOpenWithAndPassesOptsThrough(t *testing.T) {
var gotBeadsDir string
var gotOpts backends.OpenOptions
var calls int
backend := openWithCapturingBackend(&gotBeadsDir, &gotOpts, &calls)
cred := fixtureCredential{}
client := &http.Client{}
wantOpts := backends.OpenOptions{Credential: cred, HTTPClient: client, UserAgent: "test-agent/1.0"}
_, err := backend.OpenWithOptions(t.Context(), "/tmp/fixture-beads-dir", wantOpts)
if !errors.Is(err, errFixtureOpenWith) {
t.Fatalf("OpenWithOptions error = %v, want %v", err, errFixtureOpenWith)
}
if calls != 1 {
t.Fatalf("OpenWith called %d times, want 1", calls)
}
if gotBeadsDir != "/tmp/fixture-beads-dir" {
t.Fatalf("OpenWith beadsDir = %q, want /tmp/fixture-beads-dir", gotBeadsDir)
}
if gotOpts.Credential != cred {
t.Fatalf("OpenWith opts.Credential = %v, want %v", gotOpts.Credential, cred)
}
if gotOpts.HTTPClient != client {
t.Fatalf("OpenWith opts.HTTPClient = %v, want %v", gotOpts.HTTPClient, client)
}
if gotOpts.UserAgent != "test-agent/1.0" {
t.Fatalf("OpenWith opts.UserAgent = %q, want test-agent/1.0", gotOpts.UserAgent)
}
}
// TestBackendOpenWithOptionsZeroOptionsBackCompat covers back-compat for
// EVERY backend shape OSS and downstream registrants can produce: a backend
// with no OpenWith (the historical, Open-only shape) and a backend WITH
// OpenWith (the new optional seam) must both behave identically to calling
// Open directly when opts is the zero value.
func TestBackendOpenWithOptionsZeroOptionsBackCompat(t *testing.T) {
t.Run("backend without OpenWith falls back to Open", func(t *testing.T) {
backend := fixtureBackend() // from backends_test.go: Open/OpenReadOnly only, no OpenWith
_, err := backend.OpenWithOptions(t.Context(), t.TempDir(), backends.OpenOptions{})
if !errors.Is(err, errFixtureOpen) {
t.Fatalf("OpenWithOptions(zero opts) error = %v, want %v (the Open sentinel)", err, errFixtureOpen)
}
})
t.Run("backend with OpenWith still receives the call with a zero OpenOptions", func(t *testing.T) {
var gotBeadsDir string
var gotOpts backends.OpenOptions
var calls int
backend := openWithCapturingBackend(&gotBeadsDir, &gotOpts, &calls)
dir := t.TempDir()
_, err := backend.OpenWithOptions(t.Context(), dir, backends.OpenOptions{})
if !errors.Is(err, errFixtureOpenWith) {
t.Fatalf("OpenWithOptions(zero opts) error = %v, want %v", err, errFixtureOpenWith)
}
if calls != 1 {
t.Fatalf("OpenWith called %d times, want 1", calls)
}
if gotOpts != (backends.OpenOptions{}) {
t.Fatalf("OpenWith opts = %+v, want the zero value", gotOpts)
}
})
}
// TestBackendOpenWithOptionsRefusesCredentialWithoutOpenWith is the design's
// explicit requirement: a backend with no OpenWith seam must refuse a
// non-nil Credential rather than silently opening unauthenticated and
// discarding it.
func TestBackendOpenWithOptionsRefusesCredentialWithoutOpenWith(t *testing.T) {
backend := fixtureBackend() // Open/OpenReadOnly only, no OpenWith
store, err := backend.OpenWithOptions(t.Context(), t.TempDir(), backends.OpenOptions{
Credential: fixtureCredential{},
})
if store != nil {
t.Fatal("OpenWithOptions returned a non-nil store alongside the refusal")
}
if !errors.Is(err, backends.ErrCredentialWithoutOpenWith) {
t.Fatalf("OpenWithOptions error = %v, want %v", err, backends.ErrCredentialWithoutOpenWith)
}
}
// TestBackendOpenWithOptionsRefusesHTTPClientAndUserAgentWithoutOpenWith is
// the L2 fail-closed rule: a backend with no OpenWith seam must refuse a
// non-nil HTTPClient or non-empty UserAgent the same way it refuses a
// non-nil Credential, rather than silently falling back to Open and
// dropping the override — a caller that asked for a specific transport or
// User-Agent must be told that request was not honored.
func TestBackendOpenWithOptionsRefusesHTTPClientAndUserAgentWithoutOpenWith(t *testing.T) {
t.Run("HTTPClient alone", func(t *testing.T) {
backend := fixtureBackend()
store, err := backend.OpenWithOptions(t.Context(), t.TempDir(), backends.OpenOptions{
HTTPClient: &http.Client{},
})
if store != nil {
t.Fatal("OpenWithOptions returned a non-nil store alongside the refusal")
}
if !errors.Is(err, backends.ErrHTTPClientWithoutOpenWith) {
t.Fatalf("OpenWithOptions error = %v, want %v", err, backends.ErrHTTPClientWithoutOpenWith)
}
})
t.Run("UserAgent alone", func(t *testing.T) {
backend := fixtureBackend()
store, err := backend.OpenWithOptions(t.Context(), t.TempDir(), backends.OpenOptions{
UserAgent: "test-agent/1.0",
})
if store != nil {
t.Fatal("OpenWithOptions returned a non-nil store alongside the refusal")
}
if !errors.Is(err, backends.ErrUserAgentWithoutOpenWith) {
t.Fatalf("OpenWithOptions error = %v, want %v", err, backends.ErrUserAgentWithoutOpenWith)
}
})
}
// fixtureNarrowCredential is the credential type a hypothetical backend's
// OpenWith expects. fixtureCredential (the generic marker used elsewhere in
// this file) does not implement it, so passing fixtureCredential to an
// OpenWith that requires fixtureNarrowCredential must be refused.
type fixtureNarrowCredential struct{ apiKey string }
func (fixtureNarrowCredential) BackendCredential() {}
// narrowOpenWithBackend returns a Backend whose OpenWith type-asserts
// opts.Credential to fixtureNarrowCredential and refuses with
// backends.ErrUnsupportedCredential (wrapped, to prove errors.Is still
// matches through a wrap) on any non-nil Credential that fails the
// assertion — demonstrating the M3 contract OpenWith implementations must
// follow.
func narrowOpenWithBackend() backends.Backend {
open := func(context.Context, string) (storage.DoltStorage, error) {
return nil, errors.New("fixture: Open called despite backend having OpenWith")
}
return backends.Backend{
Open: open,
OpenReadOnly: open,
OpenWith: func(_ context.Context, _ string, opts backends.OpenOptions) (storage.DoltStorage, error) {
if opts.Credential == nil {
return nil, errFixtureOpenWith
}
if _, ok := opts.Credential.(fixtureNarrowCredential); !ok {
return nil, fmt.Errorf("fixture: credential %T is not fixtureNarrowCredential: %w", opts.Credential, backends.ErrUnsupportedCredential)
}
return nil, errFixtureOpenWith
},
}
}
// TestBackendOpenWithRefusesUnsupportedCredentialType is the M3 contract: an
// OpenWith implementation that receives a non-nil Credential it cannot
// type-assert to its expected concrete type MUST refuse with
// ErrUnsupportedCredential (or a wrap of it), not silently fall back to
// default/ambient auth.
func TestBackendOpenWithRefusesUnsupportedCredentialType(t *testing.T) {
backend := narrowOpenWithBackend()
t.Run("mismatched credential type is refused", func(t *testing.T) {
store, err := backend.OpenWithOptions(t.Context(), t.TempDir(), backends.OpenOptions{
Credential: fixtureCredential{},
})
if store != nil {
t.Fatal("OpenWithOptions returned a non-nil store alongside the refusal")
}
if !errors.Is(err, backends.ErrUnsupportedCredential) {
t.Fatalf("OpenWithOptions error = %v, want it to wrap %v", err, backends.ErrUnsupportedCredential)
}
})
t.Run("matching credential type is accepted", func(t *testing.T) {
_, err := backend.OpenWithOptions(t.Context(), t.TempDir(), backends.OpenOptions{
Credential: fixtureNarrowCredential{apiKey: "k"},
})
if errors.Is(err, backends.ErrUnsupportedCredential) {
t.Fatalf("OpenWithOptions refused a matching credential type: %v", err)
}
if !errors.Is(err, errFixtureOpenWith) {
t.Fatalf("OpenWithOptions error = %v, want %v (OpenWith reached, credential accepted)", err, errFixtureOpenWith)
}
})
t.Run("nil credential is unaffected", func(t *testing.T) {
_, err := backend.OpenWithOptions(t.Context(), t.TempDir(), backends.OpenOptions{})
if !errors.Is(err, errFixtureOpenWith) {
t.Fatalf("OpenWithOptions(nil Credential) error = %v, want %v", err, errFixtureOpenWith)
}
})
}
func TestBackendRemoteAndIsRemote(t *testing.T) {
const remoteName = "fixture-remote"
const localName = "fixture-local"
remote := fixtureBackend()
remote.Remote = true
backends.Register(remoteName, remote)
t.Cleanup(func() { backends.Deregister(remoteName) })
backends.Register(localName, fixtureBackend())
t.Cleanup(func() { backends.Deregister(localName) })
if !backends.IsRemote(remoteName) {
t.Errorf("IsRemote(%q) = false, want true", remoteName)
}
if backends.IsRemote(localName) {
t.Errorf("IsRemote(%q) = true, want false", localName)
}
if backends.IsRemote("never-registered") {
t.Error("IsRemote(unregistered name) = true, want false")
}
registered, ok := backends.Lookup(remoteName)
if !ok || !registered.Remote {
t.Fatalf("Lookup(%q) Remote = %v, ok = %v, want true, true", remoteName, registered.Remote, ok)
}
}

View file

@ -3,6 +3,7 @@ package beads_test
import (
"context"
"errors"
"net/http"
"os"
"path/filepath"
"strings"
@ -15,6 +16,36 @@ import (
var errRegistryBackendOpen = errors.New("registry backend open sentinel")
var errRegistryBackendOpenWith = errors.New("registry backend OpenWith sentinel")
// fixtureCredential is a minimal beads.Credential implementation for tests:
// a bare marker, since OpenOptions.Credential is deliberately opaque.
type fixtureCredential struct{}
func (fixtureCredential) BackendCredential() {}
// registerOpenWithCapturingBackend registers a backend whose OpenWith
// records the beadsDir and opts it received (via the returned pointers), and
// whose Open errors if dispatch ever falls back to it — proving
// OpenBestAvailableWith reaches OpenWith, not Open, when the backend has one.
func registerOpenWithCapturingBackend(t *testing.T, name string, gotBeadsDir *string, gotOpts *beads.OpenOptions, calls *int) {
t.Helper()
open := func(context.Context, string) (storage.DoltStorage, error) {
return nil, errors.New("fixture: Open called despite backend having OpenWith")
}
backends.Register(name, backends.Backend{
Open: open,
OpenReadOnly: open,
OpenWith: func(_ context.Context, beadsDir string, opts backends.OpenOptions) (storage.DoltStorage, error) {
*calls++
*gotBeadsDir = beadsDir
*gotOpts = opts
return nil, errRegistryBackendOpenWith
},
})
t.Cleanup(func() { backends.Deregister(name) })
}
// registerWorkspaceBackend registers a fake WorkspaceIsBeadsDir backend whose
// Open/OpenReadOnly report a sentinel instead of touching a store, so tests can
// assert that discovery and open dispatch to the registry without provisioning
@ -33,6 +64,29 @@ func registerWorkspaceBackend(t *testing.T, name string) {
t.Cleanup(func() { backends.Deregister(name) })
}
// plainDoltServerModeBeadsDir writes metadata.json naming the default "dolt"
// backend in explicit server mode, and forces the dial target to a port
// nobody listens on via env vars that GetDoltServerPort/GetDoltServerHost
// check BEFORE metadata.json — TestMain's shared test Dolt container already
// sets BEADS_DOLT_PORT ambiently for the whole process, which would
// otherwise silently out-rank a port pinned only in metadata.json and make
// this open attempt succeed against the wrong server. t.Setenv scopes the
// override to the calling (sub)test and its cleanup.
func plainDoltServerModeBeadsDir(t *testing.T) string {
t.Helper()
t.Setenv("BEADS_DOLT_SERVER_HOST", "127.0.0.1")
t.Setenv("BEADS_DOLT_SERVER_PORT", "1")
beadsDir := filepath.Join(t.TempDir(), ".beads")
if err := os.MkdirAll(beadsDir, 0o750); err != nil {
t.Fatalf("create .beads: %v", err)
}
metadata := `{"backend":"dolt","dolt_mode":"server"}`
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(metadata), 0o600); err != nil {
t.Fatalf("write metadata: %v", err)
}
return beadsDir
}
func writeBackendMetadata(t *testing.T, backend string) string {
t.Helper()
beadsDir := filepath.Join(t.TempDir(), ".beads")
@ -246,3 +300,178 @@ func TestFindDatabasePathDiscoversRegisteredWorkspace(t *testing.T) {
}
}
}
// TestOpenBestAvailableWithDispatchesRegisteredBackendAndPassesOptions proves
// the two S1 guarantees together: OpenBestAvailableWith dispatches to a
// registered backend's OpenWith (not Open), and the OpenOptions the caller
// supplied reach that OpenWith unchanged.
func TestOpenBestAvailableWithDispatchesRegisteredBackendAndPassesOptions(t *testing.T) {
const name = "registry-openwith"
var gotBeadsDir string
var gotOpts beads.OpenOptions
var calls int
registerOpenWithCapturingBackend(t, name, &gotBeadsDir, &gotOpts, &calls)
beadsDir := writeBackendMetadata(t, name)
cred := fixtureCredential{}
client := &http.Client{}
wantOpts := beads.OpenOptions{Credential: cred, HTTPClient: client, UserAgent: "test-agent/1.0"}
store, err := beads.OpenBestAvailableWith(context.Background(), beadsDir, wantOpts)
if store != nil {
_ = store.Close()
t.Fatal("OpenBestAvailableWith returned a store instead of the backend's OpenWith result")
}
if !errors.Is(err, errRegistryBackendOpenWith) {
t.Fatalf("OpenBestAvailableWith error = %v, want registered backend OpenWith result", err)
}
if calls != 1 {
t.Fatalf("OpenWith called %d times, want 1", calls)
}
if gotOpts.Credential != cred {
t.Fatalf("OpenWith opts.Credential = %v, want %v", gotOpts.Credential, cred)
}
if gotOpts.HTTPClient != client {
t.Fatalf("OpenWith opts.HTTPClient = %v, want %v", gotOpts.HTTPClient, client)
}
if gotOpts.UserAgent != "test-agent/1.0" {
t.Fatalf("OpenWith opts.UserAgent = %q, want test-agent/1.0", gotOpts.UserAgent)
}
}
// TestOpenBestAvailableWithZeroOptionsMatchesOpenBestAvailable is the S1
// back-compat requirement: OpenBestAvailableWith with a zero OpenOptions must
// behave identically to OpenBestAvailable for every existing path —
// registered backend without OpenWith, registered backend with OpenWith, and
// plain Dolt (no registered backend at all).
//
// OpenBestAvailable now simply delegates to OpenBestAvailableWith with a zero
// OpenOptions (see beads_cgo.go and beads_nocgo.go), so a subtest that calls
// both and compares their results would be vacuous: it can never fail
// regardless of what either returns, because they are the same code path.
// Each subtest instead pins a fixed, independently-meaningful expected result
// — a sentinel identity, a concrete error message, or a concrete
// store-presence/nilness — so that a future change which breaks the
// delegation (e.g. a stray early return, or dropped opts threading) still has
// something to fail against.
func TestOpenBestAvailableWithZeroOptionsMatchesOpenBestAvailable(t *testing.T) {
t.Run("registered backend without OpenWith", func(t *testing.T) {
const name = "registry-backcompat-open-only"
registerWorkspaceBackend(t, name)
beadsDir := writeBackendMetadata(t, name)
store, err := beads.OpenBestAvailableWith(context.Background(), beadsDir, beads.OpenOptions{})
if store != nil {
_ = store.Close()
t.Fatal("OpenBestAvailableWith(zero opts) returned a non-nil store, want nil: the fixture's Open always fails")
}
if !errors.Is(err, errRegistryBackendOpen) {
t.Fatalf("OpenBestAvailableWith(zero opts) error = %v, want errRegistryBackendOpen", err)
}
})
t.Run("registered backend with OpenWith", func(t *testing.T) {
const name = "registry-backcompat-openwith"
var gotBeadsDir string
var gotOpts beads.OpenOptions
var calls int
registerOpenWithCapturingBackend(t, name, &gotBeadsDir, &gotOpts, &calls)
beadsDir := writeBackendMetadata(t, name)
_, errNew := beads.OpenBestAvailableWith(context.Background(), beadsDir, beads.OpenOptions{})
if !errors.Is(errNew, errRegistryBackendOpenWith) {
t.Fatalf("OpenBestAvailableWith(zero opts) error = %v, want OpenWith sentinel", errNew)
}
if calls != 1 {
t.Fatalf("OpenWith called %d times, want 1", calls)
}
if gotOpts != (beads.OpenOptions{}) {
t.Fatalf("OpenWith opts = %+v, want the zero value (OpenBestAvailable never set any)", gotOpts)
}
if gotBeadsDir != beadsDir {
t.Fatalf("OpenWith beadsDir = %q, want %q", gotBeadsDir, beadsDir)
}
})
t.Run("no registered backend (plain Dolt, server mode)", func(t *testing.T) {
// dolt_mode:"server" plus an unreachable port (127.0.0.1:1) makes
// the dial fail fast with a fixed, well-known error rather than
// spinning up embedded Dolt (slow, and exercises a path this slice
// does not touch).
beadsDir := plainDoltServerModeBeadsDir(t)
store, err := beads.OpenBestAvailableWith(context.Background(), beadsDir, beads.OpenOptions{})
if store != nil {
_ = store.Close()
t.Fatal("OpenBestAvailableWith(zero opts) returned a non-nil store, want nil: 127.0.0.1:1 is unreachable")
}
if err == nil {
t.Fatal("plain Dolt server mode against an unreachable port unexpectedly opened")
}
const wantSubstring = "Dolt server unreachable at 127.0.0.1:1"
if !strings.Contains(err.Error(), wantSubstring) {
t.Fatalf("OpenBestAvailableWith(zero opts) error = %q, want it to contain %q", err.Error(), wantSubstring)
}
})
}
// TestOpenBestAvailableWithRefusesCredentialWithoutOpenWithOnRegisteredBackend
// covers the registered-backend half of the design's refusal requirement:
// a backend with no OpenWith must never silently drop a caller's Credential.
func TestOpenBestAvailableWithRefusesCredentialWithoutOpenWithOnRegisteredBackend(t *testing.T) {
const name = "registry-credential-refusal"
registerWorkspaceBackend(t, name) // Open/OpenReadOnly only, no OpenWith
beadsDir := writeBackendMetadata(t, name)
store, err := beads.OpenBestAvailableWith(context.Background(), beadsDir, beads.OpenOptions{
Credential: fixtureCredential{},
})
if store != nil {
_ = store.Close()
t.Fatal("OpenBestAvailableWith returned a store alongside the Credential refusal")
}
if !errors.Is(err, beads.ErrCredentialWithoutOpenWith) {
t.Fatalf("OpenBestAvailableWith error = %v, want %v", err, beads.ErrCredentialWithoutOpenWith)
}
}
// TestOpenBestAvailableWithRefusesPerOpenOptionsOnPlainDolt covers the other
// half: no registered backend at all (plain Dolt, embedded or server) has no
// per-open seam either, so the same refusal applies to each of Credential,
// HTTPClient, and UserAgent. Those refusal arms are duplicated in
// beads_cgo.go and beads_nocgo.go, so this runs against whichever copy the
// build's CGO setting compiles.
func TestOpenBestAvailableWithRefusesPerOpenOptionsOnPlainDolt(t *testing.T) {
tests := []struct {
name string
opts beads.OpenOptions
want error
}{
{name: "Credential", opts: beads.OpenOptions{Credential: fixtureCredential{}}, want: beads.ErrCredentialWithoutOpenWith},
{name: "HTTPClient", opts: beads.OpenOptions{HTTPClient: &http.Client{}}, want: beads.ErrHTTPClientWithoutOpenWith},
{name: "UserAgent", opts: beads.OpenOptions{UserAgent: "test-agent/1.0"}, want: beads.ErrUserAgentWithoutOpenWith},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
beadsDir := filepath.Join(t.TempDir(), ".beads")
if err := os.MkdirAll(beadsDir, 0o750); err != nil {
t.Fatalf("create .beads: %v", err)
}
store, err := beads.OpenBestAvailableWith(context.Background(), beadsDir, tt.opts)
if store != nil {
_ = store.Close()
t.Fatalf("OpenBestAvailableWith returned a store alongside the %s refusal", tt.name)
}
if !errors.Is(err, tt.want) {
t.Fatalf("OpenBestAvailableWith error = %v, want %v", err, tt.want)
}
// The fail-closed guarantee includes never provisioning a database
// while refusing to honor the option.
for _, artifact := range []string{"embeddeddolt", "dolt"} {
if _, statErr := os.Stat(filepath.Join(beadsDir, artifact)); !os.IsNotExist(statErr) {
t.Fatalf("%s refusal on plain Dolt created %s (stat error: %v)", tt.name, artifact, statErr)
}
}
})
}
}