lanekeep_js/
lib.rs

1//! Embedded JavaScript sandbox and host API for lanekeep rules.
2//!
3//! The embedded QuickJS runtime, the capability-restricted host API, the TypeScript
4//! stripping step, and the module loader.
5//!
6//! The sandbox boundary lives here. Rule code reaches exactly the functions this crate
7//! exposes and nothing else: no ambient filesystem, no process, no network, no clock, no
8//! randomness. Those globals are not restricted, they are absent.
9//!
10//! Every addition to the host API widens the trust boundary and bumps the API version that
11//! feeds the cache key.
12//!
13//! `FileAccess`/`ReadError` and `NodeArena`/`Handle` are re-exported rather than owned here:
14//! the first lives in `lanekeep-core`, the second in `lanekeep-nodes`. Both moved out once a
15//! second engine (`lanekeep-wasm`) needed the identical definitions — a copy per engine
16//! would let one run enforce two different notions of "the same file" or "the same node",
17//! each correct alone and disagreeing with the other.
18//!
19//! `Limits`/`RunClock` (and the `Budget`/`Trip` this sandbox arms and reads) moved to
20//! `lanekeep-core` for a sharper version of the same reason: a run has exactly one global
21//! budget, not one per engine, so two `RunClock`s would each be a correct clock in isolation
22//! while the run as a whole overran both. This sandbox still does the arming, disarming and
23//! interrupt wiring — only the type that makes "one clock" possible moved out.
24//!
25//! # How absence is achieved
26//!
27//! Two mechanisms, and the first is much stronger than the second.
28//!
29//! **Not installed.** The engine's optional intrinsics are opted into rather than opted out
30//! of, so `Date`, `Performance` and `WeakRef` are never created. There is no original for a
31//! rule to reach: nothing to patch, nothing to restore, no prototype chain leading back.
32//!
33//! **Deleted at startup.** `Math.random` lives among the non-optional base objects, so it
34//! has to go afterwards. This is weaker in principle — deletion can be undone if a
35//! reference escapes — but a rule that defines its own `Math.random` has written
36//! deterministic code, which is all this needs to guarantee.
37//!
38//! Anything a host function does not offer, a rule cannot do. `fs`, `process`, `fetch`,
39//! `setTimeout` and friends were never part of this engine to begin with, which is asserted
40//! rather than assumed.
41//!
42//! # What is here so far
43//!
44//! The sandbox and its budgets. The host API, TypeScript stripping and the module loader
45//! arrive in later milestones.
46
47pub mod error;
48pub mod host;
49pub mod loader;
50pub mod sandbox;
51pub mod typescript;
52
53pub use error::SandboxError;
54pub use host::{
55    EmittedFact, HOST_API_VERSION, HostContext, ReduceContext, ReduceFact, ReduceReport, Report,
56    merge_file,
57};
58pub use lanekeep_core::files::{FileAccess, ReadError};
59pub use lanekeep_core::limits::{
60    DEFAULT_GLOBAL_TIMEOUT, DEFAULT_MEMORY_BYTES, DEFAULT_RULE_TIMEOUT, Limits, RunClock,
61};
62/// Re-exported so consumers can supply languages without depending on `lanekeep-lang` directly.
63pub use lanekeep_lang::Language;
64pub use lanekeep_nodes::{Handle, NodeArena};
65pub use loader::{
66    BuiltinComponent, BuiltinComponentMap, BuiltinSource, HOST_MODULE, MAX_COMPONENT_NAME,
67    ResolveError, RuleLoader, RuleResolver, RuleRoot,
68};
69pub use sandbox::Sandbox;
70pub use typescript::{StripError, Unsupported, strip_types};
lanekeep_js/lib.rs

lanekeep_js/
lib.rs
