lhumina_code/hero_lib_rhai
25
0
Fork 0
Code Issues 6 Pull requests Projects Releases Packages Wiki Activity Actions

hero_runner_rhai #13

New issue
Open
opened 2026-04-28 02:37:12 +00:00 by despiegk · 3 comments
despiegk commented 2026-04-28 02:37:12 +00:00
Owner
Copy link

move functionality in this repo

/Volumes/T7/code0/hero_code/crates/hero_runner_rhai
remove in original repo once its here

its more logical here

make 2 crates

  • hero_runner_rhai_server
  • hero_runner_rhai_ui (use /hero_ui_dashboard) connect to rhai_server

requirements

  • run with fork
  • minimize memory usage, do not re-create the engine, needs to be proper copy on write fork
  • have nice openrpc to start/stop/list sessions
  • log to hero_proc (optional) well chosen tags
  • QUESTION: how can we properly log all coming from engine, so we can see all real time???

make sure we follow best practices

  • skill /hero_sockets
  • skill /hero_proc_service_selfstart
  • skill /hero_ui_dashboard
  • skill /hero_proc_sdk
move functionality in this repo /Volumes/T7/code0/hero_code/crates/hero_runner_rhai remove in original repo once its here its more logical here make 2 crates - hero_runner_rhai_server - hero_runner_rhai_ui (use /hero_ui_dashboard) connect to rhai_server requirements - run with fork - minimize memory usage, do not re-create the engine, needs to be proper copy on write fork - have nice openrpc to start/stop/list sessions - log to hero_proc (optional) well chosen tags - QUESTION: how can we properly log all coming from engine, so we can see all real time??? # make sure we follow best practices - skill /hero_sockets - skill /hero_proc_service_selfstart - skill /hero_ui_dashboard - skill /hero_proc_sdk
despiegk commented 2026-04-28 02:55:17 +00:00
Author
Owner
Copy link

Implementation Spec for Issue #13 — hero_runner_rhai

Objective

Move the existing hero_runner_rhai crate from hero_code/crates/hero_runner_rhai/ into the hero_lib_rhai workspace and split it into two functional crates: hero_runner_rhai_server (the pre-fork worker pool wrapped in a Hero-compliant OpenRPC service exposing session start/stop/list with real-time log streaming) and hero_runner_rhai_ui (an Axum + Bootstrap admin dashboard following the standard hero_ui_dashboard pattern). A small third crate hero_runner_rhai provides the --start/--stop CLI per the hero_proc_service_selfstart pattern. Engine creation happens once at server startup before the tokio runtime so every session is a true copy-on-write fork(2) of an already-built engine. Logs from each forked session are piped over a dedicated log pipe to the server, fanned out via a tokio broadcast channel for SSE consumers, and optionally persisted into hero_proc with the source hero_runner_rhai_server and tags session=<id>.

Requirements

  • Move the crate from hero_code/crates/hero_runner_rhai/ to hero_lib_rhai/crates/hero_runner_rhai_server/ (source repo deletion is out of scope — see Notes).
  • Split functionality into two crates: hero_runner_rhai_server and hero_runner_rhai_ui. A third small CLI crate hero_runner_rhai owns lifecycle.
  • The UI follows the hero_ui_dashboard skill (Bootstrap 5.3.3, navbar/sidebar/tabs, /rpc proxy to the server) and connects to hero_runner_rhai_server via the SDK pattern.
  • Sessions execute in fork(2)-ed children — the engine is built once in the parent before any tokio runtime starts, so children inherit registered modules and their lazy caches via copy-on-write rather than rebuilding them.
  • Clean OpenRPC surface: session_start, session_stop, session_list, session_get, session_logs (paged), session_result, health.
  • Optional logging of every line emitted by engine.on_print / engine.on_debug to hero_proc using hero_proc_sdk with source hero_runner_rhai_server and tags session=<id>, kind=stdout|stderr — controlled per-session and via a global env flag.
  • Real-time log streaming: per-grandchild log pipe → parent demux → tokio::sync::broadcast::Sender<LogLine> → SSE on the UI (/sse/session/:id) and OpenRPC long-poll for SDK consumers, plus optional hero_proc forward.
  • Follow /hero_sockets: bind rpc.sock and ui.sock under $HERO_SOCKET_DIR/hero_runner_rhai/, expose /health, /.well-known/heroservice.json, /openrpc.json.
  • Follow /hero_proc_service_selfstart: the CLI binary owns --start/--stop; server and UI binaries are plain foreground processes with no lifecycle flags.
  • Follow /hero_proc_sdk: ActionBuilder + ServiceBuilder with is_process(), kill_other, and health checks (openrpc_socket on rpc.sock and ui.sock).
  • Workspace builds clean with cargo check --workspace; existing crates unchanged.

Files to Modify/Create

Workspace:

  • Cargo.toml (root) — add crates/hero_runner_rhai, crates/hero_runner_rhai_server, crates/hero_runner_rhai_ui to [workspace] members; add any missing entries to [workspace.dependencies] (nix, libc, axum, hyper, hyper-util, tower, askama, rust-embed, tokio-util, futures, chrono, clap, hero_proc_sdk, hero_rpc_openrpc, hero_rpc_derive).

Server crate (crates/hero_runner_rhai_server/):

  • Cargo.toml — package hero_runner_rhai_server; lib + bin hero_runner_rhai_server; deps include all herolib_*_rhai, rhai, nix, libc, serde, serde_json, tokio, axum, hyper, hyper-util, tower, tokio-util, futures, anyhow, thiserror, hero_proc_sdk, hero_rpc_openrpc, hero_rpc_derive, ureq, log, env_logger, chrono.
  • src/lib.rs — module declarations + re-exports of WorkerPool, SessionManager, SessionId, SessionStatus, LogLine, ScriptRequest, ScriptResult.
  • src/types.rs — migrated verbatim, plus new SessionInfo, SessionStatus { Pending, Running, Succeeded, Failed, Cancelled }, LogLine { session_id, timestamp_ms, kind, line }, WorkerFrame { Started { pid }, Log(LogLine), Result(ScriptResult) }.
  • src/ipc.rs — migrated verbatim (length-prefixed JSON over UnixStream).
  • src/engine.rs — migrated; register_all_modules and configure_engine_limits become the single canonical engine builder also called by the parent at startup.
  • src/resolver.rs — migrated verbatim.
  • src/worker.rs — adapted: grandchild opens a dedicated log pipe; engine on_print/on_debug write framed WorkerFrame::Log records to it; final WorkerFrame::Result ends the session; worker forwards every frame from the log pipe to its parent stream.
  • src/pool.rs — adapted: dispatch(req) -> SessionHandle returns the worker index, a live frame receiver, and a oneshot for the final ScriptResult. Parent reader thread demuxes WorkerFrame::Started, Log, and Result.
  • src/session.rs — NEW: SessionManager (Arc, RwLock<HashMap<SessionId, SessionEntry>>); start(req) -> SessionId, stop(id) (SIGTERM then SIGKILL via nix), list(), get(id), subscribe(id) -> (backfill, broadcast::Receiver<LogLine>). Per-session bounded ring buffer (default 1024 lines).
  • src/proc_log.rs — NEW: optional log forwarder using hero_proc_sdk; activated by env HERO_RUNNER_RHAI_FORWARD_LOGS=1 and per-session forward_logs flag in session_start.
  • src/openrpc.rs — NEW: OpenRPC dispatcher (POST /rpc) handling all methods; thin async functions over Arc<SessionManager>; supports batch + 204 for notifications.
  • src/openrpc.json — NEW: hand-written OpenRPC 1.x document; consumed at compile time by openrpc_client! for the SDK and served at runtime as GET /openrpc.json.
  • src/sockets.rs — NEW: socket_dir(), socket_path("hero_runner_rhai", typ), bind_unix_socket(path, axum::Router) from the hero_sockets skill.
  • src/discovery.rs — NEW: /health and /.well-known/heroservice.json handlers.
  • src/sse.rs — NEW: GET /sse/session/:id Axum SSE handler emitting one event per LogLine with event: stdout|stderr; sends ring-buffer backfill first, then live frames.
  • src/main.rs — NEW: load-bearing order — (1) env_logger::init(), (2) build canonical Engine once (warms module registries / lazy caches), (3) WorkerPool::new(N) BEFORE any tokio runtime, (4) construct tokio::runtime::Builder::new_multi_thread().enable_all().build()? and block_on(serve(pool)), (5) inside serve build SessionManager + axum::Router and bind rpc.sock (and SSE-augmented routes) via bind_unix_socket. Default N from env HERO_RUNNER_RHAI_WORKERS (default 4).
  • src/sdk.rs — NEW: hero_rpc_derive::openrpc_client!("src/openrpc.json") generates HeroRunnerRhaiServerClient. Re-exported as hero_runner_rhai_server::sdk::Client.

