js_engine.hpp

Go to the documentation of this file.

#pragma once
 
#include <atomic>
 
#include <string>
#include <string_view>
#include <functional>
#include <optional>
#include <memory>
#include <vector>
#include <cstddef>
#include <cstdint>
#include <stdexcept>
#include <unordered_set>
#include <choc/containers/choc_Value.h>
#include <choc/text/choc_JSON.h>
 
namespace pulp::view {
 
// Callback for resolving module imports (returns source code or nullopt)
using ModuleResolver = std::function<std::optional<std::string>(std::string_view path)>;
using ModuleCompletionHandler = std::function<void(const std::string& error, const choc::value::Value& result)>;
 
// Callback for logging from JS (console.log, console.warn, etc.)
using LogCallback = std::function<void(std::string_view level, std::string_view message)>;
 
// Native function callable from JS
using NativeFunction = std::function<choc::value::Value(const choc::value::Value* args, size_t num_args)>;
using NativePromiseFunction = NativeFunction;
 
// Native-backed global objects with snapshot properties
// and native method callbacks. This is intentionally smaller than a full opaque
// proxy / HostObject API, but it gives the bridge a truthful native
// object seam to build on.
struct HostObjectProperty {
    std::string name;
    choc::value::Value value;
};
 
struct HostObjectMethod {
    std::string name;
    NativeFunction fn;
};
 
struct HostObjectDescriptor {
    std::string class_name;
    std::vector<HostObjectProperty> properties;
    std::vector<HostObjectMethod> methods;
};
 
struct JsEngineCreationStats {
    uint64_t total = 0;
    uint64_t quickjs = 0;
    uint64_t jsc = 0;
    uint64_t v8 = 0;
};
 
// Which JS engine backend is active
enum class JsEngineType {
    quickjs,
    jsc,
    v8
};
 
// Returns a human-readable name for the engine type
constexpr std::string_view engine_type_name(JsEngineType type) {
    switch (type) {
        case JsEngineType::quickjs: return "QuickJS";
        case JsEngineType::jsc:    return "JavaScriptCore";
        case JsEngineType::v8:     return "V8";
    }
    return "unknown";
}
 
// Heap ceiling applied to every newly created engine, in bytes. Sized well
// above the largest in-repo scripted-UI bundle so ordinary editors never meet
// it, while a runaway or hostile script hits a JS error instead of growing
// until the hosting process is OOM-killed. 0 means unlimited.
constexpr std::size_t kDefaultJsMemoryLimitBytes = std::size_t{512} * 1024 * 1024;
 
// Abstract JS engine backend.
// Each backend implements this interface to provide a uniform scripting API.
// Not thread-safe — all calls must happen on the same thread.
class JsEngine {
public:
    virtual ~JsEngine() = default;
 
    // Which engine type this is
    virtual JsEngineType type() const = 0;
 
    // ── Runtime / provider identity ─────────────────────────────────────────
    // Truthful identity of the JS runtime actually linked into this build.
    // Backends that can report a concrete runtime version (e.g. V8) override
    // these; the defaults return empty strings so non-reporting backends
    // (QuickJS, JSC) and forward-compatibility callers degrade cleanly.
 
    // The engine's own reported runtime version string (e.g. V8's
    // "15.7.112.5"). Empty when the backend does not report one.
    virtual std::string runtime_version() const { return {}; }
 
    // Where the runtime came from, as wired at build time: "v8builder" for the
    // sealed v8-builder seal, "libnode"/"v8_monolith"/"external" for the A/B
    // baselines, empty when not applicable.
    virtual std::string provider_kind() const { return {}; }
 
    // Absolute path to the provider library that was linked, when known.
    virtual std::string provider_path() const { return {}; }
 
    // The version the build expected from the provider (parsed from the pinned
    // V8 tag in tools/deps/manifest.json), for cross-checking against
    // runtime_version(). Empty when no expectation was pinned.
    virtual std::string expected_runtime_version() const { return {}; }
 
    // Check if the engine is in a valid state
    virtual bool is_valid() const = 0;
 
    // Evaluate JS code synchronously, returns the result.
    // Throws std::runtime_error on parse/runtime errors.
    virtual choc::value::Value evaluate(const std::string& code) = 0;
 
    // Evaluate a whole script — a bundle or prelude loaded once per realm, not
    // an expression probe. Same result and error semantics as evaluate(). An
    // engine may reuse the compiled form of a script it has already compiled
    // in this process (QuickJS keeps its bytecode), so a second realm loading
    // the same bundle skips parsing it.
    virtual choc::value::Value evaluate_script(const std::string& code) {
        return evaluate(code);
    }
 
