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 ¶
- Variables
- type Document
- type MemoryStore
- func (s *MemoryStore) Latest(ctx context.Context, after time.Time, limit int) ([]Document, error)
- func (s *MemoryStore) MGet(ctx context.Context, ids []string) ([]Document, error)
- func (s *MemoryStore) Merge(ctx context.Context, id string, update Update) error
- func (s *MemoryStore) Read(ctx context.Context, id string) (Document, error)
- type NoopStore
- func (*NoopStore) Latest(ctx context.Context, _ time.Time, _ int) ([]Document, error)
- func (*NoopStore) MGet(ctx context.Context, _ []string) ([]Document, error)
- func (*NoopStore) Merge(ctx context.Context, _ string, _ Update) error
- func (*NoopStore) Read(ctx context.Context, _ string) (Document, error)
- type OperationRecord
- type StageUpdate
- type Store
- type Update
Constants ¶
This section is empty.
Variables ¶
var ErrConflict = errors.New("timeline: invalid document identity or operation 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 (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 ¶
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
Overlay applies already accepted documents and local pending updates. Historical empty Actors remain readable; admission validates only newly recorded stages.
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 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
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 ¶
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 ¶
CoalesceUpdates keeps the last accepted state for each actor-scoped stage.