Documentation
¶
Overview ¶
Package codemode hosts the isolated QuickJS feasibility runtime for Code Mode.
The runtime deliberately installs no module loader or ambient filesystem, network, process, environment, or WASI capability. Its only host boundary is tools.invoke, which returns a Promise and runs the Go host outside the VM.
This spike pins modernc.org/quickjs v0.24.2 (Git revision 3282d3c5cb5c16ddd5d78e33441ee399a3cf3c62), embedding upstream QuickJS 2026-06-04. The binding is BSD-3-Clause and its embedded QuickJS is MIT. Any upgrade must re-run this package's no-CGO, race, interrupt, teardown, and release-target build acceptance checks.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrSourceTooLarge reports source that exceeds Limits.SourceBytes. ErrSourceTooLarge = errors.New("code source exceeds limit") // ErrResultTooLarge reports serialized JavaScript output that exceeds Limits.ResultBytes. ErrResultTooLarge = errors.New("code result exceeds limit") // ErrPayloadTooLarge reports a child invocation payload or completion that // exceeds Limits.PayloadBytes. ErrPayloadTooLarge = errors.New("code payload exceeds limit") // ErrInvocationLimit reports a script that attempts more child calls than // Limits.MaxCalls permits. ErrInvocationLimit = errors.New("code invocation count exceeds limit") // ErrCancelled reports cancellation before the script completed. ErrCancelled = errors.New("code execution cancelled") // ErrTimedOut reports expiry of the effective wall-clock limit. ErrTimedOut = errors.New("code execution timed out") )
Functions ¶
This section is empty.
Types ¶
type CatalogEntry ¶
CatalogEntry is copied into one Executor before Run starts. Discovery reads this execution-local data only, so it cannot block the VM owner on a host callback or observe a catalog that changes during a turn.
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor creates one QuickJS VM per Run. It is safe for concurrent Run calls when its Host is safe for concurrent Invoke calls.
func NewExecutor ¶
func NewExecutor(host Host, limits Limits, catalog ...CatalogEntry) (*Executor, error)
NewExecutor constructs the concrete QuickJS executor. There is deliberately no engine interface: this phase validates exactly one runtime.
type Host ¶
type Host interface {
Invoke(ctx context.Context, invocation Invocation) (json.RawMessage, error)
}
Host executes a child invocation outside the VM. It must honor ctx cancellation so Executor can join every child before the owner closes its VM.
type HostFunc ¶
type HostFunc func(context.Context, Invocation) (json.RawMessage, error)
HostFunc adapts a function to Host.
func (HostFunc) Invoke ¶
func (f HostFunc) Invoke(ctx context.Context, invocation Invocation) (json.RawMessage, error)
Invoke implements Host.
type Invocation ¶
type Invocation struct {
ID uint64
Name string
Arguments json.RawMessage
}
Invocation is a pure-Go request emitted by tools.invoke. Arguments contain JSON, never a QuickJS Value, so hosts cannot retain VM-owned memory.
type InvocationError ¶
type InvocationError struct {
Value json.RawMessage
Err error
}
InvocationError rejects tools.invoke with JSON rather than a string. It is used by bridges that need a caught child failure to retain structured data.
func (*InvocationError) Error ¶
func (e *InvocationError) Error() string
type LimitError ¶
Limits bounds a single isolated JavaScript execution. Zero values use the Phase 1 fixed defaults; they are intentionally not operator configuration. LimitError carries safe repair metadata for a fixed Code Mode ceiling. Err remains one of the exported sentinel errors so errors.Is callers keep their existing classification behavior.
func (*LimitError) Error ¶
func (e *LimitError) Error() string
func (*LimitError) Unwrap ¶
func (e *LimitError) Unwrap() error
type Result ¶
type Result struct {
JSON json.RawMessage
}
Result is the JSON-safe JavaScript value produced by the script.
Source Files