arin_protocol/lib.rs
1//! Wire protocol types for Arin.
2//!
3//! This crate is the public contract. It is pure types plus validation: no IO, no async
4//! runtime, no platform code. It must build and test anywhere.
5//!
6//! # Shape
7//!
8//! JSON lines over a Unix domain socket, one object per line, UTF-8. Every message
9//! carries a `v` field. The daemon accepts any minor version within its major and
10//! ignores fields it does not know, so changes stay additive within a major version.
11//!
12//! ```
13//! use arin_protocol::{ClientMessage, Envelope};
14//!
15//! let line = r#"{"v":"0.1","type":"point","x":412.0,"y":88.0,"display_id":1}"#;
16//! let msg: Envelope<ClientMessage> = serde_json::from_str(line).unwrap();
17//! assert!(msg.version.is_compatible_with(arin_protocol::PROTOCOL_VERSION));
18//! ```
19//!
20//! # Coordinates
21//!
22//! Every coordinate is a logical point paired with an explicit display. Never physical
23//! pixels. Physical conversion belongs inside platform crates and nowhere else.
24
25#![forbid(unsafe_code)]
26#![warn(missing_docs)]
27
28mod anchor;
29mod client;
30mod daemon;
31mod envelope;
32mod geom;
33mod ids;
34mod position;
35mod validate;
36mod version;
37
38pub use anchor::Anchor;
39pub use client::{
40 AwaitWindow, Clear, ClientMessage, Draw, Focus, Highlight, HighlightTarget, Point, PointTarget,
41 SessionStart, StrokeStyle, Textbox,
42};
43pub use daemon::{
44 Ack, Activated, DaemonMessage, ErrorCode, Invalidated, InvalidationReason, ProtocolError,
45};
46pub use envelope::Envelope;
47pub use geom::{DisplayId, DisplayInfo, LogicalPoint, LogicalRect};
48pub use ids::{AnnotationId, SessionId};
49pub use position::Position;
50pub use validate::{Validate, ValidationError};
51pub use version::{PROTOCOL_VERSION, Version, VersionParseError};
52
53/// Compiles the README's examples as doctests.
54///
55/// The README is what someone reads on crates.io before they read anything else, so its
56/// code is held to the same standard as the code in this file rather than being prose
57/// that happens to be fenced.
58#[cfg(doctest)]
59#[doc = include_str!("../README.md")]
60struct Readme;
61
62/// Maximum accepted payload for a single line, in bytes.
63///
64/// Anything larger is rejected with [`ErrorCode::PayloadTooLarge`] rather than buffered.
65pub const MAX_PAYLOAD_BYTES: usize = 1024 * 1024;