docs: lock v1 scope and terminology
This commit is contained in:
27
PROTOCOL.md
27
PROTOCOL.md
@@ -26,6 +26,22 @@ Important security rule:
|
||||
|
||||
---
|
||||
|
||||
## 1.1 Canonical Terminology
|
||||
|
||||
These names are treated as protocol-level canonical terms:
|
||||
|
||||
- `identifier`: unique logical identity of a Yonexus client instance.
|
||||
- `rule_identifier`: exact-match routing key for application messages.
|
||||
- `builtin`: reserved protocol namespace used only for Yonexus control frames.
|
||||
- `pairingCode`: short-lived out-of-band code generated by the server for human-mediated pairing.
|
||||
- `secret`: server-issued shared secret used in reconnect authentication proof construction.
|
||||
- `publicKey` / `privateKey`: client signing keypair.
|
||||
- `nextAction`: the server's directed next step in `hello_ack`.
|
||||
|
||||
The protocol and implementation repos should prefer these exact names over synonyms.
|
||||
|
||||
---
|
||||
|
||||
## 2. Transport
|
||||
|
||||
Transport is WebSocket.
|
||||
@@ -35,13 +51,12 @@ Transport is WebSocket.
|
||||
- protocol frames are UTF-8 text in v1
|
||||
- binary frames are not required in v1
|
||||
|
||||
Client connects to configured `mainHost`, which may be:
|
||||
Client connects to configured `mainHost`, which in v1 should be a full WebSocket URL:
|
||||
- `ws://host:port/path`
|
||||
- `wss://host:port/path`
|
||||
- or raw `host:port` if normalized by implementation
|
||||
|
||||
Recommended canonical config:
|
||||
- prefer full WebSocket URL
|
||||
- require/prefer a full WebSocket URL in v1 rather than raw `host:port`
|
||||
|
||||
---
|
||||
|
||||
@@ -426,6 +441,9 @@ builtin::{
|
||||
### `heartbeat_ack`
|
||||
Optional response by `Yonexus.Server`.
|
||||
|
||||
v1 policy:
|
||||
- `heartbeat_ack` may be enabled by the server but clients must not require it for healthy operation
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
@@ -624,6 +642,9 @@ Dispatch algorithm:
|
||||
4. invoke the first exact match
|
||||
5. ignore/log if no match is found
|
||||
|
||||
v1 policy:
|
||||
- rule matching is exact string match only; prefix, wildcard, and regex routing are out of scope
|
||||
|
||||
Processor input:
|
||||
- on client: `${rule_identifier}::${message_content}`
|
||||
- on server for client-originated messages: `${rule_identifier}::${sender_identifier}::${message_content}`
|
||||
|
||||
Reference in New Issue
Block a user