    // Evaluate and serialize directly inside the backend while enforcing the
    // byte/depth/cycle bounds during traversal. Backends that cannot provide
    // that resource guarantee must leave this unsupported.
    virtual bool supports_bounded_json_evaluation() const { return false; }
    virtual std::string evaluate_bounded_json(const std::string&, std::size_t) {
        throw std::runtime_error("bounded JSON evaluation is unsupported");
    }
 
    // Run JS code as a module with import resolution. Completion is invoked
    // when the engine reports module execution has either succeeded or failed.
    virtual void run_module(const std::string& code,
                            ModuleResolver resolver,
                            ModuleCompletionHandler completion = {}) = 0;
 
    // Register a C++ function callable from JS as a global.
    void register_function(const std::string& name, NativeFunction fn) {
        claim_native_symbol(name);
        register_function_impl(name, std::move(fn));
    }
 
    // Invoke a global JS function by name with no arguments
    virtual choc::value::Value invoke(std::string_view name) = 0;
 
    // Invoke a global JS function with positional arguments
    virtual choc::value::Value invoke(std::string_view name,
                                      const choc::value::Value* args,
                                      size_t num_args) = 0;
 
    // Set a log callback for console.log/warn/error/info/debug
    virtual void set_log_callback(LogCallback callback) = 0;
 
    // Register a native-backed global object with snapshot properties and
    // native method callbacks.
    void register_host_object(const std::string& name, HostObjectDescriptor descriptor) {
        claim_native_symbol(name);
        register_host_object_impl(name, std::move(descriptor));
    }
 
    // Expose a native callback as a JS function that returns a real Promise
    // and resolves on the JS microtask queue.
    // This does not yet provide a held native resolver for later completion.
    void register_promise_function(const std::string& name, NativePromiseFunction fn) {
        claim_native_symbol(name);
        register_promise_function_impl(name, std::move(fn));
    }
 
    // Hint that now is a good time to collect garbage (advisory)
    virtual void gc_hint() {}
 
    // Cap the heap this realm may allocate, in bytes (0 = unlimited). Backends
    // that enforce the cap raise a JS "out of memory" error on the allocation
    // that would exceed it. Returns false on backends that cannot enforce one,
    // leaving the realm unbounded.
    virtual bool set_memory_limit(std::size_t) {
        return false;
    }
 
    // Pump any engine-specific message loop / microtask queue. This is a no-op
    // for engines that do not expose an explicit pump hook.
    virtual void pump_message_loop() {}
 
    // ── Cooperative interrupt ────────────────────────────────────────────────
    // Whether this backend can cooperatively abort a running evaluation that
    // was started on the engine thread, from a *different* thread. QuickJS
    // supports this via its host interrupt handler; backends without an
    // equivalent hook return false.
    virtual bool supports_interrupt() const { return false; }
 
    // Request that the currently-running evaluation abort at the engine's next
    // interrupt check, surfacing as a thrown "interrupted" exception on the
    // engine thread. This ONLY sets a flag — it does not itself run JS — so it
    // is safe to call from a thread other than the engine thread (the one true
    // cross-thread entry point on this otherwise single-threaded interface).
    // A no-op on backends where supports_interrupt() is false. Arming the flag
    // while no evaluation is running would abort the *next* one, so callers
    // (see ScriptInspectorBridge) only arm it while an evaluation is in flight.
    virtual void request_interrupt() {}
 
    // Consume an interrupt that arrived after the backend's final check. Called
    // on the engine thread after evaluation quiesces so a persistent cancel
    // flag cannot abort the next otherwise-unrelated evaluation.
    // Returns true when a still-pending flag was cleared, proving that the
    // completed evaluation did not consume the interrupt request.
    virtual bool clear_pending_interrupt() { return true; }
 
    // ── Forward-compatibility capability flags (HostObject / TypedArray / Promise) ──
    // These are defined now so all backends can be designed with them in mind.
    // Default implementations return false / no-op. Backends enable as ready.
 
    virtual bool supports_host_objects() const { return false; }
    // This means the engine can surface JS TypedArray / ArrayBuffer values
    // through the current Pulp API seam without collapsing them into an
    // opaque generic object. It does not imply zero-copy bridging yet.
    virtual bool supports_typed_arrays() const { return false; }
    virtual bool supports_promises() const { return false; }
 
    // Non-copyable, non-movable (owned via unique_ptr)
    JsEngine(const JsEngine&) = delete;
    JsEngine& operator=(const JsEngine&) = delete;
    JsEngine(JsEngine&&) = delete;
    JsEngine& operator=(JsEngine&&) = delete;
 
protected:
    JsEngine() = default;
 
