sessiondb

package
v0.4.6 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrSessionDBOwnerMissing reports an events.db without immutable owner evidence.
	ErrSessionDBOwnerMissing = errors.New("store: session database owner is missing")
	// ErrSessionDBOwnerMismatch reports an events.db owned by another session or workspace.
	ErrSessionDBOwnerMismatch = errors.New("store: session database owner does not match")
	// ErrSessionDBFamilyChanged reports that events.db changed identity during an owned open.
	ErrSessionDBFamilyChanged = errors.New("store: session database family changed during owned open")
)
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 FamilyFile

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

FamilyFile retains the exact no-follow identity of one regular file in an active FamilyLease until its move or removal completes.

func (*FamilyFile) Close

func (f *FamilyFile) Close() error

Close releases the held file identity without mutating it.

func (*FamilyFile) MoveParentDirectory

func (f *FamilyFile) MoveParentDirectory(
	ctx context.Context,
	owner store.SessionDBOwner,
	directory *fileutil.Directory,
	parent *fileutil.Directory,
	targetPath string,
) (fileutil.DirectoryMoveResult, error)

MoveParentDirectory preserves database identity across a handle-bound directory rename.

func (*FamilyFile) MoveTo

func (f *FamilyFile) MoveTo(targetPath string) (committed bool, retErr error)

MoveTo moves the exact bound file to another name in the leased directory. A path substitution is rolled back and reported as ErrSessionDBFamilyChanged.

func (*FamilyFile) Remove

func (f *FamilyFile) Remove() error

Remove removes the exact bound file through its retained identity.

func (*FamilyFile) RequireSameFile

func (f *FamilyFile) RequireSameFile(file *os.File) error

RequireSameFile proves that another no-follow handle refers to the exact regular file retained by this capability.

func (*FamilyFile) SHA256

func (f *FamilyFile) SHA256() ([sha256.Size]byte, error)

SHA256 returns the digest of the held file without changing its seek offset.

func (*FamilyFile) VerifyOwnerAt

func (f *FamilyFile) VerifyOwnerAt(
	ctx context.Context,
	owner store.SessionDBOwner,
	path string,
) error

VerifyOwnerAt proves that path still names the held file and that its SQLite owner remains exact, then advances the capability to that path.

type FamilyLease

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

FamilyLease serializes physical opens and whole-family replacement for one canonical events.db path inside this process.

func AcquireFamilyLease

func AcquireFamilyLease(ctx context.Context, path string) (*FamilyLease, error)

AcquireFamilyLease acquires the mutation/open lease for one canonical events.db family. Release must be called when the protected operation is complete.

func (*FamilyLease) BindFile

func (l *FamilyLease) BindFile(path string) (*FamilyFile, error)

BindFile binds one regular file in the leased family directory.

func (*FamilyLease) BindOwnedFile

func (l *FamilyLease) BindOwnedFile(
	ctx context.Context,
	owner store.SessionDBOwner,
	path string,
) (*FamilyFile, error)

BindOwnedFile binds one SQLite database after verifying its exact owner.

func (*FamilyLease) PublishFreshOwnedDatabase

func (l *FamilyLease) PublishFreshOwnedDatabase(
	ctx context.Context,
	owner store.SessionDBOwner,
	path string,
) (retErr error)

PublishFreshOwnedDatabase publishes one complete empty SessionDB while the caller retains exclusive ownership of the family lease.

func (*FamilyLease) Release

func (l *FamilyLease) Release()

Release releases the family lease. It is safe to call more than once.

func (*FamilyLease) VerifyOwner

func (l *FamilyLease) VerifyOwner(
	ctx context.Context,
	owner store.SessionDBOwner,
	path string,
) error

VerifyOwner verifies a database file in the leased family directory against the exact immutable owner while retaining no-follow identity across the read-only SQLite probe.

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

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

func (*ReadOnlyPool) Quiesce

