diff --git a/CHANGELOG.md b/CHANGELOG.md index fce76c527..dfe3b4da1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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: diff --git a/backend/backend.go b/backend/backend.go index de2f184dd..2981739aa 100644 --- a/backend/backend.go +++ b/backend/backend.go @@ -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] diff --git a/beads.go b/beads.go index 87df68cc9..3b7d03fde 100644 --- a/beads.go +++ b/beads.go @@ -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 diff --git a/beads_cgo.go b/beads_cgo.go index 60936982c..d36297ce3 100644 --- a/beads_cgo.go +++ b/beads_cgo.go @@ -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() { diff --git a/beads_nocgo.go b/beads_nocgo.go index 6867daf84..ba6853c4a 100644 --- a/beads_nocgo.go +++ b/beads_nocgo.go @@ -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() { diff --git a/cmd/bd/backend_registry_contract_test.go b/cmd/bd/backend_registry_contract_test.go index 61f5761a1..a186e566f 100644 --- a/cmd/bd/backend_registry_contract_test.go +++ b/cmd/bd/backend_registry_contract_test.go @@ -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) + } +} diff --git a/cmd/bd/backend_support.go b/cmd/bd/backend_support.go index 6ef060c7f..2f28c48c6 100644 --- a/cmd/bd/backend_support.go +++ b/cmd/bd/backend_support.go @@ -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 { diff --git a/cmd/bd/direct_mode.go b/cmd/bd/direct_mode.go index 3643a0fe6..2508133a8 100644 --- a/cmd/bd/direct_mode.go +++ b/cmd/bd/direct_mode.go @@ -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 diff --git a/cmd/bd/main.go b/cmd/bd/main.go index 625577fd2..04fa87d78 100644 --- a/cmd/bd/main.go +++ b/cmd/bd/main.go @@ -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 diff --git a/cmd/bd/prime_test.go b/cmd/bd/prime_test.go index c953bfb7a..54b4167c0 100644 --- a/cmd/bd/prime_test.go +++ b/cmd/bd/prime_test.go @@ -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 diff --git a/internal/doltserver/BUILD.bazel b/internal/doltserver/BUILD.bazel index d823d3c8e..e5465bace 100644 --- a/internal/doltserver/BUILD.bazel +++ b/internal/doltserver/BUILD.bazel @@ -33,6 +33,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", @@ -80,6 +81,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": [ diff --git a/internal/doltserver/physical_root.go b/internal/doltserver/physical_root.go index b2a462cb7..7cbf06b48 100644 --- a/internal/doltserver/physical_root.go +++ b/internal/doltserver/physical_root.go @@ -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) diff --git a/internal/doltserver/physical_root_test.go b/internal/doltserver/physical_root_test.go index 48f607660..5e5ec0e4a 100644 --- a/internal/doltserver/physical_root_test.go +++ b/internal/doltserver/physical_root_test.go @@ -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) diff --git a/internal/storage/backends/BUILD.bazel b/internal/storage/backends/BUILD.bazel index b402d15d3..fbdb0fdb3 100644 --- a/internal/storage/backends/BUILD.bazel +++ b/internal/storage/backends/BUILD.bazel @@ -17,6 +17,7 @@ go_test( "backends_test.go", "classification_deregister_test.go", "classification_test.go", + "open_with_test.go", ], deps = [ ":backends", diff --git a/internal/storage/backends/backends.go b/internal/storage/backends/backends.go index 48b68dce4..3c4ba0fcf 100644 --- a/internal/storage/backends/backends.go +++ b/internal/storage/backends/backends.go @@ -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 +} diff --git a/internal/storage/backends/open_with_test.go b/internal/storage/backends/open_with_test.go new file mode 100644 index 000000000..105335c0d --- /dev/null +++ b/internal/storage/backends/open_with_test.go @@ -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) + } +} diff --git a/open_backend_selection_test.go b/open_backend_selection_test.go index 1ffbaa449..dc79697d7 100644 --- a/open_backend_selection_test.go +++ b/open_backend_selection_test.go @@ -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) + } + } + }) + } +}