arin-protocol 0.5.0

Wire protocol types for Arin. Pure types and validation, no IO.
Documentation

arin-protocol

Wire protocol types for Arin, an annotation layer any agent can draw on.

Arin is a local daemon that draws on the user's screen: it points at things, highlights regions, writes explanatory text boxes, and draws freehand paths. It never clicks, types, or scrolls. This crate is the contract between the daemon and whatever is driving it.

It is pure types plus validation. No IO, no async runtime, no platform code, and it builds anywhere. Use it to speak to the daemon from Rust without hand-rolling the JSON, or to implement the protocol somewhere else with the type definitions as the reference.

[dependencies]
arin-protocol = "0.2"

The crate version is not the wire version. This crate is 0.2 while the format it describes is 0.1, and they move independently: a Rust API change bumps the crate, a wire format change bumps PROTOCOL_VERSION. Compatibility checks go against that constant, not against the version in your Cargo.toml.

The shape of it

JSON lines over a Unix domain socket, one object per line, UTF-8. Every message carries a v field.

use arin_protocol::{ClientMessage, Envelope, PROTOCOL_VERSION};

let line = r#"{"v":"0.1","type":"point","x":412.0,"y":88.0,"display_id":1}"#;
let message: Envelope<ClientMessage> = serde_json::from_str(line)?;
assert!(message.version.is_compatible_with(PROTOCOL_VERSION));
# Ok::<(), serde_json::Error>(())

Client to daemon: session_start, point, highlight, textbox, draw, clear, session_end. Daemon to client: ack, invalidated, error.

Two rules worth knowing before you use it

Every coordinate is a logical point paired with an explicit display_id. Never physical pixels. A Retina screenshot is twice the logical size, and mixed-DPI multi-monitor setups make implicit conversion unrecoverable. Clients working from a screenshot divide by the scale factor reported in the ack before sending. There is no implicit primary display.

Unknown fields are ignored and unknown message types produce an error rather than a closed connection, so a client built against a later minor version keeps working. Changes are additive within a major version, and reserved fields exist so that stays true.

Stability

The protocol is not frozen. Until it is, the crate follows SemVer as a Rust API while the wire format it describes may still move.

Authentication no longer blocks the freeze. That was the open question, and it is settled: permission is a capability split rather than a handshake. Drawing is open to any process running as you, since one could draw on its own window anyway. Grounding, which is the only thing Arin can do that its clients cannot, is gated behind a consent prompt. None of that changed session_start, so nothing here moved.

What is still open is when to freeze. Freezing is a promise to people writing clients, and a second implementation is what proves a protocol is a protocol rather than a description of one renderer. Only one renderer has ever spoken this format, so the freeze may wait for a second one rather than landing with Arin 1.0. Assume additive-only changes are not guaranteed until this section says otherwise.

Licence

MIT.