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 ¶
var ErrConflict = errors.New("timeline: conflicting revision or immutable boundary")
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) MarshalJSON ¶
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 ¶
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 ¶
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
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 ¶
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 ¶
CoalesceUpdates combines full-state updates into one immutable submission. Conflicting equal revisions are rejected before reaching storage.