Files
craft-libs/crates/ipc
094537374c Integrate shared IPC with full executable ancestry validation (#1571)
* craft-ipc: local-socket server, client and discovery for Craft apps

Adds craft-ipc, the transport for a Craft app that talks to other Craft apps on
one machine. It is native only: interprocess has no wasm32 build.

- server and client: one JSON object per line, push events, a bulk connection
  for frames, token auth on every connection, connection and time limits.
- discovery: one record per running app in a per-user runtime directory, with a
  lock file that shows whether the owner is alive.
- launch, trust, cache: find an app binary, start it only after an executable
  check, keep caches in a private per-user directory.
- activate: focus hand-off between apps.
- moniker, record, payload, asset, refresh, fetch, watch: asset names, stored
  link records, open payloads, linked-file polling and a frame cache.
- PROTOCOL.md describes the wire protocol. The record schemas and fixtures are
  in the crate.

- The crate compiles and passes clippy -D warnings on x86_64-pc-windows-gnu and
  aarch64-apple-darwin. This is a compile and lint fix only. No one ran the
  Windows or macOS code paths, so this does not claim they work there.

Part of #414.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: app.activate no longer claims a request it cannot make

ActivationBackend gains can_apply_token (default false). On Linux a
token only counts when the backend can apply it to a live window.
Stock winit cannot, so the answer is false plus a request for user
attention. Wire values are unchanged. PROTOCOL.md says what each
value means.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: keep a partial reply line across client read timeouts

pull_line dropped the bytes it had read when a read timed out, so next_event
returned Ok(None) and the next read saw only the tail of the line. The client now
keeps the partial line and resumes it on the next read. A test splits an event
line across a timeout.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: scope the macOS fallback runtime directory to the user

With TMPDIR unset or relative, the fallback was the shared path /tmp/craft. The
first user to create it owned it, and every other user then failed the owner
check. The fallback is now /tmp/craft-<euid>, as on Linux. The path choice is a
pure function with a test.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: fetch rejects non-finite time, bounds its queue, keeps waited-for asks

Three changes to FrameFetcher::fetch.

A non-finite time_s was queued and failed in request_reply before any socket
I/O. The worker read that as a dead connection and exited, so enough bad asks
took every worker down. fetch now returns Fetched::Failed and queues nothing.

The queue had no length limit, so stalled workers let it grow with the request
rate. It now holds at most QUEUE_MAX asks (256, a new public constant). A miss
past the cap drops the oldest queued ask and counts it in stats.skipped.

next_job dropped any job older than max_age, even when the caller had waited
longer than max_age and was still there. The caller then re-queued at the tail.
Each job now records the latest deadline of its waiting callers and is skipped
for age only when no caller is left. Tests cover each case.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: reject file:// media URLs that do not percent-decode

local_path returned None for a file:// URL with a bad percent escape, and
missing_media then skipped it, so the server accepted a local target without the
media probe. Such a URL now gets payload_invalid. URLs that name no local file
(remote host, other scheme, relative path) are still left to the app.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: open watched files without waiting on a FIFO

Tracker::poll, Tracker::new and fingerprint opened the path with File::open
before stat checked the file type. A FIFO with no writer made that open wait,
and poll_entry held the entry lock for the whole call, so one such path stalled
every link on the watcher and the watcher drop. The open now sets O_NONBLOCK
(new crate fsopen), and stat rejects the FIFO on the open handle with
LinkError::Invalid. A check before the open would not close the window between
check and open.

craft-ipc gains a unix-only dependency on libc for the open flags. libc 0.2.190
is already in Cargo.lock. The lock file gains one dependency line for craft-ipc.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: read_private checks and reads one open handle

read_private checked the path with symlink_metadata and then read it with
fs::read, so the entry could change between the two calls. On Unix it now opens
once with O_NOFOLLOW and O_NONBLOCK, checks type, owner and mode on that handle,
and reads from the same handle. A symlink is still Refused (found by looking at
the path after a failed open, because the errno differs between Unix systems), a
FIFO is Refused and cannot stall the open, and a missing file is still an I/O
error. Other platforms keep the old checks. Tests cover the symlink and FIFO
cases.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: Tracker reports an epoch it cannot raise instead of a false bump

apply saturated the epoch at u64::MAX while poll and relink still returned
bumped: true, so Change::bumped (documented as one added to the epoch) was
false and a cached frame kept passing for changed content. poll and relink now
return LinkError::Invalid and leave the tracker as it was when the bump would
pass u64::MAX. A test covers both calls.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: document write_atomic errors that follow the rename

The directory flush and the fingerprint run after the rename. An error from
either can be returned while the path already holds the new bytes. The doc
comment now says so.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: say that check_executable accepts group-writable paths

The module and function docs described the check as protection from other local
users. A group-writable file or directory passes, and the other members of its
group can replace it. The docs now state that and keep the private-group
reason. Behavior is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: refuse an auth line that completes after the deadline

authenticate returned a completed line before it looked at the deadline, so a
line that finished after auth_deadline still authenticated. The overshoot was up
to one 250 ms read poll. The deadline is now checked first, with the same
auth failure reply as the other expiry paths. A test sends the line between the
deadline and the next poll.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: do not append an error record after a partial frame write

send_frame wrote an error record whenever write_frame failed. When the failure
came from the stream (for example a send timeout in the middle of a record), the
first record was cut short, and a peer that drained the buffer then read the
error record as the rest of it. send_frame now checks that the record can be
built before it writes. A record that cannot be built gets the error record as
before. A write failure is returned alone and the bulk loop closes the
connection.

wire gains check_cfrm, the pre-write part of write_cfrm. write_cfrm behaves as
before.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: LineReader applies the line limit to a last line without a newline

At end of stream LineReader::read returned a buffered line with no length
check, so a peer that sent one byte over the limit and closed its write side got
that line dispatched, while the same bytes with a newline were refused. The end
of stream path now returns TooLarge for a line over the limit. A test covers
both paths.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: answer a control reply over the line limit with payload_too_large

write_value passed every reply to write_line, which has no size check. A sink
result larger than MAX_LINE went out as one line that the client refuses, and the
rest of the line stayed unread on the connection. Replies now go through
wire::write_reply_line. A reply over the limit is replaced by a payload_too_large
error that keeps the request id. When that does not fit either, or the value has
no id, nothing is written and the request loop ends. Event lines are unchanged.

wire gains write_reply_line. write_line behaves as before.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: accept a shallow or deep poll in the native ticker test

The test expected the first notice to come from a shallow poll. With a 50 ms deep
interval the poll that first sees the edit can be a deep one, so the assertion
failed on a slow or loaded machine. It now takes the deep flag from the notice
and checks every other field.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: refuse a frame stride that cannot hold one row

FrameLayout::check only tested len == stride * h, so w = 4, stride = 1, h = 3,
len = 3 was a valid rgba8 layout. A reader that splits the payload by stride
cannot decode it. frames.open, a rendered frame and the client reply parser now
require stride >= w * bytes per pixel (4 for rgba8_premul, 8 for rgba16f_premul).
open checks before it mints a ticket, so a refused layout leaves no ticket.

The bulk test source used stride 16 for rgba16f with w = 4, which needs 32. It
now uses a stride that fits the format.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: reject calendar days that do not exist in a record's created field

valid_rfc3339 checked the day only against 1 to 31, so 2026-02-31T09:30:00Z
passed LinkRecord::validate while the schema's date-time format refused it. The
year, month and day now go through chrono::NaiveDate::from_ymd_opt, as the
workspace rules require for calendar logic. The accepted syntax is unchanged.
The schema agreement table gets rows for impossible days and for leap days.

craft-ipc gains the workspace chrono dependency. chrono is already in Cargo.lock;
the lock file gains one dependency line for craft-ipc.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: make the link record moniker pattern match Moniker::parse

The asset.moniker pattern accepted any id without / ? #, so a record the schema
passed could fail LinkRecord::validate (bad or truncated escape, raw space,
escape that decodes to invalid UTF-8, id over 512 bytes). The pattern is now two
patterns under allOf. One checks the shape: unreserved characters and two-digit
escapes only, 1 to 512 of them, which is 1 to 512 decoded bytes. The other checks
that the decoded bytes are valid UTF-8, written as the well-formed UTF-8 byte
sequences. Neither uses lookahead, so any ECMA 262 engine can run them.

The schema agreement test gets rows for each case in the list above and for the
length limits, and a sweep of lead, second and tail bytes that compares the schema
verdict with the Rust verdict. This tightens the published schema: documents it
accepted that Rust refused are now refused.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: document that Assets methods must return in bounded time

Server::shutdown and drop join every connection thread, and an Assets call runs
on one with no deadline and no view of the stop flag. The trait docs now say so
and ask implementations to bound their own I/O. Behavior is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: name the writer type in the listener tests

Clippy's type_complexity lint failed on the test helper's return type. Behavior
is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: run Assets and Activate calls on detached helper threads with a deadline

Server::shutdown and drop join every connection thread, and an Assets or
Activate call ran on one with no deadline and no view of the stop flag, so a
provider that never returned made shutdown hang.

These calls now run on a helper thread (server/provider.rs). The connection
thread waits for the answer in 100 ms slices, for at most
Limits::provider_deadline (default REPLY_DEADLINE_SECS) and not past the stop
flag. On timeout the caller gets a timeout reply and the helper is detached, so
shutdown does not join it. At most 32 helper threads are alive at once, stuck
ones included, and a call past that gets a busy error without starting a thread.
A panic in a provider becomes an io_error reply.

Frames stays on the connection thread because it is one call per frame. Its
trait docs now say that the stop flag is checked before each request and that a
running call is waited for. The module docs describe the shutdown guarantee for
each provider kind.

Public API: new Limits::provider_deadline field. Tests use a provider that
blocks until released, for Assets and for Activate.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: give a caller whose queued ask was dropped a Failed outcome

When the fetch queue was full, the oldest ask was dropped but its waiting
callers got no answer. They woke, found the key neither cached nor in flight,
and queued it again, which dropped another ask and repeated the cycle.

A dropped ask now records a failure for its key before the waiters are woken, so
each waiter returns Fetched::Failed and does not queue the key again. The
drop-oldest policy and stats.skipped are unchanged. Failure records are
shared with the worker path and kept to a fixed number, oldest first.

No type or variant changes. The Fetched::Failed doc now covers this case. A test
overflows the queue while a caller waits on the oldest key, and checks that the
caller returns at once and that no further asks are dropped.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: require two hex digits in a file URL percent escape

percent_decode used u8::from_str_radix, which accepts a leading plus, so
file:///tmp/a%+fb decoded to the byte 0x0f and went on to the media probe
instead of getting payload_invalid. The two bytes after a percent sign must now
both be ASCII hex digits. The decode test gets a plus, a minus, a space and a
short escape.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: make the euid probe create only its own file, and gate the macOS path test

On Unix systems other than Linux, current_euid read the owner of a file named
.craft-uid-<pid> in the temp directory, made with create and truncate. A file or
symlink planted at that name was opened and truncated. The probe now lives in
probe_euid: random name, create_new (which refuses an existing path), mode 0600,
and removal before it returns. The std library has no safe euid call and this
crate forbids unsafe code, so the probe stays. A test plants a file and a symlink
at the old and a similar name and checks that both are untouched and that the
probe file is gone.

macos_fallback_is_per_user compares Unix paths, so it and the macos_runtime_path
helper it needs are now compiled for tests on Unix only. That removes the unused
function warning in Windows test builds.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* craft-ipc: an event larger than one line becomes an events.overflow marker

Server::emit wrote the serialized event unchecked. A line over MAX_LINE made
Client::next_event return TooLarge and left the stream out of sync. enqueue
now checks the serialized size and queues the existing overflow marker instead.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NFCDiYoKS325v2rtv2F7D8

* ipc: validate executable path ancestry

* ipc: preserve queued replies after macOS peer shutdown

* ipc: validate native transports and use portable platform fixtures

* Make IPC integration fixtures portable and collision-free

* Use native paths and unique directories across IPC fixtures

* Bound Windows pipe I/O and stabilize IPC tests

* Retry empty nonblocking Windows pipes

* #433: Serialize hub tests sharing a Windows pipe

* #433: Use native endpoint in schema capability tests

* ipc: report a non-regular watch target as Invalid on every platform

* ipc: format the new error classification

---------

Co-authored-by: User <bigwolfeman@users.noreply.github.com>
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 09:55:22 -05:00
..

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::LineReader keeps the partial line. Do not read control lines with a stateless read_line on a stream that has a receive timeout.
  • On Unix, the socket file is mode 0600 inside a 0700 directory. 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::Limits holds 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_path is 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. InstanceRecord keeps caps in extra. Use caps() and add_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::resolve finds an app binary (environment, a read-only parse of the launcher's install record, PATH, usual install locations). launch starts it only when trust::check_executable accepts 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().