onlyne-proto 2.1.0

Onlyne wire protocol: envelopes, frames, events, ops, error codes, JSON Schema export
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! Onlyne wire protocol (decisions D3, D4, D8, D9, D10, D11, D16).
//!
//! Pure data: every type here is serde-only, so the protocol travels into the
//! server, the client, the gateway plugins, and the machine-readable schema
//! export from one definition. This crate holds tokio, a database, and a
//! transport in none of its code paths. The one behaviour beside data is
//! [`ops`]' phase `FromStr`: an unknown stored word is logged before the `Err`
//! returns, so a column no reader can decode still leaves a trace.
//!
//! Layers, bottom up:
//! - [`envelope`]: the unified message (§3). Text plus at most one inline image.
//! - [`frame`]: the multiplexed request/response/event wrapper (§4) and the closed
//!   [`frame::ErrorCode`] set.
//! - [`event`]: the observation plane (§9), at-most-once with cursor resync.
//! - [`ops`]: the client-to-server and admin vocabularies (§6, §8).
//! - [`adapter`]: the one adapter protocol mounted on both sides (§7).
//!
//! Compatibility posture: [`PROTOCOL_VERSION`] is checked at handshake and a
//! mismatch answers [`frame::ErrorCode::ProtocolVersion`]. Legacy layouts and
//! legacy databases are refused at startup by the binaries that load them.
//!
//! ## Frame typing
//!
//! [`Frame<R = ClientOp>`] is the single wrapper for client, admin, and gateway surfaces.
//! [`AdminFrame`] and [`GatewayFrame`] provide typed aliases for the admin and gateway vocabularies.
//! All three surfaces use the same JSON layout with `f`, `id`, `op`, and `args` fields.
//! Cross-vocabulary decoding fails by design and keeps each socket vocabulary closed.

pub mod adapter;
pub mod envelope;
pub mod event;
pub mod frame;
pub mod lifecycle;
pub mod ops;
pub mod text;
pub mod view;

pub use adapter::{
    AdapterMsg, AgentMount, AssignAckArgs, AssignArgs, ByeNotice, Capability, ClusterMount,
    ConfigGetArgs, DetachArgs, GatewayBinding, GatewayMount, HELLO_REQUIRED_MESSAGE,
    HELLO_TIMEOUT_MS, HandoffArgs, HelloAck, HelloArgs, HostOp, Mount, MountKind, MsgDirection,
    OpenArgs, OpenedArgs, PluginOp, RecycleArgs, RenderSendArgs, ServerInfo, SessionRegisterArgs,
    ToolsMount, TypingArgs, WelcomeSlice,
};
pub use envelope::{
    BODY_TEXT_MAX_BYTES, Body, CAUSALITY_LABEL_KEY_MAX_BYTES, CAUSALITY_LABEL_MAX_ENTRIES,
    CAUSALITY_LABEL_VALUE_MAX_BYTES, Causality, ControlOp, Envelope, Error, IMAGE_DATA_MAX_BYTES,
    IMAGE_DATA_MAX_ENCODED_BYTES, IMAGE_MIMES, ImagePart, MsgKind, Outcome, Principal, Result,
    new_envelope, new_id, new_op_id, new_task_id, sha256_hex,
};
pub use event::{
    CLIENT_EVENT_CLASSES, DELIVERY_BLOCKED, Event, EventRow, EventTier, FaultEvent, GatewayHealth,
    HANDOFF, LedgerState, LedgerStateEvent, Lifecycle, Presence, RolePresence, SessionStateEvent,
    SpecReloaded, TURN_END_WITHOUT_COMPLETE, client_event,
};
pub use frame::{
    AdminFrame, ErrorCode, ErrorPayload, Frame, GatewayFrame, MAX_ERROR_MESSAGE_BYTES,
    OP_ID_CONFLICT_MESSAGE, ResBody, Retry,
};
pub use lifecycle::{
    AgentPhase, DeliveryPhase, HostRef, IgnoredReason, LifecycleEvent, Observation, OrcaPane,
    RecoveryPhase, RejectReason, ResourcePhase, TaskState, Verdict, Version, apply, event_version,
    is_legal, project,
};
pub use ops::{
    AckArgs, AdminControl, AdminOp, AdminReport, AdminSend, ByeArgs, ClientOp, ControlArgs,
    ConversationInfo, DETAILS_MAX_BYTES, Delivery, Drive, FreshRead, GatewayOp, GhostSweep,
    HandshakeArgs, HealthArgs, HistoryArgs, LedgerEntry, LedgerQuery, LiveSession,
    PublishEventArgs, PullArgs, PullReply, QueryFaultsArgs, QueryRolesArgs, QuerySessionsArgs,
    Receipt, RegisterChannelArgs, RemoveRole, RepairAck, RepairAdopt, RepairFail, RepairRebind,
    RepairTarget, Report, RoleInfo, RoleRuntime, SessionProjection, SessionRow, SetProse,
    SetRuntime, SetSenders, SetSession, SetTargets, ShutdownArgs, SpecApply, SpecEdit, SpecView,
    Subscribe, UpsertRole, Welcome,
};

pub use text::{
    BINARY_NOT_FOUND_PREFIX, EXIT_NEEDS_MIGRATION, NO_SOCKET_MESSAGE, SchemaMismatch,
    binary_not_found, legacy_workspace_message, unsupported_schema_message,
};
pub use view::{
    BoardColumn, Card, ClusterSummary, DeliveryAxis, DeliveryView, EVENT_TAIL_LIMIT,
    FAULT_STATE_OPEN, RESYNC_LAG_KIND, SessionCounts, SessionState, SessionView, Snapshot, View,
    fault_is_open, is_resync_lag, snapshot_to_view, update, update_class,
};

/// Wire protocol revision, carried in every [`envelope::Envelope`] and handshake.
pub const PROTOCOL_VERSION: u16 = 1;

/// Idempotency prefix shared by every generated `op_id`.
pub const OP_ID_PREFIX: &str = "o-";

/// Envelope JSON Schema text baked at build time from `schema/envelope.schema.json`.
pub fn envelope_schema() -> &'static str {
    include_str!(concat!(env!("OUT_DIR"), "/envelope.schema.json"))
}

/// Adapter JSON Schema text baked at build time from `schema/adapter.schema.json`.
pub fn adapter_schema() -> &'static str {
    include_str!(concat!(env!("OUT_DIR"), "/adapter.schema.json"))
}