sqlhost

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 16 Imported by: 0

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:

  1. The core is never called re-entrantly: every event is processed to completion, including its read rounds, before the next one.
  2. 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.
  3. 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.
  4. Notices are delivered after the step's commits are applied.
  5. Effects start only after the step's commits are applied.
  6. Effect IDs are unique for the life of the handle. Discarding the handle cancels its effects and drops their late completions.

Index

Constants

View Source
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

View Source
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.

func (*Call) Expect

func (c *Call) Expect(test func(abi.Notice) bool) (*Expectation, error)

Expect registers a wait for a notice before the effect posts the event that provokes it. See Host.Expect.

func (*Call) Post

func (c *Call) Post(ev abi.Event)

Post delivers an event the effect produced (model_event, tool_progress, tool_done, hook_done, ...). Now is stamped when the owner delivers it. A completion that arrives after the handle was discarded is dropped.

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

func OpenDB(ctx context.Context, path string) (*DB, error)

OpenDB opens path (or ":memory:") as one connection with WAL journaling, the setting the node:sqlite host uses.

func (*DB) All

func (d *DB) All(ctx context.Context, text string, params []abi.Value) ([][]abi.Value, int, error)

All runs one query and returns its rows and column count. TEXT columns come back as text, BLOB columns as blobs.

func (*DB) Begin

func (d *DB) Begin(ctx context.Context) error

Begin starts an immediate transaction: the core's single-writer guard names the one writer, so the lock is taken up front.

func (*DB) Close

func (d *DB) Close() error

Close releases the prepared statements and the connection.

func (*DB) Commit

func (d *DB) Commit(ctx context.Context) error

Commit ends the transaction.

func (*DB) Rollback

func (d *DB) Rollback(ctx context.Context) error

Rollback abandons the transaction. A rollback that fails leaves the outcome unknown and the caller treats it as fatal.

func (*DB) Run

func (d *DB) Run(ctx context.Context, text string, params []abi.Value) (int64, error)

Run executes one write statement and returns the rows it changed.

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.

func (*Expectation) Wait

func (e *Expectation) Wait(ctx context.Context) (abi.Notice, error)

Wait resolves with the notice, or fails when ctx ends or the handle is discarded first. It releases the registration.

type FatalError

type FatalError struct {
	Message string
	Cause   error
}

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

type Handler func(ctx context.Context, call *Call) error

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.

func New

func New(opts Options) *Host

New starts the owner goroutine. Send the open event next.

func (*Host) Close

func (h *Host) Close(ctx context.Context) error

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

func (h *Host) ContextView(ctx context.Context, conv, tail int64) ([]byte, error)

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

func (h *Host) Counters() Counters

Counters returns a snapshot.

func (*Host) Err

func (h *Host) Err() error

Err returns the reason the handle was discarded, or nil.

func (*Host) Expect

func (h *Host) Expect(test func(abi.Notice) bool) (*Expectation, error)

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

func (h *Host) Post(ev abi.Event)

Post queues an event without waiting. It never blocks. A rejected step goes to OnRejected.

func (*Host) Query

func (h *Host) Query(ctx context.Context, text string, params ...abi.Value) ([][]abi.Value, error)

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

func (h *Host) Send(ctx context.Context, ev abi.Event) error

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

func (h *Host) WaitEffects(ctx context.Context) error

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

func (h *Host) WaitNotice(ctx context.Context, test func(abi.Notice) bool) (abi.Notice, error)

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

type RejectedError struct {
	Name    string
	Message string
	Raw     []byte
}

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

type Stepper

type Stepper interface {
	Step(ev abi.Event) *abi.Step
}

Stepper is the native binding of a core (ABI section 11): core.Session and the probe implement it.

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.

Jump to

Keyboard shortcuts

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