sessiondb

package
v0.3.0-beta.3 Latest Latest
Warning

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

Go to latest
Published: Aug 1, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrEventIdentityCollision = errors.New("store: session event identity collision")

ErrEventIdentityCollision reports a deterministic event ID reused with different content.

View Source
var ErrReadOnlyPoolQuiescing = errors.New("store: read-only pool session is quiescing")

ErrReadOnlyPoolQuiescing reports that destructive session work has blocked new read-only leases while existing leases drain.

Functions

func MigrationStream

func MigrationStream() store.MigrationStream

MigrationStream returns the embedded session database migration stream.

func NewEventMetadataOpener

func NewEventMetadataOpener(sessionsDir string) store.SessionEventMetadataOpener

NewEventMetadataOpener binds read-only session metadata access to one sessions directory.

Types

type ReadOnlyOpenOption

type ReadOnlyOpenOption func(*readOnlyOpenConfig)

ReadOnlyOpenOption customizes read-only session database opening.

func WithReadOnlyOpenRetry

func WithReadOnlyOpenRetry(
	maxAttempts int,
	minRetryDelay time.Duration,
	maxRetryDelay time.Duration,
) ReadOnlyOpenOption

WithReadOnlyOpenRetry configures retry behavior for read-only session database opens.

type ReadOnlyPool

type ReadOnlyPool struct {
	// contains filtered or unexported fields
}

ReadOnlyPool reuses short-lived read-only session database handles for hot inactive sessions.

func NewReadOnlyPool

func NewReadOnlyPool(config ReadOnlyPoolConfig) *ReadOnlyPool

NewReadOnlyPool constructs a read-only session recorder pool.

func (*ReadOnlyPool) Close

func (p *ReadOnlyPool) Close(ctx context.Context) error

Close closes every pooled handle and rejects future opens.

func (*ReadOnlyPool) CloseExpired

func (p *ReadOnlyPool) CloseExpired(ctx context.Context) error

CloseExpired closes idle handles whose TTL has elapsed.

func (*ReadOnlyPool) Open

func (p *ReadOnlyPool) Open(ctx context.Context, sessionID string, path string) (store.EventReadCloser, error)

Open returns a lease for a session-keyed read-only recorder.

func (*ReadOnlyPool) Quiesce

func (p *ReadOnlyPool) Quiesce(
	ctx context.Context,
	sessionID string,
	path string,
) (func(), error)

Quiesce prevents new leases for one session, waits for active leases to return, and closes the pooled database handle. The returned function must be called after the caller's destructive operation finishes so failed operations can resume read access.

type ReadOnlyPoolConfig

type ReadOnlyPoolConfig struct {
	TTL  time.Duration
	Now  func() time.Time
	Open ReadOnlyPoolOpener
}

ReadOnlyPoolConfig customizes read-only recorder pooling.

type ReadOnlyPoolOpener

type ReadOnlyPoolOpener func(ctx context.Context, sessionID string, path string) (store.EventReadCloser, error)

ReadOnlyPoolOpener opens the reader stored behind a pooled read-only lease.

type ReadOnlySessionDB

type ReadOnlySessionDB struct {
	// contains filtered or unexported fields
}

ReadOnlySessionDB opens an existing per-session events database for queries without creating, migrating, checkpointing, or otherwise mutating it.

func OpenSessionDBReadOnly

func OpenSessionDBReadOnly(
	ctx context.Context,
	sessionID string,
	path string,
	options ...ReadOnlyOpenOption,
) (*ReadOnlySessionDB, error)

OpenSessionDBReadOnly opens an existing per-session events database in SQLite read-only mode. It intentionally fails for missing paths instead of creating a fresh database during stale transcript/event reads.

func (*ReadOnlySessionDB) Close

func (s *ReadOnlySessionDB) Close(ctx context.Context) error

Close closes the read-only database handle without checkpointing.

func (*ReadOnlySessionDB) History

History returns ordered session events grouped by turn id.

func (*ReadOnlySessionDB) MaxEventSequence

func (s *ReadOnlySessionDB) MaxEventSequence(ctx context.Context) (int64, error)

MaxEventSequence returns the current highest per-session event sequence.

func (*ReadOnlySessionDB) Query

func (s *ReadOnlySessionDB) Query(
	ctx context.Context,
	query store.EventQuery,
) (events []store.SessionEvent, err error)

Query returns events filtered by the supplied options.

func (*ReadOnlySessionDB) QueryEventMetadata

func (s *ReadOnlySessionDB) QueryEventMetadata(
	ctx context.Context,
	query store.EventQuery,
) (events []store.EventMetadata, err error)

