Documentation
¶
Overview ¶
Package sessionlog mirrors native rows and their session configuration as one durable store generation, and reads and writes append-only native JSONL files.
Index ¶
- Constants
- func CutTornTail(path string) error
- func Load(ctx context.Context, store acpcore.SessionStore, sessionID string, record any) (rows [][]byte, found bool, err error)
- func LoadRecord(ctx context.Context, store acpcore.SessionStore, sessionID string, record any) (found bool, err error)
- type Cursor
- type Mirror
- func (m *Mirror) Adopt(rows [][]byte, record any, next Cursor) error
- func (m *Mirror) Commit(ctx context.Context, source Source, record func(Tail) (any, error)) error
- func (m *Mirror) Hydrate(ctx context.Context, path string, stored [][]byte, record any, ...) ([][]byte, error)
- func (m *Mirror) Reset()
- type Source
- type Tail
Constants ¶
const ConfigSubpath = "config"
ConfigSubpath holds the current session configuration.
Variables ¶
This section is empty.
Functions ¶
func CutTornTail ¶
CutTornTail ends the JSONL file at path on a line boundary, so the next line a harness appends starts on a line of its own. A trailing line without its newline that is one complete JSON object is a record whose newline was not written, and is terminated; any other unterminated tail is bytes a writer that died mid-record left behind, and is cut. A harness that writes a record without its newline in the same write can leave a record that still parses as complete while more was due; that harness must not rely on this cut. A missing file is left missing.
func Load ¶
func Load(ctx context.Context, store acpcore.SessionStore, sessionID string, record any) (rows [][]byte, found bool, err error)
Load reads the native rows and decodes the required configuration into record. found is false when the session is missing or tombstoned; a found session with no rows is a committed conversation whose native history is still empty. The rows are the store's caller-owned copies.
func LoadRecord ¶
func LoadRecord(ctx context.Context, store acpcore.SessionStore, sessionID string, record any) (found bool, err error)
LoadRecord decodes only the required configuration into record, for callers such as session listing that need no native rows. The store still reads the whole generation; only the rows' validation and copies are skipped.
Types ¶
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
Cursor records how far a source has read. A JSONL cursor holds the offset after the last complete line, the file's identity, and checksums of the first and last bytes before the offset. A non-file source carries its own position. The zero Cursor is the start of any history. Cursors are not comparable: a position may hold a map.
func Position ¶
Position is the cursor of a non-file source that has read through v, such as the last row id or sequence it returned.
func WriteJSONL ¶
WriteJSONL publishes rows as the JSONL file at path, one row per line, creating its directory. The file is staged beside its final name and renamed into place, so a reader sees the previous file or the complete new one. It returns the cursor after the last row.
type Mirror ¶
type Mirror struct {
// contains filtered or unexported fields
}
Mirror publishes one session's native rows and configuration to a store and remembers what the store holds: the row count, a digest of the rows, a digest of the encoded configuration, and the source cursor after the last committed row. When the native history still extends the committed rows, a commit appends only the new rows, replacing the configuration record only when its encoding changed. Otherwise it republishes the whole generation. Every write to the session's store generation goes through its one Mirror; a write that bypasses it with a different row count fails the next append, which a full republish repairs.
func NewMirror ¶
func NewMirror(store acpcore.SessionStore, sessionID string) *Mirror
NewMirror returns the mirror of sessionID in store. It holds nothing, so its first commit publishes the whole generation unless Adopt or Hydrate tells it what the store already holds.
func (*Mirror) Adopt ¶
Adopt records that the store already holds exactly rows and record, as Load returned them, with next the source cursor after the last row. It writes nothing; the next commit continues from next.
func (*Mirror) Commit ¶
Commit reads the native rows source returns and publishes them with the configuration record returns for that read. record runs under the mirror's lock after the read, so the configuration matches the rows it commits. When an append fails, Commit reads the whole history again and computes its configuration for that read, so source and record may each run more than once in one Commit; a caller applies anything they decide only after Commit returns nil. The commit is durable when it returns; a failure leaves the previous generation intact. A history shorter than the committed one fails unless the mirror was Reset.
func (*Mirror) Hydrate ¶
func (m *Mirror) Hydrate(ctx context.Context, path string, stored [][]byte, record any, validate func(rows [][]byte) error) ([][]byte, error)
Hydrate reconciles the native JSONL file at path with the rows the store holds for the session before a load or resume. Native rows that extend the stored rows win and are committed with record; a missing or shorter native file is rewritten from the store; a disagreement at a shared position fails. Bytes after the native file's last complete line are cut first. validate, when set, sees the reconciled history before anything is written. stored and record MUST be the generation Load returned from this mirror's store. It returns the rows the session now holds.
type Source ¶
Source reads native rows after from. A source returns a Full tail when from is the zero Cursor, and may return one whenever it cannot continue from. A continuation returns only rows after from, with the cursor after them.
type Tail ¶
type Tail struct {
// Rows are trimmed, non-empty lines. A JSONL read slices them from one
// buffer.
Rows [][]byte
// Next is where the following read continues.
Next Cursor
// Full reports that Rows are the complete history rather than a
// continuation of the cursor.
Full bool
}
Tail is what one read returned: the rows after the cursor it was given, or every row when Full is set.
func ReadJSONL ¶
ReadJSONL reads the complete lines appended to the JSONL file at path after from. It reads every line from the start, and reports Full, when from is the zero Cursor or the file no longer extends what from read: it was replaced, truncated, or rewritten within the first or last 4 KiB before the cursor. A rewrite confined to the bytes between those windows is not detected; a source that rewrites its file in place resets its mirror. A trailing line without its newline is left for a later read. A missing file reads as an empty history.