ledgerstore

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

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

View Source
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

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

PolicyAudit returns bounded policy and audit rows (requirement 2.4, 9.3).

func (*DurableStore) Sessions

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

Usage returns bounded usage rows (requirement 2.3, 9.2).

func (*DurableStore) UsageAggregate

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

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 (*MemoryStore) Usage

func (s *MemoryStore) Usage(ctx context.Context, q cp.UsageQuery) (cp.Page[cp.UsageRow], error)

func (*MemoryStore) UsageAggregate

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址