UI crate (crates/hero_runner_rhai_ui/):

  • Cargo.toml — package hero_runner_rhai_ui; bin hero_runner_rhai_ui; depends on hero_runner_rhai_server (path) for sdk::Client, plus axum, hyper, hyper-util, tower, tokio, askama, rust-embed, serde, serde_json, anyhow, futures, chrono. No hero_proc_sdk, no clap.
  • src/main.rs — NEW: binds ui.sock under hero_runner_rhai/; builds router with /, /health, /.well-known/heroservice.json, /rpc (proxy → server rpc.sock), /sse/session/:id (proxy → server SSE), embedded static assets.
  • src/assets.rs — NEW: rust-embed struct serving static/.
  • src/routes.rs — NEW: / (server-side aggregation via sdk::Client::session_list), /rpc proxy, /sse/session/:id proxy.
  • src/templates.rs — NEW: Askama template structs.
  • templates/base.html — NEW: navbar/footer skeleton per hero_ui_dashboard.
  • templates/index.html — NEW: tabs Sessions / Run Script / Logs / Stats / Admin / Docs.
  • templates/partials/sidebar.html — NEW: System Stats sidebar (Workers idle/busy, Sessions running/total, Memory, CPU).
  • static/css/{bootstrap.min.css,bootstrap-icons.min.css,dashboard.css} — NEW.
  • static/js/{bootstrap.bundle.min.js,dashboard.js} — NEW; dashboard.js includes rpcCall(), switchTab(), tailSession(id) SSE wiring, theme toggle.
  • static/{favicon.svg,openrpc.json} — NEW.
  • scripts/download-assets.sh — NEW: pulls Bootstrap 5.3.3 / bootstrap-icons into static/.

CLI crate (crates/hero_runner_rhai/):

  • Cargo.toml — package hero_runner_rhai; bin hero_runner_rhai; deps: hero_proc_sdk, clap (derive), tokio, anyhow. No server/UI deps.
  • src/main.rs — NEW: clap-derive CLI with --start/--stop. Resolves bin_dir = current_exe().parent(); builds two ActionBuilders (hero_runner_rhai_server, hero_runner_rhai_ui) with is_process(), interpreter("exec"), stop_signal("SIGTERM"), appropriate kill_other.socket paths, and health_checks of type openrpc_socket. ServiceBuilder::new("hero_runner_rhai") aggregates both with .requires(&["hero_proc"]). --start → hp.restart_service("hero_runner_rhai", spec, 30).await?. --stop → hp.stop_service("hero_runner_rhai", 15).await?.

Helper scripts and docs:

  • build_runner.sh (root) — builds three crates and copies binaries into ~/hero/bin/.
  • run_runner.sh (root) — builds then ~/hero/bin/hero_runner_rhai --start.
  • stop_runner.sh (root) — ~/hero/bin/hero_runner_rhai --stop.
  • docs/hero_runner_rhai.md — overview, architecture diagram, OpenRPC method list, log-streaming design.
  • crates/hero_runner_rhai*/README.md — three READMEs.
  • Update root README.md to mention the new crates in the workspace layout.

Source repo (cannot be modified by this skill):

  • /Volumes/T7/code0/hero_code/crates/hero_runner_rhai/ — flag for manual deletion in a follow-up issue against hero_code.

Implementation Plan

Step 1 — Migrate the source crate verbatim into the workspace

