244 lines
13 KiB
Markdown
244 lines
13 KiB
Markdown
# Runa Protocol
|
|
|
|
`runa-protocol` defines versioned request, response, and event data contracts
|
|
for clients and the `runa` dispatcher. It is independent of transport
|
|
and runtime implementation. `runa` accepts WebSocket text messages bound to an IPv4 or
|
|
IPv6 loopback address, defaulting to `127.0.0.1:3737` without arguments.
|
|
Clap parses `--listen` / `RUNA_LISTEN` on the server and `--connect` /
|
|
`RUNA_CONNECT` on `runa-cli`; explicit flags override environment variables.
|
|
The listener is unauthenticated and intended only for
|
|
trusted local development. Both the REPL and VS Code use WebSockets.
|
|
|
|
## Version 4
|
|
|
|
Every request and response carries `version: 5`. Requests also carry a
|
|
non-empty `request_id` used to correlate the response. A server must reject
|
|
unsupported versions with `unsupported_version` rather than interpreting a
|
|
request using a different contract. Events carry the protocol version and do
|
|
not have a request ID.
|
|
|
|
Requests have a tagged command object:
|
|
|
|
```json
|
|
{
|
|
"version": 5,
|
|
"request_id": "req-1",
|
|
"command": {
|
|
"operation": "send",
|
|
"parameters": {
|
|
"actor_ref": "xK8_pQ2-Lm5_012345678",
|
|
"message": {
|
|
"type": "record",
|
|
"data": {
|
|
"op": { "type": "string", "data": "send" },
|
|
"value": { "type": "integer", "data": 9 },
|
|
"target": { "type": "actor_ref", "data": "Hj2_9sM0-pQ4_7aBcD3eF" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The version 5 operations are source listing/read/write, commit/history/revision
|
|
retrieval/rollback, actor spawn, send, tick, inspect, actor listing, event
|
|
retrieval, privileged system messages, and cancellation.
|
|
Migration closures are intentionally excluded: they are host callbacks, not
|
|
portable wire values.
|
|
|
|
Source paths are extensionless relative paths such as `actors/counter`, not
|
|
behavior aliases. They exclude the `source/` root and `.rn` extension.
|
|
|
|
| Operation | Parameters | Reply kind/data |
|
|
| --- | --- | --- |
|
|
| `list_sources` | none | `sources`: file array |
|
|
| `read_source` | `path` | `source`: file |
|
|
| `write_source` | `path`, `expected_source_id` (null to create), `source` | `source`: file |
|
|
| `commit_source` | `path` | `source_committed`: commit |
|
|
| `source_history` | `path` | `source_history`: commit array |
|
|
| `revision_source` | `path`, `revision` | `behavior_source`: `{source}` |
|
|
| `rollback_source` | `path`, `revision` | `source`: restored file |
|
|
| `spawn` | `path`, tagged `state`, positive `mailbox_capacity` | `actor_spawned`: `{actor_ref}` |
|
|
| `system` | `actor_ref`, `message` | `acknowledged` |
|
|
|
|
A file is `{path, source_id, source}` and a commit is
|
|
`{revision, source_id}`. Commits generate readable random revision strings and
|
|
capture working text without compilation. Rollback restores working source
|
|
without appending history. Spawn compiles current working source even when
|
|
uncommitted; compilation failures do not spawn an actor.
|
|
|
|
System message shape is `{kind: "stop"|"kill"|"restart"|"pause"|"resume"|"reload"}`
|
|
or `{kind: "become", path: "actors/other"}`. This is a trusted host request;
|
|
actor `ctx.send` and `ctx.send_from` accept only ordinary data. Stop runs optional
|
|
`on_shutdown` after the active handler and removes the actor on success. Kill
|
|
removes the actor immediately without shutdown, including failed actors. Removed
|
|
references return `not_found`; state, mailbox, and retained logs are discarded.
|
|
Failed actors are not automatically removed. A `Stopped` event denotes removal,
|
|
and `image_changed` invalidates actor lists. Restart is independent of stop/kill and
|
|
retains identity, mailbox, the loaded script and state; removed actors cannot be
|
|
restarted. Reload/become defer installation to
|
|
the next handler boundary. The scheduler still advances only through `tick`.
|
|
|
|
Responses echo the request ID and carry either a typed reply or a protocol
|
|
error. Events use a separate versioned envelope. Actor and source snapshots
|
|
are wire DTOs, not serialized runtime objects; implementation identities are
|
|
represented by their stable display strings. Public actor identity is a
|
|
21-character URL-safe NanoID string carried in `actor_ref`. The server maps known service
|
|
failures to the defined error codes and otherwise uses `runtime_failure`
|
|
rather than claiming a more specific category.
|
|
|
|
### Portable values
|
|
|
|
Spawn state, send messages, snapshot state/mailbox/reservations, and migration
|
|
event states use the same tagged value shape:
|
|
|
|
| Value | JSON |
|
|
| --- | --- |
|
|
| Null | `{"type":"null"}` |
|
|
| Boolean | `{"type":"bool","data":true}` |
|
|
| Signed 64-bit integer | `{"type":"integer","data":42}` |
|
|
| String | `{"type":"string","data":"hello"}` |
|
|
| List | `{"type":"list","data":[<value>, ...]}` |
|
|
| Record | `{"type":"record","data":{"key":<value>, ...}}` |
|
|
| Actor reference | `{"type":"actor_ref","data":"<21-character-NanoID>"}` |
|
|
|
|
References are distinct from strings. Their shape is validated even when
|
|
nested; existence is checked when a reference is used as a send destination,
|
|
not merely stored as data. The old message envelope and protocol v2 are not
|
|
accepted. The REPL's natural JSON and `$actor`/`$record` conveniences are
|
|
client syntax, not wire encodings.
|
|
|
|
Each state/message permits a maximum nesting depth of 32 (root depth 0),
|
|
4,096 nodes, and 1 MiB of UTF-8 string/key bytes. Requests are also subject to
|
|
the transport's 1 MiB total message limit, including tags and envelope.
|
|
Unsupported value tags, malformed references, floats, and out-of-range integers
|
|
fail decoding; well-formed requests exceeding value limits receive
|
|
`invalid_request`. Invalid Rune transition output fails the actor without
|
|
acknowledging the reserved message, changing committed state, or enqueueing
|
|
any of its sends.
|
|
|
|
`get_events` drains and returns the events currently accumulated by this
|
|
single-worker image. It is not a durable subscription or replayable event log.
|
|
The transport limits each request to 1 MiB before parsing. Malformed
|
|
JSON or an oversized message terminates that connection with an error; no protocol
|
|
response is emitted when a request cannot be decoded. A WebSocket disconnect
|
|
closes only that client connection. The listener
|
|
allows up to 16 simultaneous clients and serializes each dispatch through the
|
|
same image. WebSocket response payloads are capped at 1 MiB, with one
|
|
in-flight dispatch per client and a bounded shared dispatch queue. Every local client can use the full development
|
|
API; loopback binding is not authentication or authorization. Remote access
|
|
must not be enabled until appropriate authentication and authorization exist.
|
|
The `runa-client` crate validates response protocol versions and request IDs.
|
|
Its `WebSocketClient` connects to
|
|
loopback endpoints using bounded WebSocket messages and correlation checks,
|
|
validating interleaved notifications while waiting for responses.
|
|
Connection establishment has a 5-second timeout; WebSocket writes and response
|
|
waits have 30-second timeouts. A failed network request invalidates that client connection.
|
|
No automatic retry is performed: loss of a response does not imply that the
|
|
operation failed to commit.
|
|
|
|
The interactive REPL uses WebSockets and never owns the image. Disconnecting clients
|
|
does not stop actors or reset source history; reconnecting clients can
|
|
retrieve them through `list_actors` and `list_sources`. The network executable
|
|
loads `source/actors/counter.rn` on image startup, not on connection.
|
|
The stdio transport and child-process client have been removed.
|
|
|
|
The TypeScript VS Code client issues `list_actors`, `inspect_actor`,
|
|
source file/version-control operations, `spawn`, `send`, `tick`, and `system`.
|
|
VS Code automatically displays writable image files under a `source` directory
|
|
in its dedicated Runa sidebar's source tree, without modifying workspace folders,
|
|
and caches read-only commit documents by connection, path, and revision.
|
|
It preserves i64 inputs and bounds the complete outgoing envelope as well as
|
|
incoming messages. It enforces loopback endpoints, bounded UTF-8 text messages,
|
|
version/request-ID/reply-kind checks, and portable snapshot value validation.
|
|
It decodes JSON integers as `bigint` and prints them losslessly, including
|
|
signed 64-bit state and unsigned 64-bit telemetry. It uses the same 5-second
|
|
connect and 30-second request timeouts, closes on transport/protocol corruption,
|
|
and never retries automatically. A well-formed server error is surfaced without
|
|
invalidating the stream. Server notifications trigger automatic refreshes of
|
|
the actor tree and open snapshot documents. Manual refresh remains available.
|
|
|
|
## WebSocket transport and notifications
|
|
|
|
### Actor editing and log subscriptions (v5)
|
|
|
|
- `edit_actor {actor_ref,state,messages}`: `state` is a tagged portable value or
|
|
null to leave it unchanged. `messages` is null to leave the mailbox unchanged,
|
|
or `{reserved,queued}` where reserved is a tagged value or null for no
|
|
reservation, and queued is an ordered array of tagged values. At least one
|
|
edit is required. Only paused/failed actors with no active execution
|
|
are editable; values and mailbox capacity are validated atomically.
|
|
- `set_log_level {actor_ref,level}`: level is one of `trace`, `debug`, `info`,
|
|
`warn`, `error`, `fatal`. Both mutations return `acknowledged` and invalidate
|
|
image views. Actor snapshots include `log_level`.
|
|
- `logs {actors,follow,after}`: actors is an array of references (empty means
|
|
all); after is an exclusive u64 sequence cursor. Reply kind `logs` carries
|
|
`{entries,next_sequence,has_more}`, with at most 128 entries per page.
|
|
Each entry is `{sequence,actor_ref,level,message}`. Missing actors are errors.
|
|
History queries are read-only and do not invalidate views.
|
|
- With follow true, the connection registers the filter before history is read.
|
|
Subsequent notification envelopes carry
|
|
`{event:"log",data:{sequence,actor_ref,level,message}}`. Reissuing `logs`
|
|
replaces the filter; follow false unsubscribes. Matching entries newer than
|
|
the reply's cursor are emitted after its reply, allowing history/follow
|
|
deduplication by sequence. Other connections receive no log events.
|
|
Transport and client buffers are bounded at 1,024 entries; lag is an explicit
|
|
connection error, not a guaranteed-delivery stream. Disconnect removes the
|
|
subscription. Image invalidations remain coalescible and independent of logs.
|
|
|
|
On `quit`, `exit`, Ctrl+C, or end-of-input, the CLI completes the WebSocket close
|
|
handshake with a 5-second deadline before releasing the connection. A failed
|
|
handshake is reported rather than treating an abrupt reset as a normal close.
|
|
|
|
Connect to `ws://127.0.0.1:3737/` (or a configured numeric loopback endpoint)
|
|
and offer the `runa-debug` WebSocket subprotocol. The server requires and echoes
|
|
that subprotocol. Plain TCP JSON Lines is no longer accepted by the network
|
|
listener. The request/response contract is version 5.
|
|
Each WebSocket text message contains exactly one JSON request, response, or
|
|
notification, without newline framing. Binary messages and malformed requests
|
|
terminate the connection. Fragmented text is supported with a 1 MiB aggregate
|
|
message limit; individual frames are also limited to 1 MiB. Compression is not
|
|
enabled. Upgrade handshakes have a 5-second timeout and writes have a
|
|
30-second timeout so stalled peers do not hold client slots forever.
|
|
|
|
The endpoint accepts only the root path and rejects requests carrying an
|
|
`Origin` header: browser-origin access is not enabled for this unauthenticated
|
|
local API. This is not authentication; local non-browser clients retain full
|
|
development privileges.
|
|
|
|
Every upgraded connection automatically receives non-destructive invalidations:
|
|
|
|
```json
|
|
{
|
|
"version": 5,
|
|
"event": {
|
|
"event": "image_changed",
|
|
"data": { "revision": 42 }
|
|
}
|
|
}
|
|
```
|
|
|
|
Successful mutating requests (spawn, send, tick, lifecycle controls,
|
|
source writes/commits/rollback, and system messages) increment a server-session revision
|
|
and notify all connected clients, including the initiator. Read-only requests,
|
|
failed mutations, and `get_events` do not generate invalidations. A tick
|
|
invalidates snapshots even when it only advances execution telemetry or causes
|
|
an actor failure. A successful send invalidates mailbox snapshots before any
|
|
handler runs. Notifications may appear between requests and their replies;
|
|
clients must distinguish them from correlated responses.
|
|
|
|
Revisions increase within one server session, not across server restarts.
|
|
Slow subscribers retain only the latest unsent revision; gaps are expected.
|
|
These notifications are hints to re-fetch authoritative data, not individual
|
|
runtime events, a durable log, an atomic snapshot revision, or replay.
|
|
On connection/reconnection, fetch a full listing first. The VS Code client
|
|
coalesces bursts and schedules another refresh if an invalidation arrives
|
|
during an in-flight read. Refresh never advances the scheduler or calls `get_events`;
|
|
the REPL's explicit `events` command still drains the separate runtime queue.
|
|
|
|
The current validation checks the protocol version, request ID, actor-reference
|
|
shape, structured-value limits, revision ID shape, non-empty paths, mailbox
|
|
capacity, and instruction budget. Canonical source paths, actor existence,
|
|
expected source identities, mailbox capacity at send time, and all runtime
|
|
invariants remain authoritative at the application-service boundary.
|