* 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>
629 lines
30 KiB
Go
629 lines
30 KiB
Go
// Package beads provides a minimal public API for extending bd with custom orchestration.
|
|
//
|
|
// Most extensions should use direct SQL queries against bd's database.
|
|
// This package exports only the essential types and functions needed for
|
|
// Go-based extensions that want to use bd's storage layer programmatically.
|
|
//
|
|
// For a working extension example, see examples/bd-example-extension-go.
|
|
//
|
|
// This is the CONSUMER surface: it opens and uses bd's own storage. To
|
|
// IMPLEMENT a storage backend out of tree — and prove it with the
|
|
// conformance suite — use github.com/steveyegge/beads/backend and
|
|
// github.com/steveyegge/beads/backend/conformance instead.
|
|
package beads
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"os"
|
|
"path/filepath"
|
|
"time"
|
|
|
|
"github.com/steveyegge/beads/internal/beads"
|
|
"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"
|
|
"github.com/steveyegge/beads/internal/types"
|
|
"github.com/steveyegge/beads/internal/workspacegate"
|
|
)
|
|
|
|
// Storage is the interface for beads storage operations. Its
|
|
// RunInTransaction callback is invoked at most once per public call; callers
|
|
// retry it explicitly after a callback has started when their operation is
|
|
// 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
|
|
// metadata.json edit that heals the workspace, instead of the export-and-
|
|
// reinitialize path that would destroy it.
|
|
func configuredBackendUnavailable(backend, beadsDir string, cfg *configfile.Config) error {
|
|
switch backend {
|
|
case configfile.BackendPostgres, configfile.BackendMySQL, configfile.BackendSQLite:
|
|
return configfile.RemovedBackendErrorAt(backend, beadsDir, cfg)
|
|
default:
|
|
return configfile.UnknownBackendErrorAt(backend, beadsDir, cfg)
|
|
}
|
|
}
|
|
|
|
// Transaction provides atomic multi-operation support within a database transaction.
|
|
// Use Storage.RunInTransaction() to obtain a Transaction instance.
|
|
type Transaction = beads.Transaction
|
|
|
|
// DependencyAddOptions controls transaction-scoped dependency insertion for
|
|
// Transaction.AddDependencyWithOptions. Exported so embedders' bulk graph
|
|
// writers can set SkipCycleCheck per edge and run one whole-graph
|
|
// Transaction.CycleThroughEdges pass before commit (bd-6dnrw.8) instead of
|
|
// paying the recursive per-edge cycle query — which cannot finish inside a
|
|
// per-command budget on molecule-sized graphs (observed: a 67-node/100-edge
|
|
// batch blowing a 120s deadline mid-transaction, gascity 2026-07-17).
|
|
//
|
|
// Callers that set SkipCycleCheck MUST run Transaction.CycleThroughEdges before
|
|
// commit and fail on new blocks/conditional-blocks/parent-child cycles
|
|
// (waits-for is excluded); skipping the per-edge check trades per-edge cost for
|
|
// one whole-graph check, never graph integrity.
|
|
type DependencyAddOptions = storage.DependencyAddOptions
|
|
|
|
// DependencyRemoveOptions controls transaction-scoped dependency removal for
|
|
// Transaction.RemoveDependencyWithOptions. Exported so embedders can request the
|
|
// dependency_removed history event on an explicit edge removal; the plain
|
|
// RemoveDependency default stays silent for structural edge teardown, mirroring
|
|
// the DependencyAddOptions/AddDependencyWithOptions split.
|
|
type DependencyRemoveOptions = storage.DependencyRemoveOptions
|
|
|
|
// CloseIssueOptions carries the optional inputs to Storage.CloseIssueChecked —
|
|
// an atomic, guarded close that refuses a still-blocked issue with
|
|
// ErrCloseBlocked unless Force is set. Exported so consumers can name it without
|
|
// importing internal/storage.
|
|
type CloseIssueOptions = storage.CloseIssueOptions
|
|
|
|
// CloseIssueResult reports the outcome of Storage.CloseIssueChecked. Unchanged
|
|
// is true when the issue was already closed (idempotent no-op).
|
|
type CloseIssueResult = storage.CloseIssueResult
|
|
|
|
// UpdateIssueOptions carries the optional inputs to Storage.UpdateIssueChecked —
|
|
// an update with an optional ExpectedVersion compare-and-swap that refuses a
|
|
// concurrently-modified issue with ErrVersionMismatch. Exported so consumers can
|
|
// name it without importing internal/storage.
|
|
type UpdateIssueOptions = storage.UpdateIssueOptions
|
|
|
|
// CommentPageCursor is the resume position for Storage.GetIssueCommentsPage — the
|
|
// (created_at, id) of the last comment already returned, with the zero value
|
|
// starting a walk from the beginning of the thread. Exported so consumers can
|
|
// name it without importing internal/storage.
|
|
type CommentPageCursor = storage.CommentPageCursor
|
|
|
|
// ErrUnsupported reports that an operation is unavailable for a storage
|
|
// backend — for example Storage.IssueLifecycle on a backend that cannot serve
|
|
// guarded issue mutations. Exported so consumers can match it with errors.As
|
|
// without importing internal/storage.
|
|
type ErrUnsupported = storage.ErrUnsupported
|
|
|
|
// RemoteStore provides dolt remote management and replication operations.
|
|
// Use type assertion on a Storage value to access these methods:
|
|
//
|
|
// if rs, ok := store.(beads.RemoteStore); ok {
|
|
// rs.Push(ctx)
|
|
// }
|
|
type RemoteStore = storage.RemoteStore
|
|
|
|
// SyncStore provides high-level sync operations with peers.
|
|
type SyncStore = storage.SyncStore
|
|
|
|
// EventCursor is a keyset position in the durable events stream, ordered by
|
|
// (created_at, id). The zero value means "from the beginning".
|
|
type EventCursor = storage.EventCursor
|
|
|
|
// EventQuerier is the durable-event-feed surface of a Storage: keyset paging
|
|
// over the durable event log, beyond the base Storage's time-only
|
|
// GetAllEventsSince. It is a NARROW, hand-declared root interface exposing
|
|
// exactly what consumers need — not an alias of the internal EventQueryStore —
|
|
// so the published surface stays small and independent of the engine interface.
|
|
// Reach it via AsEventQuerier.
|
|
type EventQuerier interface {
|
|
// EventsSince returns durable events strictly after cursor, ordered by
|
|
// (created_at ASC, id ASC), bounded by limit (0 = a store default, capped).
|
|
// issueID scopes the feed to one bead's history ("" = all).
|
|
EventsSince(ctx context.Context, cursor EventCursor, issueID string, limit int) ([]*Event, error)
|
|
}
|
|
|
|
// DependentQuerier is the target-keyed dependents surface of a Storage: the raw
|
|
// inbound-edge reads that back group-membership. Like EventQuerier it is a
|
|
// NARROW hand-declared root interface (not an alias of DependencyQueryStore),
|
|
// exposing only the calls consumers use. Reach it via AsDependentQuerier.
|
|
type DependentQuerier interface {
|
|
// GetDependentRecords returns raw dependency rows whose target is targetID,
|
|
// paged by the dependency row id (afterID, "" = start). See the engine doc
|
|
// for the two-table span and raw-read/policy-at-hydration contract.
|
|
GetDependentRecords(ctx context.Context, targetID string, depType string, limit int, afterID string) ([]*Dependency, error)
|
|
// GetDependentRecordsForIssues returns raw dependency rows keyed by TARGET id
|
|
// — for a SET of target ids in one batched read, each id's inbound edges (its
|
|
// dependents), across both dependency tables, ALL dep types, de-duped by row
|
|
// id. The batched, target-keyed mirror of GetDependencyRecordsForIssues; same
|
|
// two-table span and raw-read/policy-at-hydration contract as
|
|
// GetDependentRecords, without paging.
|
|
GetDependentRecordsForIssues(ctx context.Context, targetIDs []string) (map[string][]*Dependency, error)
|
|
// CountDependentRecords returns the true total inbound-edge count of targetID
|
|
// (depType "" = all) without paging.
|
|
CountDependentRecords(ctx context.Context, targetID string, depType string) (int, error)
|
|
}
|
|
|
|
// BlockedQuerier is the transitive-blocked surface of a Storage: the
|
|
// denormalized is_blocked flag, single or batched. Like EventQuerier it is a
|
|
// NARROW hand-declared root interface (not an alias of DependencyQueryStore),
|
|
// exposing only the reads consumers use. IsBlockedBatch returns the is_blocked
|
|
// column for a whole page in one round-trip — the same transitive value
|
|
// IsBlocked returns per id, with no N-call fan-out. Reach it via AsBlockedQuerier.
|
|
type BlockedQuerier interface {
|
|
// IsBlocked reports whether issueID is blocked (its denormalized transitive
|
|
// is_blocked flag) and the open direct blockers for display.
|
|
IsBlocked(ctx context.Context, issueID string) (bool, []string, error)
|
|
// IsBlockedBatch returns the denormalized transitive is_blocked flag for each
|
|
// of ids in one batched read. ids present in neither the issues nor wisps
|
|
// table are absent from the map; callers treat absent as not-blocked.
|
|
IsBlockedBatch(ctx context.Context, ids []string) (map[string]bool, error)
|
|
}
|
|
|
|
// AsEventQuerier returns the EventQuerier view of s, or (nil, false) when the
|
|
// backing store does not expose the durable-event feed. Assert once and fail
|
|
// loud. A single direct assertion is sufficient — see the decorator contract on
|
|
// AsIssueClaimer.
|
|
func AsEventQuerier(s Storage) (EventQuerier, bool) {
|
|
q, ok := s.(EventQuerier)
|
|
return q, ok
|
|
}
|
|
|
|
// AsBlockedQuerier returns the BlockedQuerier view of s, or (nil, false) when the
|
|
// backing store does not expose the transitive-blocked reads. Assert once and
|
|
// fail loud. A single direct assertion is sufficient — see the decorator
|
|
// contract on AsIssueClaimer.
|
|
func AsBlockedQuerier(s Storage) (BlockedQuerier, bool) {
|
|
q, ok := s.(BlockedQuerier)
|
|
return q, ok
|
|
}
|
|
|
|
// AsDependentQuerier returns the DependentQuerier view of s, or (nil, false) when
|
|
// the backing store does not expose the target-keyed dependents reads. Assert
|
|
// once and fail loud. A single direct assertion is sufficient — see the
|
|
// decorator contract on AsIssueClaimer.
|
|
func AsDependentQuerier(s Storage) (DependentQuerier, bool) {
|
|
q, ok := s.(DependentQuerier)
|
|
return q, ok
|
|
}
|
|
|
|
// ErrCircuitOpen is re-exported (aliased, so errors.Is works across the package
|
|
// boundary) from the Dolt storage layer: a read or write rejected because the
|
|
// Dolt circuit breaker is open wraps it. The claim sentinels ErrAlreadyClaimed
|
|
// and ErrNotClaimable — the ones ParseClaimConflict recovers assignee/status
|
|
// detail from — are re-exported with the other error sentinels below.
|
|
var (
|
|
ErrCircuitOpen = dolt.ErrCircuitOpen
|
|
ErrCommitIndeterminate = storage.ErrCommitIndeterminate
|
|
)
|
|
|
|
// IssueClaimer is the atomic-claim surface of a Storage. ClaimIssue and
|
|
// ClaimReadyIssue live on the storage.BulkIssueStore extension rather than the
|
|
// base Storage interface, so callers reach them by type-assertion via
|
|
// AsIssueClaimer rather than off the Storage value directly.
|
|
type IssueClaimer interface {
|
|
// ClaimIssue atomically claims id for actor using compare-and-swap
|
|
// semantics (open ∧ unassigned-or-same-actor). Returns a wrapped
|
|
// ErrAlreadyClaimed or ErrNotClaimable on conflict.
|
|
ClaimIssue(ctx context.Context, id string, actor string) error
|
|
// ClaimReadyIssue atomically claims the first ready issue matching filter,
|
|
// or returns (nil, nil) when none is claimable.
|
|
ClaimReadyIssue(ctx context.Context, filter WorkFilter, actor string) (*Issue, error)
|
|
}
|
|
|
|
// AsIssueClaimer returns the IssueClaimer view of s when the backing store
|
|
// supports atomic claim (Dolt-backed stores do), and (nil, false) otherwise.
|
|
// Assert once at startup and fail loud.
|
|
//
|
|
// DECORATOR CONTRACT: a single direct type-assertion is sufficient — no unwrap.
|
|
// ClaimIssue/ClaimReadyIssue (like EventsSince and the dependents reads) live on
|
|
// the engine interface storage.DoltStorage, and the compile-time drift guards
|
|
// below prove storage.DoltStorage satisfies each narrow surface. A store
|
|
// decorator therefore MUST embed storage.DoltStorage — as HookFiringStore does —
|
|
// which promotes these methods so the assertion reaches them THROUGH the
|
|
// decorator. (This is unlike the cmd/bd optional interfaces — StoreLocator,
|
|
// BackupStore, Flattener, … — which are NOT part of DoltStorage, do not promote,
|
|
// and so genuinely need storage.UnwrapStore.) A former storage.UnwrapStore
|
|
// fallback here was provably dead: whenever s satisfies storage.DoltStorage it
|
|
// already satisfies the narrow surface (drift guard), so the direct assertion
|
|
// always wins; and the only decorator, HookFiringStore, forwards by promotion.
|
|
func AsIssueClaimer(s Storage) (IssueClaimer, bool) {
|
|
c, ok := s.(IssueClaimer)
|
|
return c, ok
|
|
}
|
|
|
|
// Compile-time drift guards: the full engine interface storage.DoltStorage must
|
|
// satisfy each narrow public surface, so a signature change to the claim / event
|
|
// / dependents methods on the engine breaks the build here instead of silently
|
|
// making As* return false at runtime. Concrete-store conformance is asserted in
|
|
// the tests (both Dolt stores).
|
|
var (
|
|
_ IssueClaimer = (storage.DoltStorage)(nil)
|
|
_ EventQuerier = (storage.DoltStorage)(nil)
|
|
_ DependentQuerier = (storage.DoltStorage)(nil)
|
|
_ BlockedQuerier = (storage.DoltStorage)(nil)
|
|
)
|
|
|
|
// VersionControlReader provides read-only version control operations.
|
|
// Write operations (Branch, Checkout, Merge, DeleteBranch) are not yet
|
|
// part of the public API. If you need them, please open an issue.
|
|
type VersionControlReader interface {
|
|
CurrentBranch(ctx context.Context) (string, error)
|
|
ListBranches(ctx context.Context) ([]string, error)
|
|
CommitExists(ctx context.Context, commitHash string) (bool, error)
|
|
GetCurrentCommit(ctx context.Context) (string, error)
|
|
Status(ctx context.Context) (*VCStatus, error)
|
|
Log(ctx context.Context, limit int) ([]CommitInfo, error)
|
|
}
|
|
|
|
// Replication and version control types from internal/storage
|
|
type (
|
|
RemoteInfo = storage.RemoteInfo
|
|
SyncResult = storage.SyncResult
|
|
SyncStatus = storage.SyncStatus
|
|
Conflict = storage.Conflict
|
|
CommitInfo = storage.CommitInfo
|
|
VCStatus = storage.Status
|
|
StatusEntry = storage.StatusEntry
|
|
)
|
|
|
|
// AllowSharedSchemaMigration authorizes this process to apply pending schema
|
|
// migrations to a database that is SHARED with other bd clients — a Dolt
|
|
// sql-server, where migrating promotes the schema version for every connected
|
|
// client at once and clients still running an older bd will refuse the
|
|
// database until they are upgraded (gastownhall/beads#5920).
|
|
//
|
|
// Without it, an embedder that upgrades its beads dependency across a schema
|
|
// bump gets a migration-gate error from every writable Open* call, whose
|
|
// guidance names CLI commands (`bd migrate schema`) that mean nothing inside a
|
|
// library process. This is the programmatic equivalent of that command.
|
|
//
|
|
// It is process-local and set-or-clear, which is the point: the alternative —
|
|
// os.Setenv("BD_ALLOW_REMOTE_MIGRATE", "1") — is process-GLOBAL and inherited
|
|
// by every child process the embedder spawns, including git hooks and dolt
|
|
// subprocesses.
|
|
//
|
|
// The parity with that env var is only in the process-local mechanism, not the
|
|
// reach: BD_ALLOW_REMOTE_MIGRATE=1 unlocks BOTH the no-remote and the
|
|
// remote-backed shared arms, while this authorizes ONLY the no-remote arm. A
|
|
// remote-backed shared store still needs --force / AllowRemoteMigrateEnv,
|
|
// because #4259 cross-clone coordination is a stronger, different contract.
|
|
//
|
|
// Call it before the Open* call that should perform the migration, and clear
|
|
// it afterwards. Only grant it once the operator has confirmed that every
|
|
// other client of the server is upgraded; it is a coordination decision the
|
|
// library cannot make, because other clients' versions are not observable from
|
|
// this process.
|
|
//
|
|
// Embedded (single-writer) databases never need it: they still auto-migrate.
|
|
func AllowSharedSchemaMigration(allow bool) {
|
|
schema.SetSharedMigrateConsent(allow)
|
|
}
|
|
|
|
// Open opens a Dolt-backed beads database at the given path.
|
|
// This always opens in embedded mode. Use OpenFromConfig to respect
|
|
// server mode settings from metadata.json.
|
|
func Open(ctx context.Context, dbPath string) (Storage, error) {
|
|
return dolt.New(ctx, &dolt.Config{Path: dbPath, CreateIfMissing: true})
|
|
}
|
|
|
|
// OpenFromConfig opens the Dolt implementation using configuration from
|
|
// metadata.json. Unlike Open, this respects Dolt server mode settings and database
|
|
// name configuration.
|
|
// beadsDir is the path to the .beads directory.
|
|
func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error) {
|
|
return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
|
|
}
|
|
|
|
// OpenGated is OpenFromConfig plus participation in the workspace
|
|
// operation gate: it holds SHARED gates — the workspace gate and the
|
|
// physical database-root gate(s) — for the storage's lifetime (released by
|
|
// Close), so maintenance operations such as mode migration can DETECT
|
|
// this consumer and refuse to run over it, instead of running blind. The
|
|
// gate cannot force a holder out (there is no drain signal); it makes
|
|
// cooperating consumers visible and excludes new ones. Both levels matter:
|
|
// distinct workspaces can share one physical Dolt root, and a
|
|
// workspace-only gate would let maintenance replace that root under a
|
|
// consumer from another workspace. Library consumers that use the ungated
|
|
// Open/OpenFromConfig are invisible to the gate, and gate-aware
|
|
// maintenance operations refuse to proceed on workspaces they cannot
|
|
// prove quiet — prefer OpenGated in long-lived embedders.
|
|
//
|
|
// The physical roots are the UNION of doltserver.ResolvePhysicalRoots
|
|
// (the side-effect-free CLI-parity resolver: embedded engine's
|
|
// embeddeddolt dir, shared-server dir, proxied-server client info) and
|
|
// doltserver.LibraryOpenRootPath (the root the library open below —
|
|
// which applies central-config defaults and is server-only — will
|
|
// actually use), so the gated directory always includes the one this
|
|
// store opens. A resolver failure is
|
|
// deliberately not fatal here: the same failure will surface from the
|
|
// storage open below with a better error, and the workspace gate alone
|
|
// still covers the workspace-level maintenance conflicts. For a remote
|
|
// server backend there is no local physical root and only the workspace
|
|
// gate is taken.
|
|
//
|
|
// wait bounds how long to poll for the gates when a maintenance
|
|
// operation holds one exclusively; zero means fail fast. A busy gate is
|
|
// reported as ErrGateBusy (match with errors.Is).
|
|
func OpenGated(ctx context.Context, beadsDir string, wait time.Duration) (Storage, error) {
|
|
wsGate, err := workspacegate.ForWorkspace(beadsDir)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
gates := []workspacegate.Gate{wsGate}
|
|
|
|
// Gate the UNION of the CLI-parity resolver roots and the root the
|
|
// library open path below will actually use (they differ: the library
|
|
// path is server-only and applies central-config defaults, so an
|
|
// embedded-metadata workspace still opens at DatabasePath). Over-gating
|
|
// an extra root under a SHARED hold is benign; under-gating is the bug.
|
|
// All gates go into the ONE AcquireAll — never nested.
|
|
var roots []string
|
|
if pr, rerr := doltserver.ResolvePhysicalRoots(beadsDir); rerr == nil {
|
|
roots = append(roots, pr.Roots...)
|
|
}
|
|
roots = append(roots, doltserver.LibraryOpenRootPath(beadsDir))
|
|
for _, root := range roots {
|
|
// A root whose PARENT does not exist yet cannot be gated
|
|
// (workspacegate requires the gate file's parent) and cannot
|
|
// be holding data either; skip it rather than fail the open.
|
|
if _, serr := os.Stat(filepath.Dir(root)); serr != nil {
|
|
continue
|
|
}
|
|
physGate, gErr := workspacegate.ForPhysicalRoot(root)
|
|
if gErr != nil {
|
|
return nil, gErr
|
|
}
|
|
gates = append(gates, physGate)
|
|
}
|
|
|
|
h, err := workspacegate.AcquireAll(ctx, workspacegate.Shared,
|
|
workspacegate.Options{Wait: wait}, gates...)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
st, err := dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
|
|
if err != nil {
|
|
rerr := h.Release()
|
|
return nil, errors.Join(err, rerr)
|
|
}
|
|
return &gatedStorage{DoltStorage: st, gate: h}, nil
|
|
}
|
|
|
|
// gatedStorage ties shared gate handles to the storage lifetime: the
|
|
// gates are held exactly as long as the store is open. Per the decorator
|
|
// contract documented on AsIssueClaimer, it embeds storage.DoltStorage —
|
|
// the full engine interface, not the narrow Storage — so every capability
|
|
// assertion (RemoteStore, SyncStore, VersionControlReader, EventQuerier,
|
|
// ...) keeps working when an embedder switches from OpenFromConfig to
|
|
// OpenGated, and it exposes Unwrap for the cmd/bd optional interfaces
|
|
// that genuinely need storage.UnwrapStore.
|
|
type gatedStorage struct {
|
|
storage.DoltStorage
|
|
gate *workspacegate.MultiHandle
|
|
}
|
|
|
|
var _ storage.DoltStorage = (*gatedStorage)(nil)
|
|
|
|
// Unwrap exposes the inner store for storage.UnwrapStore, matching
|
|
// HookFiringStore's decorator shape.
|
|
func (g *gatedStorage) Unwrap() storage.DoltStorage { return g.DoltStorage }
|
|
|
|
// Close closes the store, then releases the gates — but only on a clean
|
|
// close. A failed or timed-out close can leave in-flight queries against
|
|
// the database, and releasing the gates then would let an exclusive
|
|
// maintenance operation start against storage that has not quiesced; in
|
|
// that case the flocks are deliberately left to die with the process.
|
|
func (g *gatedStorage) Close() error {
|
|
if err := g.DoltStorage.Close(); err != nil {
|
|
// Say so out loud: a long-lived embedder that ignores this error
|
|
// would otherwise silently keep excluding exclusive maintenance
|
|
// for the rest of the process lifetime.
|
|
fmt.Fprintf(os.Stderr,
|
|
"warning: beads store close failed; workspace gates deliberately retained until process exit: %v\n", err)
|
|
return err
|
|
}
|
|
return g.gate.Release()
|
|
}
|
|
|
|
// FindDatabasePath finds the beads database in the current directory tree
|
|
func FindDatabasePath() string {
|
|
return beads.FindDatabasePath()
|
|
}
|
|
|
|
// FindBeadsDir finds the .beads/ directory in the current directory tree.
|
|
// Returns empty string if not found.
|
|
func FindBeadsDir() string {
|
|
return beads.FindBeadsDir()
|
|
}
|
|
|
|
// DatabaseInfo contains information about a beads database
|
|
type DatabaseInfo = beads.DatabaseInfo
|
|
|
|
// FindAllDatabases finds all beads databases in the system
|
|
func FindAllDatabases() []DatabaseInfo {
|
|
return beads.FindAllDatabases()
|
|
}
|
|
|
|
// RedirectInfo contains information about a beads directory redirect
|
|
type RedirectInfo = beads.RedirectInfo
|
|
|
|
// GetRedirectInfo checks if the current beads directory is redirected.
|
|
// Returns RedirectInfo with IsRedirected=true if a redirect is active.
|
|
func GetRedirectInfo() RedirectInfo {
|
|
return beads.GetRedirectInfo()
|
|
}
|
|
|
|
// Core types from internal/types
|
|
type (
|
|
Issue = types.Issue
|
|
Status = types.Status
|
|
IssueType = types.IssueType
|
|
Dependency = types.Dependency
|
|
DependencyType = types.DependencyType
|
|
Label = types.Label
|
|
Comment = types.Comment
|
|
Event = types.Event
|
|
EventType = types.EventType
|
|
BlockedIssue = types.BlockedIssue
|
|
TreeNode = types.TreeNode
|
|
IssueFilter = types.IssueFilter
|
|
WorkFilter = types.WorkFilter
|
|
StaleFilter = types.StaleFilter
|
|
DependencyCounts = types.DependencyCounts
|
|
IssueWithCounts = types.IssueWithCounts
|
|
IssueWithDependencyMetadata = types.IssueWithDependencyMetadata
|
|
SortPolicy = types.SortPolicy
|
|
EpicStatus = types.EpicStatus
|
|
WispFilter = types.WispFilter
|
|
)
|
|
|
|
// Status constants
|
|
const (
|
|
StatusOpen = types.StatusOpen
|
|
StatusInProgress = types.StatusInProgress
|
|
StatusBlocked = types.StatusBlocked
|
|
StatusDeferred = types.StatusDeferred
|
|
StatusClosed = types.StatusClosed
|
|
)
|
|
|
|
// IssueType constants
|
|
const (
|
|
TypeBug = types.TypeBug
|
|
TypeFeature = types.TypeFeature
|
|
TypeTask = types.TypeTask
|
|
TypeEpic = types.TypeEpic
|
|
TypeChore = types.TypeChore
|
|
)
|
|
|
|
// DependencyType constants
|
|
const (
|
|
DepBlocks = types.DepBlocks
|
|
DepRelated = types.DepRelated
|
|
DepParentChild = types.DepParentChild
|
|
DepDiscoveredFrom = types.DepDiscoveredFrom
|
|
DepConditionalBlocks = types.DepConditionalBlocks // B runs only if A fails (bd-kzda)
|
|
)
|
|
|
|
// SortPolicy constants
|
|
const (
|
|
SortPolicyHybrid = types.SortPolicyHybrid
|
|
SortPolicyPriority = types.SortPolicyPriority
|
|
SortPolicyOldest = types.SortPolicyOldest
|
|
)
|
|
|
|
// EventType constants
|
|
const (
|
|
EventCreated = types.EventCreated
|
|
EventUpdated = types.EventUpdated
|
|
EventClaimed = types.EventClaimed
|
|
EventStatusChanged = types.EventStatusChanged
|
|
EventCommented = types.EventCommented
|
|
EventClosed = types.EventClosed
|
|
EventReopened = types.EventReopened
|
|
EventDependencyAdded = types.EventDependencyAdded
|
|
EventDependencyRemoved = types.EventDependencyRemoved
|
|
EventLabelAdded = types.EventLabelAdded
|
|
EventLabelRemoved = types.EventLabelRemoved
|
|
EventCompacted = types.EventCompacted
|
|
)
|
|
|
|
// MaxFieldLen re-exports the maximum length (in characters) of the assignee,
|
|
// owner, and label fields, paired with the ErrFieldTooLong sentinel below.
|
|
const MaxFieldLen = types.MaxFieldLen
|
|
|
|
// Re-exported error sentinels so consumers match on errors.Is rather than
|
|
// on message text. Each is an ALIAS of the internal sentinel, so the identity
|
|
// is preserved across the package boundary.
|
|
var (
|
|
ErrNotFound = storage.ErrNotFound
|
|
ErrAlreadyClaimed = storage.ErrAlreadyClaimed
|
|
ErrNotClaimable = storage.ErrNotClaimable
|
|
ErrCloseBlocked = storage.ErrCloseBlocked
|
|
ErrVersionMismatch = storage.ErrVersionMismatch
|
|
ErrSelfDependency = domain.ErrSelfDependency
|
|
ErrDependencyCycle = domain.ErrDependencyCycle
|
|
// ErrDependencySourceNotFound and ErrDependencyTargetNotFound are the two
|
|
// endpoint-existence refusals AddDependency and AddDependencies raise; the
|
|
// typed value carrying the missing id is DependencyEndpointNotFoundError.
|
|
ErrDependencySourceNotFound = domain.ErrDependencySourceNotFound
|
|
ErrDependencyTargetNotFound = domain.ErrDependencyTargetNotFound
|
|
ErrFieldTooLong = types.ErrFieldTooLong
|
|
// ErrGateBusy is returned by OpenGated when a maintenance operation
|
|
// holds the workspace or physical-root gate exclusively and the wait
|
|
// budget ran out. Alias of the internal sentinel so errors.Is works
|
|
// across the package boundary.
|
|
ErrGateBusy = workspacegate.ErrBusy
|
|
)
|
|
|
|
// DependencyTypeConflictError is returned by AddDependency when an edge of a
|
|
// different type already exists between the pair; callers errors.As it to read
|
|
// the existing/requested types instead of parsing the message.
|
|
type DependencyTypeConflictError = domain.DependencyTypeConflictError
|
|
|
|
// DependencyHierarchyConflictError is returned by AddDependency when a blocking
|
|
// edge would gate an issue on its own ancestor/descendant (a gate that can
|
|
// never clear).
|
|
type DependencyHierarchyConflictError = domain.DependencyHierarchyConflictError
|
|
|
|
// DependencyEndpointNotFoundError is returned by AddDependency when an edge
|
|
// names an endpoint this database can see the absence of; callers errors.As it
|
|
// to read the missing id instead of parsing the message.
|
|
type DependencyEndpointNotFoundError = domain.DependencyEndpointNotFoundError
|