Files: crates/hero_runner_rhai_server/Cargo.toml, crates/hero_runner_rhai_server/src/{lib,types,ipc,engine,worker,pool,resolver}.rs, root Cargo.toml.

  • Copy every file from hero_code/crates/hero_runner_rhai/src/ into crates/hero_runner_rhai_server/src/ unchanged.
  • Copy that crate's Cargo.toml, rename name to hero_runner_rhai_server, declare [lib] and [[bin]] name = "hero_runner_rhai_server" (binary main.rs follows in Step 5).
  • Add crates/hero_runner_rhai_server to root Cargo.toml [workspace] members.
  • Add nix and libc to [workspace.dependencies] (versions matching hero_code's workspace).
  • Run cargo check -p hero_runner_rhai_server to confirm clean library compile.
  • Do not delete the source crate from hero_code (sibling repo — see Notes).
    Dependencies: none.

Step 2 — Adapt worker/grandchild for live log streaming

Files: crates/hero_runner_rhai_server/src/{types,worker,engine,pool}.rs.

  • In types.rs, add LogLine, LogKind { Stdout, Stderr }, and WorkerFrame { Started { pid }, Log(LogLine), Result(ScriptResult) } (serde-tagged enum).
  • In engine.rs, change on_print/on_debug to write a WorkerFrame::Log record into a writer fd injected at engine build time. Keep Vec<String> capture as a backstop for ScriptResult.stdout/stderr.
  • In worker.rs::grandchild_main, open a dedicated log pipe alongside the result pipe; emit WorkerFrame::Started { pid } immediately after fork; write line frames during execution; write final WorkerFrame::Result and exit.
  • In pool.rs, replace execute_blocking with a streaming dispatch(req) -> (UnboundedReceiver<WorkerFrame>, JoinHandle). Reader thread reads frames in a loop until Result(_).
    Dependencies: Step 1.

Step 3 — Build the SessionManager and broadcast log fan-out

Files: crates/hero_runner_rhai_server/src/{session,proc_log}.rs, lib.rs.

  • SessionManager { pool: Arc<WorkerPool>, sessions: RwLock<HashMap<String, SessionEntry>>, forward_to_proc: bool }.
  • SessionEntry { id, started_at, status, child_pid: Option<i32>, log_tx: broadcast::Sender<LogLine>, ring: Arc<Mutex<VecDeque<LogLine>>>, final_result: OnceCell<ScriptResult> }.
  • start(req): UUID, dispatch via pool, spawn task that consumes WorkerFrames.
  • stop(id): nix::sys::signal::kill(SIGTERM) then SIGKILL after 5s.
  • list() returns lightweight SessionInfo.
  • subscribe(id) returns (Vec<LogLine>, broadcast::Receiver<LogLine>).
  • proc_log.rs: when forwarding enabled, spawn one task per session that subscribes and pushes via hero_proc_sdk log API with source hero_runner_rhai_server and tags session=<id>, kind=stdout|stderr.
    Dependencies: Step 2.

Step 4 — Author the OpenRPC document and dispatcher

Files: crates/hero_runner_rhai_server/src/openrpc.json, openrpc.rs, sdk.rs.

  • Write openrpc.json (OpenRPC 1.2.6) with all methods.
  • Implement JsonRpcDispatcher over Arc<SessionManager>; expose axum POST /rpc; handle JSON-RPC 2.0 envelope (single + batch + notifications).
  • sdk.rs: invoke hero_rpc_derive::openrpc_client!("src/openrpc.json") → HeroRunnerRhaiServerClient. Re-export pub mod sdk; from lib.rs.
    Dependencies: Step 3.

Step 5 — Server binary, sockets, SSE, discovery, health

Files: crates/hero_runner_rhai_server/src/{main,sockets,discovery,sse}.rs.

  • sockets.rs: copy from hero_sockets skill.
  • discovery.rs: /health and /.well-known/heroservice.json.
  • sse.rs: /sse/session/:id reads from SessionManager::subscribe; sends backfill, then live frames.
  • main.rs: critical ordering — engine warm-up; WorkerPool::new(N) BEFORE any tokio runtime; manually construct multi-thread runtime via tokio::runtime::Builder and block_on(serve(pool)). Do NOT use #[tokio::main]. Add SIGTERM handler for graceful shutdown.
    Dependencies: Step 4.

Step 6 — Build the UI crate and SSE-aware dashboard

Files: crates/hero_runner_rhai_ui/Cargo.toml, src/{main,assets,routes,templates}.rs, templates/{base,index}.html, templates/partials/sidebar.html, static/{css,js,favicon.svg,openrpc.json}/..., scripts/download-assets.sh.

  • UI imports hero_runner_rhai_server::sdk::Client for server-side aggregation.
  • /rpc proxies JSON body to server rpc.sock. /sse/session/:id proxies SSE stream verbatim.
  • Tabs: Sessions (stats bar + table + Stop/Logs actions), Run Script (form → session_start), Logs (session selector + EventSource live tail), Stats, Admin (stop-all), Docs.
  • dashboard.js: rpcCall(method, params), switchTab(), tailSession(id), theme toggle.
  • Bind ui.sock under $HERO_SOCKET_DIR/hero_runner_rhai/ (same dir as server).
    Dependencies: Step 5.

Step 7 — CLI binary with --start/--stop and hero_proc registration

Files: crates/hero_runner_rhai/Cargo.toml, src/main.rs.

  • Canonical /hero_proc_service_selfstart template with two ActionBuilders aggregated by ServiceBuilder::new("hero_runner_rhai").requires(&["hero_proc"]).
  • --start → hp.restart_service("hero_runner_rhai", spec, 30). --stop → hp.stop_service("hero_runner_rhai", 15).
  • Add to workspace members.
    Dependencies: Step 6.

Step 8 — Bash helpers, docs, and final wiring

Files: build_runner.sh, run_runner.sh, stop_runner.sh, docs/hero_runner_rhai.md, three crate READMEs, root README.md.

  • Make all .sh files executable, with shebang and cd into script dir.
  • cargo check --workspace and cargo build --workspace clean.
    Dependencies: Step 7.

Acceptance Criteria

  • cargo build -p hero_runner_rhai_server succeeds.
  • cargo build -p hero_runner_rhai_ui succeeds.
  • cargo build -p hero_runner_rhai succeeds.
  • cargo check --workspace passes.
  • ~/hero/bin/hero_runner_rhai --start registers and runs both components via hero_proc; hero_proc service.list shows hero_runner_rhai healthy.
  • ~/hero/var/sockets/hero_runner_rhai/{rpc.sock, ui.sock} exist after start.
  • curl --unix-socket .../rpc.sock http://localhost/openrpc.json returns the document.
  • session_start returns a session_id; session_list includes it; session_logs returns the printed line; session_result returns success: true.
  • PIDs assertion: every running session reports a child_pid distinct from the server PID; ps -p <child_pid> confirms it.
  • Real-time streaming: curl --unix-socket .../rpc.sock http://localhost/sse/session/<id> streams stdout lines as produced (10 lines, 1/s).
  • With HERO_RUNNER_RHAI_FORWARD_LOGS=1, hero_proc log.list returns the same lines tagged session=<id>.
  • UI loads, lists sessions, allows start/stop, and tails logs live.

Notes

  • Sibling-repo deletion: the source crate is in hero_code — a different repo. This skill only modifies hero_lib_rhai. Removal from hero_code and switching its consumers to import the new path must be a follow-up commit/PR there.
  • Fork + tokio: nix::unistd::fork() after a multithreaded tokio runtime exists is undefined behaviour. Engine and WorkerPool are built BEFORE any tokio runtime; main.rs manually constructs the runtime via tokio::runtime::Builder and uses block_on. #[tokio::main] is NOT used on the server binary.
  • Real-time log streaming (answer to the issue's QUESTION): dedicated per-grandchild log pipe carrying framed WorkerFrame::Log records produced by the engine's on_print/on_debug callbacks; parent demuxes and fans out via tokio::sync::broadcast. Three consumer paths: SSE on the UI (humans), OpenRPC long-poll session_logs with after_ts cursor (SDKs), and optional hero_proc forward (durable storage). A bounded ring buffer (1024 lines) per session backs late subscribers. Preferred over redirecting fd 1/2 because Rhai callbacks are line-aware; preferred over hero_proc-only because ephemeral sessions stay in-process.
  • Per-session forwarding control: session_start accepts an optional forward_logs boolean; when set it overrides the global env flag for that session.
  • Three-crate layout: the issue asks for two crates; we add a tiny third CLI crate (hero_runner_rhai) for --start/--stop per /hero_proc_service_selfstart. The functionality lives in two crates as requested; the CLI is plumbing.
  • SDK in-crate: pub mod sdk inside the server crate avoids a fourth crate while still providing a typed client; can be extracted later without API break.
  • Engine pre-warming: building an Engine and registering all modules in the parent before fork populates the binary's resident set, lazy_static caches, and global module tables. Subsequent grandchild engine constructions are then largely COW-shared.
  • PID frame: worker emits WorkerFrame::Started { pid } immediately after each grandchild fork so the parent can kill(SIGTERM) per-session.
  • UI health-check: uses openrpc_socket on ui.sock (HTTP over UDS), not tcp_port, per /hero_sockets.
  • Workspace dep versions: match what hero_code and hero_proc already use to avoid duplicate-version explosion in Cargo.lock.
## Implementation Spec for Issue #13 — hero_runner_rhai ### Objective Move the existing `hero_runner_rhai` crate from `hero_code/crates/hero_runner_rhai/` into the `hero_lib_rhai` workspace and split it into two functional crates: `hero_runner_rhai_server` (the pre-fork worker pool wrapped in a Hero-compliant OpenRPC service exposing session start/stop/list with real-time log streaming) and `hero_runner_rhai_ui` (an Axum + Bootstrap admin dashboard following the standard `hero_ui_dashboard` pattern). A small third crate `hero_runner_rhai` provides the `--start`/`--stop` CLI per the `hero_proc_service_selfstart` pattern. Engine creation happens once at server startup before the tokio runtime so every session is a true copy-on-write `fork(2)` of an already-built engine. Logs from each forked session are piped over a dedicated log pipe to the server, fanned out via a tokio broadcast channel for SSE consumers, and optionally persisted into hero_proc with the source `hero_runner_rhai_server` and tags `session=<id>`. ### Requirements - Move the crate from `hero_code/crates/hero_runner_rhai/` to `hero_lib_rhai/crates/hero_runner_rhai_server/` (source repo deletion is out of scope — see Notes). - Split functionality into two crates: `hero_runner_rhai_server` and `hero_runner_rhai_ui`. A third small CLI crate `hero_runner_rhai` owns lifecycle. - The UI follows the `hero_ui_dashboard` skill (Bootstrap 5.3.3, navbar/sidebar/tabs, `/rpc` proxy to the server) and connects to `hero_runner_rhai_server` via the SDK pattern. - Sessions execute in `fork(2)`-ed children — the engine is built **once** in the parent before any tokio runtime starts, so children inherit registered modules and their lazy caches via copy-on-write rather than rebuilding them. - Clean OpenRPC surface: `session_start`, `session_stop`, `session_list`, `session_get`, `session_logs` (paged), `session_result`, `health`. - Optional logging of every line emitted by `engine.on_print` / `engine.on_debug` to hero_proc using `hero_proc_sdk` with source `hero_runner_rhai_server` and tags `session=<id>`, `kind=stdout|stderr` — controlled per-session and via a global env flag. - Real-time log streaming: per-grandchild log pipe → parent demux → `tokio::sync::broadcast::Sender<LogLine>` → SSE on the UI (`/sse/session/:id`) and OpenRPC long-poll for SDK consumers, plus optional hero_proc forward. - Follow `/hero_sockets`: bind `rpc.sock` and `ui.sock` under `$HERO_SOCKET_DIR/hero_runner_rhai/`, expose `/health`, `/.well-known/heroservice.json`, `/openrpc.json`. - Follow `/hero_proc_service_selfstart`: the CLI binary owns `--start`/`--stop`; server and UI binaries are plain foreground processes with no lifecycle flags. - Follow `/hero_proc_sdk`: `ActionBuilder` + `ServiceBuilder` with `is_process()`, `kill_other`, and health checks (openrpc_socket on `rpc.sock` and `ui.sock`). - Workspace builds clean with `cargo check --workspace`; existing crates unchanged. ### Files to Modify/Create Workspace: - `Cargo.toml` (root) — add `crates/hero_runner_rhai`, `crates/hero_runner_rhai_server`, `crates/hero_runner_rhai_ui` to `[workspace] members`; add any missing entries to `[workspace.dependencies]` (`nix`, `libc`, `axum`, `hyper`, `hyper-util`, `tower`, `askama`, `rust-embed`, `tokio-util`, `futures`, `chrono`, `clap`, `hero_proc_sdk`, `hero_rpc_openrpc`, `hero_rpc_derive`). Server crate (`crates/hero_runner_rhai_server/`): - `Cargo.toml` — package `hero_runner_rhai_server`; lib + bin `hero_runner_rhai_server`; deps include all `herolib_*_rhai`, `rhai`, `nix`, `libc`, `serde`, `serde_json`, `tokio`, `axum`, `hyper`, `hyper-util`, `tower`, `tokio-util`, `futures`, `anyhow`, `thiserror`, `hero_proc_sdk`, `hero_rpc_openrpc`, `hero_rpc_derive`, `ureq`, `log`, `env_logger`, `chrono`. - `src/lib.rs` — module declarations + re-exports of `WorkerPool`, `SessionManager`, `SessionId`, `SessionStatus`, `LogLine`, `ScriptRequest`, `ScriptResult`. - `src/types.rs` — migrated verbatim, plus new `SessionInfo`, `SessionStatus { Pending, Running, Succeeded, Failed, Cancelled }`, `LogLine { session_id, timestamp_ms, kind, line }`, `WorkerFrame { Started { pid }, Log(LogLine), Result(ScriptResult) }`. - `src/ipc.rs` — migrated verbatim (length-prefixed JSON over UnixStream). - `src/engine.rs` — migrated; `register_all_modules` and `configure_engine_limits` become the single canonical engine builder also called by the parent at startup. - `src/resolver.rs` — migrated verbatim. - `src/worker.rs` — adapted: grandchild opens a dedicated log pipe; engine `on_print`/`on_debug` write framed `WorkerFrame::Log` records to it; final `WorkerFrame::Result` ends the session; worker forwards every frame from the log pipe to its parent stream. - `src/pool.rs` — adapted: `dispatch(req) -> SessionHandle` returns the worker index, a live frame receiver, and a oneshot for the final `ScriptResult`. Parent reader thread demuxes `WorkerFrame::Started`, `Log`, and `Result`. - `src/session.rs` — NEW: `SessionManager` (Arc, RwLock<HashMap<SessionId, SessionEntry>>); `start(req) -> SessionId`, `stop(id)` (SIGTERM then SIGKILL via `nix`), `list()`, `get(id)`, `subscribe(id) -> (backfill, broadcast::Receiver<LogLine>)`. Per-session bounded ring buffer (default 1024 lines). - `src/proc_log.rs` — NEW: optional log forwarder using `hero_proc_sdk`; activated by env `HERO_RUNNER_RHAI_FORWARD_LOGS=1` and per-session `forward_logs` flag in `session_start`. - `src/openrpc.rs` — NEW: OpenRPC dispatcher (`POST /rpc`) handling all methods; thin async functions over `Arc<SessionManager>`; supports batch + 204 for notifications. - `src/openrpc.json` — NEW: hand-written OpenRPC 1.x document; consumed at compile time by `openrpc_client!` for the SDK and served at runtime as `GET /openrpc.json`. - `src/sockets.rs` — NEW: `socket_dir()`, `socket_path("hero_runner_rhai", typ)`, `bind_unix_socket(path, axum::Router)` from the `hero_sockets` skill. - `src/discovery.rs` — NEW: `/health` and `/.well-known/heroservice.json` handlers. - `src/sse.rs` — NEW: `GET /sse/session/:id` Axum SSE handler emitting one event per `LogLine` with `event: stdout|stderr`; sends ring-buffer backfill first, then live frames. - `src/main.rs` — NEW: load-bearing order — (1) `env_logger::init()`, (2) build canonical `Engine` once (warms module registries / lazy caches), (3) `WorkerPool::new(N)` BEFORE any tokio runtime, (4) construct `tokio::runtime::Builder::new_multi_thread().enable_all().build()?` and `block_on(serve(pool))`, (5) inside `serve` build `SessionManager` + `axum::Router` and bind `rpc.sock` (and SSE-augmented routes) via `bind_unix_socket`. Default `N` from env `HERO_RUNNER_RHAI_WORKERS` (default 4). - `src/sdk.rs` — NEW: `hero_rpc_derive::openrpc_client!("src/openrpc.json")` generates `HeroRunnerRhaiServerClient`. Re-exported as `hero_runner_rhai_server::sdk::Client`. UI crate (`crates/hero_runner_rhai_ui/`): - `Cargo.toml` — package `hero_runner_rhai_ui`; bin `hero_runner_rhai_ui`; depends on `hero_runner_rhai_server` (path) for `sdk::Client`, plus `axum`, `hyper`, `hyper-util`, `tower`, `tokio`, `askama`, `rust-embed`, `serde`, `serde_json`, `anyhow`, `futures`, `chrono`. No `hero_proc_sdk`, no `clap`. - `src/main.rs` — NEW: binds `ui.sock` under `hero_runner_rhai/`; builds router with `/`, `/health`, `/.well-known/heroservice.json`, `/rpc` (proxy → server `rpc.sock`), `/sse/session/:id` (proxy → server SSE), embedded static assets. - `src/assets.rs` — NEW: `rust-embed` struct serving `static/`. - `src/routes.rs` — NEW: `/` (server-side aggregation via `sdk::Client::session_list`), `/rpc` proxy, `/sse/session/:id` proxy. - `src/templates.rs` — NEW: Askama template structs. - `templates/base.html` — NEW: navbar/footer skeleton per `hero_ui_dashboard`. - `templates/index.html` — NEW: tabs Sessions / Run Script / Logs / Stats / Admin / Docs. - `templates/partials/sidebar.html` — NEW: System Stats sidebar (Workers idle/busy, Sessions running/total, Memory, CPU). - `static/css/{bootstrap.min.css,bootstrap-icons.min.css,dashboard.css}` — NEW. - `static/js/{bootstrap.bundle.min.js,dashboard.js}` — NEW; `dashboard.js` includes `rpcCall()`, `switchTab()`, `tailSession(id)` SSE wiring, theme toggle. - `static/{favicon.svg,openrpc.json}` — NEW. - `scripts/download-assets.sh` — NEW: pulls Bootstrap 5.3.3 / bootstrap-icons into `static/`. CLI crate (`crates/hero_runner_rhai/`): - `Cargo.toml` — package `hero_runner_rhai`; bin `hero_runner_rhai`; deps: `hero_proc_sdk`, `clap` (derive), `tokio`, `anyhow`. No server/UI deps. - `src/main.rs` — NEW: clap-derive CLI with `--start`/`--stop`. Resolves `bin_dir = current_exe().parent()`; builds two `ActionBuilder`s (`hero_runner_rhai_server`, `hero_runner_rhai_ui`) with `is_process()`, `interpreter("exec")`, `stop_signal("SIGTERM")`, appropriate `kill_other.socket` paths, and `health_checks` of type `openrpc_socket`. `ServiceBuilder::new("hero_runner_rhai")` aggregates both with `.requires(&["hero_proc"])`. `--start` → `hp.restart_service("hero_runner_rhai", spec, 30).await?`. `--stop` → `hp.stop_service("hero_runner_rhai", 15).await?`. Helper scripts and docs: - `build_runner.sh` (root) — builds three crates and copies binaries into `~/hero/bin/`. - `run_runner.sh` (root) — builds then `~/hero/bin/hero_runner_rhai --start`. - `stop_runner.sh` (root) — `~/hero/bin/hero_runner_rhai --stop`. - `docs/hero_runner_rhai.md` — overview, architecture diagram, OpenRPC method list, log-streaming design. - `crates/hero_runner_rhai*/README.md` — three READMEs. - Update root `README.md` to mention the new crates in the workspace layout. Source repo (cannot be modified by this skill): - `/Volumes/T7/code0/hero_code/crates/hero_runner_rhai/` — flag for manual deletion in a follow-up issue against `hero_code`. ### Implementation Plan #### Step 1 — Migrate the source crate verbatim into the workspace Files: `crates/hero_runner_rhai_server/Cargo.toml`, `crates/hero_runner_rhai_server/src/{lib,types,ipc,engine,worker,pool,resolver}.rs`, root `Cargo.toml`. - Copy every file from `hero_code/crates/hero_runner_rhai/src/` into `crates/hero_runner_rhai_server/src/` unchanged. - Copy that crate's `Cargo.toml`, rename `name` to `hero_runner_rhai_server`, declare `[lib]` and `[[bin]] name = "hero_runner_rhai_server"` (binary `main.rs` follows in Step 5). - Add `crates/hero_runner_rhai_server` to root `Cargo.toml` `[workspace] members`. - Add `nix` and `libc` to `[workspace.dependencies]` (versions matching `hero_code`'s workspace). - Run `cargo check -p hero_runner_rhai_server` to confirm clean library compile. - Do not delete the source crate from `hero_code` (sibling repo — see Notes). Dependencies: none. #### Step 2 — Adapt worker/grandchild for live log streaming Files: `crates/hero_runner_rhai_server/src/{types,worker,engine,pool}.rs`. - In `types.rs`, add `LogLine`, `LogKind { Stdout, Stderr }`, and `WorkerFrame { Started { pid }, Log(LogLine), Result(ScriptResult) }` (serde-tagged enum). - In `engine.rs`, change `on_print`/`on_debug` to write a `WorkerFrame::Log` record into a writer fd injected at engine build time. Keep `Vec<String>` capture as a backstop for `ScriptResult.stdout/stderr`. - In `worker.rs::grandchild_main`, open a dedicated log pipe alongside the result pipe; emit `WorkerFrame::Started { pid }` immediately after fork; write line frames during execution; write final `WorkerFrame::Result` and exit. - In `pool.rs`, replace `execute_blocking` with a streaming `dispatch(req) -> (UnboundedReceiver<WorkerFrame>, JoinHandle)`. Reader thread reads frames in a loop until `Result(_)`. Dependencies: Step 1. #### Step 3 — Build the SessionManager and broadcast log fan-out Files: `crates/hero_runner_rhai_server/src/{session,proc_log}.rs`, `lib.rs`. - `SessionManager { pool: Arc<WorkerPool>, sessions: RwLock<HashMap<String, SessionEntry>>, forward_to_proc: bool }`. - `SessionEntry { id, started_at, status, child_pid: Option<i32>, log_tx: broadcast::Sender<LogLine>, ring: Arc<Mutex<VecDeque<LogLine>>>, final_result: OnceCell<ScriptResult> }`. - `start(req)`: UUID, dispatch via pool, spawn task that consumes `WorkerFrame`s. - `stop(id)`: `nix::sys::signal::kill(SIGTERM)` then SIGKILL after 5s. - `list()` returns lightweight `SessionInfo`. - `subscribe(id)` returns `(Vec<LogLine>, broadcast::Receiver<LogLine>)`. - `proc_log.rs`: when forwarding enabled, spawn one task per session that subscribes and pushes via `hero_proc_sdk` log API with source `hero_runner_rhai_server` and tags `session=<id>`, `kind=stdout|stderr`. Dependencies: Step 2. #### Step 4 — Author the OpenRPC document and dispatcher Files: `crates/hero_runner_rhai_server/src/openrpc.json`, `openrpc.rs`, `sdk.rs`. - Write `openrpc.json` (OpenRPC 1.2.6) with all methods. - Implement `JsonRpcDispatcher` over `Arc<SessionManager>`; expose `axum` `POST /rpc`; handle JSON-RPC 2.0 envelope (single + batch + notifications). - `sdk.rs`: invoke `hero_rpc_derive::openrpc_client!("src/openrpc.json")` → `HeroRunnerRhaiServerClient`. Re-export `pub mod sdk;` from `lib.rs`. Dependencies: Step 3. #### Step 5 — Server binary, sockets, SSE, discovery, health Files: `crates/hero_runner_rhai_server/src/{main,sockets,discovery,sse}.rs`. - `sockets.rs`: copy from `hero_sockets` skill. - `discovery.rs`: `/health` and `/.well-known/heroservice.json`. - `sse.rs`: `/sse/session/:id` reads from `SessionManager::subscribe`; sends backfill, then live frames. - `main.rs`: critical ordering — engine warm-up; `WorkerPool::new(N)` BEFORE any tokio runtime; manually construct multi-thread runtime via `tokio::runtime::Builder` and `block_on(serve(pool))`. Do NOT use `#[tokio::main]`. Add SIGTERM handler for graceful shutdown. Dependencies: Step 4. #### Step 6 — Build the UI crate and SSE-aware dashboard Files: `crates/hero_runner_rhai_ui/Cargo.toml`, `src/{main,assets,routes,templates}.rs`, `templates/{base,index}.html`, `templates/partials/sidebar.html`, `static/{css,js,favicon.svg,openrpc.json}/...`, `scripts/download-assets.sh`. - UI imports `hero_runner_rhai_server::sdk::Client` for server-side aggregation. - `/rpc` proxies JSON body to server `rpc.sock`. `/sse/session/:id` proxies SSE stream verbatim. - Tabs: Sessions (stats bar + table + Stop/Logs actions), Run Script (form → `session_start`), Logs (session selector + EventSource live tail), Stats, Admin (stop-all), Docs. - `dashboard.js`: `rpcCall(method, params)`, `switchTab()`, `tailSession(id)`, theme toggle. - Bind `ui.sock` under `$HERO_SOCKET_DIR/hero_runner_rhai/` (same dir as server). Dependencies: Step 5. #### Step 7 — CLI binary with --start/--stop and hero_proc registration Files: `crates/hero_runner_rhai/Cargo.toml`, `src/main.rs`. - Canonical `/hero_proc_service_selfstart` template with two `ActionBuilder`s aggregated by `ServiceBuilder::new("hero_runner_rhai").requires(&["hero_proc"])`. - `--start` → `hp.restart_service("hero_runner_rhai", spec, 30)`. `--stop` → `hp.stop_service("hero_runner_rhai", 15)`. - Add to workspace members. Dependencies: Step 6. #### Step 8 — Bash helpers, docs, and final wiring Files: `build_runner.sh`, `run_runner.sh`, `stop_runner.sh`, `docs/hero_runner_rhai.md`, three crate READMEs, root `README.md`. - Make all `.sh` files executable, with shebang and `cd` into script dir. - `cargo check --workspace` and `cargo build --workspace` clean. Dependencies: Step 7. ### Acceptance Criteria - [ ] `cargo build -p hero_runner_rhai_server` succeeds. - [ ] `cargo build -p hero_runner_rhai_ui` succeeds. - [ ] `cargo build -p hero_runner_rhai` succeeds. - [ ] `cargo check --workspace` passes. - [ ] `~/hero/bin/hero_runner_rhai --start` registers and runs both components via hero_proc; `hero_proc service.list` shows `hero_runner_rhai` healthy. - [ ] `~/hero/var/sockets/hero_runner_rhai/{rpc.sock, ui.sock}` exist after start. - [ ] `curl --unix-socket .../rpc.sock http://localhost/openrpc.json` returns the document. - [ ] `session_start` returns a `session_id`; `session_list` includes it; `session_logs` returns the printed line; `session_result` returns `success: true`. - [ ] PIDs assertion: every running session reports a `child_pid` distinct from the server PID; `ps -p <child_pid>` confirms it. - [ ] Real-time streaming: `curl --unix-socket .../rpc.sock http://localhost/sse/session/<id>` streams stdout lines as produced (10 lines, 1/s). - [ ] With `HERO_RUNNER_RHAI_FORWARD_LOGS=1`, `hero_proc log.list` returns the same lines tagged `session=<id>`. - [ ] UI loads, lists sessions, allows start/stop, and tails logs live. ### Notes - **Sibling-repo deletion:** the source crate is in `hero_code` — a different repo. This skill only modifies `hero_lib_rhai`. Removal from `hero_code` and switching its consumers to import the new path must be a follow-up commit/PR there. - **Fork + tokio:** `nix::unistd::fork()` after a multithreaded tokio runtime exists is undefined behaviour. Engine and `WorkerPool` are built BEFORE any tokio runtime; `main.rs` manually constructs the runtime via `tokio::runtime::Builder` and uses `block_on`. `#[tokio::main]` is NOT used on the server binary. - **Real-time log streaming (answer to the issue's QUESTION):** dedicated per-grandchild log pipe carrying framed `WorkerFrame::Log` records produced by the engine's `on_print`/`on_debug` callbacks; parent demuxes and fans out via `tokio::sync::broadcast`. Three consumer paths: SSE on the UI (humans), OpenRPC long-poll `session_logs` with `after_ts` cursor (SDKs), and optional hero_proc forward (durable storage). A bounded ring buffer (1024 lines) per session backs late subscribers. Preferred over redirecting fd 1/2 because Rhai callbacks are line-aware; preferred over hero_proc-only because ephemeral sessions stay in-process. - **Per-session forwarding control:** `session_start` accepts an optional `forward_logs` boolean; when set it overrides the global env flag for that session. - **Three-crate layout:** the issue asks for two crates; we add a tiny third CLI crate (`hero_runner_rhai`) for `--start`/`--stop` per `/hero_proc_service_selfstart`. The functionality lives in two crates as requested; the CLI is plumbing. - **SDK in-crate:** `pub mod sdk` inside the server crate avoids a fourth crate while still providing a typed client; can be extracted later without API break. - **Engine pre-warming:** building an `Engine` and registering all modules in the parent before fork populates the binary's resident set, lazy_static caches, and global module tables. Subsequent grandchild engine constructions are then largely COW-shared. - **PID frame:** worker emits `WorkerFrame::Started { pid }` immediately after each grandchild fork so the parent can `kill(SIGTERM)` per-session. - **UI health-check:** uses `openrpc_socket` on `ui.sock` (HTTP over UDS), not `tcp_port`, per `/hero_sockets`. - **Workspace dep versions:** match what `hero_code` and `hero_proc` already use to avoid duplicate-version explosion in `Cargo.lock`.
despiegk commented 2026-04-28 04:51:52 +00:00
Author
Owner
Copy link

Test Results

Workspace cargo test

  • Total tests: 116
  • Passed: 110
  • Failed: 0
  • Ignored: 6

New crates

The three new crates (hero_runner_rhai, hero_runner_rhai_server, hero_runner_rhai_ui) currently have no unit tests. Validation in this phase:

  • cargo build --workspace — Finished (no errors).
  • cargo check --workspace --all-targets — Finished (1 pre-existing warning in crates/hero_runner_rhai_server/src/resolver.rs::fetch_content, migrated verbatim from the source crate).
  • All three binaries produced.

Failures (if any)

None

Notes

  • Live integration validation (forking workers, OpenRPC over UDS, SSE log streaming, hero_proc registration) requires a running hero_proc and is out of scope for cargo test. Recommended manual smoke test: ./build_runner.sh && ./run_runner.sh, then exercise OpenRPC via curl --unix-socket ~/hero/var/sockets/hero_runner_rhai/rpc.sock.
## Test Results ### Workspace cargo test - Total tests: 116 - Passed: 110 - Failed: 0 - Ignored: 6 ### New crates The three new crates (`hero_runner_rhai`, `hero_runner_rhai_server`, `hero_runner_rhai_ui`) currently have no unit tests. Validation in this phase: - `cargo build --workspace` — Finished (no errors). - `cargo check --workspace --all-targets` — Finished (1 pre-existing warning in `crates/hero_runner_rhai_server/src/resolver.rs::fetch_content`, migrated verbatim from the source crate). - All three binaries produced. ### Failures (if any) None ### Notes - Live integration validation (forking workers, OpenRPC over UDS, SSE log streaming, hero_proc registration) requires a running hero_proc and is out of scope for `cargo test`. Recommended manual smoke test: `./build_runner.sh && ./run_runner.sh`, then exercise OpenRPC via `curl --unix-socket ~/hero/var/sockets/hero_runner_rhai/rpc.sock`.
despiegk commented 2026-04-28 04:53:50 +00:00
Author
Owner
Copy link

Implementation Complete

Crates added

  • crates/hero_runner_rhai — CLI lifecycle binary (--start/--stop) that registers the runner with hero_proc.
  • crates/hero_runner_rhai_server — fork-based Rhai runner with OpenRPC over UDS, SSE live log streaming, optional hero_proc log forwarding, and an embedded SDK module for in-process callers.
  • crates/hero_runner_rhai_ui — Bootstrap 5 admin dashboard with six tabs (Sessions, Run Script, Logs, Stats, Admin, Docs), proxying /rpc and /sse to the server over UDS.

Files added (high level)

  • Workspace: 3 new members; new [workspace.dependencies] entries for nix, libc, uuid, axum, tower, tokio-stream, futures, askama, rust-embed, mime_guess, hyper, hyper-util, http-body-util, chrono, clap, hero_proc_sdk, hero_rpc_openrpc.
  • crates/hero_runner_rhai_server/src/{types.rs, ipc.rs, engine.rs, resolver.rs, worker.rs, pool.rs} — migrated verbatim from hero_code/crates/hero_runner_rhai/, then refactored.
  • crates/hero_runner_rhai_server/src/{session.rs, proc_log.rs, openrpc.rs, openrpc.json, sdk.rs, sockets.rs, discovery.rs, sse.rs, main.rs} — new modules.
  • crates/hero_runner_rhai_ui/src/{main.rs, routes.rs, proxy.rs, templates.rs, assets.rs}, templates/{base.html, index.html, partials/sidebar.html}, static/{css,js,favicon.svg,openrpc.json}, scripts/download-assets.sh.
  • crates/hero_runner_rhai/src/main.rs.
  • Root: build_runner.sh, run_runner.sh, stop_runner.sh.
  • Docs: docs/hero_runner_rhai.md; three crate READMEs; updated root README.md.

Architecture decisions

  • Fork model is preserved. WorkerPool::new(N) is called BEFORE any tokio runtime exists in hero_runner_rhai_server main.rs. The runtime is constructed manually via tokio::runtime::Builder::new_multi_thread().enable_all().build()? and block_on(serve(pool)). #[tokio::main] is NOT used on the server binary.
  • Engine warm-up at parent startup. Before WorkerPool::new, the parent builds and drops a canonical Engine so that all register_all_modules paths and any lazy_static / global tables in herolib_*_rhai are resident in the binary's process image. Subsequent grandchild engine constructions are cheap because those globals are inherited via copy-on-write.
  • Live log streaming. Each grandchild emits WorkerFrame::Started { pid }, then a stream of WorkerFrame::Log { line } while the script runs, then a final WorkerFrame::Result { result }. The worker forwards every frame to the parent over its existing UnixStream. The parent's SessionManager fans out via tokio::sync::broadcast::Sender<LogLine> and a per-session ring buffer (1024 lines) so late subscribers can backfill. Three consumer paths: SSE on /sse/session/{id} for the UI, OpenRPC session_logs long-poll for SDK consumers, and an optional hero_proc log forwarder enabled by HERO_RUNNER_RHAI_FORWARD_LOGS=1 or per-session forward_logs: true.
  • Three-crate layout. The issue asked for two crates; we added a small CLI crate (hero_runner_rhai) for lifecycle per hero_proc_service_selfstart. Functionality lives in the two requested crates; the CLI is plumbing.
  • SDK in-crate. hero_runner_rhai_server::sdk::Client is hand-rolled over hero_rpc_openrpc::OpenRpcTransport::unix_socket rather than auto-generated via openrpc_client!, to avoid name-colliding parallel types and to keep Option<ScriptResult> returns ergonomic. Can be extracted into a separate crate later without API break.

OpenRPC method surface

  • health — service status
  • session_start({ script, working_dir?, env_vars?, timeout_ms?, forward_logs? }) -> { session_id }
  • session_stop({ session_id }) -> { ok } — sends SIGTERM, then SIGKILL after 5 s
  • session_list() -> { sessions: SessionInfo[] }
  • session_get({ session_id }) -> SessionInfo
  • session_logs({ session_id, after_ts_ms?, limit? }) -> { lines, next_ts_ms }
  • session_result({ session_id }) -> ScriptResult | null

Tests

  • cargo test --workspace --no-fail-fast: 110 passed, 0 failed, 6 ignored. No regressions; full results posted in the previous comment.
  • The three new crates have no unit tests; the source crate did not ship any. Live validation (forking workers, OpenRPC over UDS, SSE streaming, hero_proc registration) requires a running hero_proc and a manual smoke run via ./build_runner.sh && ./run_runner.sh.

Pre-existing workspace breakage repaired in passing

The development branch was already broken before this PR — cargo check --workspace --lib failed with forge_token and inputs field errors against stale cached revs of hero_proc_sdk and herolib_tools. A cargo update -p hero_proc_sdk to rev e1898890 resolved both errors transitively. No source edits to proc_rhai/src/secrets.rs were needed.

Follow-up required in the source repo (out of scope here)

The original crate at /Volumes/T7/code0/hero_code/crates/hero_runner_rhai/ is untouched. A separate commit/PR in hero_code should:

  1. Delete crates/hero_runner_rhai/ from hero_code.
  2. Switch any hero_code consumers (if any) to import the new path: hero_runner_rhai_server from hero_lib_rhai.

Build & run

./build_runner.sh                # release build, install to ~/hero/bin
./run_runner.sh                  # build + start via hero_proc
./stop_runner.sh                 # stop via hero_proc

OpenRPC smoke test (hero_proc must be running):

curl --unix-socket ~/hero/var/sockets/hero_runner_rhai/rpc.sock \
     http://localhost/openrpc.json
curl --unix-socket ~/hero/var/sockets/hero_runner_rhai/rpc.sock \
     -X POST -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"session_start","params":{"script":"print(\"hi\");"}}' \
     http://localhost/rpc

UI is reachable at ~/hero/var/sockets/hero_runner_rhai/ui.sock (typically exposed via hero_router).

## Implementation Complete ### Crates added - `crates/hero_runner_rhai` — CLI lifecycle binary (`--start`/`--stop`) that registers the runner with hero_proc. - `crates/hero_runner_rhai_server` — fork-based Rhai runner with OpenRPC over UDS, SSE live log streaming, optional hero_proc log forwarding, and an embedded SDK module for in-process callers. - `crates/hero_runner_rhai_ui` — Bootstrap 5 admin dashboard with six tabs (Sessions, Run Script, Logs, Stats, Admin, Docs), proxying `/rpc` and `/sse` to the server over UDS. ### Files added (high level) - Workspace: 3 new `members`; new `[workspace.dependencies]` entries for `nix`, `libc`, `uuid`, `axum`, `tower`, `tokio-stream`, `futures`, `askama`, `rust-embed`, `mime_guess`, `hyper`, `hyper-util`, `http-body-util`, `chrono`, `clap`, `hero_proc_sdk`, `hero_rpc_openrpc`. - `crates/hero_runner_rhai_server/src/{types.rs, ipc.rs, engine.rs, resolver.rs, worker.rs, pool.rs}` — migrated verbatim from `hero_code/crates/hero_runner_rhai/`, then refactored. - `crates/hero_runner_rhai_server/src/{session.rs, proc_log.rs, openrpc.rs, openrpc.json, sdk.rs, sockets.rs, discovery.rs, sse.rs, main.rs}` — new modules. - `crates/hero_runner_rhai_ui/src/{main.rs, routes.rs, proxy.rs, templates.rs, assets.rs}`, `templates/{base.html, index.html, partials/sidebar.html}`, `static/{css,js,favicon.svg,openrpc.json}`, `scripts/download-assets.sh`. - `crates/hero_runner_rhai/src/main.rs`. - Root: `build_runner.sh`, `run_runner.sh`, `stop_runner.sh`. - Docs: `docs/hero_runner_rhai.md`; three crate READMEs; updated root `README.md`. ### Architecture decisions - **Fork model is preserved.** `WorkerPool::new(N)` is called BEFORE any tokio runtime exists in `hero_runner_rhai_server` `main.rs`. The runtime is constructed manually via `tokio::runtime::Builder::new_multi_thread().enable_all().build()?` and `block_on(serve(pool))`. `#[tokio::main]` is NOT used on the server binary. - **Engine warm-up at parent startup.** Before `WorkerPool::new`, the parent builds and drops a canonical `Engine` so that all `register_all_modules` paths and any `lazy_static` / global tables in `herolib_*_rhai` are resident in the binary's process image. Subsequent grandchild engine constructions are cheap because those globals are inherited via copy-on-write. - **Live log streaming.** Each grandchild emits `WorkerFrame::Started { pid }`, then a stream of `WorkerFrame::Log { line }` while the script runs, then a final `WorkerFrame::Result { result }`. The worker forwards every frame to the parent over its existing UnixStream. The parent's `SessionManager` fans out via `tokio::sync::broadcast::Sender<LogLine>` and a per-session ring buffer (1024 lines) so late subscribers can backfill. Three consumer paths: SSE on `/sse/session/{id}` for the UI, OpenRPC `session_logs` long-poll for SDK consumers, and an optional hero_proc log forwarder enabled by `HERO_RUNNER_RHAI_FORWARD_LOGS=1` or per-session `forward_logs: true`. - **Three-crate layout.** The issue asked for two crates; we added a small CLI crate (`hero_runner_rhai`) for lifecycle per `hero_proc_service_selfstart`. Functionality lives in the two requested crates; the CLI is plumbing. - **SDK in-crate.** `hero_runner_rhai_server::sdk::Client` is hand-rolled over `hero_rpc_openrpc::OpenRpcTransport::unix_socket` rather than auto-generated via `openrpc_client!`, to avoid name-colliding parallel types and to keep `Option<ScriptResult>` returns ergonomic. Can be extracted into a separate crate later without API break. ### OpenRPC method surface - `health` — service status - `session_start({ script, working_dir?, env_vars?, timeout_ms?, forward_logs? }) -> { session_id }` - `session_stop({ session_id }) -> { ok }` — sends SIGTERM, then SIGKILL after 5 s - `session_list() -> { sessions: SessionInfo[] }` - `session_get({ session_id }) -> SessionInfo` - `session_logs({ session_id, after_ts_ms?, limit? }) -> { lines, next_ts_ms }` - `session_result({ session_id }) -> ScriptResult | null` ### Tests - `cargo test --workspace --no-fail-fast`: 110 passed, 0 failed, 6 ignored. No regressions; full results posted in the previous comment. - The three new crates have no unit tests; the source crate did not ship any. Live validation (forking workers, OpenRPC over UDS, SSE streaming, hero_proc registration) requires a running hero_proc and a manual smoke run via `./build_runner.sh && ./run_runner.sh`. ### Pre-existing workspace breakage repaired in passing The `development` branch was already broken before this PR — `cargo check --workspace --lib` failed with `forge_token` and `inputs` field errors against stale cached revs of `hero_proc_sdk` and `herolib_tools`. A `cargo update -p hero_proc_sdk` to rev `e1898890` resolved both errors transitively. No source edits to `proc_rhai/src/secrets.rs` were needed. ### Follow-up required in the source repo (out of scope here) The original crate at `/Volumes/T7/code0/hero_code/crates/hero_runner_rhai/` is untouched. A separate commit/PR in `hero_code` should: 1. Delete `crates/hero_runner_rhai/` from `hero_code`. 2. Switch any `hero_code` consumers (if any) to import the new path: `hero_runner_rhai_server` from `hero_lib_rhai`. ### Build & run ``` ./build_runner.sh # release build, install to ~/hero/bin ./run_runner.sh # build + start via hero_proc ./stop_runner.sh # stop via hero_proc ``` OpenRPC smoke test (hero_proc must be running): ``` curl --unix-socket ~/hero/var/sockets/hero_runner_rhai/rpc.sock \ http://localhost/openrpc.json curl --unix-socket ~/hero/var/sockets/hero_runner_rhai/rpc.sock \ -X POST -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"session_start","params":{"script":"print(\"hi\");"}}' \ http://localhost/rpc ``` UI is reachable at `~/hero/var/sockets/hero_runner_rhai/ui.sock` (typically exposed via hero_router).
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_casper
development_8
main
No results found.
Labels
Clear labels   
prio_critical

   
prio_low

   
type_bug

   
type_contact

   
type_issue

   
type_lead

   
type_question

   
type_story

   
type_task
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_lib_rhai#13
No description provided.