store

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package store defines the timeline persistence protocol and its in-memory implementation. spec: Recording depends on this contract; storage depends only on shared values, never on Recorder, manager, or their process-local lifecycle.

Index

Constants

This section is empty.

Variables

View Source
var ErrConflict = errors.New("timeline: invalid document identity or operation boundary")
View Source
var ErrNotFound = errors.New("timeline: document not found")

Functions

This section is empty.

Types

type Document

type Document struct {
	ID          string        `json:"id"`
	RootStageID model.StageID `json:"root_stage_id"`
	OperationRecord
	Stages []StageUpdate `json:"stages,omitempty"`
}

Document is the durable, current state of one timeline, without read-time collection metadata. It retains one state per (StageID, Actor.Key), not an event history. JSON uses a document-local actors table and 1-based stage actor_ref values; the Go data always contains full Actors.

func MergeDocument

func MergeDocument(id string, current Document, update Update) (Document, bool, error)

MergeDocument merges actor-scoped states in acceptance order without mutating its inputs. Revisions are local bookkeeping, never distributed arbitration. +spec=`Different actors may update the same logical stage independently. Identical states are no-ops; competing states for one actor use last accepted write.`

func Overlay added in v0.3.0

func Overlay(base Document, updates ...Update) Document

Overlay applies already accepted documents and local pending updates. Historical empty Actors remain readable; admission validates only newly recorded stages.

func (Document) Clone

func (doc Document) Clone() Document

func (Document) MarshalJSON

func (d Document) MarshalJSON() ([]byte, error)

MarshalJSON stores each distinct nonempty Actor once. actor_ref is 1-based and local to this payload; serialization neither mutates d nor changes stage order.

func (Document) Snapshot

func (d Document) Snapshot(capturedAt time.Time) model.Snapshot

Snapshot returns detached read-time data. Storage success is set by the reader, never persisted as a claim about future collection completeness.

func (*Document) UnmarshalJSON

func (d *Document) UnmarshalJSON(raw []byte) error

UnmarshalJSON resolves payload-local actor references back to full Actor values. Invalid references return an error without replacing the receiver.

func (Document) Update added in v0.3.0

func (d Document) Update() Update

type MemoryStore

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

MemoryStore shares documents among handles in one process.

func NewMemoryStore

func NewMemoryStore() *MemoryStore

func (*MemoryStore) Latest added in v0.3.0

func (s *MemoryStore) Latest(ctx context.Context, after time.Time, limit int) ([]Document, error)

func (*MemoryStore) MGet added in v0.3.0

func (s *MemoryStore) MGet(ctx context.Context, ids []string) ([]Document, error)

func (*MemoryStore) Merge

func (s *MemoryStore) Merge(ctx context.Context, id string, update Update) error

func (*MemoryStore) Read

func (s *MemoryStore) Read(ctx context.Context, id string) (Document, error)

type NoopStore added in v0.3.0

type NoopStore struct{}

NoopStore accepts submissions without retaining facts. Reads return ErrNotFound; the recording cache is the only document owner and eviction cannot be recovered.

func NewNoopStore added in v0.3.0

func NewNoopStore() *NoopStore

func (*NoopStore) Latest added in v0.3.0

func (*NoopStore) Latest(ctx context.Context, _ time.Time, _ int) ([]Document, error)

func (*NoopStore) MGet added in v0.3.0

func (*NoopStore) MGet(ctx context.Context, _ []string) ([]Document, error)

func (*NoopStore) Merge added in v0.3.0

func (*NoopStore) Merge(ctx context.Context, _ string, _ Update) error

func (*NoopStore) Read added in v0.3.0

func (*NoopStore) Read(ctx context.Context, _ string) (Document, error)

type OperationRecord

type OperationRecord struct {
	Revision   uint64                     `json:"revision"`
	Operation  string                     `json:"operation"`
	StartedAt  time.Time                  `json:"started_at"`
	FinishedAt time.Time                  `json:"finished_at,omitempty"`
	Status     model.Status               `json:"status"`
	Error      string                     `json:"error,omitempty"`
	Attributes map[string]json.RawMessage `json:"attributes,omitempty"`
}

OperationRecord holds independently optional start and finish observations. Revision is writer-local metadata, not a cross-process ordering authority.

type StageUpdate

type StageUpdate struct {
	model.Stage
	Revision uint64 `json:"revision"`
}

StageUpdate is the storage envelope. Revision belongs to the writer protocol, not to the public stage data returned in snapshots.

func (*StageUpdate) UnmarshalJSON

func (s *StageUpdate) UnmarshalJSON(raw []byte) error

type Store

type Store interface {
	Merge(context.Context, string, Update) error
	Read(context.Context, string) (Document, error)
	// MGet omits missing IDs and returns each found document once; order is unspecified.
	MGet(context.Context, []string) ([]Document, error)
	// Latest returns documents updated strictly after the time, ordered by
	// updated_at DESC, id DESC. A nonpositive limit returns no documents.
	Latest(context.Context, time.Time, int) ([]Document, error)
}

Store atomically merges actor-scoped updates into one document per ID. The last accepted state replaces the same stage/actor; identical content is a no-op. On error acceptance may be uncertain. Retrying unchanged content does not duplicate records, but may overwrite a competing same-actor write. Reads return detached data. Connections, schema and retention belong to callers.

type Update

type Update struct {
	Operation *OperationRecord
	Stages    []StageUpdate
	// Completed contains imported intervals, with no caller-managed revision.
	Completed []model.Stage
}

Update contains only locally accepted changes. Stages carry full states; operation start and finish boundaries may arrive independently.

func CoalesceUpdates

func CoalesceUpdates(updates []Update) (Update, error)

CoalesceUpdates keeps the last accepted state for each actor-scoped stage.

Directories

Path Synopsis
Package sqlstore persists one document per timeline using an application-owned database/sql pool.
Package sqlstore persists one document per timeline using an application-owned database/sql pool.

Jump to

Keyboard shortcuts

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