abi

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 5 Imported by: 0

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

View Source
const (
	OrderNotice uint8 = iota
	OrderEffect
)

Region of an OrderRef.

View Source
const (
	ModelBytesHead uint8 = iota
	ModelBytesChunk
	ModelBytesEnd
	ModelBytesError
)

Phase values of a model_bytes event (ABI section 5).

View Source
const (
	ToolProgressOutput uint8 = iota
	ToolProgressDetails
	ToolProgressDiagnostic
)

Kind kinds of a tool_progress event (ABI section 5).

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

View Source
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")
)
View Source
const ChunkSize = 64 << 10

ChunkSize is the size of the blocks Chunks starts once a payload outgrows its first block.

View Source
const ID = "1b078df222ac3e4af422e2649b282307deb5a18436305d7686f19fcfc47501c0"

ID is abi_id: the hex sha256 of the canonical rendering of the ABI 1 tables in package spec.

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

func AppendAnswer(dst []byte, cols uint8, rows [][]Value) []byte

AppendAnswer appends the answer of the pig.read import: u32 nRows, u8 nCols, value{nRows*nCols}.

func AppendHops

func AppendHops(dst []byte, h Hops) []byte

AppendHops appends the wire form of a hops payload: u32 n, u32 at, then the commits, each as in a step.

func AppendHopsChunks

func AppendHopsChunks(c *Chunks, h Hops)

AppendHopsChunks appends the wire form of h to c, as AppendHops does, a statement at a time.

func AppendReadRequest

func AppendReadRequest(dst []byte, sql uint16, params []Value) []byte

AppendReadRequest appends the request of the pig.read import (ABI section 4.2): u16 sqlId, u8 nParams, value*.

func AppendRows

func AppendRows(dst []byte, answers []ReadRows) []byte

AppendRows appends the payload of a rows event (ABI section 4.5).

func AppendStep

func AppendStep(dst []byte, s *Step) []byte

AppendStep appends the wire form of s (ABI section 4.4).

func AppendValue

func AppendValue(dst []byte, v Value) []byte

AppendValue appends the wire form of v.

func DecodeAnswer

func DecodeAnswer(b []byte) ([][]Value, error)

DecodeAnswer parses a pig.read answer. Text and blob values are copies, as DecodeRows makes them: the binding reuses b.

func ErrorJSON

func ErrorJSON(name, message string) []byte

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

func F64Payload(v float64) []byte

F64Payload encodes a payload that is one f64 (liveness).

func HopsSize

func HopsSize(h Hops) int

HopsSize is the length of AppendHops' wire form of h.

func SQLTable

func SQLTable(statements []string) []byte

SQLTable encodes the sql_table export: u16 n, then n x (u32 len, UTF-8).

func StepSize

func StepSize(s *Step) int

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

func StepSizeInline(s *Step, big int) int

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

func U32Payload(v uint32) []byte

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

func (b *Builder) Cancel(effectID uint32)

Cancel aborts the signal of a running effect.

func (*Builder) ClearTimer

func (b *Builder) ClearTimer(id uint32)

ClearTimer cancels a timer armed by Timer.

func (*Builder) Commit

func (b *Builder) Commit(seq int64, stmts []Stmt)

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

func (b *Builder) DetachCommit() Commit

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

func (b *Builder) Fatal(errJSON []byte)

Fatal makes the step fatal: the host discards the handle (ABI section 4.6).

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

func (b *Builder) Read(sql uint16, params []Value) uint32

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

func (b *Builder) Reject(errJSON []byte)

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

func (b *Builder) Step() *Step

Step returns the step built since Reset. It is valid until the next Reset.

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

func (c *Chunks) Append(item []byte)

Append appends item to the payload, in the last block when it fits (see Tail).

func (Chunks) Len

func (c Chunks) Len() int

Len is the payload's length.

func (*Chunks) Set

func (c *Chunks) Set(b []byte)

Set stores b, the block Tail returned with an item appended, as the last block.

func (*Chunks) Tail

func (c *Chunks) Tail(n int) []byte

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

func (*Effect) Data

func (e *Effect) Data() []byte

Data returns the payload in one slice: Payload, or a copy of the Chunks' concatenation.

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
)

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

func DecodeEvent(kind EventKind, now float64, wire []byte) (Event, error)

DecodeEvent is the inverse of Event.Wire: it reads the payload a host wrote into in_reserve. Payload aliases wire.

func (Event) Wire

func (ev Event) Wire() []byte

