Documentation
¶
Overview ¶
Package sqlhost is the native Go host of the Durable core (docs/plan/durable-core/ABI.md section 11, ADR-0001 D17).
One Host owns one core session and one SQLite connection. A single owner goroutine calls the core's Step, applies each commit of a step in its own transaction, answers read rounds before any other event, delivers notices after the commits, and only then starts effects. Effects run in owned goroutines under a context.Context; their completions return to the owner through an unbounded mailbox, so an effect never blocks the owner and the owner never blocks an effect.
The host holds the ABI host loop invariants of section 3:
- The core is never called re-entrantly: every event is processed to completion, including its read rounds, before the next one.
- Each commit is one transaction. A failed commit, or a durable_metadata update that does not change exactly one row (the single-writer guard), is fatal to the handle.
- A step with reads has no effects. Its commits are applied, in order, before its reads run, and the reads are answered by one rows event before any other event is delivered.
- Notices are delivered after the step's commits are applied.
- Effects start only after the step's commits are applied.
- Effect IDs are unique for the life of the handle. Discarding the handle cancels its effects and drops their late completions.
Index ¶
- Constants
- Variables
- type Call
- type Counters
- type DB
- func (d *DB) All(ctx context.Context, text string, params []abi.Value) ([][]abi.Value, int, error)
- func (d *DB) Begin(ctx context.Context) error
- func (d *DB) Close() error
- func (d *DB) Commit(ctx context.Context) error
- func (d *DB) Rollback(ctx context.Context) error
- func (d *DB) Run(ctx context.Context, text string, params []abi.Value) (int64, error)
- type Expectation
- type FatalError
- type Handler
- type Host
- func (h *Host) Close(ctx context.Context) error
- func (h *Host) ContextView(ctx context.Context, conv, tail int64) ([]byte, error)
- func (h *Host) Counters() Counters
- func (h *Host) Err() error
- func (h *Host) Expect(test func(abi.Notice) bool) (*Expectation, error)
- func (h *Host) ExpectNotice(kind abi.NoticeKind, id uint32, accept func(body []byte) bool) (*Expectation, error)
- func (h *Host) Post(ev abi.Event)
- func (h *Host) Query(ctx context.Context, text string, params ...abi.Value) ([][]abi.Value, error)
- func (h *Host) Send(ctx context.Context, ev abi.Event) error
- func (h *Host) WaitEffects(ctx context.Context) error
- func (h *Host) WaitNotice(ctx context.Context, test func(abi.Notice) bool) (abi.Notice, error)
- type MessageRange
- type Options
- type RejectedError
- type Stepper
Constants ¶
const FatalCommitFailed = "a commit failed"
FatalCommitFailed is the Message of the FatalError a failed commit returns. The store may have taken the commit, so a caller treats the session as poisoned (Pi session.ts #runCommit).
Variables ¶
var ErrClosed = errors.New("sqlhost: the host is closed")
ErrClosed is returned for an event sent after Close.
Functions ¶
This section is empty.
Types ¶
type Call ¶
type Call struct {
ID uint32
Kind abi.EffectKind
Payload []byte // the host's copy
// Range is the committed context a model_context effect names. Its messages are not in Payload (the list there is empty):
// the handler decodes them from Range, and only those whose identity changed since its last call.
Range *MessageRange
// contains filtered or unexported fields
}
Call is one started effect.
type Counters ¶
type Counters struct {
Events int
Steps int
Commits int
Statements int
Reads int
RowsRead int
// ContextReads and ContextRows are the reads the host ran to derive the contexts it holds (range requests and the
// core's context reads) and the rows they returned: they do not cross the core's pig.read, so Reads and RowsRead exclude them.
ContextReads int
ContextRows int
Notices int
Rejected int
// WaiterTests counts the pending waiters notify tested against a notice.
WaiterTests int
Effects map[abi.EffectKind]int
}
Counters are the host's measurements (BAKEOFF M6, M7).
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is one dedicated SQLite connection. Only the owner goroutine of a Host uses it, so it takes no lock. Statements are prepared once per SQL text, the way the core's sql_table is used: a core statement ID is a stable index.
func OpenDB ¶
OpenDB opens path (or ":memory:") as one connection with WAL journaling, the setting the node:sqlite host uses.
func (*DB) All ¶
All runs one query and returns its rows and column count. TEXT columns come back as text, BLOB columns as blobs.
func (*DB) Begin ¶
Begin starts an immediate transaction: the core's single-writer guard names the one writer, so the lock is taken up front.
type Expectation ¶
type Expectation struct {
// contains filtered or unexported fields
}
Expectation is a registered wait for one notice.
func (*Expectation) Cancel ¶
func (e *Expectation) Cancel()
Cancel releases the registration. It is safe after Wait.
type FatalError ¶
FatalError is the reason a host discarded its handle (ABI section 4.6, ADR D16). The next event needs a new Host: a cold open from SQLite loses nothing Pi would keep.
func (*FatalError) Error ¶
func (e *FatalError) Error() string
func (*FatalError) Unwrap ¶
func (e *FatalError) Unwrap() error
Unwrap returns the underlying error.
type Handler ¶
Handler runs one effect. It returns when the effect is complete or its ctx is canceled. Completions travel back through call.Post. A handler that returns an error other than a context cancellation discards the handle: the host does not guess the outcome of work the core is waiting on.
type Host ¶
type Host struct {
// contains filtered or unexported fields
}
Host is one core session and its SQLite connection: the native Go host of one Session, which the SQLite engine drives through the core ABI. Host.Close is Session.close; the rest of the Session's behavior is the core's, not this host's.
Ports packages/durable/src/session/session.ts
func (*Host) Close ¶
Close seals the session: the core receives close and cancels its effects, then the host cancels what remains, waits for the effect goroutines (bounded by ctx), and closes the connection when it owns it.
func (*Host) ContextView ¶
ContextView answers a context read the core names instead of building (ABI section 8.1, `{"$context":{conversationId, tail}}`): the context of conversation conv through entry tail, derived on the host's goroutine from the range store the core's context reads use, rendered as Pi's ContextView.
func (*Host) Expect ¶
Expect registers a wait before the caller sends the event that provokes the notice, so the notice cannot be missed. Wait or Cancel must follow. test runs on the owner goroutine and must not block.
func (*Host) ExpectNotice ¶
func (h *Host) ExpectNotice(kind abi.NoticeKind, id uint32, accept func(body []byte) bool) (*Expectation, error)
ExpectNotice is Expect for a notice of the given kind whose payload starts with the u32 id (api_result, tx_result); accept sees the payload after the id. A notice is tested only against the waiters of its own kind and id, so the cost of a notice does not grow with the number of requests in flight.
func (*Host) Post ¶
Post queues an event without waiting. It never blocks. A rejected step goes to OnRejected.
func (*Host) Query ¶
Query runs a read on the owner's connection, after every event queued before it. It serves Harness reads that need no core state (CONTRACT section 3.10): old history pages, task and submission lookups.
func (*Host) Send ¶
Send delivers one event and returns when the owner has processed it, its read rounds and its commits included. The error is a *RejectedError for a rejected step, a *FatalError when the handle was or is discarded, or ErrClosed. When ctx ends first Send returns the context cause; the queued event still runs, because an event cannot be retracted from a core.
func (*Host) WaitEffects ¶
WaitEffects returns once every effect handler that is running has returned, while the owner keeps delivering events (the completions the handlers post still reach the core). It is the join of Harness.close() before the core closes: a run's end reaches the core, which ends its invocation and answers what joined it.
func (*Host) WaitNotice ¶
WaitNotice resolves with the first notice delivered after the call that satisfies test. It fails when the handle is discarded first. test runs on the owner goroutine and must not block.
type MessageRange ¶
type MessageRange struct {
Conv int64
Lineage uint64
Msgs [][]byte // message i as JSON
Idents []history.MessageIdent // identity of each message; !Stored[i] for a synthesized one
Stored []bool
}
MessageRange is the committed context a model_context effect names, as the host derived it: the model messages as JSON, in order, and what stored bytes each is, so a handler that decoded an earlier range of the conversation decodes only the messages that differ. A stored message's bytes are the history store's record text, shared, not copied: a store never rewrites bytes it handed out, so they stay valid and must not be modified.
Msgs, Idents and Stored are read-only views of arrays the host extends at their end: two ranges with the same non-zero Lineage agree on every index both have, so a handler that kept the earlier one need not compare that prefix.
type Options ¶
type Options struct {
// Core is the session the owner goroutine drives.
Core Stepper
// SQL is the core's sql_table: statement ID to text.
SQL []string
// DB is the connection commits and reads run on. The Host uses it from the owner goroutine only.
DB *DB
// OwnDB closes DB when the Host closes.
OwnDB bool
// Clock returns milliseconds since the epoch. Every event carries it as now (ADR D8). Defaults to the wall clock.
Clock func() float64
// TimerFired, when set, runs as a timer fires, before its event is queued, with the time the timer was armed for. A
// virtual clock (the conformance gate's detenv) moves there: virtual time advances only when a timer is due, so a
// frozen clock would otherwise deliver every timer before its time and the core would re-arm it forever.
TimerFired func(at float64)
// Handlers start effects by kind. Timer, timer_clear, cancel and liveness are the host's own and need none.
Handlers map[abi.EffectKind]Handler
// OnNotice receives each notice on the owner goroutine, after the step's commits are applied. It must not block.
OnNotice func(abi.Notice)
// TimerLead makes a timer fire this much before its deadline. A deterministic clock sets 1ns so that, among timers and
// effect completions due at the same instant, the host's timers run first (the order the reference's seq-ordered virtual
// timers give a timer armed before the completion's own). Zero fires at the deadline.
TimerLead time.Duration
// Settle, when set, is called by the owner after it starts an effect's goroutine, before it takes the next event, and at
// each hop of a hops chain. A deterministic run (a synctest bubble) sets synctest.Wait so that an effect that completes
// without waiting posts its completion before the next effect starts (completions then reach the core in the order the
// effects were issued, as they do from the reference's FIFO of resolved promises), and so that host code a step woke
// posts before the chain's next hop.
Settle func()
// OnCancel receives each cancel effect (ABI effect 5) on the owner goroutine, also for an effect that has already
// settled: the core cancels a settled phase effect to say its invocation has ended. It must not block.
OnCancel func(effect uint32)
// SetTimer, when set, arms every timer effect (HarnessOptions.SetTimer): callback fires once about delayMs from now, and
// the returned function disarms it. background marks a timer that only frees memory, which it may decline by returning
// nil; any other it arms or the host arms with a Go timer. Nil arms Go timers.
SetTimer func(callback func(), delayMs float64, background bool) (disarm func())
// OnLiveness receives the watchdog target (ABI effect 10): a time, or -1 when nothing is live. A native process
// has nothing to wake, so the default ignores it.
OnLiveness func(at float64)
// OnFatal is called once, from the owner goroutine, when the handle is discarded.
OnFatal func(error)
// OnRejected receives a rejected step that no caller waits on: an effect completion the core refused.
OnRejected func(kind abi.EventKind, err *RejectedError)
// Settings, when set, returns the host's current resolved settings as JSON, or nil when they cannot be read now. Pi reads HarnessSettings at each use; the
// core holds the copy open sent, so before each Send but open and close (every API call, not hops or effect
// completions, which keeps the hot path free of it) the owner compares and, when they changed, delivers a registry
// event {"settings": ...} first (host/cf/src/host.ts enqueue).
Settings func() []byte
// OnCommit observes every commit before it applies (trace capture).
OnCommit func(c abi.Commit, sql []string)
// OnCommitted observes every commit after the store applied it, in order. A trace that must hold exactly what the store
// holds writes here: a process killed in this callback has the commit in the store and in the trace.
OnCommitted func(c abi.Commit, sql []string)
}
Options configure a Host.
type RejectedError ¶
RejectedError is a step with status rejected: Pi's error name and message, and no state changed.
func (*RejectedError) Error ¶
func (e *RejectedError) Error() string
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bench
command
Command bench is the native candidate of the Durable conformance gate (durable/contract/impls/native.mjs): the bench scenario (durable/contract/scenarios/bench.mjs) run through the native session on the core, with its statements written as a trace of statements only (contracttest.Writer), which the Node tools replay onto the starting store.
|
Command bench is the native candidate of the Durable conformance gate (durable/contract/impls/native.mjs): the bench scenario (durable/contract/scenarios/bench.mjs) run through the native session on the core, with its statements written as a trace of statements only (contracttest.Writer), which the Node tools replay onto the starting store. |