waos_dev_protocol/lib.rs
1//! What `cargo waos` and a running WaOS say to each other: the messages of one run, how they
2//! are framed on a stream, and the Unix socket on this machine that carries them.
3//!
4//! The connection is the run (the design's decision 29): `cargo waos run` connects, sends one
5//! [`ToWaOS::Run`], and reads what comes back until the run ends. Closing the connection, by
6//! Ctrl-C or the terminal closing, stops the program; a later run of the same id replaces it.
7//! A run is the program its id names (decision 11 of the permissions proposal), with that
8//! program's settings and folders, installed or not. `waos open` connects the same way and sends
9//! one [`ToWaOS::Open`], files to open with the program an id names, which a WaOS answers once
10//! (decision 3 of the opening proposal, until programs register what opens them). `cargo waos
11//! screenshot`, `tap`, `type`, `key` and `scroll` connect the same way and send one
12//! [`ToWaOS::Screenshot`] or [`ToWaOS::Input`] for the program an id names, which a WaOS answers
13//! once, and only for a program a run of `cargo waos run` runs (the design's decision 60).
14//! There is no stop message. On this machine the socket is in the user's own folder, so the
15//! system's file permissions decide who may connect (decision 30); the network transport for
16//! phones carries the same messages.
17//!
18//! The invariants a later editor will break:
19//! - A variant's place among its enum's, and a field's place in its record, is its encoding:
20//! postcard writes a variant by its index and a record as its fields in order, with no names.
21//! Add at the end, and raise [`PROTOCOL`] for anything else.
22//! - The first frame each way says [`PROTOCOL`], the number of the build that wrote it, outside
23//! the messages' encoding, and a side reads no message until the numbers agree: `cargo waos`
24//! and the WaOS it reaches are built from the same crate, and find out when they are not.
25//!
26//! On Windows the crate carries the messages and [`Connection`] but no transport: its named
27//! pipe is step 11, and [`socket_path`] and [`Listener`] are not there.
28
29mod connection;
30mod messages;
31#[cfg(unix)]
32mod socket;
33
34pub use connection::{Connection, MAX_FRAME_BYTES, PROTOCOL};
35pub use messages::{FromWaOS, Input, OutputStream, RunEnd, ToWaOS, Unreached, WindowPicture};
36#[cfg(unix)]
37pub use socket::{Listener, socket_path};