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 ¶
- Variables
- func AddressOf(kind string, scope durable.DocumentRecordScope, key *string, owner string) chordstore.DocumentAddress
- func AliveAt(record durable.DocumentRecord, at durable.DocumentPoint) bool
- func ConversationRow(value durable.ConversationRecord) (chordstore.Row, error)
- func DurableRecord(record chordstore.DocumentRecord, owner string) (*durable.DocumentRecord, error)
- func EncodeIndexed(value string) string
- func EngineRecord(create durable.DocumentCreate, owner string, version, seq int64, retired bool) (chordstore.DocumentRecord, error)
- func EntryRow(value durable.EntryRecord) (chordstore.Row, error)
- func HistoryOf(scope durable.DocumentRecordScope, history durable.DocumentHistory) chordstore.DocumentHistory
- func NamespaceOf(scope durable.DocumentRecordScope) string
- func RecordOfEntry(entry chordstore.DocumentEntry) (durable.DocumentRecord, error)
- func SubmissionRow(value durable.SubmissionRecord) (chordstore.Row, error)
- func TaskRow(...) (chordstore.Row, error)
- type CommitTables
- type Condition
- type DocumentRead
- type DurableCommit
- type RecordRow
- type RecordType
- type StorageQueries
- type StoreStorage
- func (storage *StoreStorage) Close(ctx context.Context) error
- func (storage *StoreStorage) Commit(ctx context.Context, batches [][]durable.StorageWrite, ...) (durable.CommitResult, error)
- func (storage *StoreStorage) Conversation(ctx context.Context, id durable.ConversationId) (*durable.ConversationRecord, error)
- func (storage *StoreStorage) Document(ctx context.Context, id durable.DocumentId, at durable.DocumentPoint) (*durable.StoredDocument, error)
- func (storage *StoreStorage) Entry(ctx context.Context, id durable.EntryId) (*durable.EntryAt, error)
- func (storage *StoreStorage) FindDocument(ctx context.Context, address durable.DocumentAddress, at durable.DocumentPoint) (*durable.DocumentRecord, error)
- func (storage *StoreStorage) FindLatestHeadMarker(ctx context.Context, conversationID durable.ConversationId, ...) (*durable.EntryRecord, error)
- func (storage *StoreStorage) MintId() (int64, error)
- func (storage *StoreStorage) Publishing(ctx context.Context, publish func())
- func (storage *StoreStorage) ScanConversations(ctx context.Context, query durable.ConversationQuery, limit int, ...) (durable.Page[durable.ConversationRecord, durable.Cursor], error)
- func (storage *StoreStorage) ScanDocuments(ctx context.Context, query durable.DocumentQuery, limit int, ...) (durable.Page[durable.DocumentRecord, durable.Cursor], error)
- func (storage *StoreStorage) ScanEntries(ctx context.Context, query durable.EntryQuery, limit int, ...) (durable.Page[durable.EntryRecord, durable.Cursor], error)
- func (storage *StoreStorage) ScanSubmissions(ctx context.Context, query durable.SubmissionQuery, limit int, ...) (durable.Page[durable.SubmissionRecord, durable.Cursor], error)
- func (storage *StoreStorage) ScanTasks(ctx context.Context, query durable.TaskQuery, limit int, cursor durable.Cursor) (durable.Page[storedTask, durable.Cursor], error)
- func (storage *StoreStorage) Submission(ctx context.Context, id durable.SubmissionId) (*durable.SubmissionRecord, error)
- func (storage *StoreStorage) SubmissionByRequest(ctx context.Context, conversationID durable.ConversationId, requestID string) (*durable.SubmissionRecord, error)
- func (storage *StoreStorage) Task(ctx context.Context, id durable.TaskId) (*storedTask, error)
- func (storage *StoreStorage) VisibleEntry(ctx context.Context, conversationID durable.ConversationId, id durable.EntryId) (*durable.EntryAt, error)
- type TableQueries
- func (queries *TableQueries) ByID(executor interface{ ... }, id int64) (*RecordRow, error)
- func (queries *TableQueries) First(executor interface{ ... }, conditions []Condition, order chordstore.Order) (*RecordRow, error)
- func (queries *TableQueries) Select(executor interface{ ... }, conditions []Condition, order chordstore.Order, ...) ([]RecordRow, error)
Constants ¶
This section is empty.
Variables ¶
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.
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.
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.
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.
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 `:`).
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.
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 ¶
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 ¶
func HistoryOf(scope durable.DocumentRecordScope, history durable.DocumentHistory) chordstore.DocumentHistory
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.
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 ¶
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 ¶
func (storage *StoreStorage) Conversation(ctx context.Context, id durable.ConversationId) (*durable.ConversationRecord, error)
Conversation looks up one conversation by exact id; nil when absent.
func (*StoreStorage) Document ¶
func (storage *StoreStorage) Document(ctx context.Context, id durable.DocumentId, at durable.DocumentPoint) (*durable.StoredDocument, error)
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 ¶
func (storage *StoreStorage) FindDocument(ctx context.Context, address durable.DocumentAddress, at durable.DocumentPoint) (*durable.DocumentRecord, error)
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) 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.