func (p *ReadOnlyPool) Quiesce(
	ctx context.Context,
	owner store.SessionDBOwner,
	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,
	owner store.SessionDBOwner,
	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,
	owner store.SessionDBOwner,
	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 OpenSessionDBReadOnlyWithProjectionUpgrade

func OpenSessionDBReadOnlyWithProjectionUpgrade(
	ctx context.Context,
	owner store.SessionDBOwner,
	path string,
) (*ReadOnlySessionDB, error)

OpenSessionDBReadOnlyWithProjectionUpgrade repairs legacy projections before returning a reader.

func (*ReadOnlySessionDB) Close

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

Close closes the read-only database handle without checkpointing.

func (*ReadOnlySessionDB) ConversationRewindReceipt

func (s *ReadOnlySessionDB) ConversationRewindReceipt(
	ctx context.Context,
	idempotencyKey string,
	requestHash string,
) (store.ConversationRewindResult, bool, error)

func (*ReadOnlySessionDB) ConversationRewindState

func (s *ReadOnlySessionDB) ConversationRewindState(
	ctx context.Context,
) (store.ConversationRewindState, bool, error)

func (*ReadOnlySessionDB) ConversationRewindTarget

func (s *ReadOnlySessionDB) ConversationRewindTarget(
	ctx context.Context,
	messageID string,
) (store.ConversationRewindTarget, error)

func (*ReadOnlySessionDB) History

History returns ordered session events grouped by turn id.

func (*ReadOnlySessionDB) ListTokenUsage

func (s *ReadOnlySessionDB) ListTokenUsage(ctx context.Context) ([]store.TokenUsage, error)

ListTokenUsage returns the per-turn usage projection without mutating the database.

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) TranscriptOutline

func (s *ReadOnlySessionDB) TranscriptOutline(ctx context.Context) (transcript.OutlineResult, error)

TranscriptOutline reads the operator-message trail without a live writer.

func (*ReadOnlySessionDB) TranscriptPage

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

TranscriptPage returns one bounded materialized transcript window.

func (*ReadOnlySessionDB) TranscriptSearch

func (s *ReadOnlySessionDB) TranscriptSearch(
	ctx context.Context,
	query transcript.SearchQuery,
) (transcript.SearchResult, error)

TranscriptSearch reads matching messages without a live writer.

func (*ReadOnlySessionDB) TranscriptUserAnchor

func (s *ReadOnlySessionDB) TranscriptUserAnchor(
	ctx context.Context,
	messageID string,
) (store.TranscriptUserAnchor, error)

TranscriptUserAnchor resolves a durable user message to its turn.

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, owner store.SessionDBOwner, 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, bool, 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) ConversationRewindReceipt

func (s *SessionDB) ConversationRewindReceipt(
	ctx context.Context,
	idempotencyKey string,
	requestHash string,
) (store.ConversationRewindResult, bool, error)

func (*SessionDB) ConversationRewindState

func (s *SessionDB) ConversationRewindState(
	ctx context.Context,
) (store.ConversationRewindState, bool, error)

func (*SessionDB) ConversationRewindTarget

func (s *SessionDB) ConversationRewindTarget(
	ctx context.Context,
	messageID string,
) (store.ConversationRewindTarget, error)

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) ListTokenUsage

func (s *SessionDB) ListTokenUsage(ctx context.Context) ([]store.TokenUsage, error)

ListTokenUsage returns the per-turn usage projection recorded for the session.

func (*SessionDB) MaxEventSequence

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

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) QueryEventMetadata

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

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) RefreshConversationRewindBaseline

func (s *SessionDB) RefreshConversationRewindBaseline(
	ctx context.Context,
	coveredThrough int64,
	messagesJSON string,
) error

func (*SessionDB) RewindConversation

func (s *SessionDB) RewindConversation(
	ctx context.Context,
	request store.ConversationRewindRequest,
) (store.ConversationRewindResult, error)

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) TranscriptOutline

func (s *SessionDB) TranscriptOutline(ctx context.Context) (transcript.OutlineResult, error)

TranscriptOutline reads the operator-message trail from the retained projection.

func (*SessionDB) TranscriptPage

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

TranscriptPage returns one bounded materialized transcript window.

func (*SessionDB) TranscriptSearch

func (s *SessionDB) TranscriptSearch(
	ctx context.Context,
	query transcript.SearchQuery,
) (transcript.SearchResult, error)

TranscriptSearch reads matching projected messages from the whole retained history.

func (*SessionDB) TranscriptUserAnchor

func (s *SessionDB) TranscriptUserAnchor(ctx context.Context, messageID string) (store.TranscriptUserAnchor, error)

TranscriptUserAnchor resolves a durable user message to its turn.

func (*SessionDB) WorkspaceID

func (s *SessionDB) WorkspaceID() string

WorkspaceID reports the owning workspace identifier for the database.

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