QjsProcessRuntime class final

A JsrRuntime over a qjs subprocess using the stdio wire protocol.

Engine resolution: explicit binary override, then the FA_QJS_BIN environment variable, then qjs from PATH. A missing binary surfaces as ExtEngineUnavailableException (spawn ProcessException), never a raw crash.

Wire protocol (host side): one JSON object per \n line.

• JS→host bridge request {seq, method, args} — answered with {seq, ok, value} or {seq, ok: false, error} via bridges.
• Host→JS invoke {invoke, fn, args} — answered with {invoke, ok, value} or {invoke, ok: false, error}.
• {fatal: m} — bootstrap/main failure; fails start and every pending call with ExtProtocolException.

Constructors

QjsProcessRuntime({Duration startTimeout = const Duration(seconds: 30), String? binary})

Properties

commitPayload → Future<Map<String, dynamic>>

Registration payload returned by __extCommit. Fails when start has not completed.

no setter

engineId → String

'qjs-process' | 'flutter-js' | 'web-worker' | 'qjs-wasm' | 'fake'.

no setter

hashCode → int

The hash code for this object.

no setter, inherited

lastStderr → String

Last engine diagnostics lines (stderr + stdout notes) — see ExtEngineRouter.lastNotes.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

startTimeout → Duration

Bound for start (spawn + __extCommit round trip). Overrun kills the engine with SIGKILL and surfaces TimeoutException.

final

Methods

answerBridge(int seq, String method, Object? args) → void

Answers a {seq, method, args} bridge request on stdin.

dispose() → Future<void>

SIGTERM, 2s grace, SIGKILL, then deletes the temp script directory. Idempotent.

invoke(String fn, List<Object?> args, {Duration? timeout}) → Future<Object?>

Invokes the global JS function fn with JSON-able args; resolves with a JSON-able result. Implementations enforce timeout (kill/dispose on overrun => TimeoutException).

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

note(String line) → void

Records one diagnostic line in the engine stderr buffer.

start({required String bootstrapJs, required String mainJs, required ExtBridgeHandler bridges}) → Future<void>

Bootstraps the engine: evaluates bootstrapJs (engine transport + shared core, see ext_bootstrap_js.dart) then mainJs (the extension source), and must resolve only after __extCommit() returned the registration payload. bridges dispatches the extension's jsr.ext.* host calls.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

composeScript(String bootstrapJs, String mainJs) → String

The exact extension script handed to qjs (composition defined in composeExtScript).

engineProbe() → Future<String>

Verifies the resolved qjs binary by running <bin> -e 'print(1)' and returns a version string (<bin> -v, falling back to the binary path). Throws ExtEngineUnavailableException when the binary is missing or broken. Used by fa ext list.

resolveBinary({String? binaryOverride}) → String

Resolves the qjs binary: binaryOverride, then FA_QJS_BIN, then PATH.

Constants

kEngineId → const String

engineId reported by __extPing parity fixtures.