    virtual void register_function_impl(const std::string& name, NativeFunction fn) = 0;
 
    virtual void register_host_object_impl(const std::string& name, HostObjectDescriptor descriptor) {
        const auto quote_string = [] (std::string_view text) {
            return choc::json::toString(choc::value::createString(std::string(text)));
        };
 
        const auto js_literal = [&] (const choc::value::Value& value) -> std::string {
            if (value.isVoid())
                return "undefined";
            return choc::json::toString(value);
        };
 
        static uint64_t global_host_symbol = 0;
 
        std::string target = "globalThis[" + quote_string(name) + "]";
        std::string script;
        script.reserve(256 + descriptor.properties.size() * 64 + descriptor.methods.size() * 96);
        script += target + " = {};\n";
 
        if (!descriptor.class_name.empty())
            script += target + "[\"_objectName\"] = " + quote_string(descriptor.class_name) + ";\n";
 
        for (const auto& property : descriptor.properties)
            script += target + "[" + quote_string(property.name) + "] = " + js_literal(property.value) + ";\n";
 
        for (auto& method : descriptor.methods) {
            auto hidden_name = "__pulp_host_object_" + std::to_string(global_host_symbol++);
            register_function(hidden_name, std::move(method.fn));
            script += target + "[" + quote_string(method.name) + "] = globalThis[" + quote_string(hidden_name) + "];\n";
            script += "delete globalThis[" + quote_string(hidden_name) + "];\n";
        }
 
        evaluate(script + target + ";");
    }
 
    virtual void register_promise_function_impl(const std::string& name, NativePromiseFunction fn) {
        const auto quote_string = [] (std::string_view text) {
            return choc::json::toString(choc::value::createString(std::string(text)));
        };
 
        static uint64_t global_promise_symbol = 0;
        auto hidden_name = "__pulp_promise_function_" + std::to_string(global_promise_symbol++);
        register_function(hidden_name, std::move(fn));
 
        std::string quoted_hidden = quote_string(hidden_name);
        std::string quoted_name = quote_string(name);
        std::string script =
            "globalThis[" + quoted_name + "] = ((fn) => (...args) => Promise.resolve().then(() => fn(...args)))(globalThis[" + quoted_hidden + "]);\n"
            "delete globalThis[" + quoted_hidden + "];\n"
            "globalThis[" + quoted_name + "];";
        evaluate(script);
    }
 
private:
    std::unordered_set<std::string> registered_native_symbols_;
 
    void claim_native_symbol(const std::string& name) {
        if (!registered_native_symbols_.insert(name).second)
            throw std::runtime_error("JsEngine native symbol already registered: " + name);
    }
};
 
// ── Engine factory ─────────────────────────────────────────────────────────
 
// Create a JS engine of the specified type.
// Throws std::runtime_error if the requested engine is not available on this platform/build.
std::unique_ptr<JsEngine> create_js_engine(JsEngineType type);
 
// Create a JS engine using the build default. QuickJS remains the
// compatibility default unless a PULP_DEFAULT_ENGINE_* option selects
// JavaScriptCore or V8 at compile time.
std::unique_ptr<JsEngine> create_default_js_engine();
 
// Query which engines are available in this build
bool is_engine_available(JsEngineType type);
 
// Diagnostic hook used by native-import validation to prove that a generated
// C++ view path did not initialize a scripting backend while building/rendering.
JsEngineCreationStats js_engine_creation_stats();
void reset_js_engine_creation_stats_for_tests();

struct ScriptBytecodeCacheStats {
    std::uint64_t compiles = 0;   
    std::uint64_t hits = 0;       
    std::uint64_t bypassed = 0;   
    std::uint64_t precompiled = 0;  
    std::uint64_t waits = 0;      
    std::uint64_t embedded = 0;   
    std::size_t entries = 0;
    std::size_t bytes = 0;        
};
ScriptBytecodeCacheStats script_bytecode_cache_stats();
void clear_script_bytecode_cache();

std::size_t precompile_scripts(const std::vector<std::string>& sources,
                               const std::atomic<bool>* cancel = nullptr);
bool script_bytecode_cached(const std::string& source);

std::vector<std::uint8_t> build_embedded_script_bytecode(const std::string& source);
bool register_embedded_script_bytecode(const std::uint8_t* blob, std::size_t size);
std::string script_bytecode_engine_fingerprint();
 
namespace detail {
void set_precompile_claim_hook_for_tests(std::function<void(const std::string&)> hook);
std::function<void(const std::string&)> precompile_claim_hook_for_tests();
void clear_embedded_script_bytecode_for_tests();
}  // namespace detail
 
} // namespace pulp::view