script_inspector_bridge.hpp

Go to the documentation of this file.

// script_inspector_bridge.hpp — thread-marshaling seam between an off-thread
// inspector and the single-threaded scripted-UI JS engine.
#pragma once
 
#include <pulp/view/script_inspector_port.hpp>
 
#include <chrono>
#include <condition_variable>
#include <functional>
#include <memory>
#include <mutex>
#include <string>
#include <thread>
 
namespace pulp::view {
 
class ScriptEngine;
 
// Lets an inspector running on a *background* thread evaluate expressions
// against a ScriptEngine that lives on the UI / engine-owner thread, query the
// engine's honest debug capabilities, and cooperatively abort a runaway
// evaluation — without ever touching the (not-thread-safe) engine off-thread.
//
// The engine thread is whichever thread calls attach()/pump()/detach(). It
// drains queued evaluate requests in pump(), which a host runs once per frame
// from ScriptedUiSession::poll(). A background evaluate() enqueues a request
// and blocks (with a timeout) until pump() fulfills it; if evaluate() is itself
// called on the engine thread it runs inline, with a watchdog using the
// backend's cross-thread interrupt seam to enforce the same deadline. Only one
// evaluation is in flight at a time — including owner-thread calls — and a
// concurrent request returns `busy`.
//
// This is deliberately NOT a step debugger: mainline QuickJS (Pulp's bundled
// engine) exposes no source-line breakpoint / stepping / local-scope API, so
// capabilities() reports can_break/can_step/can_inspect_locals = false. It is
// an honest runtime inspector: evaluate, capability reporting, and interrupt.
class ScriptInspectorBridge final : public ScriptInspectorPort {
  public:
    struct EvalResult {
        bool ok = false;          
        bool timed_out = false;   
        bool busy = false;        
        bool detached = false;    
        bool refused = false;     
        std::string json;         
        std::string error;        
    };
 
    // Honest snapshot of what the attached engine can do for debugging. Fixed
    // at attach() time from the engine's immutable identity, so it can be read
    // from any thread without touching the engine.
    struct Capabilities {
        std::string engine;              
        bool can_evaluate = false;       
        bool can_interrupt = false;      
        bool can_break = false;          
        bool can_step = false;           
        bool can_inspect_locals = false; 
        std::string refused_capability;
    };
 
    static constexpr std::chrono::milliseconds kDefaultTimeout{2000};
 
    ScriptInspectorBridge() = default;
    ~ScriptInspectorBridge() override;
 
    ScriptInspectorBridge(const ScriptInspectorBridge&) = delete;
    ScriptInspectorBridge& operator=(const ScriptInspectorBridge&) = delete;
 
    // [engine thread] Record the realm's native grant. An explicit grant with
    // an effectful capability makes evaluate() refuse and capabilities()
    // report can_evaluate=false with the offending name; the legacy all()
    // default grant is not a decision and leaves evaluation eligible.
    void set_realm_capabilities(const CapabilitySet& granted) override;
 
    // [engine thread] Attach the engine and capture its capability snapshot.
    // Passing a new engine replaces the previous one; the calling thread is
    // recorded as the engine thread for inline-eval detection.
    void attach(ScriptEngine* engine) override;
 
    // [engine thread] Detach the engine. Queued work fails with `detached`;
    // running work is interrupted and detach waits for engine quiescence.
    void detach() override;
 
    // [engine thread] Install the host-owned realm reset owed after evaluated
    // code has stopped. A completed evaluation records the debt; the host
    // discharges it at its next frame boundary via
    // run_pending_post_evaluation_reset(). The reset does NOT run inside the
    // request, so an evaluation leaves the caller's view of the realm intact
    // until the host returns to its run loop.
    void set_post_evaluation_reset(std::function<std::string(EvaluationDeadline)> reset) override;
 
    // [any thread] Whether a completed evaluation still owes a realm reset.
    bool post_evaluation_reset_pending() const;
 
    // [engine thread] Run the realm reset owed by a completed evaluation and
    // clear the debt, or do nothing when none is owed. Returns the reset's
    // failure text, empty on success. The host MUST call this before any frame
    // pump that could execute what evaluated code left behind, and again at
    // teardown so a caller that never pumps cannot drop a reset failure.
    std::string run_pending_post_evaluation_reset() override;
 
