storage

package
v0.62.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 13, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package storage defines the interface for issue storage backends.

Package storage defines the interface for issue storage backends.

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 provides shared types for issue storage.

Index

Constants

This section is empty.

Variables

View Source 
var ErrAlreadyClaimed = errors.New("issue already claimed")

ErrAlreadyClaimed is returned when attempting to claim an issue that is already claimed by another user. The error message contains the current assignee.

View Source 
var ErrNotFound = errors.New("not found")

ErrNotFound is returned when a requested entity does not exist in the database.

View Source 
var ErrNotInitialized = errors.New("database not initialized")

ErrNotInitialized is returned when the database has not been initialized (e.g., issue_prefix config is missing).

View Source 
var ErrPrefixMismatch = errors.New("prefix mismatch")

ErrPrefixMismatch is returned when an issue ID does not match the configured prefix.

Functions

func NormalizeMetadataValue 

func NormalizeMetadataValue(value interface{}) (string, error)

NormalizeMetadataValue converts metadata values to a validated JSON string. Accepts string, []byte, or json.RawMessage and returns a validated JSON string. Returns an error if the value is not valid JSON or is an unsupported type.

This supports GH#1417: allow UpdateIssue metadata updates via json.RawMessage/[]byte.

func ValidateMetadataKey 

func ValidateMetadataKey(key string) error

ValidateMetadataKey checks that a metadata key is safe for use in JSON path expressions. Keys must start with a letter or underscore and contain only alphanumeric characters, underscores, and dots.

Types

type AdvancedQueryStore 

type AdvancedQueryStore interface {
	GetRepoMtime(ctx context.Context, repoPath string) (int64, error)
	SetRepoMtime(ctx context.Context, repoPath, jsonlPath string, mtimeNs int64) error
	ClearRepoMtime(ctx context.Context, repoPath string) error
	GetMoleculeProgress(ctx context.Context, moleculeID string) (*types.MoleculeProgressStats, error)
	GetMoleculeLastActivity(ctx context.Context, moleculeID string) (*types.MoleculeLastActivity, error)
	GetStaleIssues(ctx context.Context, filter types.StaleFilter) ([]*types.Issue, error)
}

AdvancedQueryStore provides repo mtime tracking, molecule queries, and stale issue detection.

type AnnotationStore 

type AnnotationStore interface {
	AddComment(ctx context.Context, issueID, actor, comment string) error
	ImportIssueComment(ctx context.Context, issueID, author, text string, createdAt time.Time) (*types.Comment, error)
	GetCommentCounts(ctx context.Context, issueIDs []string) (map[string]int, error)
	GetCommentsForIssues(ctx context.Context, issueIDs []string) (map[string][]*types.Comment, error)
	GetLabelsForIssues(ctx context.Context, issueIDs []string) (map[string][]string, error)
}

AnnotationStore provides comment and label operations, including bulk queries.

type BatchCreateOptions 

type BatchCreateOptions struct {
	// OrphanHandling specifies how to handle issues with missing parent references
	OrphanHandling OrphanHandling
	// SkipPrefixValidation skips prefix validation for existing IDs (used during import)
	SkipPrefixValidation bool
}

BatchCreateOptions contains options for batch issue creation. This is a backend-agnostic type that can be used by any storage implementation.

type BulkIssueStore 

type BulkIssueStore interface {
	CreateIssuesWithFullOptions(ctx context.Context, issues []*types.Issue, actor string, opts BatchCreateOptions) error
	DeleteIssues(ctx context.Context, ids []string, cascade bool, force bool, dryRun bool) (*types.DeleteIssuesResult, error)
	DeleteIssuesBySourceRepo(ctx context.Context, sourceRepo string) (int, error)
	UpdateIssueID(ctx context.Context, oldID, newID string, issue *types.Issue, actor string) error
	ClaimIssue(ctx context.Context, id string, actor string) error
	PromoteFromEphemeral(ctx context.Context, id string, actor string) error
	GetNextChildID(ctx context.Context, parentID string) (string, error)
	RenameCounterPrefix(ctx context.Context, oldPrefix, newPrefix string) error
}

BulkIssueStore provides extended issue CRUD beyond the base Storage interface.

type CommitInfo 

type CommitInfo struct {
	Hash    string
	Author  string
	Email   string
	Date    time.Time
	Message string
}

CommitInfo represents a version control commit.

type CompactionStore 

type CompactionStore interface {
	CheckEligibility(ctx context.Context, issueID string, tier int) (bool, string, error)
	ApplyCompaction(ctx context.Context, issueID string, tier int, originalSize int, compactedSize int, commitHash string) error
	GetTier1Candidates(ctx context.Context) ([]*types.CompactionCandidate, error)
	GetTier2Candidates(ctx context.Context) ([]*types.CompactionCandidate, error)
}

CompactionStore provides issue compaction and tiering operations.

type ConfigMetadataStore 

