Documentation
¶
Overview ¶
Package jsexec defines the transport-neutral JavaScript execution contract. Permission isolation and resource limits are described in README.md.
Index ¶
- Constants
- Variables
- func BuildImage(ctx context.Context, tag string) error
- func Main()
- func PrepareDockerImage(ctx context.Context, image string) (string, error)
- func RuntimeFingerprint() string
- func Serve(ctx context.Context, transport io.ReadWriteCloser, config SupervisorOptions) error
- type ArgumentSession
- type Binding
- type Client
- type DockerSession
- type Exception
- type Invoker
- type InvokerFunc
- type Limits
- type Log
- type LogLevel
- type Options
- type Result
- type Session
- type SupervisorOptions
- type User
Constants ¶
const DenoImage = "denoland/deno@sha256:2014dc167ece617ef7e7ba40631ac2234c59e75ce693e7cc2dc2602b3c87859d"
DenoImage pins the registry manifest list for the stock Deno 2.9.6 image. Verified with docker pull and docker image inspect; see README.md.
const MaxArgsBytes = 64 << 10
const PublishedExecutorImage = "ghcr.io/airlockrun/airlock-js-executor@sha256:460592372756ec350e30c3c7701481733b31368d42565eecc709bb9619090cd6"
PublishedExecutorImage is an immutable Airlock release artifact, not an SDK version-derived tag. Its compatibility is tied to the reviewed runtime below.
Variables ¶
var ( ErrBusy = errors.New("jsexec: invocation already executing") ErrClosed = errors.New("jsexec: session closed") )
var ProbeAssets embed.FS
ProbeAssets contains a diagnostic image recipe and the hostile loader probes. These assets are not a production executor or a security boundary.
var RuntimeAssets embed.FS
RuntimeAssets contains the production/test Docker recipe, Deno assets, and dependency-free supervisor sources used by BuildImage.
Functions ¶
func BuildImage ¶
BuildImage builds the shared executor recipe using embedded sources and the caller's installed Go toolchain and Docker CLI. It needs no Airlock release, module dependencies, credentials in the build context, or source checkout. The output is Linux for the calling process's architecture.
func Main ¶
func Main()
Main is the cmd/jsexecutor entrypoint. It accepts no credentials or runtime permission switches. Container policy is the launcher's responsibility.
func PrepareDockerImage ¶ added in v0.8.1
PrepareDockerImage validates or pulls an explicitly selected image. Newly built images carry the full runtime fingerprint. The reviewed public artifact also requires exact protocol/Deno metadata, scripts and a framed smoke call.
func RuntimeFingerprint ¶ added in v0.8.1
func RuntimeFingerprint() string
RuntimeFingerprint covers the trusted, dependency-free Docker supervisor and scripts plus the pinned Deno runtime, independently of SDK semver.
func Serve ¶
func Serve(ctx context.Context, transport io.ReadWriteCloser, config SupervisorOptions) error
Serve owns one Deno subprocess and one attach stream. All subprocess stdio is /dev/null. Only the trusted controller isolate can connect to the local IPC socket; snippet workers receive an explicit permission set of "none".
Types ¶
type ArgumentSession ¶ added in v0.8.1
type ArgumentSession interface {
Session
ExecuteWithArgs(context.Context, string, json.RawMessage, Invoker) (Result, error)
}
ArgumentSession executes a JS body with a structured lexical args object. Arguments travel over the existing framed callback channel, never as source. The intrinsic is invocation-bound and grants no host capability.
type Binding ¶
Binding exposes a capability under a JavaScript path, for example {Name: "file_read", Path: []string{"air", "fileRead"}}. Invoke receives Name. Authorization and argument validation remain the host Invoker's responsibility.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements Session over an owned, full-duplex attach transport. Closing the transport must unblock concurrent reads and writes.
type DockerSession ¶
DockerSession owns a disposable, credential-free executor container. Its state cannot migrate between replicas; a lost attach/session is terminal.
func NewDockerSession ¶
NewDockerSession creates and attaches a container using the same production image built by BuildImage. ctx owns its lifetime, not just startup.
type Invoker ¶
type Invoker interface {
Invoke(ctx context.Context, name string, args json.RawMessage) (json.RawMessage, error)
}
Invoker dispatches a named capability with a JSON array of positional args. The caller must supply a non-nil invoker even when no capabilities are exposed. Implementations must honor context cancellation and may be called concurrently up to the session's finite broker limit. Results must be valid JSON.
Each Execute immutably binds its invoker and context. A retained JS function from a completed invocation must not gain access to a subsequent invoker. No callback may begin after Execute returns; all accepted broker requests must settle or be canceled before completion. Session implementations must enforce these rules outside the untrusted JavaScript realm.
type InvokerFunc ¶
type InvokerFunc func(context.Context, string, json.RawMessage) (json.RawMessage, error)
InvokerFunc adapts a function to Invoker.
func (InvokerFunc) Invoke ¶
func (f InvokerFunc) Invoke(ctx context.Context, name string, args json.RawMessage) (json.RawMessage, error)
type Limits ¶
type Limits struct {
FrameBytes int `json:"frameBytes"`
CodeBytes int `json:"codeBytes"`
OutputBytes int `json:"outputBytes"`
LogBytes int `json:"logBytes"`
Logs int `json:"logs"`
ConcurrentCalls int `json:"concurrentCalls"`
Calls int `json:"calls"`
ExecutionMS int `json:"executionMS"`
IdleMS int `json:"idleMS"`
}
Limits are required. DefaultLimits supplies an explicit starting policy. Wire deadlines are milliseconds; all size limits count UTF-8 bytes.
func DefaultLimits ¶
func DefaultLimits() Limits
type Result ¶
type Result struct {
Output json.RawMessage `json:"output,omitempty"`
Undefined bool `json:"undefined,omitempty"`
Logs []Log `json:"logs,omitempty"`
}
Result carries a JSON return value and ordered, bounded console output. Output is absent only for JavaScript undefined; JSON null is the bytes "null". Logs may accompany an execution error. Implementations must enforce finite code, frame, output, log, execution-time, and concurrent broker limits.
type Session ¶
type Session interface {
Execute(ctx context.Context, code string, callback Invoker) (Result, error)
Close() error
}
Session owns one uninterrupted JavaScript realm. Implementations must reject overlapping Execute calls, not queue them. Close is idempotent and cancels execution. Loss of the realm is terminal: never recreate it or replay code.
Code is an async function body: await and an explicit return are supported. Function-local declarations do not persist. Properties stored on globalThis persist across executions for the uninterrupted lifetime of this session. This state is ephemeral, not durable or shared across replicas.
type SupervisorOptions ¶
type SupervisorOptions struct{ DenoPath, RuntimePath string }
SupervisorOptions specifies installed, trusted runtime assets. Serve must run inside a network-none, finite-memory/CPU/PID container, never on an agent host.