    // [any thread] Evaluate `code`, marshaled to the engine thread. Blocks up
    // to `timeout`. On timeout the running evaluation is interrupted (if the
    // engine supports it) so a runaway loop cannot wedge the bridge forever.
    EvalResult evaluate(const std::string& code,
                        std::chrono::milliseconds timeout = kDefaultTimeout,
                        std::size_t max_result_bytes = 1024 * 1024);
 
    // [any thread] Capability snapshot (empty engine name when detached).
    Capabilities capabilities() const;
 
    // [any thread] Cancel queued work or cooperatively abort running work.
    // Returns false when there is no cancellable request.
    bool interrupt();
 
    // [engine thread] Drain the pending evaluate request, if any. Returns true
    // when a request was serviced. Host calls this once per frame.
    bool pump() override;
 
    // [any thread] Whether an evaluation is currently queued or executing.
    bool is_busy() const;
 
private:
    enum class RequestState { queued, running, finished };
 
    struct Request {
        std::string code;
        std::size_t max_result_bytes = 0;
        std::condition_variable cv;
        RequestState state = RequestState::queued;
        bool timeout_requested = false;
        bool detach_requested = false;
        bool interrupt_requested = false;
        bool interrupt_consumed = false;
        bool evaluation_finished = false;
        EvaluationDeadline deadline{};
        ScriptEngine* engine = nullptr;
        bool can_interrupt = false;
        // Protected by mutex_. A cancelling thread closes the window and arms
        // the engine interrupt while holding that mutex; the engine thread
        // takes the same mutex before closing/draining at quiescence. That
        // ordering prevents a cancel flag from being armed after the drain.
        bool interrupt_window_open = false;
        EvalResult result;
    };
 
    // Runs engine->evaluate on the engine thread, serializing the result or the
    // thrown exception into an EvalResult. Takes the engine explicitly so the
    // caller's snapshot is the one used. Caller guarantees engine-thread.
    EvalResult serialize_eval(ScriptEngine* engine, const std::string& code,
                              std::size_t max_result_bytes) const;
    // [engine thread] Execute, reset, normalize, and publish one already
    // claimed request. Inline evaluation and pump share this state machine.
    EvalResult run_claimed_request(const std::shared_ptr<Request>& request,
                                   ScriptEngine* engine);
 
    // mutex_ must be held. Publishes a terminal result and releases the
    // single-flight slot. Request waiters use the same mutex, so completion and
    // cancellation have one ordering point.
    void finish_locked(const std::shared_ptr<Request>& request, EvalResult result);
    // mutex_ must be held. The engine interrupt seam is explicitly nonblocking;
    // retaining the lock through the call prevents detach() from returning and
    // the caller-owned engine from being destroyed before the dereference.
    static bool interrupt_if_active_locked(const std::shared_ptr<Request>& request);
 
    friend struct ScriptInspectorBridgeTestAccess;
 
    // mutex_ must be held. Re-derives caps_.refused_capability / can_evaluate
    // from the attached engine and the recorded realm grant.
    void apply_realm_gate_locked();
 
    mutable std::mutex mutex_;
    std::condition_variable state_cv_;
    ScriptEngine* engine_ = nullptr;
    Capabilities caps_{};
    // Grant of the realm the engine belongs to. Default-constructed (empty) so
    // a bridge attached without a session evaluates as before.
    CapabilitySet realm_capabilities_{};
    std::thread::id engine_thread_{};
    bool have_engine_thread_ = false;
    bool in_flight_ = false;
    // Set by a completed evaluation, cleared by the host's next reset drain.
    // Several evaluations between two frames collapse into one debt: they all
    // ran in the same realm, and one reconstruction from last-good source
    // discards everything any of them left behind.
    bool reset_pending_ = false;
    bool reset_in_progress_ = false;
    std::thread::id reset_thread_{};
    std::shared_ptr<Request> pending_;  // single-slot queue, drained by pump()
    std::shared_ptr<Request> running_;  // engine remains attached until this clears
    std::function<std::string(EvaluationDeadline)> post_evaluation_reset_;
};
 
class ScriptedUiSession;

void install_script_inspector_bridge() noexcept;

ScriptInspectorBridge* script_inspector(ScriptedUiSession& session) noexcept;
 
} // namespace pulp::view