type ConfigMetadataStore interface {
	GetMetadata(ctx context.Context, key string) (string, error)
	SetMetadata(ctx context.Context, key, value string) error
	DeleteConfig(ctx context.Context, key string) error
	GetCustomStatuses(ctx context.Context) ([]string, error)
	GetCustomTypes(ctx context.Context) ([]string, error)
	GetInfraTypes(ctx context.Context) map[string]bool
	IsInfraTypeCtx(ctx context.Context, t types.IssueType) bool
}

ConfigMetadataStore provides extended config, metadata, and type introspection.

type Conflict 

type Conflict struct {
	IssueID     string      // The ID of the conflicting issue
	Field       string      // Which field has the conflict (empty for table-level)
	OursValue   interface{} // Value on current branch
	TheirsValue interface{} // Value on merged branch
}

Conflict represents a merge conflict.

type DependencyQueryStore 

type DependencyQueryStore interface {
	GetDependencyRecords(ctx context.Context, issueID string) ([]*types.Dependency, error)
	GetDependencyRecordsForIssues(ctx context.Context, issueIDs []string) (map[string][]*types.Dependency, error)
	GetAllDependencyRecords(ctx context.Context) (map[string][]*types.Dependency, error)
	GetDependencyCounts(ctx context.Context, issueIDs []string) (map[string]*types.DependencyCounts, error)
	GetBlockingInfoForIssues(ctx context.Context, issueIDs []string) (blockedByMap map[string][]string, blocksMap map[string][]string, parentMap map[string]string, err error)
	IsBlocked(ctx context.Context, issueID string) (bool, []string, error)
	GetNewlyUnblockedByClose(ctx context.Context, closedIssueID string) ([]*types.Issue, error)
	DetectCycles(ctx context.Context) ([][]*types.Issue, error)
	FindWispDependentsRecursive(ctx context.Context, ids []string) (map[string]bool, error)
	RenameDependencyPrefix(ctx context.Context, oldPrefix, newPrefix string) error
}

DependencyQueryStore provides extended dependency queries beyond the base Storage interface.

type DiffEntry 

type DiffEntry struct {
	IssueID  string       // The ID of the affected issue
	DiffType string       // "added", "modified", or "removed"
	OldValue *types.Issue // State before (nil for "added")
	NewValue *types.Issue // State after (nil for "removed")
}

DiffEntry represents a change between two commits.

type DoltStorage 

type DoltStorage interface {
	Storage
	VersionControl
	HistoryViewer
	RemoteStore
	SyncStore
	FederationStore
	BulkIssueStore
	DependencyQueryStore
	AnnotationStore
	ConfigMetadataStore
	CompactionStore
	AdvancedQueryStore
}

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 FederationPeer 

