store

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package store is Durable's Storage on Chord's store: StoreStorage keeps Durable's records as declared tables of the store, its documents in the store's documents engine, and commits as one series of the store's commit queue.

Index

Constants

This section is empty.

Variables

View Source
var Conversations = define("conversations", chordstore.TableOptions{
	Version: 1,
	Columns: []chordstore.ColumnProp{
		chordstore.Col("id", chordstore.Int()),
		chordstore.Col("owner_conversation_id", chordstore.Int()),
		chordstore.Col("owner_task_id", chordstore.Int()),
		chordstore.Col("record", record()),
	},
	Key: []string{"id"},
	Indexes: chordstore.IndexRecords{
		{Name: "by_owner_conversation", Columns: []string{"owner_conversation_id"}},
		{Name: "by_owner_task", Columns: []string{"owner_task_id"}},
	},
})

Conversations are the conversation records.

View Source
var Entries = define("entries", chordstore.TableOptions{
	Version: 1,
	Columns: []chordstore.ColumnProp{
		chordstore.Col("id", chordstore.Int()),
		chordstore.Col("conversation_id", chordstore.Int()),
		chordstore.Col("commit_seq", chordstore.Int()),
		chordstore.Col("record", record()),
	},
	Key:     []string{"id"},
	Indexes: chordstore.IndexRecords{{Name: "by_conversation", Columns: []string{"conversation_id"}}},
})

Entries are the entry records.

View Source
var EntryHeads = define("entry_heads", chordstore.TableOptions{
	Version: 1,
	Columns: []chordstore.ColumnProp{chordstore.Col("id", chordstore.Int()), chordstore.Col("conversation_id", chordstore.Int())},
	Key:     []string{"id"},
	Indexes: chordstore.IndexRecords{{Name: "by_conversation", Columns: []string{"conversation_id"}}},
})

EntryHeads are the entries with a head marker, by conversation: what `SqliteStorage`'s partial index on `head IS NOT NULL` is, as rows written only with such an entry, so a commit of an entry without one updates no second index.

View Source
var RecordIds = define("record_ids", chordstore.TableOptions{
	Version: 1,
	Columns: []chordstore.ColumnProp{chordstore.Col("id", chordstore.Int()), chordstore.Col("record_type", chordstore.Str())},
	Key:     []string{"id"},
})

RecordIds says which record type owns an id: Durable's one namespace across its five record types.

View Source
var ScopeNamespaces = []string{"session", "conversation:", "task:"}

ScopeNamespaces are the namespaces a storage claims under its owner: Durable's scopes (Chord's namespaces never contain a `:`).

View Source
var Submissions = define("submissions", chordstore.TableOptions{
	Version: 1,
	Columns: []chordstore.ColumnProp{
		chordstore.Col("id", chordstore.Int()),
		chordstore.Col("conversation_id", chordstore.Int()),
		chordstore.Col("request_id", chordstore.Str()),
		chordstore.Col("status", chordstore.Str()),
		chordstore.Col("record", record()),
	},
	Key: []string{"id"},
	Indexes: chordstore.IndexRecords{
		{Name: "by_request", Columns: []string{"conversation_id", "request_id"}},
		{Name: "by_conversation", Columns: []string{"conversation_id"}},
		{Name: "by_status", Columns: []string{"status"}},
	},
})

Submissions are the submission records.

View Source
var Tasks = define("tasks", chordstore.TableOptions{
	Version: 1,
	Columns: []chordstore.ColumnProp{
		chordstore.Col("id", chordstore.Int()),
		chordstore.Col("conversation_id", chordstore.Int()),
		chordstore.Col("kind", chordstore.Str()),
		chordstore.Col("status", chordstore.Str()),
		chordstore.Col("abort_requested", chordstore.Int()),
		chordstore.Col("background", chordstore.Int()),
		chordstore.Col("record", record()),
	},
	Key: []string{"id"},
	Indexes: chordstore.IndexRecords{
		{Name: "by_status", Columns: []string{"status"}},
		{Name: "by_conversation", Columns: []string{"conversation_id"}},
		{Name: "by_kind", Columns: []string{"kind"}},
		{Name: "by_abort_requested", Columns: []string{"abort_requested"}},
		{Name: "by_background", Columns: []string{"background"}},
	},
})

