* 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>
19 KiB
Craft Link protocol, version 1
Extends the existing Craft control channel (the control protocol document of each app). Every
existing method keeps its exact behaviour. New methods are additive. craft-ipc implements this
protocol.
1. Transport and framing
- Endpoint: from the instance record (
schemas/instance-record.schema.json). Unix domain socket file (mode 0600, directory 0700) on Linux and macOS; named pipe with an owner-only SDDL descriptor on Windows; loopback TCP only when the user opts in (--control <port>, legacy). - Control framing: one UTF-8 JSON object per line, max 4 MiB per line. A request has
method(string), optionalid(number or string), optionalparams(object). A reply has the request'sid,ok(bool), andresultorerror. Malformed input gets one error line and the connection is closed (existing behaviour). - Push events (new): lines with
eventandseqand noid:{"event": "<name>", "seq": <u64>, "data": {...}}. Sent only on connections that calledevents.subscribe. Per-subscriber queue of 256; on overflow the server sends{"event":"events.overflow","seq":n,"data":{"since":<seq>}}and drops events until the client catches up. - Bulk connection (new): a second connection to the same endpoint, used only for frames (section 6).
- Connection limit: 16 concurrent connections per app (existing). Bulk connections count. At most
4 of the 16 may be unauthenticated at one time; the other 12 slots go only to peers that sent the
right token. A peer past either limit gets one line
{"ok":false,"error":"too many control connections"}or"too many unauthenticated connections"and a close. - Time limits (server defaults): a connection must send a valid
authline within 2 s of the accept; a request line that has started must end within 10 s; an authenticated control connection with no input for 1 h, no event subscription and no bulk role is closed with{"id":null,"ok":false,"error":"idle connection closed"}. A client that keeps a quiet connection longer must callevents.subscribeor reconnect. A request may arrive in any number of pieces with pauses between them; the server keeps the bytes of an unfinished line. - Launch on demand (library rule, not wire):
craft_ipc::launchruns an app binary only if the path is absolute and the file is regular and executable, and the file and its directory belong to the user or root and are not writable by every user. Empty and relativePATHentries are skipped. A fork that starts an app by another route must callcraft_ipc::trust::check_executable. Caches usecraft_ipc::cache::private_cache_dir(0700, owner checked, no symlink, no fallback to a shared temp directory);CRAFT_LINK_CACHE_DIRmust be absolute.
2. Authentication (required on every transport: sockets, pipes, loopback TCP)
The first line on every connection must be:
{"id": 0, "method": "auth", "params": {"token": "<64 hex from the instance record>"}}
Reply {"id":0,"ok":true,"result":{"authenticated":true}}, or
{"id":0,"ok":false,"error":"authentication required"} followed by close. The server also checks
the peer's user id (Linux/macOS euid; Windows token user) and refuses other users. Any other first
line gets the same refusal. (Shape copied from PhotoCraft's existing handshake.)
Loopback TCP (--control <port>, legacy) runs the same handshake, the same unauthenticated cap and
the same 2 s auth deadline. It binds 127.0.0.1 only. There is no uid check on TCP, so the token is
the only proof. The instance record (0600) publishes the port as tcp_port next to the token;
a TCP client reads both from the record (Client::connect_tcp). Never print the token or put it
in a config file or on a command line. A TCP client without a token gets the auth refusal.
3. Session methods (answered on the connection thread, no UI frame needed)
link.hello
{"id":1,"method":"link.hello","params":{"client":{"app":"filmcraft","app_version":"0.9.1","pid":4242,"instance":"<uuid>"},"protocol":{"min":1,"max":1}}}
-> {"id":1,"ok":true,"result":{"app":"effectcraft","app_version":"0.8.3","pid":5151,"instance":"<uuid>","protocol":1,"caps":["events","frames","activate","link.receive"]}}
Errors: protocol_unsupported{server_min, server_max}. The client must check pid and instance
equal the instance record. Legacy clients that never call link.hello keep today's behaviour.
caps is the fixed base set (events, activate, link.receive, frames) plus the caps array of
the instance record (schemas/instance-record.schema.json), without duplicates. Roles and optional verbs use
this array. Defined names:
| Cap | Meaning |
|---|---|
hub |
The peer is a browser or launcher hub. It owns no document, it only reads and opens assets (section 9). |
assets |
The peer answers link.resolve and asset.describe itself, on the connection thread (section 4). |
A client that does not know a cap ignores it.
events.subscribe / events.unsubscribe
{"id":2,"method":"events.subscribe","params":{"events":["doc.changed","link.changed","app.closing"]}}
-> {"id":2,"ok":true,"result":{"seq":0}}
app.activate
{"id":3,"method":"app.activate","params":{"token":"<xdg activation token or null>","from_pid":4242,"open":{"link_id":"<uuid>"}}}
-> {"id":3,"ok":true,"result":{"activated":"requested"}}
activated has three values:
| Value | Meaning |
|---|---|
true |
The window has focus now. |
"requested" |
The app asked the OS to focus the window. The OS decides later. Nobody confirmed it, and the reply does not say it will happen. |
false |
Focus was not taken. The app asked for user attention instead (taskbar flash, dock bounce). |
On Linux, "requested" needs a token that the app could apply to its existing window. An app whose
toolkit can mint a token but cannot apply one (stock winit 0.30 on Wayland) answers false. The
sender can still pass token. Old senders and receivers keep working: the three values did not change.
activated is distinct from the existing ui.focus method, which never steals focus by design.
open is an object that names what to show. It carries link_id (open a link), asset (a moniker,
section 9: open that asset in its document) or both. A hub or launcher uses asset to send the user
to the app and document that owns the asset, with no link in between. The server rejects an asset
that is not a valid moniker with bad_params. An open with neither key is passed on unchanged
(existing behaviour). The receiving app decides what "show" means for the asset.
link.bye
Clean close. The server drops subscriptions and bulk tickets of this connection.
4. Link methods (run on the UI thread through the app's existing request channel)
link.open (FilmCraft -> EffectCraft)
{"id":10,"method":"link.open","params":{
"link_id":"<uuid>",
"payload":{"format":"otio-json","data":"<OTIO JSON string>"},
"place":{"seconds":12.48,"selection":[{"start_s":10.0,"end_s":14.0,"track_index":0}],"view":{"zoom":1.0}},
"result_path":"/abs/path/Project Links/<link_id>.mov",
"source":{"app":"filmcraft","doc_id":"<uuid>","item":"<nest item id>"}}}
-> {"id":10,"ok":true,"result":{"comp":"<comp id>","project":"/abs/path/Project Links/<link_id>.ecproj",
"format":{"w":1920,"h":1080,"rate_num":24,"rate_den":1,"duration_ticks":...,"alpha":true},
"unsupported":[{"what":"effect","name":"Lumetri Color","kept_as":"none"}]}}
Errors: payload_invalid, media_missing, payload_too_large (OTIO string > 4 MiB), io_error.
A request line longer than 4 MiB (MAX_LINE) is not an error reply: the server answers once in text
and closes the connection. unsupported lists parts that
did not survive the hand-off.
Payload formats. payload.format selects the shape of the rest of payload:
format |
Other fields | Use |
|---|---|---|
otio-json |
data: OTIO JSON string |
Video: a nested sequence (above). |
image-doc |
asset: moniker (section 9), path: absolute path of the producer document or image file |
Stills, vectors and other single images. result_path is the last-known flattened image. place, source and format in the reply stay as above. rate_num, rate_den and duration_ticks are absent from format in the reply. |
An unknown format gets payload_invalid. A new format value is additive and needs no protocol
bump. The server checks the shape of payload with craft_ipc::payload::OpenPayload before it
forwards link.open to the app. A missing payload, a payload that is not an object, a missing or
unknown format, a missing field, a relative path or a bad asset moniker gets payload_invalid
and the app never sees the request. params that is not an object stays bad_params. The server
checks shape, and for otio-json it also opens every ExternalReference whose target_url is a
file:// URL or an absolute path. A file that does not open gets media_missing with
data.missing (the paths) and the app never sees the request. A file:// URL whose path has a bad
percent escape, or does not decode to UTF-8, gets payload_invalid. Relative targets are left to the app.
Path rules. result_path, payload.path and every absolute media target_url must
be absolute, hold no NUL byte and no .. component, or the request gets payload_invalid. The
server does not canonicalise and does not confine paths to a root: footage lives anywhere and
may be a symlink. The media check is the only file probe. It looks only at paths the payload
names, at most 4096 distinct ones, and reports a path as missing when it is not a regular file
(after symlinks) or does not open for reading. A missing file, a directory, a FIFO, a device and a
file without read access all look the same, and the probe never opens a FIFO. An OTIO document
with more than 4096 distinct files, more than 2^20 JSON values or nesting over 128 gets
payload_invalid. The app must apply its own checks to result_path before it writes there;
the server check is a first filter.
An app still answers payload_invalid when the content is bad (for example OTIO that does not
parse).
link.attach (FilmCraft -> EffectCraft, reopen an existing link)
{"link_id","project","comp"} -> {"format", "epoch"}. Errors: comp_missing (link becomes Broken).
The receiver makes the comp of the link the active one. It reads project (the sidecar written by
link.open) when it holds no such link and has no unsaved edits, otherwise busy.
FilmCraft sends this when link.editIn runs on a clip that plays a linked item already. It nests
nothing and creates no item. On comp_missing or io_error (no sidecar, damaged sidecar) it sends
link.open again with the same link_id and result_path, built from the nest in nested_sequence.
link.focus (either direction, used by Back)
{"link_id","place"} -> {}. The receiver moves to place and is then activated with app.activate.
link.close
{"link_id"} -> {}. EffectCraft drops the binding; the sidecar project stays on disk.
link.refresh (consumer side, any app that holds a link)
{"link_id"} -> {"link_id","epoch","state":"current"|"modified"|"missing","result_path","hash"}.
The receiver compares the last-known result file with the disk (rules in section 10), bumps the epoch
when the content changed, and answers the state. hash is sha256:<64 hex> and is absent when the
state is missing. A link that exists in the receiver but whose file is gone is not an error. The
answer is state:"missing". Errors: link_unknown, bad_params, io_error.
link.resolve (producer or hub, any app that owns assets)
{"asset":"craft://..."} -> {"asset","path","epoch","size","hash","mtime_ms"}. path is an
absolute path of the last-known flattened result that a consumer can read now. hash is
sha256:<64 hex> of that file. epoch is the producer epoch. Errors: link_unknown (no such asset,
or the asset has no result file yet), bad_params (not a moniker), io_error.
asset.describe (producer or hub)
{"asset":"craft://..."} -> {"asset","name","kind","epoch","w","h","hash","thumb_path","modified_ms"}.
kind is still, vector, sequence or comp. w, h, hash and thumb_path are null when
unknown. thumb_path is an absolute path of a PNG, at most 512 px on the long side, that the
producer keeps in a per-document sidecar. A hub browses assets with this call and never opens the
document. Errors as link.resolve.
link.resolve and asset.describe have no side effects and never need a UI frame. A server that was
started with an asset provider (Server::start_with and Extensions) answers both on the connection thread
and lists assets in caps. link.refresh is answered by the provider the same way. A server
started without a provider forwards all three to the app like any other link method (existing
behaviour).
Events
link.changed:{"link_id","epoch"}. Sent by EffectCraft when the bound comp changes (anybump()whose change touches the comp).link.result:{"link_id","epoch","path"}. A fresh last-known result was written.doc.changed:{"doc_id","revision","cause"}. Generic change feed (fromcraft-command).app.closing:{}. Sent before a clean exit.
5. Command passthrough (existing, unchanged)
engine.execute {command, params}, engine.commands, ui.*, perf.stats keep their current
contracts. engine.commands now also lists plugin commands and carries a schema per command
(x-craft-source: doc | derived | opaque).
6. Bulk frames
- Control connection:
frames.open {"link_id","format":"rgba8_premul"|"rgba16f_premul","scale":1.0}->{"ticket":"<32 hex>","w","h","stride","len"}. - New connection:
auth, then{"method":"bulk.attach","params":{"ticket":"..."}}->{"ok":true}. The connection is now binary in both directions. - Client request record (binary):
'CFRQ' | u32 header_len | header JSONwith header{"req":<u64>,"time_s":<f64>,"epoch":<u64>,"region":[x,y,w,h]|null}. - Server reply record:
'CFRM' | u32 header_len | u64 payload_len | header JSON | payload, header{"req","epoch","w","h","stride","format","render_ms"}.epochis the epoch the frame was rendered at; a client that asked for an older epoch may get a newer one.payload_lenisstride * h, andstrideis at least one row:wtimes 4 bytes forrgba8_premul,wtimes 8 bytes forrgba16f_premul. A layout that breaks this is refused atframes.open, and a reply that breaks it is refused by the server and by the client. - Errors: header
{"req","error":"..."}withpayload_len0. All integers little endian. Tickets expire when the control connection closes.
7. Error codes (in error objects for new methods)
{"code": "<snake_case>", "message": "<human text>", "data": {...}}. Codes: auth_required,
protocol_unsupported, unknown_method, bad_params, not_ready, payload_invalid,
media_missing, payload_too_large, comp_missing, link_unknown, io_error, busy, internal.
link_unknown also covers an unknown asset moniker.
Existing methods keep their current string error field.
8. Versioning
protocolis an integer. A server serves any client version in[min, max]. New methods and new optional fields do not bump the version. Removing or changing the meaning of a field does.- Method names are never reused with a different meaning.
9. Asset identity: the moniker
An asset is addressed by a moniker, a string that stays valid across restarts:
craft://<app>/<doc>/<kind>/<id>
| Part | Rule |
|---|---|
app |
Same pattern as the instance record app: ^[a-z][a-z0-9-]{1,31}$. The app that owns the document. |
doc |
The document id, a UUID in 8-4-4-4-12 hex form. Parsers accept either hex case and keep the text as written. |
kind |
^[a-z][a-z0-9-]{0,31}$. Known values: comp, image, vector, sequence, layer. An unknown value is valid and is kept. |
id |
Non-empty, at most 512 bytes after decoding, valid UTF-8. Characters other than A-Z a-z 0-9 - . _ ~ are percent-encoded as %XX (uppercase hex) by the formatter. The parser accepts either hex case. A raw /, ?, # or % not followed by two hex digits is invalid. |
The asset.moniker pattern in schemas/link-record.schema.json states the same id rules, so a
record that the schema accepts also parses in Rust.
A moniker has no query and no fragment. It names an asset, not a state: the state is the epoch.
A moniker can outlive its asset. Resolving a dead moniker gives link_unknown. Parsing then
formatting a moniker gives the canonical text (uppercase %XX). Formatting then parsing gives back
an equal moniker. craft_ipc::moniker::Moniker implements both. The module uses only serde and
std, so an app can copy it to a wasm build. The craft-ipc crate as a whole still does not build
for wasm32 (local sockets).
10. Refresh and watch rules for linked files
These rules apply to any linked asset with a result_path (a still, a rendered movie).
- Producer writes are atomic. The producer writes the file to a temporary name in the same
directory (
.<name>.<pid>.<n>.tmp), flushes it, renames it overresult_path, and then flushes the directory. A reader sees the old file or the new file, never a half file. A reader ignores names that start with.and end with.tmp. - Epoch.
result_epochis a counter of result versions. The producer adds 1 on every saved change and emitslink.changedandlink.result. A consumer that detects a change by polling (rule 4) adds 1 to its own stored epoch. When the producer is reachable again, the consumer keeps the larger of the two values. An epoch never decreases. - Fingerprint.
(size, mtime_ms, sha256)of the file. The hash is of the full content. - Polling when the producer is offline. The consumer calls
pollabout once per second (craft_ipc::watch::Watcherruns this schedule with a thread and an injectable ticker). A poll reads size and mtime. It hashes the file only when size or mtime differ from the last fingerprint. Some file systems have coarse mtime, so the consumer also calls a deep poll (always hash) about once every 30 seconds. A touch that leaves the hash equal does not bump the epoch. - States.
current(disk equals what the consumer loaded),modified(disk differs from what the consumer loaded; the epoch was bumped),missing(the file does not exist). The consumer movesmodifiedtocurrentwhen it has loaded the new content. A file that returns with the hash it had when loaded goes back tocurrentwith no epoch bump. A file that returns with a different hash ismodifiedand bumps the epoch. - Other read errors (permission denied, I/O error) are errors, not
missing. The state does not change and the next poll tries again. - Relink. A consumer can point a link at a new path. The new path is polled at once. The state
is
currentwhen its hash equals what the consumer loaded andmodified(epoch bump) otherwise. A missing new path is rejected and the old path stays.