type FederationPeer struct {
	Name        string     // Unique name for this peer (used as remote name)
	RemoteURL   string     // Dolt remote URL (e.g., http://host:port/org/db)
	Username    string     // SQL username for authentication
	Password    string     // Password (decrypted, not stored directly)
	Sovereignty string     // Sovereignty tier: T1, T2, T3, T4
	LastSync    *time.Time // Last successful sync time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

FederationPeer represents a remote peer with authentication credentials. Used for peer-to-peer Dolt remotes between Gas Towns with SQL user auth.

type FederationStore 

type FederationStore interface {
	AddFederationPeer(ctx context.Context, peer *FederationPeer) error
	GetFederationPeer(ctx context.Context, name string) (*FederationPeer, error)
	ListFederationPeers(ctx context.Context) ([]*FederationPeer, error)
	RemoveFederationPeer(ctx context.Context, name string) error
}

FederationStore provides federation peer management.

type HistoryEntry 

type HistoryEntry struct {
	CommitHash string       // The commit hash at this point
	Committer  string       // Who made the commit
	CommitDate time.Time    // When the commit was made
	Issue      *types.Issue // The issue state at that commit
}

HistoryEntry represents an issue at a specific point in history.

type HistoryViewer 

type HistoryViewer interface {
	History(ctx context.Context, issueID string) ([]*HistoryEntry, error)
	AsOf(ctx context.Context, issueID string, ref string) (*types.Issue, error)
	Diff(ctx context.Context, fromRef, toRef string) ([]*DiffEntry, error)
}

HistoryViewer provides time-travel queries and diffs.

type MetadataFieldSchema 

type MetadataFieldSchema struct {
	Type     MetadataFieldType
	Values   []string // allowed values for enum type
	Required bool
	Min      *float64 // min value for int/float
	Max      *float64 // max value for int/float
}

MetadataFieldSchema defines validation rules for a single metadata field.

type MetadataFieldType 

type MetadataFieldType string

MetadataFieldType defines the type of a metadata field for schema validation. 

const (
	MetadataFieldString MetadataFieldType = "string"
	MetadataFieldInt    MetadataFieldType = "int"
	MetadataFieldFloat  MetadataFieldType = "float"
	MetadataFieldBool   MetadataFieldType = "bool"
	MetadataFieldEnum   MetadataFieldType = "enum"
)

type MetadataSchemaConfig 

type MetadataSchemaConfig struct {
	Mode   string                         // "none", "warn", "error"
	Fields map[string]MetadataFieldSchema // field name → schema
}

MetadataSchemaConfig holds the parsed metadata validation configuration.

type MetadataValidationError 

type MetadataValidationError struct {
	Field   string
	Message string
}

MetadataValidationError describes a single schema violation.

func ValidateMetadataSchema 

func ValidateMetadataSchema(metadata json.RawMessage, schema MetadataSchemaConfig) []MetadataValidationError

ValidateMetadataSchema validates a metadata blob against a schema config. Returns a list of validation errors. An empty list means validation passed. If metadata is nil/empty and no fields are required, returns no errors.

func (MetadataValidationError) Error 

func (e MetadataValidationError) Error() string

type OrphanHandling 

type OrphanHandling string

OrphanHandling specifies how to handle issues with missing parent references. 

const (
	// OrphanStrict fails import on missing parent (safest)
	OrphanStrict OrphanHandling = "strict"
	// OrphanResurrect auto-resurrects missing parents from database history
	OrphanResurrect OrphanHandling = "resurrect"
	// OrphanSkip skips orphaned issues with warning
	OrphanSkip OrphanHandling = "skip"
	// OrphanAllow imports orphans without validation (default, works around bugs)
	OrphanAllow OrphanHandling = "allow"
)

type RemoteInfo 

type RemoteInfo struct {
	Name string // Remote name (e.g., "town-beta")
	URL  string // Remote URL (e.g., "dolthub://org/repo")
}

RemoteInfo describes a configured remote.

type RemoteStore 

type RemoteStore interface {
	AddRemote(ctx context.Context, name, url string) error
	RemoveRemote(ctx context.Context, name string) error
	HasRemote(ctx context.Context, name string) (bool, error)
	ListRemotes(ctx context.Context) ([]RemoteInfo, error)
	Push(ctx context.Context) error
	Pull(ctx context.Context) error
	ForcePush(ctx context.Context) error
	Fetch(ctx context.Context, peer string) error
	PushTo(ctx context.Context, peer string) error
	PullFrom(ctx context.Context, peer string) ([]Conflict, error)
}

RemoteStore provides remote management and push/pull/fetch operations.

type Status 

type Status struct {
	Staged   []StatusEntry
	Unstaged []StatusEntry
}

Status represents the current repository status.

type StatusEntry 

type StatusEntry struct {
	Table  string
	Status string // "new", "modified", "deleted"
}

StatusEntry represents a changed table in the working set.

type Storage 

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
	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)

	// 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, sinceID int64) ([]*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)

	// Transactions
	RunInTransaction(ctx context.Context, commitMsg string, fn func(tx Transaction) error) error

	// Lifecycle
	Close() error
}

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 SyncResult 

type SyncResult struct {
	Peer              string
	StartTime         time.Time
	EndTime           time.Time
	Fetched           bool
	Merged            bool
	Pushed            bool
	PulledCommits     int
	PushedCommits     int
	Conflicts         []Conflict
	ConflictsResolved bool
	Error             error
	PushError         error // Non-fatal push error
}

SyncResult contains the outcome of a Sync operation.

type SyncStatus 

type SyncStatus struct {
	Peer         string    // Peer name
	LastSync     time.Time // When last synced
	LocalAhead   int       // Commits ahead of peer
	LocalBehind  int       // Commits behind peer
	HasConflicts bool      // Whether there are unresolved conflicts
}

SyncStatus describes the synchronization state with a peer.

type SyncStore 

type SyncStore interface {
	Sync(ctx context.Context, peer string, strategy string) (*SyncResult, error)
	SyncStatus(ctx context.Context, peer string) (*SyncStatus, error)
}

SyncStore provides sync operations with peers.

type Transaction 

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
	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)

	// 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)
}

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 VersionControl 

type VersionControl interface {
	Branch(ctx context.Context, name string) error
	Checkout(ctx context.Context, branch string) error
	CurrentBranch(ctx context.Context) (string, error)
	DeleteBranch(ctx context.Context, branch string) error
	ListBranches(ctx context.Context) ([]string, error)
	Commit(ctx context.Context, message string) error
	CommitPending(ctx context.Context, actor string) (bool, error)
	CommitExists(ctx context.Context, commitHash string) (bool, error)
	GetCurrentCommit(ctx context.Context) (string, error)
	Status(ctx context.Context) (*Status, error)
	Log(ctx context.Context, limit int) ([]CommitInfo, error)
	Merge(ctx context.Context, branch string) ([]Conflict, error)
	GetConflicts(ctx context.Context) ([]Conflict, error)
	ResolveConflicts(ctx context.Context, table string, strategy string) error
}

VersionControl provides branch, commit, merge, and status operations.

Source Files

View all Source files

Directories

Path Synopsis
Package dolt implements the storage interface using Dolt (versioned MySQL-compatible database).
 Package dolt implements the storage interface using Dolt (versioned MySQL-compatible database).
migrations
Package doltutil provides shared utilities for Dolt operations.
 Package doltutil provides shared utilities for Dolt operations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.