Struct QuickJsRuntime 

pub struct QuickJsRuntime { /* private fields */ }

QuickJS-backed runtime adapter. One instance is reusable across many documents; callers MUST invoke XfaJsRuntime::reset_for_new_document at the start of each flatten.

Implementations

impl QuickJsRuntime

pub fn new() -> Result<Self, SandboxError>

Construct a new sandboxed runtime with default budgets.

pub fn with_time_budget(self, budget: Duration) -> Self

Override the per-script wall-clock budget. Must be called before any execute_script invocation; takes effect on the next call.

pub fn with_memory_budget(self, bytes: usize) -> Self

Override the per-document memory budget. Must be called before any execute_script invocation; takes effect on the next document.

pub fn with_walltime_fallback_multiplier(self, multiplier: u32) -> Self

QF1-E / SEC-01 — override the wall-time fallback multiplier. The default is read from super::ENV_WALLTIME_FALLBACK_MULTIPLIER / falls back to super::WALLTIME_FALLBACK_MULTIPLIER_DEFAULT. Values below 2 are clamped to 2 so a clean timeout cannot be re-labelled as WallTimeExceeded by accident. Tests use this to deterministically pin the multiplier without racing the process-global env var.

Trait Implementations

impl Debug for QuickJsRuntime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl XfaJsRuntime for QuickJsRuntime

fn init(&mut self) -> Result<(), SandboxError>

One-time initialisation. Idempotent.

fn reset_for_new_document(&mut self) -> Result<(), SandboxError>

Reset per-document state (memory budget, instruction counter, any cached compiled scripts). Called once per flatten.

fn set_form_handle( &mut self, form: *mut FormTree, root_id: FormNodeId, ) -> Result<(), SandboxError>

Phase C: install the FormTree the runtime should resolve paths against and mutate. The dispatch path owns the mutable borrow and clears the handle before returning.

fn set_data_handle(&mut self, dom: *const DataDom)

Phase D-γ: install a read-only view of the DataDom for the current document. Called once per document after set_form_handle, before any scripts run. Default: no-op (backends without DataDom support ignore it).

fn set_declared_subform_names(&mut self, names: HashSet<String>)

BE-1 tranche #1 (benign zero-instance SOM): install the set of template-declared container names (subform/subformSet/exclGroup/ area) for the current document. Backends that resolve implicit SOM identifiers use it to return a benign empty-node façade for a declared-but-absent reference instead of undefined (Adobe semantics), so guarded scripts (if (!Sub.Child.isNull) {...} else {...}) run their else branch instead of throwing. Like set_data_handle, the caller installs this before script execution. Default: no-op (the static NullRuntime ignores it, so the default/non-sandboxed path is unaffected and stays byte-identical).

fn reset_per_script( &mut self, current_id: FormNodeId, activity: Option<&str>, ) -> Result<(), SandboxError>

Phase C: reset per-script host counters and install the current script context node / activity. Backends without host bindings ignore it.

fn set_static_page_count(&mut self, page_count: u32) -> Result<(), SandboxError>

Phase C page-count foundation. The current flatten order runs scripts before layout, so callers normally leave this at 0.

fn set_presave_gate(&mut self, enabled: bool)

D1.B gated allow. Inform the runtime whether the XFA_PRESAVE_DURING_FLATTEN=1 opt-in is active for the current flatten. The dispatch path computes this once per document via presave_during_flatten_enabled and forwards it here so the host binding layer can mirror the dispatch decision (defence-in-depth).

fn execute_script( &mut self, activity: Option<&str>, body: &str, ) -> Result<RuntimeOutcome, SandboxError>

Execute one script body inside the sandbox.

fn take_metadata(&mut self) -> RuntimeMetadata

Take the cumulative metadata since the last take_metadata call (or since reset_for_new_document, whichever was later).

fn take_occur_mutations(&mut self) -> Vec<(usize, String, i64)>

D6: drain captured occur.min/occur.max write intents (node_index, prop, value) recorded during the script pass. The dispatch path applies them (only when XFA_OCCUR_APPLY=1) after the rollback decision. Default: none (non-sandboxed runtimes capture nothing).

fn take_diag_logs(&mut self) -> RuntimeDiagLogs

Epic A E-2/E-3: drain verbose per-entry diagnostic logs. Only populated when XFA_RUNTIME_DIAG=1 is set at the host call sites. Default impl returns empty logs (NullRuntime, non-sandboxed paths).