craft-ipc
craft-ipc is how a Craft app talks to another Craft app on the same machine. It has a server, a client, instance discovery, launch on demand and focus hand-off. It has no async runtime. The wire protocol is in PROTOCOL.md. The crate depends on no app and on no other Craft crate.
Native only. craft-ipc does not build for wasm32-unknown-unknown, because interprocess (local sockets and named pipes) has no wasm32 build. An app gates the dependency by target. The pure data modules (moniker, record, payload, asset, ids) use only std and serde.
Boundaries
- Never crashes: no panics, no
unsafe. - Every connection must present a 64 hex token within 2 seconds. The server also checks the peer user id (Unix) or the token user (Windows). At most 16 connections are open, and at most 4 of them are unauthenticated.
- One UTF-8 JSON object per line, at most 4 MiB per line. A request can arrive in pieces with pauses between them.
wire::LineReaderkeeps the partial line. Do not read control lines with a statelessread_lineon a stream that has a receive timeout. - On Unix, the socket file is mode
0600inside a0700directory. The Windows code paths (named pipe, token user check) have not been run on Windows.
Modules
| Module | Role |
|---|---|
server, client, wire, bulk, auth, launch, activate, discovery |
transport, session, frames, focus hand-off, instance records |
moniker, record, payload, asset, ids |
pure data types |
refresh |
Tracker (poll, epoch bump, relink) and write_atomic for linked files |
fetch |
FrameFetcher: ticket, a few BulkClient workers, a RAM cache keyed FrameKey with a byte budget and LRU eviction. fetch never waits past its wait argument. A late frame still lands in the cache |
watch |
Watcher thread that polls Trackers: shallow every second, deep every 30 seconds. IntervalTicker runs on real time and ManualTicker is for tests |
trust, cache |
check_executable guards every launch (absolute path, regular file, executable, owner and mode checks). private_cache_dir, write_private and read_private make a 0700 cache with no /tmp fallback |
server::Limitsholds the connection limits: auth deadline 2 s, started line 10 s, idle 1 h for unsubscribed control connections, 4 unauthenticated of 16.payload::check_peer_pathis the one path filter: absolute, no NUL, no... The media probe only touches regular files and never opens a FIFO.Server::start_with(config, Extensions { assets, caps })adds an asset provider and extra caps.InstanceRecordkeepscapsinextra. Usecaps()andadd_cap().- Discovery: each app writes one JSON record, mode
0600, into a per-user runtime directory. A lock file held for the life of the app shows whether the owner is alive. - Launch:
launch::resolvefinds an app binary (environment, a read-only parse of the launcher's install record,PATH, usual install locations).launchstarts it only whentrust::check_executableaccepts the file. - Loopback TCP is available only when the app opts in. It binds 127.0.0.1 and runs the same handshake. A TCP client reads the port and token from the instance record (
Client::connect_tcp).
Schemas and fixtures
schemas/instance-record.schema.json and schemas/link-record.schema.json describe the stored records. tests/schemas.rs checks that each schema and its Rust type agree, and that the stored records in tests/fixtures/ stay valid.
Tests
A forked child holds a copy of every open file descriptor until exec, so a flock released by drop can look held. Unit tests that start a process take crate::SPAWN_GUARD.write(). Unit tests that publish or scan a discovery lock take .read().