Documentation
¶
Overview ¶
Package store provides the single-host storage and authorization boundary. Every publication is one SQLite transaction, including its immutable content, current pointer, retry receipt, and audit record.
Index ¶
- Constants
- type Error
- type Principal
- type StorageInfo
- type StorageReport
- type Store
- func (s *Store) Audit(ctx context.Context, p Principal, limit int) ([]protocol.AuditEvent, error)
- func (s *Store) Authenticate(ctx context.Context, token string) (Principal, error)
- func (s *Store) Close() error
- func (s *Store) CreateToken(ctx context.Context, agentID, scope string) (tokenResult string, resultErr error)
- func (s *Store) Get(ctx context.Context, p Principal, key string) (result protocol.Artifact, resultErr error)
- func (s *Store) Identity(ctx context.Context, p Principal) (protocol.Identity, error)
- func (s *Store) List(ctx context.Context, p Principal) ([]protocol.Artifact, error)
- func (s *Store) Publish(ctx context.Context, p Principal, r protocol.PublishRequest) (protocol.PublishResult, error)
- func (s *Store) PublishPinned(ctx context.Context, p Principal, r protocol.PublishRequest, ...) (protocol.PublishResult, error)
- func (s *Store) PutSemantic(ctx context.Context, p Principal, request semantic.PutRequest) (err error)
- func (s *Store) QuerySemantic(ctx context.Context, p Principal, query semantic.Query) (result semantic.SearchResult, err error)
- func (s *Store) RevokeAgent(ctx context.Context, agentID string) (err error)
- func (s *Store) SetStorageObserver(f func(context.Context, retention.Event))
- func (s *Store) StartStorageMaintenance(ctx context.Context, interval time.Duration, source admission.Source) (stop func(), err error)
- func (s *Store) StorageArchive(ctx context.Context, dryRun bool, now time.Time, budget retention.Budget) (report StorageReport, err error)
- func (s *Store) StorageCompact(ctx context.Context) (err error)
- func (s *Store) StorageConfigure(ctx context.Context, c retention.Config) (err error)
- func (s *Store) StorageHistory(ctx context.Context, scope, key string, version int64) (a protocol.Artifact, err error)
- func (s *Store) StorageInfo(ctx context.Context) (info StorageInfo, err error)
- func (s *Store) StorageRestore(ctx context.Context, maxItems int) (report StorageReport, err error)
- func (s *Store) StorageVerify(ctx context.Context) (report StorageReport, err error)
- func (s *Store) Sync(ctx context.Context, p Principal, request protocol.SyncRequest) (result protocol.SyncPage, resultErr error)
Constants ¶
const DefaultStorageInterval = 5 * time.Minute
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Principal ¶
Principal is established by Authenticate. Store operations verify it again, so constructing a Principal alone does not grant access.
type StorageInfo ¶ added in v0.12.0
type StorageInfo struct {
Policy *retention.Config `json:"policy"`
CurrentArtifacts int64 `json:"current_artifacts"`
Versions int64 `json:"versions"`
ArchivedVersions int64 `json:"archived_versions"`
HotPayloadBytes int64 `json:"hot_payload_bytes"`
ColdBytes int64 `json:"cold_bytes"`
DatabaseBytes int64 `json:"database_bytes"`
WALBytes int64 `json:"wal_bytes"`
FreePageBytes int64 `json:"free_page_bytes"`
ColdFiles int64 `json:"cold_files"`
TemporaryBytes int64 `json:"temporary_bytes"`
}
type StorageReport ¶ added in v0.12.0
type StorageReport struct {
Operation string `json:"operation"`
Status string `json:"status"`
Items int64 `json:"items"`
Bytes int64 `json:"bytes"`
DryRun bool `json:"dry_run"`
Deferred bool `json:"deferred"`
Reason string `json:"reason,omitempty"`
ScannedItems int64 `json:"scanned_items,omitempty"`
ScannedBytes int64 `json:"scanned_bytes,omitempty"`
}
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
func Open ¶
Open creates or opens a local SQLite database. New directories are private; existing parent directories retain their permissions. SQLite must reside on a local filesystem, not a shared network volume.
func (*Store) Audit ¶
Audit returns at most 1000 events in the principal's scope, newest first. Nonpositive limits use the default of 100.
func (*Store) Authenticate ¶
func (*Store) CreateToken ¶
func (s *Store) CreateToken(ctx context.Context, agentID, scope string) (tokenResult string, resultErr error)
CreateToken creates a new immutable agent identity. The plaintext token is returned once; only its SHA-256 digest is persisted. Revoked agent IDs cannot be recycled, preserving the meaning of audit and idempotency records.
func (*Store) List ¶
List returns metadata for at most the first 1000 current artifacts ordered by key. Content is deliberately omitted to keep list responses bounded; Get fetches an individual artifact's content.
func (*Store) Publish ¶
func (s *Store) Publish(ctx context.Context, p Principal, r protocol.PublishRequest) (protocol.PublishResult, error)
Publish applies compare-and-swap within the authenticated scope. A successful operation ID is permanently bound to the complete original request. Retries return that original version even after newer versions have been published.
func (*Store) PublishPinned ¶ added in v0.8.0
func (s *Store) PublishPinned(ctx context.Context, p Principal, r protocol.PublishRequest, expected protocol.Identity) (protocol.PublishResult, error)
PublishPinned adds a rejection-only identity precondition inside the existing CAS transaction. It never grants the supplied scope or agent any authority.
func (*Store) PutSemantic ¶ added in v0.14.0
func (s *Store) PutSemantic(ctx context.Context, p Principal, request semantic.PutRequest) (err error)
PutSemantic writes only the derived index. It cannot mutate an inference claim, an artifact version, a receipt, or a budget reservation.
func (*Store) QuerySemantic ¶ added in v0.14.0
func (s *Store) QuerySemantic(ctx context.Context, p Principal, query semantic.Query) (result semantic.SearchResult, err error)
QuerySemantic scans a bounded, deterministic subset after all metadata filters. Vectors are decoded one at a time, never accumulated in memory.
func (*Store) RevokeAgent ¶
func (*Store) SetStorageObserver ¶ added in v0.12.0
func (*Store) StartStorageMaintenance ¶ added in v0.12.0
func (s *Store) StartStorageMaintenance(ctx context.Context, interval time.Duration, source admission.Source) (stop func(), err error)
StartStorageMaintenance schedules one bounded batch per interval. An absent policy does nothing; resource pressure defers work without changing claim or payload eligibility. Stop must finish before closing the store.
func (*Store) StorageArchive ¶ added in v0.12.0
func (s *Store) StorageArchive(ctx context.Context, dryRun bool, now time.Time, budget retention.Budget) (report StorageReport, err error)
StorageArchive reads at most max(64, budget.Items*16) metadata rows and max(64 KiB, budget.Bytes) payload bytes per invocation. Artifact output remains bounded by budget.Items and budget.Bytes. A private SQLite checkpoint advances rejected rows atomically with archival and wraps after exhausting the keyspace; dry runs preserve it. The checkpoint schema is allocated only with retention.
func (*Store) StorageCompact ¶ added in v0.12.0
func (*Store) StorageConfigure ¶ added in v0.12.0
func (*Store) StorageHistory ¶ added in v0.12.0
func (*Store) StorageInfo ¶ added in v0.12.0
func (s *Store) StorageInfo(ctx context.Context) (info StorageInfo, err error)
func (*Store) StorageRestore ¶ added in v0.12.0
func (*Store) StorageVerify ¶ added in v0.12.0
func (s *Store) StorageVerify(ctx context.Context) (report StorageReport, err error)
func (*Store) Sync ¶ added in v0.8.0
func (s *Store) Sync(ctx context.Context, p Principal, request protocol.SyncRequest) (result protocol.SyncPage, resultErr error)
Sync reconstructs bounded historical snapshots and accepted-write deltas. It authenticates inside one read transaction and accepts no incoming writes.
Source Files