Wire returns the payload bytes of ev that a host writes into in_reserve.

type EventKind

type EventKind uint8

EventKind is the kind of an event a host sends with step (ABI section 5).

const (
	EventOpen EventKind = iota + 1
	EventRows
	EventSubmit
	EventModelEvent
	EventModelBytes
	EventToolProgress
	EventToolDone
	EventHookDone
	EventPhaseDone
	EventTx
	EventTimer
	EventAbort
	EventRegistry
	EventAPI
	EventClose
	EventInspect
	EventResume
	EventHopped
	EventSeal
)

Event kinds.

type Hops

type Hops struct {
	N, At   uint32
	Commits []Commit
}

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

func DecodeHops(b []byte) (Hops, error)

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.

func (*Notice) Data

func (n *Notice) Data() []byte

Data returns the payload in one slice: Payload, or a copy of the Chunks' concatenation.

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
)

Notice kinds.

type OrderRef

type OrderRef struct {
	Region uint8
	Index  uint16
}

OrderRef names one notice (OrderNotice) or effect (OrderEffect) of a step by its index in that list.

type Part

type Part struct {
	Off, End int
	Ext      []byte
}

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

func AppendStepParts(dst []byte, s *Step, big int, parts []Part) ([]byte, []Part)

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

func NewPayload

func NewPayload(b []byte) *Payload

NewPayload starts reading b.

func (*Payload) Err

func (p *Payload) Err() error

Err reports a truncated payload.

func (*Payload) F64

func (p *Payload) F64() float64

F64 reads a little-endian f64.

func (*Payload) Rest

func (p *Payload) Rest() []byte

Rest returns the unread bytes.

func (*Payload) U8

func (p *Payload) U8() uint8

U8 reads one byte.

func (*Payload) U32

func (p *Payload) U32() uint32

U32 reads a little-endian u32.

type RangeLoader

type RangeLoader func(conv, head, tail uint32) ([]byte, error)

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 Read

type Read struct {
	ID     uint32
	SQL    uint16
	Params []Value
}

Read asks the host to run one query and answer it in a rows event.

type ReadRows

type ReadRows struct {
	ID   uint32
	Cols uint8
	Rows [][]Value // each row has Cols values
}

ReadRows answers one read.

func DecodeRows

func DecodeRows(b []byte) ([]ReadRows, error)

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 NewRecipe

func NewRecipe(buf []byte) *Recipe

NewRecipe starts a recipe in buf's storage (buf is reset).

func (*Recipe) Bytes

func (r *Recipe) Bytes() []byte

Bytes finishes the recipe and returns it.

func (*Recipe) Range

func (r *Recipe) Range(conv, head, tail int64)

Range appends a range segment: the model messages of conversation conv's context cut off at entry tail under head marker head (0: none).

func (*Recipe) SetText

func (r *Recipe) SetText(b []byte)

SetText stores the buffer Text returned after the caller appended to it.

func (*Recipe) Text

func (r *Recipe) Text() []byte

Text returns the buffer to append the next text to; the caller passes the grown buffer back to SetText.

type Status

type Status uint8

Status is the outcome of a step (ABI section 4.4).

const (
	StatusOK Status = iota
	StatusRejected
	StatusFatal
)

Statuses.

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

func DecodeStep(b []byte) (*Step, error)

DecodeStep parses the wire form of a step. Slices in the result alias b.

type Stmt

type Stmt struct {
	SQL    uint16
	Params []Value
}

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 Blob

func Blob(v []byte) Value

func DecodeReadRequest

func DecodeReadRequest(b []byte) (uint16, []Value, error)

DecodeReadRequest parses a pig.read request.

func Float

func Float(v float64) Value

func Int

func Int(v int64) Value

func Null

func Null() Value

Null, Int, Float, Text and Blob build values.

func Text

func Text(v string) Value

func TextBytes

func TextBytes(v []byte) Value

func (Value) Equal

func (v Value) Equal(w Value) bool

func (Value) Number

func (v Value) Number() float64

Number returns an integer or float value as a float64. A JavaScript host cannot tell an integral REAL from an INTEGER, so a core must read numeric columns through Number, never by tag.

func (Value) String

func (v Value) String() string

type ValueKind

type ValueKind uint8

ValueKind is the tag of a bound or returned value (ABI section 4.3).

const (
	ValueNull ValueKind = iota
	ValueInt
	ValueFloat
	ValueText
	ValueBlob
)

Value tags.

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.

Jump to

Keyboard shortcuts

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