Crate waos_dev_protocol 

What cargo waos and a running WaOS say to each other: the messages of one run, how they are framed on a stream, and the Unix socket on this machine that carries them.

The connection is the run (the design’s decision 29): cargo waos run connects, sends one ToWaOS::Run, and reads what comes back until the run ends. Closing the connection, by Ctrl-C or the terminal closing, stops the program; a later run of the same id replaces it. A run is the program its id names (decision 11 of the permissions proposal), with that program’s settings and folders, installed or not. waos open connects the same way and sends one ToWaOS::Open, files to open with the program an id names, which a WaOS answers once (decision 3 of the opening proposal, until programs register what opens them). There is no stop message. On this machine the socket is in the user’s own folder, so the system’s file permissions decide who may connect (decision 30); the network transport for phones carries the same messages.

The invariants a later editor will break:

• A variant’s place among its enum’s, and a field’s place in its record, is its encoding: postcard writes a variant by its index and a record as its fields in order, with no names. Add at the end, and raise PROTOCOL for anything else.
• The first frame each way says PROTOCOL, the number of the build that wrote it, outside the messages’ encoding, and a side reads no message until the numbers agree: cargo waos and the WaOS it reaches are built from the same crate, and find out when they are not.

On Windows the crate carries the messages and Connection but no transport: its named pipe is step 11, and socket_path and Listener are not there.

Structs

Connection

One connection: length-prefixed postcard frames over S, the Unix socket on this machine. Split into its halves, each is a Connection that only sends or only receives, so a WaOS sends a program’s output on one task while another watches for the connection closing.

Listener

Where a WaOS accepts cargo waos’s connections. Dropping it removes its socket file, so a WaOS that quit leaves none; one that died leaves a file the next WaOS replaces.

Enums

FromWaOS

What a WaOS says back, about the run or the opening the connection asked for.

OutputStream

Which of a program’s two output streams some bytes came from.

RunEnd

How the run ended.

ToWaOS

What cargo waos says to a WaOS.

Constants

MAX_FRAME_BYTES

The largest frame either side accepts. A component is megabytes, a debug build tens of them; a count beyond this is a stream that is not ours, refused before a byte of it is read.

PROTOCOL

The protocol’s number, which the first frame each way says: the messages and their encoding as this build of the crate has them. Raised with any change a side of the build before would misread, which, with postcard, is any change to a message but a variant or a field added at the end.

Functions

socket_path

Where WaOS listens on this machine, in the user’s own folder: on Apple’s systems ~/Library/Application Support/WaOS/dev.sock; elsewhere $XDG_RUNTIME_DIR/waos/dev.sock, the folder a system keeps for the user’s sockets, or ~/.local/share/waos/dev.sock when there is none. macOS allows a socket path 103 bytes long, so a user’s name may be 50 bytes; binding or connecting to a longer path fails with the system’s message.