store

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 8 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: conflicting revision or immutable 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 stage, 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) (doc Document, changed bool, err error)

MergeDocument is the shared merge contract for storage implementations. It never mutates its inputs. A conflict rejects the entire update. changed=false lets durable stores acknowledge duplicate delivery without rewriting the row.

func (Document) Clone

func (doc Document) Clone() Document

Clone returns a detached document, including all JSON attribute values.

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.

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) 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 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 facts. Accepted boundaries are immutable; Revision orders attributes from the start writer.

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)
}

Store atomically merges updates into one document per ID. Older revisions are ignored; equal revisions with different content and changed immutable boundaries return ErrConflict. On error acceptance may be uncertain, so retry the same update. Read returns detached data or ErrNotFound. Implementations support concurrent callers and cancellation. Connections, schema and retention belong to the caller.

type Update

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

Update contains only this writer's changes. Each value is a complete state at its revision. Operation boundaries may arrive independently; stage owners write Stages.

func CoalesceUpdates

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

CoalesceUpdates combines full-state updates into one immutable submission. Conflicting equal revisions are rejected before reaching storage.

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