Documentation
¶
Overview ¶
Package ledgerstore provides control-plane event-store adapters: an in-memory store for deterministic local recording and tests, and a Bun-backed durable store for SQLite and Postgres deployments.
Both adapters implement the core-owned controlplane.Store port. SQL, Bun, HTTP, transport, and provider SDK types never cross into pkg/lipsdk/controlplane or internal/core/controlplane; adapters translate into and out of the SDK DTOs at their own edges (design "Allowed Dependencies"; requirements 9.5, 10.5).
Index ¶
- Constants
- type DurableConfig
- type DurableStore
- func (s *DurableStore) Append(ctx context.Context, ev cp.Event) (cp.RecordResult, error)
- func (s *DurableStore) ApplyRetention(ctx context.Context, cmd controlplane.RetentionCommand) (controlplane.RetentionResult, error)
- func (s *DurableStore) Attempts(ctx context.Context, q cp.AttemptQuery) (cp.Page[cp.AttemptRow], error)
- func (s *DurableStore) CheckReadiness(ctx context.Context) error
- func (s *DurableStore) Close() error
- func (s *DurableStore) Events(ctx context.Context, q cp.EventQuery) (cp.Page[cp.Event], error)
- func (s *DurableStore) PolicyAudit(ctx context.Context, q cp.EvidenceQuery) (cp.Page[cp.PolicyAuditRow], error)
- func (s *DurableStore) Sessions(ctx context.Context, q cp.SessionQuery) (cp.Page[cp.SessionSummary], error)
- func (s *DurableStore) Usage(ctx context.Context, q cp.UsageQuery) (cp.Page[cp.UsageRow], error)
- func (s *DurableStore) UsageAggregate(ctx context.Context, q cp.UsageAggregateQuery) (cp.Page[cp.UsageAggregate], error)
- type MemoryConfig
- type MemoryStore
- func (s *MemoryStore) Append(ctx context.Context, ev cp.Event) (cp.RecordResult, error)
- func (s *MemoryStore) ApplyRetention(ctx context.Context, cmd controlplane.RetentionCommand) (controlplane.RetentionResult, error)
- func (s *MemoryStore) Attempts(ctx context.Context, q cp.AttemptQuery) (cp.Page[cp.AttemptRow], error)
- func (s *MemoryStore) CheckReadiness(ctx context.Context) error
- func (s *MemoryStore) Close() error
- func (s *MemoryStore) Events(ctx context.Context, q cp.EventQuery) (cp.Page[cp.Event], error)
- func (s *MemoryStore) PolicyAudit(ctx context.Context, q cp.EvidenceQuery) (cp.Page[cp.PolicyAuditRow], error)
- func (s *MemoryStore) Sessions(ctx context.Context, q cp.SessionQuery) (cp.Page[cp.SessionSummary], error)
- func (s *MemoryStore) Usage(ctx context.Context, q cp.UsageQuery) (cp.Page[cp.UsageRow], error)
- func (s *MemoryStore) UsageAggregate(ctx context.Context, q cp.UsageAggregateQuery) (cp.Page[cp.UsageAggregate], error)
Constants ¶
const BaselineMigrationName = "20260704000000"
BaselineMigrationName is the name bun/migrate records for this adapter's baseline (file prefix).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DurableConfig ¶
type DurableConfig struct {
// StoreID is the stable store identifier embedded in assigned EventIDs.
StoreID string
// DefaultPageSize is applied when a query omits Limit. Defaults to 100.
DefaultPageSize int
// MaxPageSize is the upper bound for any query page. Defaults to 500.
MaxPageSize int
// UnsupportedFilters is the set of canonical filter field names this store
// cannot apply (see internal/infra/controlplane/contract). Empty means all
// documented filters are supported (requirement 2.5, 8.6, 9.4).
UnsupportedFilters []string
// MaxDetailBytes bounds detail_json before persistence. Defaults to 16384.
MaxDetailBytes int
// MaxScopeBytes bounds scope_json before persistence. Defaults to 16384.
MaxScopeBytes int
// MaxSummaryBytes bounds the summary string. Defaults to MaxSummaryBytes
// from core validation (4096).
MaxSummaryBytes int
}
DurableConfig configures a Bun-backed durable control-plane event store.
type DurableStore ¶
type DurableStore struct {
// contains filtered or unexported fields
}
DurableStore persists control-plane events through Bun-supported SQL dialects (SQLite and Postgres). It implements the core-owned Store port without leaking SQL, Bun, DSN, driver, or infrastructure types into core or SDK contracts (requirement 9.5, 7.3).
func NewDurableStore ¶
func NewDurableStore(ctx context.Context, db *bun.DB, cfg DurableConfig) (*DurableStore, error)
NewDurableStore runs schema migrations against db and returns a durable store. The caller owns closing db; Close on the store closes the bun handle.
func (*DurableStore) Append ¶
func (s *DurableStore) Append(ctx context.Context, ev cp.Event) (cp.RecordResult, error)
Append persists one validated event atomically with its safe detail and scope snapshots, returning a stable record result for new and deduplicated source events (requirement 1.7, 1.8, 4.4, 4.5, 9.5).
func (*DurableStore) ApplyRetention ¶
func (s *DurableStore) ApplyRetention(ctx context.Context, cmd controlplane.RetentionCommand) (controlplane.RetentionResult, error)
ApplyRetention marks or prunes records at or before the cutoff. Records remain in the table with explicit expired/redacted state and cleared detail_json so consumers can see the lifecycle state; repeated runs at the same cutoff affect no additional rows (requirement 6.1, 6.2, 6.6).
func (*DurableStore) Attempts ¶
func (s *DurableStore) Attempts(ctx context.Context, q cp.AttemptQuery) (cp.Page[cp.AttemptRow], error)
Attempts returns bounded backend attempt rows (requirement 2.2).
func (*DurableStore) CheckReadiness ¶
func (s *DurableStore) CheckReadiness(ctx context.Context) error
CheckReadiness pings the backing database and reports availability without leaking raw infrastructure errors (requirement 7.1, 7.3).
func (*DurableStore) Close ¶
func (s *DurableStore) Close() error
Close closes the underlying bun handle.
func (*DurableStore) Events ¶
func (s *DurableStore) Events(ctx context.Context, q cp.EventQuery) (cp.Page[cp.Event], error)
Events returns bounded raw control-plane events (requirement 9.1).
func (*DurableStore) PolicyAudit ¶
func (s *DurableStore) PolicyAudit(ctx context.Context, q cp.EvidenceQuery) (cp.Page[cp.PolicyAuditRow], error)
PolicyAudit returns bounded policy and audit rows (requirement 2.4, 9.3).
func (*DurableStore) Sessions ¶
func (s *DurableStore) Sessions(ctx context.Context, q cp.SessionQuery) (cp.Page[cp.SessionSummary], error)
Sessions returns bounded session summaries projected from recorded events (requirement 2.1). Grouping is performed in Go from filtered durable rows so the projection stays consistent with the memory adapter.
func (*DurableStore) Usage ¶
func (s *DurableStore) Usage(ctx context.Context, q cp.UsageQuery) (cp.Page[cp.UsageRow], error)
Usage returns bounded usage rows (requirement 2.3, 9.2).
func (*DurableStore) UsageAggregate ¶
func (s *DurableStore) UsageAggregate(ctx context.Context, q cp.UsageAggregateQuery) (cp.Page[cp.UsageAggregate], error)
UsageAggregate returns bounded usage aggregates (requirement 2.3, 6.4).
type MemoryConfig ¶
type MemoryConfig struct {
// StoreID is the stable store identifier embedded in assigned EventIDs.
StoreID string
// DefaultPageSize is applied when a query omits Limit. Defaults to 100.
DefaultPageSize int
// MaxPageSize is the upper bound for any query page. Defaults to 500.
MaxPageSize int
// UnsupportedFilters is the set of canonical filter field names
// (see internal/infra/controlplane/ledgerstore/contract) this store cannot
// apply. Filter requests for these fields are reported explicitly via
// Page.Unsupported rather than silently widening the query (requirement
// 2.5, 8.6, 9.4). Empty means all documented filters are supported.
UnsupportedFilters []string
}
MemoryConfig configures an in-memory control-plane event store.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is the in-memory control-plane event store. It is safe for concurrent use. It assigns monotonic sequence numbers per store, deduplicates by SourceEventKey, and serves bounded query views from the same recorded facts (tasks 2.1, 2.4, 2.5).
func NewMemoryStore ¶
func NewMemoryStore(cfg MemoryConfig) (*MemoryStore, error)
NewMemoryStore returns a fresh in-memory store. It does not perform I/O and is always ready.
func (*MemoryStore) Append ¶
func (s *MemoryStore) Append(ctx context.Context, ev cp.Event) (cp.RecordResult, error)
Append records one validated event with a stable monotonic identity and source-event-key dedupe (requirement 1.7, 1.8).
func (*MemoryStore) ApplyRetention ¶
func (s *MemoryStore) ApplyRetention(ctx context.Context, cmd controlplane.RetentionCommand) (controlplane.RetentionResult, error)
ApplyRetention marks records at or before the cutoff as expired (standard) or redacted (strict). Records remain queryable so consumers can see explicit expired/redacted state; details are cleared for redacted/expired rows. Repeated runs at the same cutoff mark no additional records (requirement 6.1, 6.2, 6.6; design "Idempotency").
func (*MemoryStore) Attempts ¶
func (s *MemoryStore) Attempts(ctx context.Context, q cp.AttemptQuery) (cp.Page[cp.AttemptRow], error)
func (*MemoryStore) CheckReadiness ¶
func (s *MemoryStore) CheckReadiness(ctx context.Context) error
CheckReadiness reports backing capability availability. The memory store is always ready (requirement 7.1).
func (*MemoryStore) Close ¶
func (s *MemoryStore) Close() error
Close releases no resources for the memory store; it is provided so callers can uniform-close memory and durable stores.
func (*MemoryStore) Events ¶
func (s *MemoryStore) Events(ctx context.Context, q cp.EventQuery) (cp.Page[cp.Event], error)
func (*MemoryStore) PolicyAudit ¶
func (s *MemoryStore) PolicyAudit(ctx context.Context, q cp.EvidenceQuery) (cp.Page[cp.PolicyAuditRow], error)
func (*MemoryStore) Sessions ¶
func (s *MemoryStore) Sessions(ctx context.Context, q cp.SessionQuery) (cp.Page[cp.SessionSummary], error)
func (*MemoryStore) Usage ¶
func (s *MemoryStore) Usage(ctx context.Context, q cp.UsageQuery) (cp.Page[cp.UsageRow], error)
func (*MemoryStore) UsageAggregate ¶
func (s *MemoryStore) UsageAggregate(ctx context.Context, q cp.UsageAggregateQuery) (cp.Page[cp.UsageAggregate], error)
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contract provides a reusable store-contract test suite for control-plane event stores (spec control-plane-persistence-query-event-ledger, tasks 2.1–2.5).
|
Package contract provides a reusable store-contract test suite for control-plane event stores (spec control-plane-persistence-query-event-ledger, tasks 2.1–2.5). |
|
Package fields owns the canonical filter-field string names reported by control-plane ledger stores in cp.UnsupportedFilter.Field.
|
Package fields owns the canonical filter-field string names reported by control-plane ledger stores in cp.UnsupportedFilter.Field. |