QueryEventMetadata returns ordered session event metadata without reading content.

func (*ReadOnlySessionDB) TranscriptChanges

func (s *ReadOnlySessionDB) TranscriptChanges(
	ctx context.Context,
	query transcript.ChangeQuery,
) (transcript.ChangePage, error)

TranscriptChanges returns entries changed by events after the supplied cursor.

func (*ReadOnlySessionDB) TranscriptPage

func (s *ReadOnlySessionDB) TranscriptPage(
	ctx context.Context,
	query transcript.PageQuery,
) (transcript.Page, error)

TranscriptPage returns one bounded materialized transcript window.

type SessionDB

type SessionDB struct {
	// contains filtered or unexported fields
}

SessionDB owns a per-session SQLite database and its dedicated writer loop.

func OpenSessionDB

func OpenSessionDB(ctx context.Context, sessionID string, path string) (*SessionDB, error)

OpenSessionDB opens or creates the per-session events database at path.

func (*SessionDB) AppendEventIfAbsent

func (s *SessionDB) AppendEventIfAbsent(
	ctx context.Context,
	event store.SessionEvent,
) (store.SessionEvent, error)

AppendEventIfAbsent inserts one deterministic event or returns its byte-identical existing row.

func (*SessionDB) ArchiveEvents

func (s *SessionDB) ArchiveEvents(
	ctx context.Context,
	request store.EventArchiveRequest,
) (store.EventArchiveResult, error)

ArchiveEvents marks one fixed event range as excluded from replay.

func (*SessionDB) Clear

func (s *SessionDB) Clear(ctx context.Context) error

Clear removes all persisted per-session runtime records while preserving the migrated database schema and the open writer. It is used by session reset flows before the recorder is exposed to any live session goroutine.

func (*SessionDB) Close

func (s *SessionDB) Close(ctx context.Context) error

Close drains queued writes, checkpoints the WAL, and closes the database.

func (*SessionDB) History

func (s *SessionDB) History(ctx context.Context, query store.EventQuery) ([]store.TurnHistory, error)

History returns ordered session events grouped by turn id.

func (*SessionDB) Path

func (s *SessionDB) Path() string

Path reports the on-disk path for the database file.

func (*SessionDB) Query

func (s *SessionDB) Query(ctx context.Context, query store.EventQuery) ([]store.SessionEvent, error)

Query returns events filtered by the supplied options.

func (*SessionDB) QueryHookRuns

func (s *SessionDB) QueryHookRuns(ctx context.Context, query store.HookRunQuery) ([]hookspkg.HookRunRecord, error)

QueryHookRuns returns persisted hook execution records filtered by the supplied options.

func (*SessionDB) Record

func (s *SessionDB) Record(ctx context.Context, event store.SessionEvent) error

Record appends a session event using the dedicated writer goroutine.

func (*SessionDB) RecordHookRun

func (s *SessionDB) RecordHookRun(ctx context.Context, record hookspkg.HookRunRecord) error

RecordHookRun stores one hook execution audit record in the per-session store.

func (*SessionDB) RecordPersisted

func (s *SessionDB) RecordPersisted(ctx context.Context, event store.SessionEvent) (store.SessionEvent, error)

RecordPersisted appends a session event and returns the stored row with sequence metadata.

func (*SessionDB) RecordPersistedBatch

func (s *SessionDB) RecordPersistedBatch(
	ctx context.Context,
	events []store.SessionEvent,
) ([]store.SessionEvent, error)

RecordPersistedBatch appends session events in one writer-owned transaction.

func (*SessionDB) RecordTokenUsage

func (s *SessionDB) RecordTokenUsage(ctx context.Context, usage store.TokenUsage) error

RecordTokenUsage stores or merges per-turn usage data for the session.

func (*SessionDB) SessionID

func (s *SessionDB) SessionID() string

SessionID reports the owning session identifier for the database.

func (*SessionDB) TranscriptChanges

func (s *SessionDB) TranscriptChanges(
	ctx context.Context,
	query transcript.ChangeQuery,
) (transcript.ChangePage, error)

TranscriptChanges returns entries changed by events after the supplied cursor.

func (*SessionDB) TranscriptPage

func (s *SessionDB) TranscriptPage(
	ctx context.Context,
	query transcript.PageQuery,
) (transcript.Page, error)

TranscriptPage returns one bounded materialized transcript window.

Directories

Path Synopsis
Package schema embeds the session database schema and migration directory.
Package schema embeds the session database schema and migration directory.

Jump to

Keyboard shortcuts

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