script

type CmdExec ¶

type CmdExec struct {
	Lang    Lang          // language spec
	Bin     string        // interpreter override; empty means Lang.Bin
	Timeout time.Duration // per-script wall-clock limit; <= 0 means defaultTimeout
	// Sandbox is the operating-system isolation profile. Empty/off preserves the
	// historical path; strict is the fail-closed Linux profile from
	// ADR-0303.
	Sandbox SandboxMode
	// MaxOutput bounds what one script may write to stdout, in bytes; <= 0 means
	// defaultMaxOutput. The server sets it from the installation's budgets.
	MaxOutput int64
	// contains filtered or unexported fields
}

CmdExec runs script tasks by shelling out to a real interpreter for its Lang. It is the production Exec; tests use a fake instead so they need no interpreter.

Security posture (ADR-0047): the interpreter runs with -NoProfile / -NonInteractive (or the language equivalent), the instance's variables and the source arrive as environment values (not interpolated), each run is bounded by Timeout (the process is killed at the deadline), and it runs in the worker's trust domain. Run gives the interpreter an allowlisted runtime environment, never the worker's Atlas token or deployment secrets. The eventual isolation boundary is an external worker in the customer's environment.

func New(l Lang) *CmdExec

func (e *CmdExec) Check() error

func (e *CmdExec) Run(ctx context.Context, source string, input map[string]any) (any, error)

type CodedError ¶ added in v0.15.0

type CodedError struct {
	Code    string // the code, trimmed; never empty
	Message string // the error's own message, without the interpreter's framing
	Err     error  // the failure as the interpreter reported it
}

CodedError is a script failure that carries the code the script gave its error: the ErrorId of a PowerShell error, the code attribute of a Python exception, the code property of a JavaScript error. It reads as the interpreter's own failure, so an incident shows what it showed before. Whether the code makes the failure a BPMN error is Run's decision, because only the codes the task's process catches do (ADR-0461).

func (e *CodedError) Error() string

func (e *CodedError) Unwrap() error

type Exec ¶

type Exec interface {
	Run(ctx context.Context, source string, input map[string]any) (any, error)
}

Exec runs a script off the hot path and returns its result. It is the seam between the worker and the real interpreter: CmdExec shells out to the language's interpreter, but tests inject a deterministic fake so they need no interpreter installed. input is the instance's variables keyed by name; the returned value is the script's result, a JSON-shaped Go value (nil, bool, json.Number, string, []any, or map[string]any) that becomes the result variable.

type Job ¶ added in v0.3.0

type Job struct {
	Source string `json:"source"`
	// Input is the scope chain flattened for the script, nearest scope winning
	// (ADR-0068) — resolved by the engine, which is the only one that can walk it.
	Input map[string]any `json:"input,omitempty"`
	// Result names the process variable the script's output is written to; empty
	// means the task writes nothing back.
	Result string `json:"resultVariable,omitempty"`
	// ErrorCodes are the codes an error boundary or error event subprocess of the
	// task's process catches. A script that fails with one of them threw a BPMN error;
	// any other failure is a failure (ADR-0461). They travel with
	// the job because a worker has no compiled process to ask.
	ErrorCodes []string `json:"errorCodes,omitempty"`
}

Job is a script task with everything already looked up: the source to run and the variables it sees. It is what travels with a leased job.

func Resolve(store state.Reader, cp *compiler.CompiledProcess, detail *compiler.ScriptJobTaskDetail, elementInstanceKey uint64) (Job, error)

type Lang ¶

type Lang struct {
	Name        string // model/UI name, e.g. "python"
	JobTypeName string // reserved job-type name (compiler.*JobType)
	JobType     int32  // reserved job-type index (compiler.*JobTypeIndex)
	Bin         string // default interpreter binary
	Args        func(bootstrap string) []string
	Wrap        string // the bootstrap program
}

Lang describes how to run one scripting language: the reserved job type its worker subscribes to, the default interpreter binary, the interpreter arguments that run a bootstrap program, and that bootstrap. The bootstrap is a fixed program (never the author's source) that reads the source and variables from the environment, exposes the variables, runs the source, and prints the result as JSON on stdout (empty output = null). Each language keeps its own idiomatic result convention (see the bootstraps).

func LangByName(name string) (Lang, bool)

type ProcessLookup ¶

type ProcessLookup func(defKey uint64) *compiler.CompiledProcess

ProcessLookup resolves a process-definition key to its compiled process. The worker uses it to find the script source and result variable a job belongs to, so one handler serves every deployed process.

type Result ¶ added in v0.3.0

type Result struct {
	ResultVariable string
	Output         any
}

Result is what running a Job produces.

func Run(ctx context.Context, j Job, exec Exec) (Result, error)

type SandboxMode ¶ added in v0.7.0

type SandboxMode string

SandboxMode selects the operating-system boundary around an interpreter.

const (
	// SandboxOff preserves the historical execution contract. It is the initial
	// default because existing models may deliberately use files or the network.
	SandboxOff SandboxMode = "off"
	// SandboxStrict permits only the installed runtime and a private per-run
	// scratch directory, and denies creation of every network socket.
	SandboxStrict SandboxMode = "strict"

	// SandboxEnv configures the built-in script Worker Instance. A supervised
	// worker receives the equivalent typed command-line flag from its parent.
	SandboxEnv = "ATLAS_SCRIPT_SANDBOX"
)

func ParseSandboxMode(raw string) (SandboxMode, error)