kv

Documentation

Overview

Package kv is a thin, tenant-scoped wrapper over the configured key-value store backend that backs the op-writable key-value ops (txco://kv/*). It is the only general, mutable, op-writable persistence in the chassis — distinct from the immutable filecas/continuation/artifact stores and the secret store.

The same store.Store interface is satisfied by boltdb (embedded, on-disk) and redis (shared, networked — native TTL + atomic ops), selected by --kvstore. This wrapper adds the three things the raw store doesn't give us:

• Tenant + namespace scoping: every key is composed as <tenant>/<namespace>/<userkey>. The tenant comes from the trusted request scope (never the mutable _txc.tenant); the namespace is an organizational prefix (default = the routed stack), not a security boundary.
• JSON values: callers store/retrieve arbitrary JSON, not opaque bytes.
• Uniform TTL: values are wrapped with an optional expiry and lazy-expired on read, AND WriteOptions.TTL is passed so native backends (redis) also GC. Persistent keys (the default) carry no expiry. A configurable max-TTL clamps requested TTLs downward.

Index

• func ParseTTLSeconds(secs int64) time.Duration
• type KV
  • func New(s store.Store, maxValueBytes int, maxTTL time.Duration) *KV
  • func (k *KV) CAS(ctx context.Context, tenant, ns, key string, expectAbsent bool, ...) (swapped bool, current json.RawMessage, err error)
  • func (k *KV) Delete(ctx context.Context, tenant, ns, key string) error
  • func (k *KV) Get(ctx context.Context, tenant, ns, key string) (value json.RawMessage, found bool, err error)
  • func (k *KV) Incr(ctx context.Context, tenant, ns, key string, delta int64, ttl time.Duration) (int64, error)
  • func (k *KV) ListKeys(ctx context.Context, tenant, ns string) ([]string, error)
  • func (k *KV) Set(ctx context.Context, tenant, ns, key string, value json.RawMessage, ...) error

Functions

func ParseTTLSeconds

func ParseTTLSeconds(secs int64) time.Duration

ParseTTLSeconds converts an integer-seconds WITH param to a Duration. Zero or negative → 0 (persistent).

Types

type KV

type KV struct {
	// contains filtered or unexported fields
}

KV is a tenant-scoped view over the underlying key-value store.

func New

func New(s store.Store, maxValueBytes int, maxTTL time.Duration) *KV

New returns a KV over s. maxValueBytes/maxTTL of 0 mean unlimited.

func (*KV) CAS

func (k *KV) CAS(ctx context.Context, tenant, ns, key string, expectAbsent bool, expected, newVal json.RawMessage, ttl time.Duration) (swapped bool, current json.RawMessage, err error)

CAS is check-and-set: write newVal at (tenant, ns, key) only if the current value passes the check, using the store's atomic compare so it stays race-safe under concurrency. With expectAbsent=true it writes only if the key is absent (a create-if-missing / lock primitive); otherwise it writes only if the current value equals `expected`. Returns whether it swapped and the value now in the store (newVal if swapped, else the existing value — nil if the key was absent).

func (*KV) Delete

func (k *KV) Delete(ctx context.Context, tenant, ns, key string) error

Delete removes (tenant, ns, key). A missing key is not an error.

func (*KV) Get

func (k *KV) Get(ctx context.Context, tenant, ns, key string) (value json.RawMessage, found bool, err error)

Get returns the JSON value for (tenant, ns, key). found is false for a missing or lazily-expired key (no error in either case).

func (*KV) Incr

func (k *KV) Incr(ctx context.Context, tenant, ns, key string, delta int64, ttl time.Duration) (int64, error)

Incr atomically adds delta to an integer value (creating it at delta if absent or expired) using the store's CAS primitive, and returns the new value. A positive ttl (clamped) is (re)applied on each increment.

func (*KV) ListKeys

func (k *KV) ListKeys(ctx context.Context, tenant, ns string) ([]string, error)

ListKeys returns the user keys currently stored under (tenant, ns) — the namespace view the declarative store-seed reconciler needs to find which managed keys a re-applied pack dropped. Lazily-expired keys are filtered (parity with Get); order is unspecified; an empty namespace yields nil. The composed <tenant>/<ns>/ prefix is stripped so callers get bare user keys.

func (*KV) Set

func (k *KV) Set(ctx context.Context, tenant, ns, key string, value json.RawMessage, ttl time.Duration) error

Set writes value at (tenant, ns, key). A ttl <= 0 stores a persistent key (no expiry); a positive ttl is clamped to maxTTL.