solvi.experimental.compile.sandbox¶
Code a model wrote, held to pure functions: an ast allowlist, a subprocess with limits under a trusted driver, and a
restricted load into this process.
A sandbox for code a model wrote: only pure functions over facts.
from solvi.experimental.compile.sandbox import check, load, run
check(source) # [] when allowed, else the reasons it is refused
ns = load(source) # the module's namespace, in this process (refuses what check refuses)
out = run(source, "mypkg.driver:main", payload) # the module run in a subprocess by a trusted driver → its JSON
outs = run_many(sources, "mypkg.driver:main", payload) # many modules, one subprocess → a result per module
check and load are the stable solvi.core.versions._sandbox's since 1.1 (a catalog version's module is loaded the same
way): see there for what they refuse. run executes the module in a fresh python -I subprocess: an empty
environment, a scratch working directory, limits on memory (RLIMIT_AS; RLIMIT_DATA on macOS), CPU time and wall-clock time, the same
restricted builtins. The driver — your code, never the model's — is imported before the module runs; it gets the
module's namespace, the payload and the signal module (for a per-item alarm) and returns JSON. A module that does not
load, a crash, a run over its limits come back as {"load_error": ...} or {"crash": ...}; a failure of the sandbox
itself (the interpreter, the driver, a limit) as {"sandbox_error": ...} — never as the module's.
run_many runs many modules in one subprocess (the interpreter starts once), each with its own limits on CPU and wall
time, and gives each its own result; a module that ends the process (a CPU limit, memory, a crash) is reported as
{"crash": ...} and the modules after it run in a fresh subprocess. The modules of one batch share the process: a
module that changes an allowed standard-library module (math.pi = 3) changes it for the modules after it — use run
for one you do not trust that far.
What it does not do: the limits hold in run and run_many only; once loaded into your process a module is held by
the checks alone.
Refused ¶
Bases: ValueError
The module breaks the sandbox's rules; .reasons lists each one with its line.
SandboxWarning ¶
Bases: UserWarning
The sandbox ran without one of its limits (the platform refused it): the module's run is not held by it.
check ¶
The reasons the sandbox refuses this module, each with its line ([] — allowed). allowed: more modules it may import, beyond ALLOWED (top-level names; never a forbidden one). See the module docs.
load ¶
Execute an allowed module in this process → its namespace. Raises Refused with the reasons when check refuses
it. extra: names put into the namespace before it runs (trusted helpers such as Fail). allowed: more modules it
may import, as for check.
safe_builtins ¶
The builtins a sandboxed module sees: the forbidden names removed, __import__ admitting ALLOWED (and
allowed) only.
source_name ¶
The file name a module is compiled under: <solvi-sandbox-<sha256 prefix>>, the same for the same text.
set_limits ¶
Set the child's limits: memory mem bytes, CPU time cpu seconds → notes on what could not be set. Memory is
RLIMIT_AS (the address space) on Linux; on macOS RLIMIT_DATA, because there RLIMIT_AS below the address space the
interpreter has already reserved raises ValueError("current limit exceeds maximum limit") — every limit under tens
of gigabytes would. A memory limit the platform refuses is skipped and noted (the run goes on: not the module's
fault); the CPU limit is required (cpu=None: not set here — run_many sets one per module).
run ¶
run(source: str, driver: str, payload, *, mem_mb: int = 1024, cpu_s: int = 300, wall_s: int = 600, path=(), allowed=()) -> dict
Run the module in a subprocess under driver ("package.module:function": trusted code, importable in the child
from solvi's own folder or the folders in path; it gets (namespace, payload, signal) and returns JSON) → the
driver's result, {"load_error": reason} when the module is refused or does not load, {"crash": reason} (a
crash, a limit, no result), or {"sandbox_error": reason} when the sandbox itself failed — the interpreter did not
start, the driver did not import, a required limit could not be set: not the module's failure. A memory limit
the platform refuses is skipped with a SandboxWarning (see set_limits). The driver module's SANDBOX_EXTRA dict,
if any, is put into the namespace. allowed: more modules the module may import, beyond ALLOWED (as for check).
run_many ¶
run_many(sources, driver: str, payload, *, mem_mb: int = 1024, cpu_s: int = 300, wall_s: int = 600, path=(), allowed=()) -> list
run for many modules in one subprocess → a result per module, in order, each what run would give for it:
the driver's result, {"load_error"}, {"crash"} (the driver raised, or the module ended the process) or
{"sandbox_error"}. Every module is loaded into its own namespace and gets cpu_s seconds of CPU and wall_s
seconds of wall time from its start (the driver's per-item alarm as in run); mem_mb holds the whole process. A
module that ends the process or runs over wall_s is a crash, and the modules after it run in a fresh subprocess.
The modules of a batch share the process (see the module docs).