wire_protocol.hpp File Reference

Wire protocol v2 for the HTTP adapter. More...

#include "aria/abi/export.hpp"
#include <cstdint>
#include <optional>
#include <string>
#include <variant>

Include dependency graph for wire_protocol.hpp:

Go to the source code of this file.

Namespaces
namespace	aria
namespace	aria::adapters
namespace	aria::adapters::http
namespace	aria::adapters::http::wire
namespace	aria::adapters::http::wire::fields
	Field-name string constants used in JSON envelopes.
namespace	aria::adapters::http::wire::event_types
namespace	aria::adapters::http::wire::field_kinds
namespace	aria::adapters::http::wire::list_ops

Variables
constexpr int	aria::adapters::http::wire::kProtocolVersion = 2
	Protocol version. Incremented on incompatible changes only.
constexpr const char *	aria::adapters::http::wire::kDefaultApiPrefix = "/aria"
	Default API path prefix. All endpoints are mounted under this.
constexpr int	aria::adapters::http::wire::kDefaultHeartbeatSec = 25
	Default heartbeat interval (seconds).
constexpr const char *	aria::adapters::http::wire::fields::kType = "type"
constexpr const char *	aria::adapters::http::wire::fields::kView = "view"
constexpr const char *	aria::adapters::http::wire::fields::kField = "field"
constexpr const char *	aria::adapters::http::wire::fields::kValue = "value"
constexpr const char *	aria::adapters::http::wire::fields::kCommand = "command"
constexpr const char *	aria::adapters::http::wire::fields::kArgs = "args"
constexpr const char *	aria::adapters::http::wire::fields::kOp = "op"
constexpr const char *	aria::adapters::http::wire::fields::kIndex = "index"
constexpr const char *	aria::adapters::http::wire::fields::kTo = "to"
constexpr const char *	aria::adapters::http::wire::fields::kMessage = "message"
constexpr const char *	aria::adapters::http::wire::event_types::kHello = "hello"
constexpr const char *	aria::adapters::http::wire::event_types::kState = "state"
constexpr const char *	aria::adapters::http::wire::event_types::kEvent = "event"
constexpr const char *	aria::adapters::http::wire::event_types::kList = "list"
constexpr const char *	aria::adapters::http::wire::event_types::kVisibility = "visibility"
constexpr const char *	aria::adapters::http::wire::event_types::kEnabled = "enabled"
constexpr const char *	aria::adapters::http::wire::event_types::kError = "error"
constexpr const char *	aria::adapters::http::wire::event_types::kPing = "ping"
constexpr const char *	aria::adapters::http::wire::field_kinds::kText = "text"
constexpr const char *	aria::adapters::http::wire::field_kinds::kBool = "bool"
constexpr const char *	aria::adapters::http::wire::field_kinds::kInt = "int"
constexpr const char *	aria::adapters::http::wire::field_kinds::kInt64 = "int64"
constexpr const char *	aria::adapters::http::wire::field_kinds::kUInt64 = "uint64"
constexpr const char *	aria::adapters::http::wire::field_kinds::kFloat = "float"
constexpr const char *	aria::adapters::http::wire::field_kinds::kDouble = "double"
constexpr const char *	aria::adapters::http::wire::field_kinds::kClick = "click"
constexpr const char *	aria::adapters::http::wire::list_ops::kInsert = "insert"
constexpr const char *	aria::adapters::http::wire::list_ops::kRemove = "remove"
constexpr const char *	aria::adapters::http::wire::list_ops::kReplace = "replace"
constexpr const char *	aria::adapters::http::wire::list_ops::kReset = "reset"
constexpr const char *	aria::adapters::http::wire::list_ops::kMove = "move"

Detailed Description

Wire protocol v2 for the HTTP adapter.

All payloads are JSON, UTF-8 encoded. The protocol is intentionally simple — anything that needs to be efficient should use a different adapter. The HTTP adapter is for "ergonomic and ubiquitous", not for "fastest".

Topology

Browser/JS ──HTTP/REST──▶ HttpAdapter ──ViewModel──▶ Aria core ▲ │ └────────SSE stream────────┘

SSE (Server-Sent Events) carries server-to-client updates. Protocol 2 preserves int64/uint64 outside JavaScript's safe integer range as decimal strings, with the same typed field tag. Safe integers remain JSON numbers. The SDK exposes unsafe values as BigInt; upgrade v1 clients accordingly. WebSocket transport and list envelopes remain reserved, not implemented.

Endpoints

Method	Path	Purpose
GET	/aria/health	Readiness probe
GET	/aria/views	Enumerate registered views
GET	/aria/state?view=X	Snapshot of one view's shadow state
POST	/aria/state	Update a view's value (JSON body)
POST	/aria/click	Fire a click event
POST	/aria/command	Invoke a custom command
GET	/aria/stream	Subscribe to server-sent events

Message envelopes

Server → Client (SSE) — data: lines carry JSON of these shapes:

{"type":"hello","platform":"http","protocol":2}
{"type":"state","view":"<id>","field":"text|bool|int|int64|uint64|float|double","value":<v>}
{"type":"event","view":"<id>","field":"click"}
// Reserved for future list adapter support:
{"type":"list","view":"<id>","op":"insert|remove|replace|reset|move",
               "index":<n>,"to":<n>,"value":<json>}
{"type":"visibility","view":"<id>","value":true|false}
{"type":"enabled","view":"<id>","value":true|false}
{"type":"error","message":"<text>"}
{"type":"ping"}                       // every 25s for keep-alive

Client → Server (REST body):

POST /aria/state    {"view":"<id>","field":"text","value":"hello"}
POST /aria/click    {"view":"<id>"}
POST /aria/command  {"view":"<id>","command":"<name>","args":<json>}

Servers MUST tolerate unknown fields (forward-compat). Clients MUST tolerate unknown type values (forward-compat).