Tasks are the task records.

Functions

func AddressOf

func AddressOf(kind string, scope durable.DocumentRecordScope, key *string, owner string) chordstore.DocumentAddress

AddressOf is the engine address of a Durable address under owner.

func AliveAt

func AliveAt(record durable.DocumentRecord, at durable.DocumentPoint) bool

AliveAt reports whether a document is alive at at (the half-open lifetime).

func ConversationRow

func ConversationRow(value durable.ConversationRecord) (chordstore.Row, error)

ConversationRow is the row of a conversation record.

func DurableRecord

func DurableRecord(record chordstore.DocumentRecord, owner string) (*durable.DocumentRecord, error)

DurableRecord is the Durable record of an engine record of this storage's owner and scopes, nil for anyone else's (a Chord document, another owner's): its id is unknown to this storage.

func EncodeIndexed

func EncodeIndexed(value string) string

EncodeIndexed is Durable's JSON encoding of an indexed string: lossless whatever the string (lone surrogates, NUL).

func EngineRecord

func EngineRecord(create durable.DocumentCreate, owner string, version, seq int64, retired bool) (chordstore.DocumentRecord, error)

EngineRecord is the engine record of a Durable creation at seq (retired at once for an empty lifetime): the Durable record itself, its creation seq included, in `meta`, so a read of a live record parses one JSON text from one column, as `SqliteStorage`'s does (a retirement later sets only the engine's `retired_at`).

func EntryRow

func EntryRow(value durable.EntryRecord) (chordstore.Row, error)

EntryRow is the row of an entry record; `commit_seq` is stamped by the step.

func HistoryOf

HistoryOf is what a record of scope keeps: session and task documents and latest conversation ones their latest state.

func NamespaceOf

func NamespaceOf(scope durable.DocumentRecordScope) string

NamespaceOf is the engine namespace of a Durable scope: `session`, `conversation:<id>`, `task:<id>`.

func RecordOfEntry

func RecordOfEntry(entry chordstore.DocumentEntry) (durable.DocumentRecord, error)

RecordOfEntry is the Durable record of an engine entry read at one of this storage's addresses or scopes (the record in `meta`).

func SubmissionRow

func SubmissionRow(value durable.SubmissionRecord) (chordstore.Row, error)

SubmissionRow is the row of a submission record.

func TaskRow

TaskRow is the row of a task record.

Types

type CommitTables

type CommitTables struct {
	RecordIds     *chordstore.OwnerTable
	Conversations *chordstore.OwnerTable
	Entries       *chordstore.OwnerTable
	EntryHeads    *chordstore.OwnerTable
	Tasks         *chordstore.OwnerTable
	Submissions   *chordstore.OwnerTable
}

CommitTables are the storage's tables, as a commit writes them.

type Condition

type Condition struct {
	Column string
	Op     chordstore.WhereOp
	Value  sqlite.SqliteValue
}

Condition is one condition of a read: a column, how it compares, its value; a call site keeps one order of them.

type DocumentRead

type DocumentRead struct {
	Document      *durable.StoredDocument
	CurrentOnly   bool
	CurrentOnlyID durable.DocumentId
}

DocumentRead is a document read at a point, as a tagged result: request errors are told after the guarded read (slice 6b §1.4), never returned inside it. CurrentOnly is set when the record keeps no history at the point; the document is then absent and CurrentOnlyID names it.

func ReadAt

func ReadAt(executor readExecutor, id durable.DocumentId, at durable.DocumentPoint, owner string) (DocumentRead, error)

