Documentation
¶
Overview ¶
Package abi is the Durable core host ABI 1 (docs/plan/durable-core/ABI.md): the event, step and value types, their wire codecs, the step builder every core package emits into, and ID, the abi_id every build exports.
The normative tables live in package spec, which computes ID; spec's test fails when ID here is stale (regenerate with go generate ./durable/core/abi). This package is part of the core: no reflection, no encoding/json, no fmt, no package-level mutable state.
Index ¶
- Constants
- func AppendAnswer(dst []byte, cols uint8, rows [][]Value) []byte
- func AppendHops(dst []byte, h Hops) []byte
- func AppendHopsChunks(c *Chunks, h Hops)
- func AppendReadRequest(dst []byte, sql uint16, params []Value) []byte
- func AppendRows(dst []byte, answers []ReadRows) []byte
- func AppendStep(dst []byte, s *Step) []byte
- func AppendValue(dst []byte, v Value) []byte
- func ConsumeHopsChunks(c *Chunks, h Hops)
- func DecodeAnswer(b []byte) ([][]Value, error)
- func ErrorJSON(name, message string) []byte
- func Expand(recipe []byte, rng RangeLoader) ([]byte, error)
- func F64Payload(v float64) []byte
- func HopsSize(h Hops) int
- func SQLTable(statements []string) []byte
- func StepSize(s *Step) int
- func StepSizeInline(s *Step, big int) int
- func TimerEffect(timerID uint32, at float64, class TimerClass) []byte
- func U32Payload(v uint32) []byte
- type Builder
- func (b *Builder) Cancel(effectID uint32)
- func (b *Builder) ClearTimer(id uint32)
- func (b *Builder) Commit(seq int64, stmts []Stmt)
- func (b *Builder) DetachCommit() Commit
- func (b *Builder) Effect(kind EffectKind, payload []byte) uint32
- func (b *Builder) EffectBare(kind EffectKind, payload []byte) uint32
- func (b *Builder) EffectChunks(kind EffectKind, c Chunks) uint32
- func (b *Builder) EffectChunksBare(kind EffectKind, c Chunks) uint32
- func (b *Builder) Fatal(errJSON []byte)
- func (b *Builder) JoinLast()
- func (b *Builder) Notice(kind NoticeKind, payload []byte)
- func (b *Builder) NoticeChunks(kind NoticeKind, c Chunks)
- func (b *Builder) Read(sql uint16, params []Value) uint32
- func (b *Builder) Reject(errJSON []byte)
- func (b *Builder) Reset()
- func (b *Builder) Step() *Step
- func (b *Builder) Timer(at float64, class TimerClass) uint32
- type Chunks
- type Commit
- type Effect
- type EffectKind
- type Event
- type EventKind
- type Hops
- type Notice
- type NoticeKind
- type OrderRef
- type Part
- type Payload
- type RangeLoader
- type Read
- type ReadRows
- type Recipe
- type Status
- type Step
- type Stmt
- type TimerClass
- type Value
- type ValueKind
Constants ¶
const ( OrderNotice uint8 = iota OrderEffect )
Region of an OrderRef.
const ( ModelBytesHead uint8 = iota ModelBytesChunk ModelBytesEnd ModelBytesError )
Phase values of a model_bytes event (ABI section 5).
const ( ToolProgressOutput uint8 = iota ToolProgressDetails ToolProgressDiagnostic )
Kind kinds of a tool_progress event (ABI section 5).
const ( OutcomeResult uint8 = iota OutcomeThrown // OutcomeUnrecordable is a tool_done whose result the host could not hand over as strict JSON: the call faults. OutcomeUnrecordable )
Outcomes of tool_done, hook_done and phase_done events.
const ( // ErrRecipe reports a recipe that is truncated, has an unknown segment kind or trailing bytes, or a range segment // where the host cannot derive one. ErrRecipe = recipeError("abi: malformed recipe") // ErrRecipeRecord reports a range the host's storage does not agree with: a head marker, tail or conversation it lacks. ErrRecipeRecord = recipeError("abi: recipe names a context storage does not have") )
const ChunkSize = 64 << 10
ChunkSize is the size of the blocks Chunks starts once a payload outgrows its first block.
const ID = "2014bb9829cfda2cef5bb6c41910f75af7945d98a09a902bed6f6c83ffa72c94"
ID is abi_id: the hex sha256 of the canonical rendering of the ABI 1 tables in package spec.
const MaxEventPayload = 1 << 30
MaxEventPayload is the largest event payload a host sends and the native core server reads: a corrupt length must not allocate before the read fails.
const MaxRecipeID = math.MaxUint32
MaxRecipeID is the largest conversation or entry id a range can name; a request whose ids exceed it carries its messages as text.
Variables ¶
This section is empty.
Functions ¶
func AppendAnswer ¶
AppendAnswer appends the answer of the pig.read import: u32 nRows, u8 nCols, value{nRows*nCols}.
func AppendHops ¶
AppendHops appends the wire form of a hops payload: u32 n, u32 at, then the commits, each as in a step.
func AppendHopsChunks ¶
AppendHopsChunks appends the wire form of h to c, as AppendHops does, a statement at a time.
func AppendReadRequest ¶
AppendReadRequest appends the request of the pig.read import (ABI section 4.2): u16 sqlId, u8 nParams, value*.
func AppendRows ¶
AppendRows appends the payload of a rows event (ABI section 4.5).
func AppendStep ¶
AppendStep appends the wire form of s (ABI section 4.4).
func AppendValue ¶
AppendValue appends the wire form of v.
func ConsumeHopsChunks ¶
ConsumeHopsChunks is AppendHopsChunks for a caller that is done with h: each statement of h.Commits loses its parameters once it is in the payload, so the collector can take them while the rest of a 20,000-task commit is still being encoded (they were the third copy of each record's data, with its text and its payload bytes).
func DecodeAnswer ¶
DecodeAnswer parses a pig.read answer. Text and blob values are copies, as DecodeRows makes them: the binding reuses b.
func ErrorJSON ¶
ErrorJSON renders Pi's {"name","message"} error payload. name must be an identifier; message is escaped minimally (quotes, backslashes and control characters), as JSON.stringify does.
func Expand ¶
func Expand(recipe []byte, rng RangeLoader) ([]byte, error)
Expand returns the text the recipe stands for. rng derives a range segment; it may be nil for a recipe without one.
func F64Payload ¶
F64Payload encodes a payload that is one f64 (liveness).
func StepSize ¶
StepSize is the length of AppendStep's wire form of s, so a binding sizes its output buffer once for a step that carries a large payload.
func StepSizeInline ¶
StepSizeInline is the length AppendStepParts appends to dst for s and big: StepSize less the payloads it does not copy.
func TimerEffect ¶
func TimerEffect(timerID uint32, at float64, class TimerClass) []byte
TimerEffect encodes the payload of a timer effect.
func U32Payload ¶
U32Payload encodes a payload that is one u32 (timer_clear, cancel).
Types ¶
type Builder ¶
type Builder struct {
// Origin, when set, reports the host async context of the code that is running (ABI section 5.4): the builder stamps
// every notice and effect it is given with it. A core without it stamps 0.
Origin func() uint32
// contains filtered or unexported fields
}
Builder accumulates the step of one event. Every core package that commits, reads, publishes or starts an effect writes into the one Builder of its session; nothing else produces step content. A Builder lives as long as its session: Reset clears the step between events and keeps the ID counters, so effect, read and timer IDs are unique for the life of the handle (ABI section 3 invariant 6).
Ordering rules the builder enforces for its callers (ABI section 3):
- commits keep the order of Commit calls;
- a step with reads carries no effects, and its commits precede its reads (Read, Effect and Commit panic otherwise; that is a core bug); the host applies the commits before it runs the reads;
- notices and effects keep call order and are applied by the host after every commit of the step.
func NewBuilder ¶
func NewBuilder() *Builder
NewBuilder returns a builder whose first effect, read and timer IDs are 1.
func (*Builder) ClearTimer ¶
ClearTimer cancels a timer armed by Timer.
func (*Builder) Commit ¶
Commit appends one SQL transaction. seq is the next_seq value it consumes, or -1 for a sidecar-only commit. The statements are owned by the builder from here on.
func (*Builder) DetachCommit ¶
DetachCommit removes and returns the step's last commit (a core that holds a line job's statements until Pi's COMMIT hop). Its slot is cleared, as Reset clears the others: the holder decides how long the statements live.
func (*Builder) Effect ¶
func (b *Builder) Effect(kind EffectKind, payload []byte) uint32
Effect starts an effect after the step's commits and returns its ID.
func (*Builder) EffectBare ¶
func (b *Builder) EffectBare(kind EffectKind, payload []byte) uint32
EffectBare is Effect for an effect the host starts in no context: a hops chain runs no host code, and the core keeps the origin of the work parked on it.
func (*Builder) EffectChunks ¶
func (b *Builder) EffectChunks(kind EffectKind, c Chunks) uint32
EffectChunks starts an effect with the payload built in c, in one slice when it is one block, and returns its ID.
func (*Builder) EffectChunksBare ¶
func (b *Builder) EffectChunksBare(kind EffectKind, c Chunks) uint32
EffectChunksBare is EffectChunks for an effect the host starts in no context (EffectBare).
func (*Builder) JoinLast ¶
func (b *Builder) JoinLast()
JoinLast marks the step's last commit as belonging to the same Storage call as the commit before it (ABI section 5.5).
func (*Builder) Notice ¶
func (b *Builder) Notice(kind NoticeKind, payload []byte)
Notice publishes payload after the step's commits.
func (*Builder) NoticeChunks ¶
func (b *Builder) NoticeChunks(kind NoticeKind, c Chunks)
NoticeChunks publishes the payload built in c after the step's commits: in one slice when it is one block.
func (*Builder) Read ¶
Read asks the host to run statement sql with params and returns the read ID its rows event answers. The host applies the step's commits before it runs the reads (ABI section 3, invariant 3), so a read sees them.
func (*Builder) Reject ¶
Reject makes the step a rejected step: the session's state must be unchanged, and every commit, read, notice and effect added so far is dropped. errJSON is Pi's error as {"name","message"}.
func (*Builder) Reset ¶
func (b *Builder) Reset()
Reset starts the step of the next event. The step's slices keep their arrays for the next event, and their elements are cleared first: an element past the new length is still scanned by the collector, so a commit's statements, a read's parameters or a notice's payload would stay alive until a later step happened to overwrite its slot. The commit of a 20,000-task transaction held about 22 MB that way on the TinyGo core, past its 96 MiB ceiling.
func (*Builder) Timer ¶
func (b *Builder) Timer(at float64, class TimerClass) uint32
Timer arms a timer effect at the absolute Harness time at and returns the timer ID a timer event carries back. durable timers are re-derived from checkpoints on reopen and keep the object alarm; volatile ones may be lost (ADR D8); background ones only free memory and may be declined by the host.
type Chunks ¶
type Chunks [][]byte
Chunks is a payload built in blocks of at most ChunkSize bytes, or of one item when that is larger; each block grows by append. A notice or effect of megabytes (a 20,000-task commit's hops payload is 7 MB, its published notice 1.2 MB) then needs no block of its size: the TinyGo core's collector does not move objects, and late in a long run its heap has room for such a payload only in smaller free ranges. The payload is the blocks' concatenation; the step encoder hands each block to the host as a part of its own.
func (*Chunks) Append ¶
Append appends item to the payload, in the last block when it fits (see Tail).
func (*Chunks) Set ¶
Set stores b, the block Tail returned with an item appended, as the last block.
func (*Chunks) Tail ¶
Tail returns the block the caller appends its next item of n bytes to, and the caller stores the result back with Set: the last block while the item keeps it within ChunkSize, else a new, empty block with room for len(tailRoom) bytes. The blocks grow by append, so Chunks has no allocation site of its own (budget/allocs.json): the room is appended from tailRoom, not made.
type Commit ¶
type Commit struct {
Seq int64
// Joined: the commit belongs to the same Storage call as the commit before it in the step, so the host applies the run of joined
// commits in one transaction (ABI section 5.5).
Joined bool
Stmts []Stmt
}
Commit is one SQL transaction. Seq is the next_seq value it consumes, or -1 for a sidecar-only commit.
type Effect ¶
type Effect struct {
ID uint32
Kind EffectKind
// Origin is the host async context the effect starts in (ABI section 5.4). 0: none; a hops effect always has 0.
Origin uint32
Payload []byte
// Chunks, when not nil, is the payload in blocks (see Chunks), and Payload is nil. A decoded step never has it.
Chunks Chunks
}
Effect is work the host starts after the step's commits are applied.
type EffectKind ¶
type EffectKind uint8
EffectKind is the kind of an effect a step asks the host to start (ABI section 6).
const ( EffectTimer EffectKind = iota + 1 EffectTimerClear EffectModelContext EffectModelHTTP EffectCancel EffectTool EffectHook EffectPhase EffectEnv EffectLiveness EffectSection EffectDeferred EffectCallback EffectHops EffectMacrotask )
Effect kinds.
type Event ¶
type Event struct {
Kind EventKind
Now float64 // the Harness clock; the core never reads another clock
// Origin names the host's async context for the code this event starts (ABI section 4.1, step): the host's tag for the
// AsyncLocalStorage snapshot it took when the caller made the call, 0 for none. The core reads it for the events a host
// caller makes (open, submit, abort, registry, api, inspect, resume, seal, close, tx, timer) and ignores it for the
// completions of its own effects and for hopped, which continue the origin of the effect or chain they answer.
Origin uint32
ID uint32 // effect, tx, timer or request ID, by kind
Phase uint8 // model_bytes phase, tool_progress kind, tool_done/hook_done/phase_done outcome
Skipped uint32 // tool_progress
WaitID uint32 // tool_progress kind 1: the progress_ack to answer
Payload []byte // JSON, bytes, or empty
Rows []ReadRows
}
Event is one input of a session (ABI sections 5 and 11). Payload and Rows alias the host's input buffer and are valid only during the Step call that receives them; a core package that keeps any of it copies it first.
func DecodeEvent ¶
DecodeEvent is the inverse of Event.Wire: it reads the payload a host wrote into in_reserve. Payload aliases wire.
type EventKind ¶
type EventKind uint8
EventKind is the kind of an event a host sends with step (ABI section 5).
type Hops ¶
Hops is the payload of a hops effect (ABI section 5.3): the host runs N microtask hops and then sends hopped; after hop At (0 < At < N) it applies Commits, in order, as the core would have had it emit them in the step of a hopped event at that hop. At is 0 and Commits empty for a chain that carries none.
func DecodeHops ¶
DecodeHops parses a hops payload. Slices in the result alias b.
type Notice ¶
type Notice struct {
Kind NoticeKind
// Origin is the host async context the notice was published from (ABI section 5.4): the host runs its listeners in it. 0: none.
Origin uint32
Payload []byte
// Chunks, when not nil, is the payload in blocks (see Chunks), and Payload is nil. A decoded step never has it.
Chunks Chunks
}
Notice is published after the step's commits are applied.
type NoticeKind ¶
type NoticeKind uint8
NoticeKind is the kind of a notice a step publishes (ABI section 7).
const ( NoticePublished NoticeKind = iota + 1 NoticeAPIResult NoticeTxResult NoticeReport NoticeSidecar NoticeProgressAck NoticeDocCache NoticeIndexSizes NoticeWake NoticeOriginFree NoticeTelemetry )
Notice kinds.
type OrderRef ¶
OrderRef names one notice (OrderNotice) or effect (OrderEffect) of a step by its index in that list.
type Part ¶
Part is one piece of a step's wire form: Ext when it is not nil, else bytes [Off, End) of the buffer AppendStepParts appended to.
func AppendStepParts ¶
AppendStepParts appends the wire form of s as AppendStep does, except that the payload of a notice or effect of at least big bytes, and each block of a payload in Chunks, is not copied: it is a part of its own, between the parts of dst around it. The concatenation of the parts is AppendStep's wire form, so a binding hands a model request (the whole transcript, megabytes) to its host from where the core built it. StepSizeInline(s, big) is the length appended to dst.
type Payload ¶
type Payload struct {
// contains filtered or unexported fields
}
Payload is a little-endian reader for the binary event payloads (effect IDs, timer IDs, phases).
type RangeLoader ¶
RangeLoader returns the comma-separated JSON text of the model messages of conversation conv's committed context cut off at entry tail under head marker entry head (0: none).
type ReadRows ¶
ReadRows answers one read.
func DecodeRows ¶
DecodeRows parses the payload of a rows event. Text and blob values are copies in chunks of a few KiB, not slices of b: the host reuses b for the next event, and a record the core keeps would otherwise keep a pointer into a buffer of hundreds of KiB, which under TinyGo costs the whole buffer on every collection (the collector finds the start of the object a pointer lands in by walking its blocks).
type Recipe ¶
type Recipe struct {
// contains filtered or unexported fields
}
Recipe builds a recipe. Adjacent text segments merge into one.
func (*Recipe) Range ¶
Range appends a range segment: the model messages of conversation conv's context cut off at entry tail under head marker head (0: none).
type Step ¶
type Step struct {
Status Status
Commits []Commit
Reads []Read
Notices []Notice
Effects []Effect
// Order lists the notices and effects in Pi's synchronous order (ABI section 5.3). Empty means all notices, then all effects.
Order []OrderRef
Err []byte // JSON, only when Status != StatusOK
}
Step is the result of one event.
func DecodeStep ¶
DecodeStep parses the wire form of a step. Slices in the result alias b.
type Stmt ¶
Stmt is one statement of a commit: an index into the core's SQL table and its parameters.
type TimerClass ¶
type TimerClass uint8
TimerClass is the u8 of a timer effect: what the timer is for, which decides how a host arms it.
const ( // TimerVolatile paces work already held by a stream or tool (a throttle window): a process timer; it may be lost. TimerVolatile TimerClass = 0 // TimerDurable resumes a sleeping task: re-derived from its checkpoint on reopen, and kept by the object alarm of a host that // wakes its process itself. TimerDurable TimerClass = 1 // TimerBackground only frees memory (an idle context or document expiring): a host may decline it, as one that cannot // keep a pending timer without keeping its process alive does; the core frees that memory at later commits instead. TimerBackground TimerClass = 2 )
Timer classes.
type Value ¶
type Value struct {
Int int64
Float float64
Bytes []byte // text (UTF-8) or blob; read-only, so values may share one array
Kind ValueKind
}
Value is a bound parameter or a returned column (ABI section 4.3). Kind comes last, so the value is 32 bytes on wasm32 (40 with Kind first); a 20,000-task commit binds seven per task.
func DecodeReadRequest ¶
DecodeReadRequest parses a pig.read request.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package abitest reads ABI event scripts and runs them through a native core.
|
Package abitest reads ABI event scripts and runs them through a native core. |
|
Package payload holds the JSON shapes of ABI 1 event and effect payloads as hosts send and read them (ABI sections 5-7).
|
Package payload holds the JSON shapes of ABI 1 event and effect payloads as hosts send and read them (ABI sections 5-7). |
|
Package spec holds the normative tables of ABI 1 (docs/plan/durable-core/ABI.md sections 4-8) and computes abi_id, the sha256 of their canonical rendering.
|
Package spec holds the normative tables of ABI 1 (docs/plan/durable-core/ABI.md sections 4-8) and computes abi_id, the sha256 of their canonical rendering. |
|
cmd/abigen
command
Command abigen writes durable/core/abi/id.go (the abi_id constant the core exports) and durable/core/abi/abi.json (the tables and abi_id the JavaScript hosts read) from the tables in package spec.
|
Command abigen writes durable/core/abi/id.go (the abi_id constant the core exports) and durable/core/abi/abi.json (the tables and abi_id the JavaScript hosts read) from the tables in package spec. |