89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
|
# Runa VS Code client
|
||
|
|
|
||
|
|
This is the first, read-only client for a trusted localhost Runa image. It uses
|
||
|
|
the [version 3 JSON-lines protocol](../docs/protocol.md), not Rust APIs, and never
|
||
|
|
hosts actors or starts its own image.
|
||
|
|
|
||
|
|
## Run from source
|
||
|
|
|
||
|
|
Requirements: VS Code 1.96+, Node.js 22+, npm, and the repository's Rust toolchain.
|
||
|
|
|
||
|
|
From the repository root:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
npm --prefix vscode ci
|
||
|
|
mise run serve-network
|
||
|
|
```
|
||
|
|
|
||
|
|
Open the repository in VS Code. In Run and Debug, select **Run Runa Extension**
|
||
|
|
and press F5. The launch task compiles TypeScript before opening an Extension
|
||
|
|
Development Host.
|
||
|
|
|
||
|
|
In that host:
|
||
|
|
|
||
|
|
1. Run **Runa: Connect to Local Image**. The default is `127.0.0.1:3737`;
|
||
|
|
`runa.address` changes the suggested endpoint.
|
||
|
|
2. Expand **Runa Actors** in Explorer. Use the REPL (`mise run start`) to
|
||
|
|
spawn actors in the same server, then run **Runa: Refresh Actors**.
|
||
|
|
3. Click an actor or run **Runa: Inspect Actor** to open its JSON snapshot.
|
||
|
|
4. Run **Runa: Disconnect** to close only this client connection.
|
||
|
|
|
||
|
|
Connection prompts accept numeric IPv4 loopback addresses (`127.x.x.x`) or
|
||
|
|
`[::1]:port`. DNS names, wildcard addresses, remote addresses, and IPv4-mapped
|
||
|
|
IPv6 addresses are rejected. There is no authentication: connect only to a
|
||
|
|
trusted local server. In a remote VS Code window, localhost refers to the
|
||
|
|
machine running the extension host, not necessarily the desktop.
|
||
|
|
|
||
|
|
## Snapshot semantics
|
||
|
|
|
||
|
|
- The tree shows actor references, lifecycle status, and queued/reserved counts.
|
||
|
|
Tooltips include implementation ID, incarnation, and failure text.
|
||
|
|
- Inspect fetches a fresh snapshot through `inspect_actor`. Documents show
|
||
|
|
committed state, FIFO queued messages, the reserved message, status, and
|
||
|
|
active-execution telemetry. Tagged values distinguish actor references from
|
||
|
|
strings and preserve signed 64-bit integers exactly.
|
||
|
|
- Documents are read-only snapshots, not editable actor state or live VM frames.
|
||
|
|
The timestamp records when this client received the data, not a runtime clock.
|
||
|
|
**Refresh Actors** updates the tree and existing documents for that connection.
|
||
|
|
- Open documents are retained and marked `connected: false` on disconnect.
|
||
|
|
Each connection gets distinct document URIs; reconnecting never replaces
|
||
|
|
snapshots from an earlier connection or another image. Closing a document
|
||
|
|
releases its cache; snapshots are not persisted across VS Code restarts.
|
||
|
|
- There is no auto-connect, polling, automatic reconnect, or request retry.
|
||
|
|
Timeout, peer disconnect, malformed data, and version/correlation failures
|
||
|
|
invalidate the connection and are surfaced in a notification and the **Runa**
|
||
|
|
output channel. Server-reported operation errors leave the connection usable.
|
||
|
|
- The client does not tick the scheduler, drain `get_events`, spawn/send, or
|
||
|
|
change actor lifecycle/behavior. Use the REPL for those operations.
|
||
|
|
|
||
|
|
For automation, the `runa.connect` command also accepts an explicit endpoint
|
||
|
|
string, and `runa.inspect` accepts an object with an `actor_ref` field.
|
||
|
|
|
||
|
|
## Development and validation
|
||
|
|
|
||
|
|
From the repository root:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
mise run format
|
||
|
|
mise run lint
|
||
|
|
mise run test
|
||
|
|
mise run test-extension-host
|
||
|
|
```
|
||
|
|
|
||
|
|
The normal test task covers portable-value validation, framing and UTF-8
|
||
|
|
fragmentation, timeout/disconnect behavior, exact 64-bit integer display, and
|
||
|
|
interoperation with the real Rust server on an ephemeral loopback port.
|
||
|
|
|
||
|
|
The separate host test downloads VS Code 1.96.4 to the ignored `.vscode-test/`
|
||
|
|
cache and runs connection, inspection, refresh, disconnect, and reconnect
|
||
|
|
commands against a test-owned Rust server. It verifies actual virtual document
|
||
|
|
content and session isolation. On headless Linux:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
xvfb-run -a mise run test-extension-host
|
||
|
|
```
|
||
|
|
|
||
|
|
Behavior/source browsing and editing, spawn/send and lifecycle controls,
|
||
|
|
compilation diagnostics, non-destructive event subscriptions, packaging for
|
||
|
|
distribution, and debugging remain future work.
|