ReadAt is document id of owner at at: absent (unknown, someone else's, not alive at at), a record whose history does not reach back to at, or its value from the base at or below at and the deltas up to it.

type DurableCommit

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

DurableCommit is a Durable commit staged for the store's series: its checks, then itself as its one write.

func NewDurableCommit

func NewDurableCommit(batch []durable.StorageWrite, owner string, tables *CommitTables, raise func(id int64), ctx context.Context) (*DurableCommit, error)

NewDurableCommit stages writes (rule 8: rows and contents encoded here, before the queue); raise makes room above each explicit id. A malformed batch (two content commands for one document, a second retirement) returns Durable's message.

func (*DurableCommit) Apply

func (commit *DurableCommit) Apply(step *chordstore.Step) ([]chordstore.StoreWrite, error)

Apply is the commit's writes, after its Check in the same step.

func (*DurableCommit) Check

func (commit *DurableCommit) Check(step *chordstore.Step) error

Check is Durable's checks against the state the series' earlier commits left, writing nothing: the ids, the documents and the copies; an error refuses the commit.

func (*DurableCommit) Series

func (commit *DurableCommit) Series() chordstore.SeriesCommit

Series is the commit as a commit of the store's series: Check, then itself as its one write.

func (*DurableCommit) StageOrder

func (commit *DurableCommit) StageOrder() chordstore.WriteOrder

StageOrder is the write's phase: the commit is one composite write.

type RecordRow

type RecordRow struct {
	Record    string
	RecordV   int64
	CommitSeq int64
}

RecordRow is a stored row as a query selects it: the record cell, its version (selected only once the column has versions past 1), and an entry's commit seq.

type RecordType

type RecordType string

RecordType is Durable's record types, as `record_ids` names them.

const (
	RecordConversation RecordType = "conversation"
	RecordEntry        RecordType = "entry"
	RecordTask         RecordType = "task"
	RecordSubmission   RecordType = "submission"
	RecordDocument     RecordType = "document"
)

The record types.

type StorageQueries

type StorageQueries struct {
	Conversations *TableQueries
	Entries       *TableQueries
	// LatestHead is the id of a conversation's newest entry with a head marker: any, or at or before an id (bound
	// second).
	LatestHeadAny      string
	LatestHeadAtBefore string
	Tasks              *TableQueries
	Submissions        *TableQueries
}

StorageQueries are the compiled reads of the storage's tables.

func NewStorageQueries

func NewStorageQueries(tables *CommitTables) (*StorageQueries, error)

NewStorageQueries is the reads of tables.

type StoreStorage

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

StoreStorage is Durable's `Storage` on Chord's store (slice 6b D1, D2, §2): its records as declared tables under an owner name, its documents in the store's documents engine, its ids from the store's one allocator, each commit call as one series of the store's commit queue (one backend transaction, one seq per batch), published in the host's batch. Several may share a store under distinct owner names (claims); the app owns the store, and Close leaves it open.

func Open

func Open(ctx context.Context, store chordstore.Store, owner string) (_ *StoreStorage, err error)

Open opens Durable's storage in store under owner (a lowercase `[a-z0-9@/._~-]` name): claims its tables and its document namespaces (a second claim is refused `invalid/args`), creates or migrates its tables, and raises the store's allocator above every id it holds (one index read). A failure releases what it claimed.

func (*StoreStorage) Close

func (storage *StoreStorage) Close(ctx context.Context) error

Close refuses new calls, waits for its commits underway, then releases its claims; the store stays open (the app's), and finishes the reads underway, which change nothing.

func (*StoreStorage) Commit

func (storage *StoreStorage) Commit(ctx context.Context, batches [][]durable.StorageWrite, receive func(index int, seq durable.Seq)) (durable.CommitResult, error)

Commit commits batches as one series of the store (ChordStore.CommitSeries): one backend transaction, one seq per batch, each batch's checks (at staging, then against the state the earlier ones left) before its writes.

func (*StoreStorage) Conversation

Conversation looks up one conversation by exact id; nil when absent.

func (*StoreStorage) Document

Document materializes one specific incarnation by id at the selected point without following a replacement at its address; nil when absent.

func (*StoreStorage) Entry

func (storage *StoreStorage) Entry(ctx context.Context, id durable.EntryId) (*durable.EntryAt, error)

Entry looks up one global entry and the sequence of the commit that persisted it; nil when absent.

func (*StoreStorage) FindDocument

FindDocument resolves the incarnation occupying one exact logical address at the selected point; nil when absent.

func (*StoreStorage) FindLatestHeadMarker

func (storage *StoreStorage) FindLatestHeadMarker(ctx context.Context, conversationID durable.ConversationId, atOrBeforeEntryID *durable.EntryId) (*durable.EntryRecord, error)

FindLatestHeadMarker returns the newest visible entry with a Head at or below the optional inclusive cutoff.

func (*StoreStorage) MintId

func (storage *StoreStorage) MintId() (int64, error)

MintId takes a fresh id from the store's one allocator.

func (*StoreStorage) Publishing

func (storage *StoreStorage) Publishing(ctx context.Context, publish func())

Publishing runs a commit's publication in the attached host's batch (`batch.Within`: it joins a running batch, opens one, or runs next while one sends): Chord sources over Durable's views are marked in one batch per commit. Plainly without a host.

func (*StoreStorage) ScanConversations

func (storage *StoreStorage) ScanConversations(ctx context.Context, query durable.ConversationQuery, limit int, cursor durable.Cursor) (durable.Page[durable.ConversationRecord, durable.Cursor], error)

ScanConversations scans conversations in query.Order (default ascending) by id.

func (*StoreStorage) ScanDocuments

func (storage *StoreStorage) ScanDocuments(ctx context.Context, query durable.DocumentQuery, limit int, cursor durable.Cursor) (durable.Page[durable.DocumentRecord, durable.Cursor], error)

ScanDocuments scans incarnations alive in one exact scope at the selected point.

func (*StoreStorage) ScanEntries

func (storage *StoreStorage) ScanEntries(ctx context.Context, query durable.EntryQuery, limit int, cursor durable.Cursor) (durable.Page[durable.EntryRecord, durable.Cursor], error)

ScanEntries scans the inclusive visible range in query.Order (default descending), returning at most limit entries.

func (*StoreStorage) ScanSubmissions

func (storage *StoreStorage) ScanSubmissions(ctx context.Context, query durable.SubmissionQuery, limit int, cursor durable.Cursor) (durable.Page[durable.SubmissionRecord, durable.Cursor], error)

ScanSubmissions scans submissions matching every supplied filter in query.Order (default ascending) by id.

func (*StoreStorage) ScanTasks

func (storage *StoreStorage) ScanTasks(ctx context.Context, query durable.TaskQuery, limit int, cursor durable.Cursor) (durable.Page[storedTask, durable.Cursor], error)

ScanTasks scans task records matching every supplied filter in query.Order (default ascending) by id.

func (*StoreStorage) Submission

func (storage *StoreStorage) Submission(ctx context.Context, id durable.SubmissionId) (*durable.SubmissionRecord, error)

Submission looks up the latest complete record for one admitted submission; nil when absent.

func (*StoreStorage) SubmissionByRequest

func (storage *StoreStorage) SubmissionByRequest(ctx context.Context, conversationID durable.ConversationId, requestID string) (*durable.SubmissionRecord, error)

SubmissionByRequest finds a submission by its conversation-scoped host deduplication key; nil when absent.

func (*StoreStorage) Task

func (storage *StoreStorage) Task(ctx context.Context, id durable.TaskId) (*storedTask, error)

Task looks up the latest complete record for one task; nil when absent.

func (*StoreStorage) VisibleEntry

func (storage *StoreStorage) VisibleEntry(ctx context.Context, conversationID durable.ConversationId, id durable.EntryId) (*durable.EntryAt, error)

VisibleEntry looks up one entry only when it is visible through the requested conversation's ancestry.

type TableQueries

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

TableQueries is one table's compiled reads: by id (with the byIdExtra columns), and by shape (conditions in binding order, an order; the record only), each shape compiled at its first use.

func NewTableQueries

func NewTableQueries(table *chordstore.OwnerTable, byIDExtra ...string) (*TableQueries, error)

NewTableQueries compiles the by-id read of table, selecting byIdExtra besides the record.

func (*TableQueries) ByID

func (queries *TableQueries) ByID(executor interface {
	Get(sql string, params ...sqlite.SqliteValue) (sqlite.SqliteRow, error)
}, id int64) (*RecordRow, error)

ByID is the row with id; nil when absent.

func (*TableQueries) First

func (queries *TableQueries) First(executor interface {
	Get(sql string, params ...sqlite.SqliteValue) (sqlite.SqliteRow, error)
}, conditions []Condition, order chordstore.Order) (*RecordRow, error)

First is the first row whose conditions hold, by id in order; nil when none does.

func (*TableQueries) Select

func (queries *TableQueries) Select(executor interface {
	All(sql string, params ...sqlite.SqliteValue) ([]sqlite.SqliteRow, error)
}, conditions []Condition, order chordstore.Order, limit int64) ([]RecordRow, error)

Select is up to limit rows whose conditions hold, by id in order.

Jump to

Keyboard shortcuts

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