Documentation
¶
Overview ¶
Package store is the dispatcher's resource store: the runtime kinds (Event, WorkItem, Task, Run, Agent, Effect, BudgetCounter, Approval, and the internal Lease, Debounce, Session and Delivery records) with get, list, watch, compare-and-swap updates, advisory leased locks, retention and the transcript blobs.
Config kinds live in the catalog snapshot, never here. The in-memory implementation is in store/memory, the file-backed one (memory plus a snapshot and journal) in store/filestore; store/storetest is the conformance suite every implementation must pass.
Design: design/workstreams/dispatcher-runtime/LLD/store.md.
Index ¶
- Constants
- Variables
- func CreatedAt(obj Object) time.Time
- func DecodeCursor(kind, s string) (string, error)
- func EncodeCursor(kind, name string) string
- func EnvironmentLogBlob(run string) string
- func Expired(r Retention, created, updated, now time.Time, retention time.Duration) bool
- func FieldValues(obj Object) map[string][]string
- func FormatVersion(v uint64) string
- func HasResourceVersion(obj Object) bool
- func IndexedFields(kind string) []string
- func Labels(obj Object) map[string]string
- func LinkFieldValue(provider, ref string) string
- func ParseVersion(op string, k Key, s string) (uint64, error)
- func ResourceVersion(obj Object) string
- func RunSweeper(ctx context.Context, s Sweeper, interval time.Duration, log *slog.Logger)
- func SetCreatedAt(obj Object, t time.Time) bool
- func SetResourceVersion(obj Object, rv string) bool
- func ValidateFields(kind string, fields map[string]string) error
- type Error
- type Key
- type ListMeta
- type ListOptions
- type MetaObject
- type Object
- type Options
- type Retention
- type Store
- type SweepResult
- type Sweeper
- type TranscriptStore
- type Unlock
- type WatchEvent
- type WatchEventType
- type WatchOptions
- type Watcher
Constants ¶
const ( FieldTaskPhase = "status.phase" // Task FieldTaskQueue = "spec.queue" // Task FieldTaskWorkItem = "metadata.workItem" // Task FieldRunTask = "spec.task" // Run FieldWorkItemLink = "spec.links" // WorkItem: LinkFieldValue(provider, ref), one per link FieldEffectIdemKey = "spec.idempotencyKey" // Effect FieldEffectTask = "spec.task" // Effect )
Indexed fields, for ListOptions.Field.
const ( DefaultRetention = 90 * 24 * time.Hour DefaultSweepInterval = 10 * time.Minute DefaultWatchBuffer = 256 DefaultHistory = 10_000 DefaultTranscriptMaxBytes = 20 << 20 DefaultTranscriptTotalBytes = 2 << 30 )
Defaults.
const EnvironmentLogSuffix = ".environment-log"
EnvironmentLogSuffix ends an environment log's blob name. Run names never end with it.
Variables ¶
var ( // ErrNotFound: no object (or transcript) with that key. ErrNotFound = errors.New("not found") // ErrAlreadyExists: Create on a key that is taken. ErrAlreadyExists = errors.New("already exists") // ErrConflict: Update with a stale resourceVersion; re-read and retry. ErrConflict = errors.New("resourceVersion conflict") // ErrInvalid: a malformed request (missing kind or name, config kind, bad selector, cursor, // field or version, wrong output type). ErrInvalid = errors.New("invalid") // ErrWatchExpired: the watch fell behind (buffer full) or SinceVersion is older than the // history; re-list and watch again. ErrWatchExpired = errors.New("watch expired") // ErrLockLost: Renew on a lease that expired or was released. ErrLockLost = errors.New("lock lost") // ErrTooLarge: a transcript over the per-transcript cap. ErrTooLarge = errors.New("too large") )
Errors. Every error a store returns wraps one of these (test with errors.Is); most come as an *Error carrying the operation and key.
Functions ¶
func DecodeCursor ¶
DecodeCursor returns the name after which kind's list continues ("" for an empty cursor). ErrInvalid for a malformed cursor or one from another kind's list.
func EncodeCursor ¶
EncodeCursor returns the opaque cursor that continues kind's list after name.
func EnvironmentLogBlob ¶
EnvironmentLogBlob is the TranscriptStore name of run's environment log: it is kept beside the transcript, under the same caps and retention, and deleted with the Run.
func Expired ¶
Expired reports whether an object under rule r, created and last written at the given times, is past retention at now.
func FieldValues ¶
FieldValues returns obj's indexed field values (several for a multi-valued field such as WorkItem links). Kinds without indexed fields return nil.
func FormatVersion ¶
FormatVersion renders a resourceVersion: the store's global monotonic counter, in decimal.
func HasResourceVersion ¶
HasResourceVersion reports whether obj's kind carries a resourceVersion, i.e. whether Update is compare-and-swap for it.
func IndexedFields ¶
IndexedFields lists the fields kind can be listed by.
func LinkFieldValue ¶
LinkFieldValue is the FieldWorkItemLink value of the link {provider, ref}. Provider names have no "/", so the first "/" separates the two.
func ParseVersion ¶
ParseVersion parses a resourceVersion. ErrInvalid when it isn't one.
func ResourceVersion ¶
ResourceVersion returns obj's resourceVersion ("" for kinds without one).
func RunSweeper ¶
RunSweeper calls s.Sweep every interval (DefaultSweepInterval when 0) until ctx ends. Errors are logged, not returned: the next tick tries again.
func SetCreatedAt ¶
SetCreatedAt sets obj's creation time; false for kinds without one.
func SetResourceVersion ¶
SetResourceVersion sets obj's resourceVersion; false for kinds without one.
Types ¶
type Error ¶
type Error struct {
// Op is the operation: get, list, create, update, delete, watch, lock, renew, transcript.
Op string
// Key is the object, when there is one (Kind only for list and watch; Name only for locks
// and transcripts).
Key Key
// Detail says more, when there is more to say.
Detail string
Err error
}
Error is a store error on one operation.
type Key ¶
type Key struct {
Kind, Name string
}
Key names one stored object.
func CheckObject ¶
CheckObject validates obj for a write by op and returns its key: a non-nil pointer with a kind (not a config kind) and a name.
type ListMeta ¶
type ListMeta struct {
// NextCursor continues the list; empty on the last page.
NextCursor string
// ResourceVersion is the store's version when the list was read: pass it as
// WatchOptions.SinceVersion to watch from exactly where the list left off (resync).
ResourceVersion string
}
ListMeta describes a List result.
type ListOptions ¶
type ListOptions struct {
// LabelSelector keeps the objects whose labels match; nil or empty matches all.
LabelSelector *v1alpha1.LabelSelector
// Field keeps the objects whose indexed field has the value (all entries must match). The
// fields are per kind: see IndexedFields. An unknown field is ErrInvalid.
Field map[string]string
// Cursor is a previous page's ListMeta.NextCursor; empty starts at the beginning.
Cursor string
// Limit caps the page size; 0 means no limit.
Limit int
}
ListOptions select and page a List.
type MetaObject ¶
type MetaObject interface {
Object
GetObjectMeta() *v1alpha1.ObjectMeta
}
MetaObject is implemented by stored kinds outside v1alpha1 (the internal Lease, Debounce, Session and Delivery records) to give the store their ObjectMeta.
type Object ¶
Object is any stored kind. The store reads its kind from TypeMeta and its name from GetName (metadata.name, or the id for Task and Event); ResourceVersion, CreatedAt and Labels reach its metadata (see meta.go).
type Options ¶
type Options struct {
// Clock sets CreatedAt and drives lock expiry and retention. Default clock.Real.
Clock clock.Clock
// Retention is how long Runs, transcripts, Events, Effects and BudgetCounters are kept
// (and terminal Tasks after their last change). Default 90 days (`--retention`).
Retention time.Duration
// WatchBuffer is the default per-watcher buffer. Default 256.
WatchBuffer int
// History is how many changes are kept for WatchOptions.SinceVersion. Default 10 000.
History int
// TranscriptMaxBytes caps one transcript. Default 20 MB.
TranscriptMaxBytes int64
// TranscriptTotalBytes caps all transcripts. Default 2 GB.
TranscriptTotalBytes int64
// Logger logs evictions and sweeps. Default slog.Default().
Logger *slog.Logger
}
Options configure a store implementation. Zero fields take the defaults.
func (Options) WithDefaults ¶
WithDefaults returns o with its zero fields set to the defaults.
type Retention ¶
type Retention int
Retention says how an object ages out.
const ( // Keep: never swept (WorkItem, Agent, Approval, internal kinds). Keep Retention = iota // SinceCreated: swept Options.Retention after creation (Run, Event, Effect, BudgetCounter; // transcripts likewise). SinceCreated // SinceUpdated: swept Options.Retention after its last write (a Task in a terminal phase, // Succeeded, Failed or Cancelled: its last write is when it got there). SinceUpdated )
Retention rules (LLD store.md §Retention).
func RetentionOf ¶
RetentionOf returns obj's retention rule. It depends on obj's state (a Task's phase), so a store evaluates it on every write.
type Store ¶
type Store interface {
// Get decodes the object at k into out, which must be a pointer to the kind's Go type.
// ErrNotFound when there is none.
Get(ctx context.Context, k Key, out Object) error
// List decodes the objects of kind that match opts into out, a *[]T where T is the kind's
// Go type, a pointer to it, or an interface it implements (Object). Objects come in name
// order; ListMeta.NextCursor continues the list when opts.Limit cut it short.
List(ctx context.Context, kind string, opts ListOptions, out any) (ListMeta, error)
// Create stores a new object. It sets obj's ResourceVersion and CreatedAt (from the
// store's clock) on the stored copy and on obj. ErrAlreadyExists when the key is taken.
Create(ctx context.Context, obj Object) error
// Update replaces an object if obj's ResourceVersion is the stored one (compare-and-swap),
// else ErrConflict; ErrNotFound when there is none. It sets the new ResourceVersion on obj
// and keeps the stored CreatedAt. Kinds without a resourceVersion field (Event) are
// replaced unconditionally.
Update(ctx context.Context, obj Object) error
// Delete removes an object. ErrNotFound when there is none.
Delete(ctx context.Context, k Key) error
// Watch streams the changes to kind's objects that match opts, in version order.
Watch(ctx context.Context, kind string, opts WatchOptions) (Watcher, error)
// Lock takes the advisory lock name for ttl, waiting while another holder has it and it
// hasn't expired. It returns ctx's error (wrapped) if ctx ends first. An expired lock is
// reclaimable by anyone.
Lock(ctx context.Context, name string, ttl time.Duration) (Unlock, error)
}
Store is the resource store.
type SweepResult ¶
SweepResult counts what a sweep deleted.
type Sweeper ¶
type Sweeper interface {
Sweep(ctx context.Context) (SweepResult, error)
}
Sweeper deletes what is past retention (see Retention). Deletions are sent to watchers.
type TranscriptStore ¶
type TranscriptStore interface {
// PutTranscript stores (or replaces) run's transcript. ErrTooLarge over the per-transcript
// cap.
PutTranscript(ctx context.Context, run string, blob []byte) error
// GetTranscript returns a copy of run's transcript. ErrNotFound when there is none.
GetTranscript(ctx context.Context, run string) ([]byte, error)
}
TranscriptStore holds run transcripts as the compressed blobs the agent uploads (gzip JSON Lines), keyed by run name. Blobs are capped per transcript and in total; when the total cap is reached the oldest are evicted (logged). They are deleted with their Run and swept by age like Runs. A run's environment log is a second blob, named EnvironmentLogBlob(run).
type Unlock ¶
type Unlock interface {
// Unlock releases the lock if this holder still has it. It is idempotent, and never
// releases a lock someone else reclaimed after expiry.
Unlock()
// Renew extends the lease to now+ttl. ErrLockLost when the lease expired or was released.
Renew(ctx context.Context, ttl time.Duration) error
}
Unlock is a held lock (the LLD's Unlock, with renewal).
type WatchEvent ¶
type WatchEvent struct {
Type WatchEventType
Object Object
Version string
}
WatchEvent is one change. Object is the watcher's own copy: the new state, or the last state for Deleted. Version is the change's resourceVersion (also set on Object when its kind has one).
type WatchEventType ¶
type WatchEventType string
WatchEventType is what happened to an object.
const ( Added WatchEventType = "added" Modified WatchEventType = "modified" Deleted WatchEventType = "deleted" )
Watch event types.
type WatchOptions ¶
type WatchOptions struct {
// LabelSelector keeps the objects whose labels match. An object that stops matching is
// sent as Deleted, one that starts matching as Added.
LabelSelector *v1alpha1.LabelSelector
// SinceVersion replays the changes after this version before the live ones. Empty starts
// with the next change. A version older than the store's history is ErrWatchExpired.
SinceVersion string
// Buffer is the channel buffer; 0 is the store's default. A watcher whose buffer is full
// when a change is sent is expired (its channel closed, Err() == ErrWatchExpired): writers
// never wait for readers.
Buffer int
}
WatchOptions select a Watch.
type Watcher ¶
type Watcher interface {
// Events is closed when the watch ends (ctx done, Stop, or expiry).
Events() <-chan WatchEvent
// Err is, once Events is closed: nil after Stop, the context's error, or ErrWatchExpired
// (the consumer re-lists and starts a new watch).
Err() error
// Stop ends the watch. It is idempotent.
Stop()
}
Watcher is a running watch.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package filestore is the single-node durable store: the in-memory store (store/memory) is the engine, and every committed change is appended to an fsync'd JSON Lines journal before it is applied.
|
Package filestore is the single-node durable store: the in-memory store (store/memory) is the engine, and every committed change is appended to an fsync'd JSON Lines journal before it is applied. |
|
Package memory is the in-memory store.Store: one map per kind behind a single RWMutex (PoC scale: thousands of objects), JSON deep copies on the way in and out, field indexes, watch fan-out with bounded buffers and a replay history, leased locks, retention and the transcript blobs.
|
Package memory is the in-memory store.Store: one map per kind behind a single RWMutex (PoC scale: thousands of objects), JSON deep copies on the way in and out, field indexes, watch fan-out with bounded buffers and a replay history, leased locks, retention and the transcript blobs. |
|
Package storetest is the conformance suite for store implementations: the in-memory store passes it today and a Postgres store must pass it later.
|
Package storetest is the conformance suite for store implementations: the in-memory store passes it today and a Postgres store must pass it later. |