50 lines
1.9 KiB
Markdown
50 lines
1.9 KiB
Markdown
|
# Runa Protocol
|
||
|
|
|
||
|
|
`runa-protocol` defines versioned request, response, and event data contracts
|
||
|
|
for clients and a future server. It is independent of transport and runtime
|
||
|
|
implementation; the current crate does not dispatch requests, expose a network
|
||
|
|
endpoint, or provide authentication.
|
||
|
|
|
||
|
|
## Version 1
|
||
|
|
|
||
|
|
Every request and response carries `version: 1`. 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": 1,
|
||
|
|
"request_id": "req-1",
|
||
|
|
"command": {
|
||
|
|
"operation": "send",
|
||
|
|
"parameters": {
|
||
|
|
"actor_id": 7,
|
||
|
|
"message": { "kind": 2, "value": 9 }
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
The version 1 operations are behavior publication, rollback, lookup, source
|
||
|
|
retrieval, actor spawn, send, tick, inspect, actor listing, event retrieval,
|
||
|
|
stop, restart, pause, resume, cancellation, and behavior installation.
|
||
|
|
Migration closures are intentionally excluded: they are host callbacks, not
|
||
|
|
portable wire values.
|
||
|
|
|
||
|
|
Responses echo the request ID and carry either a typed reply or a protocol
|
||
|
|
error. Events use a separate versioned envelope. Actor and behavior snapshots
|
||
|
|
are wire DTOs, not serialized runtime objects; implementation identities are
|
||
|
|
represented by their stable display strings. Runtime errors and validation
|
||
|
|
errors must be mapped by a future server to the defined error codes without
|
||
|
|
claiming a more specific category than it can establish.
|
||
|
|
|
||
|
|
The current validation checks the protocol version, request ID, positive
|
||
|
|
actor/revision identifiers where required, non-empty behavior names, mailbox
|
||
|
|
capacity, and instruction budget. Behavior-name grammar, actor existence,
|
||
|
|
current behavior revisions, mailbox capacity at send time, and all runtime
|
||
|
|
invariants remain authoritative at the application-service boundary.
|