Documentation
¶
Overview ¶
Package storage owns the CLI's persistent-state layer. It is the only package allowed to import a sql driver or write raw SQL. Commands access primitives (KV[T], etc.) through accessors on internal/app; they MUST NOT construct primitives directly or reach into this package's unexported surface.
Index ¶
- Constants
- Variables
- type CleanupPolicy
- type CleanupReport
- type DBStats
- type Entry
- type KV
- func (kv *KV[T]) Delete(ctx context.Context, key string) error
- func (kv *KV[T]) Get(ctx context.Context, key string) (T, error)
- func (kv *KV[T]) GetEntry(ctx context.Context, key string) (Entry[T], error)
- func (kv *KV[T]) Has(ctx context.Context, key string) (bool, error)
- func (kv *KV[T]) List(ctx context.Context) ([]Entry[T], error)
- func (kv *KV[T]) Put(ctx context.Context, key string, value T) error
- func (kv *KV[T]) PutWithTTL(ctx context.Context, key string, value T, ttl time.Duration) error
- type Options
- type PrimitiveCleanup
- type PrimitiveName
- type PrimitiveStats
- type Storage
Constants ¶
const ( BackendSqlite = "sqlite" BackendPostgres = "postgres" BackendMySQL = "mysql" )
Backend identifies the concrete storage implementation. Only BackendSqlite is implemented today; the constants are reserved for the daemon-mode swap path described in the ADR.
Variables ¶
var ( ErrNotFound = errors.New("storage: not found") ErrSchemaTooNew = errors.New("storage: db schema is newer than this binary: upgrade the CLI or run `safedep cleanup --reset`") // ErrKVDecode is returned by KV.Get and KV.List when the stored value // cannot be JSON-decoded into the target type. Callers can distinguish // this from a DB-level error (e.g. locked file, permission denied) via // errors.Is to decide whether a reset is safe. ErrKVDecode = errors.New("storage: kv decode") )
Sentinel errors returned by the storage layer. Use errors.Is to match. Callers may wrap with extra context, except ErrSchemaTooNew whose message is meant to surface verbatim to the user.
Functions ¶
This section is empty.
Types ¶
type CleanupPolicy ¶
type CleanupPolicy struct {
DryRun bool
MaxAge map[PrimitiveName]time.Duration
Vacuum bool
}
CleanupPolicy controls the cleanup walk.
type CleanupReport ¶
type CleanupReport struct {
Primitives []PrimitiveCleanup
Vacuumed bool
Reclaimed int64
}
CleanupReport summarises the result of a Cleanup invocation.
type DBStats ¶
type DBStats struct {
Path string
SizeBytes int64
SchemaVer int
Primitives []PrimitiveStats
}
DBStats summarises overall database usage for the doctor command.
type Entry ¶
type Entry[T any] struct { Key string Value T CreatedAt time.Time UpdatedAt time.Time ExpiresAt *time.Time }
Entry wraps a stored value with its metadata.
type KV ¶
type KV[T any] struct { // contains filtered or unexported fields }
KV is a typed key-value store scoped to one (scope, namespace). Construct via app.ProfileKV or app.GlobalKV; do not instantiate directly outside this package.
func NewGlobalKV ¶
NewGlobalKV returns a KV in the global scope. Internal.
func NewProfileKV ¶
NewProfileKV returns a KV scoped to the given profile. Internal: app-layer accessors are the public entry point.
type Options ¶
Options configures Open. Backend selects the implementation; Path is the absolute file path for sqlite (ignored for other backends).
type PrimitiveCleanup ¶
type PrimitiveCleanup struct {
Name PrimitiveName
DeletedRows int64
PolicySeconds int64
}
PrimitiveCleanup is the per-primitive line item in CleanupReport.
type PrimitiveName ¶
type PrimitiveName string
PrimitiveName identifies a storage primitive in cross-cutting APIs (cleanup retention overrides, doctor stats, config keys). It is a named string so typos at the API boundary become compile-time errors and the set of valid values is discoverable via the exported constants below.
const (
PrimitiveKV PrimitiveName = "kv"
)
type PrimitiveStats ¶
type PrimitiveStats struct {
Name PrimitiveName
RowCount int64
OldestEntry *time.Time
NewestEntry *time.Time
ExpiredRows int64
}
PrimitiveStats reports per-primitive usage.
type Storage ¶
type Storage interface {
Stats(ctx context.Context) (DBStats, error)
Cleanup(ctx context.Context, policy CleanupPolicy) (CleanupReport, error)
Close() error
// contains filtered or unexported methods
}
Storage is the dialect-neutral contract every backend implementation satisfies. Primitives live in this package; commands talk to them (not to Storage) for normal data access. Storage exposes only the cross-cutting operations doctor and cleanup need.
Source Files