sessionlog

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 14 Imported by: 3

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

View Source
const ConfigSubpath = "config"

ConfigSubpath holds the current session configuration.

Variables

This section is empty.

Functions

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 CommitReport added in v0.1.1

type CommitReport struct {
	// Appended is how many rows an append added.
	Appended int
	// Republish is why the whole generation was published, or empty when the
	// commit appended or wrote nothing.
	Republish Republish
	// AppendErr is the append failure behind RepublishAppendFailed.
	AppendErr error
}

CommitReport describes what one commit wrote.

func (CommitReport) Recovery added in v0.1.1

func (r CommitReport) Recovery() bool

Recovery reports a republish that repaired a divergence between the store and the native history, which a caller logs.

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

func Position(v any) Cursor

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

func WriteJSONL(path string, rows [][]byte) (Cursor, error)

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.

func (Cursor) Offset

func (c Cursor) Offset() int64

Offset is the byte offset after the last complete line a JSONL read returned.

func (Cursor) Position

func (c Cursor) Position() any

Position returns the value a non-file source stored with Position, or nil.

type HydrateReport added in v0.1.1

type HydrateReport struct {
	// Tail is what CutTornTail did to the native file's last line.
	Tail TornTail
	// InvalidCut is how many bytes of invalid native rows past the stored
	// ones were cut from the native file. Those rows were never committed.
	InvalidCut int64
	// Rewritten reports that the native file was rewritten from the stored
	// rows.
	Rewritten bool
	// Commit is what committing native rows past the stored ones wrote.
	Commit CommitReport
}

HydrateReport describes how Hydrate changed the native file and the store.

func (HydrateReport) Changed added in v0.1.1

func (r HydrateReport) Changed() bool

Changed reports whether Hydrate modified the native file, which a caller logs.

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

func (m *Mirror) Adopt(rows [][]byte, record any, next Cursor) error

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

func (m *Mirror) Commit(ctx context.Context, source Source, record func(Tail) (any, error)) (CommitReport, error)

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. An invalid row fails the commit with an error naming its file and byte offset when source is a JSONL read.

func (*Mirror) Hydrate

func (m *Mirror) Hydrate(ctx context.Context, path string, stored [][]byte, record any, validate func(rows [][]byte) error) ([][]byte, HydrateReport, 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, and so is everything from the first invalid native row past the stored ones, which was never committed. 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.

func (*Mirror) Reset

func (m *Mirror) Reset()

Reset forgets what the mirror committed, so its next commit republishes the whole generation and may shorten the history, as a native binding change requires.

type Republish added in v0.1.1

type Republish string

Republish names why a commit published the whole generation.

const (
	// RepublishInitial is the first commit, or the first after Reset.
	RepublishInitial Republish = "initial"
	// RepublishRewritten is a native history that no longer extends the
	// committed rows.
	RepublishRewritten Republish = "rewritten"
	// RepublishAppendFailed is an append the store refused or failed.
	RepublishAppendFailed Republish = "append_failed"
)

type Source

type Source func(from Cursor) (Tail, error)

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.

func File

func File(path string) Source

File is the source for an append-only JSONL file at path.

func Rows

func Rows(rows [][]byte) Source

Rows is the source for a history the caller already holds in full.

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
	// contains filtered or unexported fields
}

Tail is what one read returned: the rows after the cursor it was given, or every row when Full is set.

func ReadJSONL

func ReadJSONL(path string, from Cursor) (Tail, error)

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.

func ReadJSONLFile

func ReadJSONLFile(file *os.File, from Cursor, size int64) (Tail, error)

ReadJSONLFile is ReadJSONL over an open file, reading no further than size bytes; a negative size reads to the file's current end. A size beyond the file's end fails.

type TornTail added in v0.1.1

type TornTail struct {
	// Cut is how many bytes of an incomplete last line were removed.
	Cut int64
	// Terminated reports that a complete last record received its newline.
	Terminated bool
}

TornTail reports what CutTornTail did to a file's unterminated last line. The zero TornTail means the file already ended on a line boundary.

func CutTornTail

func CutTornTail(path string) (TornTail, error)

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. The tail is examined as a stream, never read whole. A missing file is left missing.

func (TornTail) Changed added in v0.1.1

func (t TornTail) Changed() bool

Changed reports whether CutTornTail modified the file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL