beads/internal/storage/storage.go
2026-04-28 07:11:13 -07:00

297 lines
13 KiB
Go

// Package storage provides shared types for issue storage.
//
// The concrete storage implementation lives in the dolt sub-package.
// This package holds interface and value types that are referenced by
// both the dolt implementation and its consumers (cmd/bd, etc.).
package storage
import (
"context"
"database/sql"
"errors"
"time"
"github.com/steveyegge/beads/internal/types"
)
// ErrAlreadyClaimed is returned when attempting to claim an issue that is already
// claimed by another user. The error message contains the current assignee.
var ErrAlreadyClaimed = errors.New("issue already claimed")
// ErrNotClaimable is returned when attempting to claim an issue that is not in a
// claimable state, such as closed, deferred, or already in progress without the
// same actor owning the claim.
var ErrNotClaimable = errors.New("issue not claimable")
// ErrNotFound is returned when a requested entity does not exist in the database.
var ErrNotFound = errors.New("not found")
// ErrNotInitialized is returned when the database has not been initialized
// (e.g., issue_prefix config is missing).
var ErrNotInitialized = errors.New("database not initialized")
// ErrPrefixMismatch is returned when an issue ID does not match the configured prefix.
var ErrPrefixMismatch = errors.New("prefix mismatch")
// Storage is the interface satisfied by *dolt.DoltStore.
// Consumers depend on this interface rather than on the concrete type so that
// alternative implementations (mocks, proxies, etc.) can be substituted.
type Storage interface {
// Issue CRUD
CreateIssue(ctx context.Context, issue *types.Issue, actor string) error
CreateIssues(ctx context.Context, issues []*types.Issue, actor string) error
GetIssue(ctx context.Context, id string) (*types.Issue, error)
GetIssueByExternalRef(ctx context.Context, externalRef string) (*types.Issue, error)
GetIssuesByIDs(ctx context.Context, ids []string) ([]*types.Issue, error)
UpdateIssue(ctx context.Context, id string, updates map[string]interface{}, actor string) error
ReopenIssue(ctx context.Context, id string, reason string, actor string) error
UpdateIssueType(ctx context.Context, id string, issueType string, actor string) error
CloseIssue(ctx context.Context, id string, reason string, actor string, session string) error
DeleteIssue(ctx context.Context, id string) error
SearchIssues(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error)
// Dependencies
AddDependency(ctx context.Context, dep *types.Dependency, actor string) error
RemoveDependency(ctx context.Context, issueID, dependsOnID string, actor string) error
GetDependencies(ctx context.Context, issueID string) ([]*types.Issue, error)
GetDependents(ctx context.Context, issueID string) ([]*types.Issue, error)
GetDependenciesWithMetadata(ctx context.Context, issueID string) ([]*types.IssueWithDependencyMetadata, error)
GetDependentsWithMetadata(ctx context.Context, issueID string) ([]*types.IssueWithDependencyMetadata, error)
GetDependencyTree(ctx context.Context, issueID string, maxDepth int, showAllPaths bool, reverse bool) ([]*types.TreeNode, error)
// Labels
AddLabel(ctx context.Context, issueID, label, actor string) error
RemoveLabel(ctx context.Context, issueID, label, actor string) error
GetLabels(ctx context.Context, issueID string) ([]string, error)
GetIssuesByLabel(ctx context.Context, label string) ([]*types.Issue, error)
// Work queries
GetReadyWork(ctx context.Context, filter types.WorkFilter) ([]*types.Issue, error)
GetBlockedIssues(ctx context.Context, filter types.WorkFilter) ([]*types.BlockedIssue, error)
GetEpicsEligibleForClosure(ctx context.Context) ([]*types.EpicStatus, error)
// Wisp queries
// ListWisps returns ephemeral issues matching the filter.
// It always restricts to Ephemeral=true; callers do not need to set that flag.
ListWisps(ctx context.Context, filter types.WispFilter) ([]*types.Issue, error)
// Comments and events
AddIssueComment(ctx context.Context, issueID, author, text string) (*types.Comment, error)
GetIssueComments(ctx context.Context, issueID string) ([]*types.Comment, error)
GetEvents(ctx context.Context, issueID string, limit int) ([]*types.Event, error)
GetAllEventsSince(ctx context.Context, since time.Time) ([]*types.Event, error)
// Statistics
GetStatistics(ctx context.Context) (*types.Statistics, error)
// Configuration
SetConfig(ctx context.Context, key, value string) error
GetConfig(ctx context.Context, key string) (string, error)
GetAllConfig(ctx context.Context) (map[string]string, error)
// Local metadata operations (dolt-ignored, clone-local state).
// Used for tip timestamps, version stamps, tracker sync cursors, etc.
// Data is ephemeral — callers must handle ("", nil) as the normal case.
SetLocalMetadata(ctx context.Context, key, value string) error
GetLocalMetadata(ctx context.Context, key string) (string, error)
// Transactions
RunInTransaction(ctx context.Context, commitMsg string, fn func(tx Transaction) error) error
// MergeSlot — serialized conflict resolution primitive.
// Each rig has one merge slot bead (<prefix>-merge-slot, labeled gt:slot).
// The slot ID is derived from the issue_prefix config key.
MergeSlotCreate(ctx context.Context, actor string) (*types.Issue, error)
MergeSlotCheck(ctx context.Context) (*MergeSlotStatus, error)
MergeSlotAcquire(ctx context.Context, holder, actor string, wait bool) (*MergeSlotResult, error)
MergeSlotRelease(ctx context.Context, holder, actor string) error
// Metadata slots — key-value pairs stored in issue metadata JSON.
// Used by gt for delegation tracking, hook state, and other per-issue data.
SlotSet(ctx context.Context, issueID, key, value, actor string) error
SlotGet(ctx context.Context, issueID, key string) (string, error)
SlotClear(ctx context.Context, issueID, key, actor string) error
// Lifecycle
Close() error
}
// MergeSlotStatus is returned by MergeSlotCheck and describes the current
// state of the merge slot bead.
type MergeSlotStatus struct {
SlotID string
Available bool
Holder string
Waiters []string
}
// MergeSlotResult is returned by MergeSlotAcquire.
type MergeSlotResult struct {
// SlotID is the bead ID of the merge slot.
SlotID string
// Acquired is true when the slot was successfully acquired by the caller.
Acquired bool
// Waiting is true when --wait was passed and the caller was added to the
// waiters queue (the slot was held by someone else).
Waiting bool
// Holder is the current holder of the slot. When Acquired is true this
// is the caller; when Waiting is true this is the previous holder.
Holder string
// Position is the 1-based position in the waiters queue when Waiting is true.
Position int
}
// DoltStorage is the full interface for Dolt-backed stores, composing the core
// Storage interface with all capability sub-interfaces. Both DoltStore and
// EmbeddedDoltStore satisfy this interface.
type DoltStorage interface {
Storage
VersionControl
HistoryViewer
RemoteStore
SyncStore
FederationStore
BulkIssueStore
DependencyQueryStore
AnnotationStore
ConfigMetadataStore
CompactionStore
AdvancedQueryStore
}
// RawDBAccessor provides raw *sql.DB access for diagnostics and migrations.
// Callers that need raw SQL should type-assert to this interface.
type RawDBAccessor interface {
DB() *sql.DB
UnderlyingDB() *sql.DB
}
// StoreLocator provides filesystem path information for the store.
// Callers that need the store's on-disk location should type-assert to this interface.
type StoreLocator interface {
Path() string
CLIDir() string
}
// GarbageCollector provides Dolt garbage collection capability.
// Callers that need to reclaim disk space should type-assert to this interface.
type GarbageCollector interface {
DoltGC(ctx context.Context) error
}
// Flattener squashes all Dolt commit history into a single commit.
// Callers should type-assert to this interface for history compaction.
type Flattener interface {
Flatten(ctx context.Context) error
}
// Compactor squashes old Dolt commits while preserving recent ones.
// Callers should type-assert to this interface for selective history compaction.
type Compactor interface {
Compact(ctx context.Context, initialHash, boundaryHash string, oldCommits int, recentHashes []string) error
}
// LifecycleManager provides lifecycle inspection beyond Close().
type LifecycleManager interface {
IsClosed() bool
}
// PendingCommitter provides the ability to commit pending (dirty) changes.
// Used by auto-commit and auto-push flows.
type PendingCommitter interface {
CommitPending(ctx context.Context, actor string) (bool, error)
}
// BackupStore provides Dolt backup operations (CALL DOLT_BACKUP) for
// disaster recovery.
// Callers that need backup functionality should type-assert to this interface.
type BackupStore interface {
BackupAdd(ctx context.Context, name, url string) error
BackupSync(ctx context.Context, name string) error
BackupRemove(ctx context.Context, name string) error
// BackupDatabase registers dir as a file:// Dolt backup remote and syncs
// the full database to it, preserving complete commit history.
BackupDatabase(ctx context.Context, dir string) error
// RestoreDatabase restores the database from a Dolt backup at dir.
// When force is true, the existing database is dropped before restoring.
RestoreDatabase(ctx context.Context, dir string, force bool) error
}
// Transaction provides atomic multi-operation support within a single database transaction.
//
// The Transaction interface exposes a subset of storage methods that execute within
// a single database transaction. This enables atomic workflows where multiple operations
// must either all succeed or all fail (e.g., creating issues with dependencies and labels).
//
// # Transaction Semantics
//
// - All operations within the transaction share the same database connection
// - Changes are not visible to other connections until commit
// - If any operation returns an error, the transaction is rolled back
// - If the callback function panics, the transaction is rolled back
// - On successful return from the callback, the transaction is committed
//
// # Example Usage
//
// err := store.RunInTransaction(ctx, "bd: create parent and child", func(tx storage.Transaction) error {
// // Create parent issue
// if err := tx.CreateIssue(ctx, parentIssue, actor); err != nil {
// return err // Triggers rollback
// }
// // Create child issue
// if err := tx.CreateIssue(ctx, childIssue, actor); err != nil {
// return err // Triggers rollback
// }
// // Add dependency between them
// if err := tx.AddDependency(ctx, dep, actor); err != nil {
// return err // Triggers rollback
// }
// return nil // Triggers commit
// })
type Transaction interface {
// Issue operations
CreateIssue(ctx context.Context, issue *types.Issue, actor string) error
CreateIssues(ctx context.Context, issues []*types.Issue, actor string) error
UpdateIssue(ctx context.Context, id string, updates map[string]interface{}, actor string) error
CloseIssue(ctx context.Context, id string, reason string, actor string, session string) error
DeleteIssue(ctx context.Context, id string) error
GetIssue(ctx context.Context, id string) (*types.Issue, error) // For read-your-writes within transaction
SearchIssues(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error) // For read-your-writes within transaction
// Dependency operations
AddDependency(ctx context.Context, dep *types.Dependency, actor string) error
AddDependencyWithOptions(ctx context.Context, dep *types.Dependency, actor string, opts DependencyAddOptions) error
RemoveDependency(ctx context.Context, issueID, dependsOnID string, actor string) error
GetDependencyRecords(ctx context.Context, issueID string) ([]*types.Dependency, error)
// Label operations
AddLabel(ctx context.Context, issueID, label, actor string) error
RemoveLabel(ctx context.Context, issueID, label, actor string) error
GetLabels(ctx context.Context, issueID string) ([]string, error)
// Config operations (for atomic config + issue workflows)
SetConfig(ctx context.Context, key, value string) error
GetConfig(ctx context.Context, key string) (string, error)
// Metadata operations (for internal state like import hashes)
SetMetadata(ctx context.Context, key, value string) error
GetMetadata(ctx context.Context, key string) (string, error)
// Local metadata operations (dolt-ignored, clone-local state).
// Used for tip timestamps, version stamps, tracker sync cursors, etc.
// Data is ephemeral — callers must handle ("", nil) as the normal case.
SetLocalMetadata(ctx context.Context, key, value string) error
GetLocalMetadata(ctx context.Context, key string) (string, error)
// Comment operations
AddComment(ctx context.Context, issueID, actor, comment string) error
ImportIssueComment(ctx context.Context, issueID, author, text string, createdAt time.Time) (*types.Comment, error)
GetIssueComments(ctx context.Context, issueID string) ([]*types.Comment, error)
}
// DependencyAddOptions controls transaction-scoped dependency insertion.
type DependencyAddOptions struct {
// SkipCycleCheck bypasses the recursive pre-insert cycle check. This is
// intended for bulk wiring paths that perform a final graph check separately.
SkipCycleCheck bool
}