Documentation
¶
Overview ¶
Package file provides a filesystem-backed statestore implementation.
One directory per conversation under Options.Root holds:
state.json — atomically-rewritten snapshot of meta + metadata messages.jsonl — append-only message log (one types.Message per line) summaries.jsonl — append-only summary log lists/<name>.jsonl — opaque-byte append-only lists for ListAccessor
The store is single-process: pointing two stores at the same Root is undefined behavior. A future revision may add an OS-level lock file.
Index ¶
- Variables
- type FSyncPolicy
- type Options
- type Store
- func (s *Store) AppendList(_ context.Context, id, listName string, items [][]byte) error
- func (s *Store) AppendMessages(_ context.Context, id string, messages []types.Message) error
- func (s *Store) Close() error
- func (s *Store) Delete(_ context.Context, id string) error
- func (s *Store) Fork(_ context.Context, sourceID, newID string) error
- func (s *Store) List(_ context.Context, opts statestore.ListOptions) ([]string, error)
- func (s *Store) ListLen(_ context.Context, id, listName string) (int, error)
- func (s *Store) Load(_ context.Context, id string) (*statestore.ConversationState, error)
- func (s *Store) LoadList(_ context.Context, id, listName string) ([][]byte, error)
- func (s *Store) LoadMetadata(_ context.Context, id string) (map[string]any, error)
- func (s *Store) LoadRecentMessages(ctx context.Context, id string, n int) ([]types.Message, error)
- func (s *Store) LoadSummaries(_ context.Context, id string) ([]statestore.Summary, error)
- func (s *Store) LogAppend(_ context.Context, id string, startSeq int, messages []types.Message) (int, error)
- func (s *Store) LogLen(_ context.Context, id string) (int, error)
- func (s *Store) LogLoad(_ context.Context, id string, recent int) ([]types.Message, error)
- func (s *Store) MergeMetadata(_ context.Context, id string, updates map[string]any) error
- func (s *Store) MessageCount(_ context.Context, id string) (int, error)
- func (s *Store) Save(_ context.Context, state *statestore.ConversationState) error
- func (s *Store) SaveSummary(_ context.Context, id string, summary statestore.Summary) error
Constants ¶
This section is empty.
Variables ¶
var ErrStoreClosed = errors.New("filestore: store closed")
ErrStoreClosed is returned from any method called after Close.
Functions ¶
This section is empty.
Types ¶
type FSyncPolicy ¶
type FSyncPolicy int
FSyncPolicy controls when on-disk writes are fsync'd.
const ( // FSyncOff matches MemoryStore durability semantics: writes are buffered // by the OS and may be lost on power-loss / kernel panic. FSyncOff FSyncPolicy = iota // FSyncOnSave fsyncs only on Save (the atomic rename of state.json). // Mid-loop message-log appends are not fsync'd. Default. FSyncOnSave // FSyncOnAppend fsyncs on every JSONL append (slowest, most durable). FSyncOnAppend )
type Options ¶
type Options struct {
// Root is the directory under which per-conversation directories live.
// Created if absent. Required.
Root string
// FSync controls fsync behavior. Defaults to FSyncOnSave.
FSync FSyncPolicy
// TTL, if non-zero, removes conversation directories whose state.json
// mtime is older than now-TTL at NewStore time.
TTL time.Duration
}
Options configures the file-backed store.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a filesystem-backed implementation of statestore.Store and the optional MessageLog / MessageReader / MessageAppender / MetadataAccessor / SummaryAccessor / ListAccessor interfaces.
func NewStore ¶
NewStore opens (or creates) a file-backed store at opts.Root. Returns an error if Root is empty or the directory cannot be created.
func (*Store) AppendList ¶
AppendList appends opaque-byte items to the named list. Each item becomes one line in lists/<listName>.jsonl. Auto-creates the conversation and list.
func (*Store) AppendMessages ¶
AppendMessages appends without dedup. Auto-creates the conversation. Differs from LogAppend in that it takes no startSeq — used by pipeline paths that already track their own offset.
func (*Store) Close ¶
Close releases in-memory resources. Idempotent. Outstanding handles to the store after Close return ErrStoreClosed.
func (*Store) Fork ¶
Fork copies all files in <root>/conv-<sourceID>/ to <root>/conv-<newID>/. Returns ErrNotFound when source is missing.
func (*Store) List ¶
func (s *Store) List(_ context.Context, opts statestore.ListOptions) ([]string, error)
List returns conversation IDs filtered by ListOptions. The UserID filter reads each candidate's state.json (no separate user index in v1; ample for typical scales).
func (*Store) Load ¶
func (s *Store) Load(_ context.Context, id string) (*statestore.ConversationState, error)
Load reads state.json + messages.jsonl + summaries.jsonl into a ConversationState. Returns ErrNotFound when state.json is absent.
func (*Store) LoadList ¶
LoadList returns all items of the named list in append order. Returns (nil, nil) when the list is empty or missing.
func (*Store) LoadMetadata ¶
LoadMetadata returns the metadata map for the conversation. Returns ErrNotFound if no state.json exists for the conv. The returned map is a deep copy safe for caller mutation.
func (*Store) LoadRecentMessages ¶
func (s *Store) LoadRecentMessages( ctx context.Context, id string, n int, ) ([]types.Message, error)
LoadRecentMessages returns the last n messages. Returns ErrNotFound if the conversation has no state.json (the caller asked about a conv that doesn't exist).
func (*Store) LoadSummaries ¶
LoadSummaries returns all summaries for the conversation, or nil if none.
func (*Store) LogAppend ¶
func (s *Store) LogAppend( _ context.Context, id string, startSeq int, messages []types.Message, ) (int, error)
LogAppend appends messages with clamp-and-skip idempotent dedup. Mirrors MemoryStore.LogAppend / RedisStore.LogAppend semantics exactly. Also writes a minimal state.json stub on first append so Load(id) works during crash recovery before the end-of-turn Save runs.
func (*Store) LogLoad ¶
LogLoad returns messages for the conversation. If recent > 0, returns only the last N. Returns nil (not an error) when the file doesn't exist.
func (*Store) MergeMetadata ¶
MergeMetadata atomically merges updates into the conversation's metadata. Auto-creates the conversation. Read-modify-write under the per-conv lock.
func (*Store) MessageCount ¶
MessageCount returns the total number of messages. Returns ErrNotFound when the conversation has no state.json.
func (*Store) Save ¶
func (s *Store) Save(_ context.Context, state *statestore.ConversationState) error
Save atomically writes state.json and reconciles messages.jsonl / summaries.jsonl with the provided state. When the on-disk message log is shorter than state.Messages, only the delta is appended (matches the Redis delta-append branch). When it is longer, the file is rewritten in full.
func (*Store) SaveSummary ¶
SaveSummary appends a summary to summaries.jsonl. Auto-creates the conv.
Source Files