SmolBox.Command (SmolBox v0.1.0)

A bounded argument-vector command. No shell is inserted by SmolBox.

Timeouts are positive whole seconds, matching SmolVM's timeoutSecs field. The initial maximum is five minutes; managed execution can impose an earlier absolute deadline. stdin must be UTF-8 and is only supported by buffered execution in SmolVM 1.14.1. Arbitrary binary data belongs in staged files.

Summary

Types

t()

Functions

new(argv, options \\ [])

Create a command from an executable and argument list, without inserting a shell.

to_wire(command)

Return the exact camelCase request fields after validation.

validate(command)

Revalidate a struct before transport, including manually constructed values.

Types

t()

@type t() :: %SmolBox.Command{
  argv: [String.t()],
  env: [{String.t(), String.t()}],
  stdin: String.t() | nil,
  timeout_secs: pos_integer(),
  user: String.t() | nil,
  workdir: String.t()
}

Functions

new(argv, options \\ [])

@spec new(term(), term()) :: {:ok, t()} | {:error, SmolBox.Error.t()}

Create a command from an executable and argument list, without inserting a shell.

argv has 1–256 UTF-8 entries, at most 16 KiB each and 64 KiB combined. The executable must be nonempty; arguments may be empty. NUL bytes are rejected.

Option	Default	Meaning
`:workdir`	`"/workspace"`	Validated absolute guest workspace path
`:timeout_secs`	`30`	Upstream command timeout, a whole number from 1–300 seconds
`:env`	`[]`	Up to 64 unique `{string_name, string_value}` pairs; names up to 128 bytes, values up to 8192 bytes
`:stdin`	`nil`	Up to 64 KiB of UTF-8 text; buffered execution only
`:user`	`nil`	Optional nonempty guest user string, at most 128 bytes

Environment variable names use letters/digits/underscores and cannot begin with a digit. Binary inputs belong in files. In managed execution, the command timeout must fit the profile's execution_ms budget.

Example

iex> {:ok, command} = SmolBox.Command.new(["python", "/workspace/main.py"], timeout_secs: 10, env: [{"MODE", "demo"}])
iex> {command.argv, command.timeout_secs, command.workdir}
{["python", "/workspace/main.py"], 10, "/workspace"}

to_wire(command)

@spec to_wire(t()) :: {:ok, map()} | {:error, SmolBox.Error.t()}

Return the exact camelCase request fields after validation.

validate(command)

@spec validate(term()) :: :ok | {:error, SmolBox.Error.t()}

Revalidate a struct before transport, including manually constructed values.