store

type Encryptor ¶

type Encryptor interface {
	Encrypt(ctx context.Context, plaintext []byte) ([]byte, error)
	Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)
}

Encryptor is the at-rest encryption seam (Decision §7). P-P/F15 supplies the implementation (tink/envelope); the store stays generic — it encrypts opaque value bytes for the configured kinds. With no encryptor, values are stored as-is.

type Engine ¶

type Engine interface {
	View(ctx context.Context, fn func(Txn) error) error
	Update(ctx context.Context, fn func(Txn) error) error
	snapshot.Source
	snapshot.Loader
	Close() error
}

Engine is the minimal key/value seam the store is built on. memory + badger implement it.

Update is contractually only an ATOMIC WRITE-BATCH (all-or-nothing); the seam does NOT promise serializable, in-txn read-your-writes isolation, so the store must not rely on it. Cross-writer serialization (the resourceVersion compare-and-set) is the store wrapper's job (a write mutex), not the engine's — an engine may happen to be serializable (badger's txns are), but the store treats the seam conservatively.

View runs read-only operations. The seam does not guarantee a consistent point-in-time snapshot across multiple reads on every engine (the memory engine holds a read lock, so it is; not all engines must). Consequently List's collection resourceVersion is best-effort under concurrent writes; a caller needing a strict snapshot re-reads at the returned resourceVersion.

Snapshot emits every record, the timeline included, from one read with Key = bucket+NUL+key, and returns "". Load runs before New on an empty engine: it splits each Key at its last NUL (keys hold none; metaBucket starts with one) and skips the record IsTimelineRecord names, so the next New mints a new timeline (ADR-0202).

type Event ¶

type Event struct {
	Type   EventType
	Object v1.Object
}

Event is a single change delivered on a Watch stream.

type EventType ¶

type EventType string

EventType is the kind of change a Watch reports.

const (
	Added    EventType = "Added"
	Modified EventType = "Modified"
	Deleted  EventType = "Deleted"
)

type List ¶

type List struct {
	Items           []v1.Object
	ResourceVersion string
}

List is the result of a List call: the matching objects plus the collection resourceVersion (the store-wide revision at read time).

type ListOptions ¶

type ListOptions struct {
	Namespace     v1.NamespaceName
	ResourceGroup v1.ResourceGroupName
	Tags          v1.Tags
}

ListOptions narrows a List by namespace, resource group, and tag subset.

type Option ¶

type Option func(*config) error

Option configures a Store at construction (functional options, ADR-0002).

func WithEncryptor(kinds []v1.Kind, enc Encryptor) Option

type Store ¶

type Store interface {
	Get(ctx context.Context, gvk v1.GroupVersionKind, ns v1.NamespaceName, name v1.ObjectName) (v1.Object, error)
	List(ctx context.Context, gvk v1.GroupVersionKind, opts ListOptions) (List, error)
	Create(ctx context.Context, obj v1.Object) (v1.Object, error) // stamps uid, generation=1, resourceVersion, creationTimestamp
	Update(ctx context.Context, obj v1.Object) (v1.Object, error) // RV precondition; bumps generation iff spec changed
	Delete(ctx context.Context, gvk v1.GroupVersionKind, ns v1.NamespaceName, name v1.ObjectName, rv string) error
	Watch(ctx context.Context, gvk v1.GroupVersionKind, opts WatchOptions) (Watch, error)
	Close() error
	// Snapshot is Engine.Snapshot without the timeline record (ADR-0202); it returns "<timeline>-<revision>"
	// from the meta records of the same stream, which come first; no revision record reads as 0.
	snapshot.Source
}

Store is the metastore port: generic CRUD + List + in-process Watch over v1alpha1.Object, keyed by (GroupVersionKind, NamespaceName, ObjectName). Every method is ctx-first; every error is an api/fault kind.

func New(e Engine, opts ...Option) Store

type Txn ¶

type Txn interface {
	Get(bucket, key string) ([]byte, bool, error)
	Put(bucket, key string, val []byte) error
	Delete(bucket, key string) error
	Scan(bucket string, fn func(key string, val []byte) error) error
}

Txn is the key/value surface within a View/Update. Keys are scoped by bucket.

type Version ¶ added in v0.11.0

type Version struct {
	Timeline string // lowercase hex
	N        uint64
}

Version is a parsed resourceVersion (ADR-0202): "<timeline>-<n>", or a plain "<n>" written before timelines (Timeline ""). N orders versions only inside one timeline.

func ParseVersion(rv string) (Version, error)

func ResumePoint(seen, v Version) Version

func (v Version) String() string

type Watch ¶

type Watch interface {
	ResultChan() <-chan Event
	Stop()
}

Watch is an open change stream. Stop releases it (idempotent); ResultChan is closed when the watch ends (Stop, ctx cancellation, or a dropped slow watcher).

type WatchOptions ¶

type WatchOptions struct {
	Namespace            v1.NamespaceName
	SinceResourceVersion string
}

WatchOptions narrows a Watch and optionally replays from a resourceVersion.