IPC Protocol
This page is the contributor-facing reference for the protocol spoken between the daemon (yerdd) and its clients - the yerd CLI and the Tauri desktop app. Everything here lives in the yerd-ipc crate (crates/yerd-ipc/), with socket/pipe binding deferred to the binaries.
The crate has three jobs, layered so they can be tested in isolation:
message model Request / Response / ErrorCode + status payloads (always built)
JSON codec encode_message / decode_message (serde_json) (always built)
frame codec encode_frame / FrameDecoder (4-byte length prefix) (always built)
----------------------------------------------------------------------------------
transport read_frame / read_message / write_message (tokio) (feature = "transport")
socket / pipe interprocess local-socket bind + connect (lives in the binaries)The top three layers are pure: no sockets, no async, no I/O. The transport feature pulls in tokio async helpers; the actual socket/named-pipe binding never enters the crate at all - it lives in yerdd, yerd, and the Tauri sidecar.
Source map
crates/yerd-ipc/src/: lib.rs (re-exports + PROTOCOL_VERSION), frame.rs (framing), message.rs (JSON codec), request.rs / response.rs / status.rs (the wire types), dump.rs (the Laravel ▸ Dumps data model: DumpCategory, DumpEvent, DumpCounts, DumpExtStatus), error.rs (FrameError / IpcError), transport.rs (feature-gated async helpers). Tests: tests/frame_codec.rs, tests/wire_stability.rs, tests/roundtrip.rs. Browse them on GitHub.
Transport
The default build of yerd-ipc has no transport at all. Enable it explicitly:
# yerdd / yerd / the Tauri backend depend on it like this
yerd-ipc = { path = "../../crates/yerd-ipc", features = ["transport"] }In the crate's own Cargo.toml, tokio is optional = true and the feature simply turns it on:
[features]
default = []
transport = ["dep:tokio"]Keeping the codec runtime-free means tests of framing and wire shapes compile and run with no async runtime, and any consumer that only needs the types (for example, to share Request/Response definitions) pays nothing for tokio.
The transport helpers in transport.rs are generic over tokio::io::AsyncRead / AsyncWrite - they never name a concrete socket type. The concrete binding is done in the binaries with the interprocess crate's local_socket, which maps to:
- Unix domain socket on macOS and Linux -
<runtime>/yerd.sock, where<runtime>is resolved byyerd-platform(with the/tmp/yerd-$UIDfallback whenXDG_RUNTIME_DIRis unset). The daemon removes any stale socket file, thenrestrict_to_owners it (0o700runtime dir plus an owner-only socket) because the IPC server performs no peer-credential check - file permissions are the access boundary. - Named pipe on Windows - currently
yerd-<pid>viaGenericNamespaced.
The daemon side (bin/yerdd/src/startup.rs) selects the name per OS:
#[cfg(unix)]
let socket_path = dirs.runtime.join("yerd.sock");
// ... to_fs_name::<GenericFilePath>() ...
#[cfg(windows)]
let name = {
let pipe = format!("yerd-{}", std::process::id());
pipe.clone().to_ns_name::<GenericNamespaced>()? // namespaced pipe
};
let listener = ListenerOptions::new().name(name).create_tokio()?;Windows client is not wired up yet
The yerd CLI derives the Unix socket path identically to the daemon, so they always agree. The Windows pipe name is PID-based and therefore not derivable by a client; the CLI returns ClientError::DaemonUnreachable on non-Unix targets today. This is tracked as a follow-up - treat full Windows client support as roadmap. See Cross-Platform Model.
The accept loop is one tokio::spawn per connection, and a connection is a long-lived request/response stream - the daemon reads a Request, dispatches it, writes a Response, and loops until EOF (bin/yerdd/src/ipc_server.rs). The CLI typically does a single exchange and drops the connection.
Framing
Every message is one length-prefixed frame: a 4-byte big-endian u32 length followed by exactly that many payload bytes. The codec is byte-agnostic - it takes and returns &[u8] / Vec<u8> and never inspects the payload - so framing and the JSON codec are fully orthogonal.
+----------------+--------------------------------+
| len: u32 (BE) | payload: `len` bytes |
+----------------+--------------------------------+
4 bytes 0 .. DEFAULT_MAX_FRAMEThe maximum frame size is 16 MiB:
/// 16 MiB - the default maximum frame size on both sides.
pub const DEFAULT_MAX_FRAME: usize = 16 * 1024 * 1024;Encoding
encode_frame validates the payload length against a caller-supplied max (inclusive - len == max is allowed) and prepends the big-endian length:
pub fn encode_frame(payload: &[u8], max: usize) -> Result<Vec<u8>, FrameError>;It fails with FrameError::TooLarge { size, max } if the payload exceeds max, or FrameError::PayloadOverflowsLengthPrefix { size } if the length does not fit in the 4-byte prefix (only reachable on 64-bit hosts). Both sides default to DEFAULT_MAX_FRAME; the sender's cap lets it reject an oversized payload before it ever hits the wire, while the receiver enforces its own cap independently.
Decoding - FrameDecoder
FrameDecoder is the stateful read side. You feed it socket bytes and pull complete frames:
let mut dec = FrameDecoder::new(); // DEFAULT_MAX_FRAME cap
dec.extend_from_slice(&chunk); // append raw socket bytes
match dec.next_frame()? {
Some(payload) => { /* one full frame; surplus stays buffered */ }
None => { /* header or body incomplete - read more */ }
}It is built to survive the realities of stream sockets, all pinned in tests/frame_codec.rs:
| Situation | Behaviour |
|---|---|
| Partial header (< 4 bytes) | next_frame() returns Ok(None) |
| Partial body (header read, body short) | Ok(None) |
| Multiple frames in one buffer (pipelined) | successive next_frame() calls drain them in order |
| Trailing surplus bytes | kept buffered for the next frame; buffered() reflects the count |
| Slow-loris, one byte at a time | reassembles correctly over many extend_from_slice calls |
Declared length > max | Err(FrameError::TooLarge { size, max }), decoder is poisoned |
Decoder poisoning
When next_frame rejects an oversized declared length, the decoder is poisoned: it clears (and shrinks) its internal buffer to release memory, every later next_frame() returns the same TooLarge error, and extend_from_slice becomes a no-op. Because buffered() then returns 0, a subsequent EOF on a poisoned decoder surfaces through the transport layer as IpcError::UnexpectedEof { bytes: 0 }. Tested by decoder_stays_poisoned_after_oversized.
An empty payload is a valid frame - encode_frame(b"", _) yields exactly [0, 0, 0, 0].
JSON codec
message.rs is a thin pair of serde_json wrappers that map errors into the IPC error space:
pub fn encode_message<T: Serialize>(value: &T) -> Result<Vec<u8>, IpcError>; // -> IpcError::Encode
pub fn decode_message<T: DeserializeOwned>(bytes: &[u8]) -> Result<T, IpcError>; // -> IpcError::DecodeThe framing layer carries this UTF-8 JSON; the two never depend on each other.
Message model
Both envelopes are enums, internally tagged on type, snake_case, and #[non_exhaustive]:
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum Request { /* ... */ }#[non_exhaustive] means consumers in other crates cannot exhaustively match, so new variants are additive without a breaking change.
The two derives differ in one respect: Request derives Eq, but Response does not - it is PartialEq only. Response::Dumps carries DumpEvents whose payload is an opaque serde_json::Value (which can hold floats, so it is PartialEq but not Eq). PartialEq is all the wire-stability round-trips need on the response side.
Request (client → daemon)
The variant set is the daemon's whole RPC surface - liveness, site management, PHP version management, database/cache service management, SQL database administration, mail capture, dump telemetry, Cloudflare Tunnel sharing, status/doctor, and daemon lifecycle. A representative sample with its exact wire shape (the full list of tags lives in request.rs):
| Variant | Wire JSON |
|---|---|
Ping | {"type":"ping"} |
ListSites | {"type":"list_sites"} |
Park { path } | {"type":"park","path":"/srv/foo"} |
Link { name, path } | {"type":"link","name":"foo","path":"/srv/foo"} |
SetPhp { name, version } | {"type":"set_php","name":"foo","version":"8.3"} |
SetSecure { name, secure } | {"type":"set_secure","name":"foo","secure":true} |
SetWebRoot { name, path: Option } | {"type":"set_web_root","name":"foo","path":"public"} or …,"path":null (reset to auto-detect) |
AddDomain { name, domain } | {"type":"add_domain","name":"foo","domain":"api.foo.test"} (exact host or single-label wildcard *.foo.test) |
RemoveDomain { name, domain } | {"type":"remove_domain","name":"foo","domain":"api.foo.test"} (refused for a site's last exact domain) |
SetPrimaryDomain { name, domain } | {"type":"set_primary_domain","name":"foo","domain":"corp.foo.test"} (exact host only, never a wildcard; auto-added if absent) |
ResetDomains { name } | {"type":"reset_domains","name":"foo"} (back to apex only) |
InstallPhp { version, confirm_legacy } | {"type":"install_php","version":"8.5"} (confirm_legacy defaults false and is skipped on the wire; {"type":"install_php","version":"7.4","confirm_legacy":true} to install a legacy minor) |
InstallPhpStreamed { version, confirm_legacy } | {"type":"install_php_streamed","version":"8.5"} (same confirm_legacy convention; replies JobStarted; poll JobStatus) |
UpdatePhp { version: Option } | {"type":"update_php","version":"8.5"} or …,"version":null |
SetPhpSettings { settings } | {"type":"set_php_settings","settings":{…}} |
SetPhpVersionSettings { version, settings } | {"type":"set_php_version_settings","version":"8.3","settings":{…}} (per-version overrides; "" removes → falls back to global) |
SetPhpDirectives { version, directives } | {"type":"set_php_directives","version":"8.3","directives":{"xdebug.mode":"debug"}} (free-form ini directives; "" removes) |
SetPhpPoolSettings { version, settings } | {"type":"set_php_pool_settings","version":"8.4","settings":{"max_children":"32"}} (FPM pool settings, currently only max_children at 1..=1024; "" resets to the default of 16; never reaches the CLI ini) |
SetXdebug { version: Option, enabled, modes: Option, start: Option } | {"type":"set_xdebug","version":"8.4","enabled":true,"modes":["debug","profile"],"start":"trigger"} or minimally {"type":"set_xdebug","enabled":false} (the bundled Xdebug toggle; an omitted version means the default PHP, omitted modes/start keep the version's current value; replies PhpVersions) |
AddPhpExtension { version, path, name: Option, zend } | {"type":"add_php_extension","version":"8.5","path":"/a/scrypt.so","name":null,"zend":false} |
RemovePhpExtension { version, name } | {"type":"remove_php_extension","version":"8.5","name":"scrypt"} |
ListPhpExtensions | {"type":"list_php_extensions"} (replies PhpExtensions { by_version }) |
ListServices / AvailableServices | {"type":"list_services"} / {"type":"available_services"} |
InstallService { service, version } | {"type":"install_service","service":"redis","version":"8"} |
ChangeServiceVersion { service, version } | {"type":"change_service_version","service":"redis","version":"8.1"} |
UninstallService { service, version, purge } | {"type":"uninstall_service","service":"redis","version":"8","purge":false} |
StartService / StopService / RestartService | {"type":"start_service","service":"redis"} (and stop_/restart_) |
SetServicePort { service, port } | {"type":"set_service_port","service":"redis","port":6380} |
SetServiceOverrides { service, overrides } | {"type":"set_service_overrides","service":"mysql","overrides":{"max_connections":"500","sql_mode":""}} (free-form engine config directives, merged into the instance; "" removes a key; takes effect on the next start/restart, nothing is restarted implicitly) |
ServiceOverrides { service } | {"type":"service_overrides","service":"mysql"} (replies ServiceOverrides { overrides }) |
AddRouteRule { site, prefix, target } | {"type":"add_route_rule","site":"portal","prefix":"/api","target":"api/index.php"} (target is relative to the served root; never absolute, never containing ..) |
RemoveRouteRule { site, prefix } | {"type":"remove_route_rule","site":"portal","prefix":"/api"} |
ListRoutes | {"type":"list_routes"} (replies Routes { rules }) |
SetResponseHeader { site, name, value } | {"type":"set_response_header","site":"api","name":"Access-Control-Allow-Origin","value":"https://app.test"} (replaces the site's existing entry with that name, ignoring case; validated by the daemon) |
RemoveResponseHeader { site, name } | {"type":"remove_response_header","site":"api","name":"Access-Control-Allow-Origin"} (name matched ignoring case) |
ListResponseHeaders | {"type":"list_response_headers"} (replies ResponseHeaders { headers }) |
ServiceLogs { service, lines } | {"type":"service_logs","service":"redis","lines":100} |
ListDatabases { service } | {"type":"list_databases","service":"mysql"} |
CreateDatabase / DropDatabase | {"type":"create_database","service":"mysql","name":"app"} (and drop_database) |
BackupDatabase { service, name, path } | {"type":"backup_database","service":"mysql","name":"app","path":"/tmp/app.sql"} |
RestoreDatabase { service, name, path } | {"type":"restore_database","service":"mysql","name":"app","path":"/tmp/app.sql"} |
Status | {"type":"status"} |
Diagnose / DoctorFix | {"type":"diagnose"} / {"type":"doctor_fix"} |
RestartDaemon | {"type":"restart_daemon"} (Unix-only re-exec) |
ListMails | {"type":"list_mails"} |
GetMail { id } | {"type":"get_mail","id":"000001"} |
ClearMails | {"type":"clear_mails"} |
DeleteMails { ids } | {"type":"delete_mails","ids":["000001"]} |
MarkMailsRead { ids } | {"type":"mark_mails_read","ids":["000001"]} |
SetMailPort { port } | {"type":"set_mail_port","port":2525} |
SetMailEnabled { enabled } | {"type":"set_mail_enabled","enabled":true} |
SetMcpEnabled { enabled } | {"type":"set_mcp_enabled","enabled":true} |
ListDumps { since_id } | {"type":"list_dumps","since_id":0} |
ClearDumps | {"type":"clear_dumps"} |
DeleteDump { id } | {"type":"delete_dump","id":1} |
SetDumpsEnabled { enabled } | {"type":"set_dumps_enabled","enabled":true} |
SetDumpsPort { port } | {"type":"set_dumps_port","port":2304} |
SetDumpFeature { feature, enabled } | {"type":"set_dump_feature","feature":"queries","enabled":true} |
SetDumpsPersist { persist } | {"type":"set_dumps_persist","persist":true} |
DumpsStatus | {"type":"dumps_status"} |
ListTools | {"type":"list_tools"} |
InstallTool { tool } | {"type":"install_tool","tool":"node"} |
UninstallTool { tool } | {"type":"uninstall_tool","tool":"bun"} |
InstallNode { version } | {"type":"install_node","version":"24"} (blocking; major, minor, exact, node, lts/*, or lts/<codename>; the CLI sends it only with --json) |
SetNodeVersion { version, site: Option } | {"type":"set_node_version","version":"22.9.0","site":"blog"} or …,"site":null (global default) |
ListNode | {"type":"list_node"} (replies NodeVersions { installed }; disk only) |
AvailableNode | {"type":"available_node"} (replies AvailableNode { majors }; fetches the nodejs.org index on demand) |
InstallNodeStreamed { version, update } | {"type":"install_node_streamed","version":"22"} (update defaults false and is skipped; …,"update":true may move the global default; replies JobStarted) |
UninstallNode { version } | {"type":"uninstall_node","version":"22.9.0"} (one exact release; replies NodeVersions) |
ClearNodeVersion { site } | {"type":"clear_node_version","site":"blog"} (removes the saved preference; idempotent; replies Ok) |
NodeSite { site } | {"type":"node_site","site":"blog"} (replies NodeSite) |
NodeSites | {"type":"node_sites"} (replies NodeSites { sites }, one entry per routed site) |
ReleaseNotes | {"type":"release_notes"} (replies ReleaseNotes; the running release's notes plus up to 5 earlier stable releases, read from the CDN release-notes/<tag>.json files and cached for 6 hours; a failed refresh serves the stale value, and internal is returned only with nothing cached) |
Contributors | {"type":"contributors"} (replies Contributors; GitHub contributors with bots removed, cached for 24 hours, stale on failure like ReleaseNotes) |
SetSiteFavourite { site, favourite } | {"type":"set_site_favourite","site":"blog","favourite":true} (stars or unstars a site in the GUI; idempotent, not validated against live sites; replies Ok) |
CreateSite { spec } | {"type":"create_site","spec":{"name":"blog","parent_dir":"/srv","php":"8.3","secure":false,"framework":{"framework":"wordpress",…}}} (replies JobStarted; poll JobStatus) |
AvailableWordpressVersions | {"type":"available_wordpress_versions"} |
MintWordpressLoginToken { site } | {"type":"mint_wordpress_login_token","site":"blog"} |
SetWordpressAutoLogin { name, enabled, user: Option } | {"type":"set_wordpress_auto_login","name":"blog","enabled":true,"user":"admin"} |
WordpressAdminUsers { site } | {"type":"wordpress_admin_users","site":"blog"} |
Database name has operation-specific validation. CreateDatabase uses Yerd's portable creation allowlist. DropDatabase, BackupDatabase, and RestoreDatabase address an existing engine database and preserve the supplied name exactly; only an empty name or embedded NUL is rejected. Drop and restore continue to protect engine system databases. ListDatabases returns exact decoded names in DatabaseSummary, including surrounding whitespace and line breaks.
Note Unpark { path: String } deliberately uses a String, not PathBuf: clients echo a value straight back from Response::Parked, and an exact-identity match avoids lossy path normalisation (the daemon does not canonicalise it).
Legacy PHP support: an additive confirm_legacy field
InstallPhp and InstallPhpStreamed both gained confirm_legacy: bool (#[serde(default, skip_serializing_if = "std::ops::Not::not")], last field): false is the default and is skipped on the wire, so an install of a supported version is byte-identical to before the field existed, and an old client's payload (missing the field entirely) decodes with confirm_legacy: false. The daemon requires confirm_legacy: true to install an out-of-support legacy version (7.4 / 8.0 / 8.1) and otherwise replies Response::Error { code: ErrorCode::LegacyRestricted, .. }.
CreateSite { spec: CreateSiteSpec } is the wizard's entry point (both Laravel and WordPress): CreateSiteSpec carries the shared fields (name, parent_dir, php, secure) plus a framework: Framework enum internally tagged on "framework" ("laravel" with LaravelOptions - including an optional node release to build frontend assets with and save as the site's Node preference, omitted for the default - "wordpress" with WordPressOptions - core version, locale, admin credentials, database engine/name/table-prefix). It replies JobStarted { job_id } immediately; the caller polls Request::JobStatus { job_id } (streamed via Response::JobProgress) the same way InstallPhpStreamed/InstallToolStreamed do. See yerdd's WordPress support section for what runs behind the job.
Response (daemon → client)
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum Response {
Pong,
Ok, // generic mutation success
Sites { sites: Vec<Site> },
Error { code: ErrorCode, message: String },
Parked { paths: Vec<String> },
Info { dns_addr, tld, ca_path, ca_fingerprint, http_port, https_port },
PhpVersions { installed, default, updates, settings, version_settings, directives, pool, ffi_versions, libvips_found, xdebug, xdebug_versions },
AvailablePhp { available, installed, legacy },
PhpExtensions { by_version }, // version → [PhpExtInfo{name,path,zend,present}]
Status { report: Box<StatusReport> }, // boxed: large payload
Diagnoses { items: Vec<Diagnosis> },
DoctorFix { report: FixReport },
Services { services: Vec<ServiceStatus> },
AvailableServices { services: Vec<ServiceAvailability> },
ServiceOverrides { overrides: BTreeMap<String, String> }, // name → value, in name order
Routes { rules: Vec<RouteRuleEntry> }, // every site's path-prefix routing rules
ResponseHeaders { headers: Vec<ResponseHeaderEntry> }, // every site's custom response headers
ServiceLogs { lines: Vec<String> },
Databases { databases: Vec<DatabaseSummary> },
Mails { mails: Vec<MailSummary> },
Mail { mail: Box<MailDetail> }, // boxed: large payload
Tools { tools: Vec<ToolStatus> }, // installable dev tools
NodeVersions { installed: Vec<NodeRelease> }, // ListNode / UninstallNode
AvailableNode { majors: Vec<MajorLine> }, // newest major first
NodeSite { preference, project_file, effective, source, error },
NodeSites { sites: Vec<NodeSiteEntry> }, // NodeSite fields plus `site`, router order
ReleaseNotes { current: Option<Box<ReleaseNotesEntry>>, earlier: Vec<ReleaseNotesEntry> }, // `current` skipped when absent
Contributors { contributors: Vec<Contributor>, total: u32 }, // GitHub order, bots excluded
WordpressVersions { versions: Vec<WordPressVersionInfo> },
WordpressLoginToken { token: String },
WordpressAdminUsers { users: Vec<WordPressAdminUser> },
Dumps {
events: Vec<DumpEvent>,
removed_ids: Vec<u64>,
counts: DumpCounts,
latest_id: u64,
min_live_id: u64,
},
DumpsStatus {
enabled: bool,
port: u16,
running: bool,
persist: bool,
extensions: Vec<DumpExtStatus>,
counts: DumpCounts,
features: BTreeMap<String, bool>,
},
JobStarted { job_id: JobId }, // CreateSite / InstallToolStreamed / InstallPhpStreamed / InstallNodeStreamed
JobProgress { state: JobState, /* phase label, … */ }, // streamed updates
}Response::Ok is the generic success for mutating requests (Park, Link, Unlink, SetPhp, SetSecure, SetWebRoot, …). The large StatusReport is boxed so it does not bloat every Response value; Box<T> serializes transparently, so the wire bytes are unchanged.
The Site payload gained a field additively
Site (inside Response::Sites) gained an optional web_subpath after document_root. It is skipped when empty, so a root-served site's JSON is byte-identical to before the field existed - the wire-stability goldens for the empty case are unchanged, and only the non-empty case ("web_subpath":"public") added a new pin. Old clients ignore the field; no PROTOCOL_VERSION bump was needed.
WordPress fields on Site and SiteEntry
Site gained wp_auto_login: bool and wp_auto_login_user: Option<String>, both skipped on the wire when absent/false - same additive, no-bump pattern as web_subpath. Response::Sites's per-entry payload (SiteEntry, #[serde(flatten)] over Site) separately gained is_wordpress: bool, also skipped when false - it's a runtime detection fact (see wordpress_detect, yerdd's WordPress support), not a persisted config field, so it lives on the response wrapper rather than the config-backed Site itself.
Domain fields on SiteEntry, and StatusReport.shadows
The multi-domain feature adds three more SiteEntry fields alongside is_wordpress: primary_domain: Option<String> (the canonical FQDN, populated only when it differs from the default {name}.{tld} apex), domains: Vec<String> (the full routable set, populated only for a customized site), and apex_shadowed_by: Option<String> (the other site claiming this apex, if any). All three are skipped when default/empty, so a default site's Response::Sites bytes are byte-identical to before - same additive, no-bump pattern as web_subpath. Separately, StatusReport gained shadows: Vec<DomainShadow> (skipped when empty): one DomainShadow { site, shadowed_by } per site that lost a domain to another when the router was built, which yerd doctor surfaces as a DomainShadowed warning. The four domain mutators (AddDomain / RemoveDomain / SetPrimaryDomain / ResetDomains) reply with the generic Ok.
Favourites on SiteEntry
SiteEntry gained favourite: bool (last field, skipped when false): whether the user starred the site in the GUI, read from the config's [favourites] table. The matching mutator is Request::SetSiteFavourite { site, favourite }, which replies Ok. Same additive, no-bump pattern as web_subpath.
Framework on SiteEntry
SiteEntry gained framework: Option<SiteFramework> (after favourite, skipped when None): the framework detected at the site's project root, one of "laravel", "wordpress", "symfony", "statamic", "craft" or "drupal". It is served from a daemon cache refreshed on every router rebuild, like is_wordpress, and a WordPress site always reports "wordpress". A newer daemon may add values, so a strict older client decoding this enum fails closed; the GUI, CLI and daemon ship together.
Update availability on ToolStatus and CloudflaredStatus
ToolStatus (in Response::Tools) gained update_available: Option<String> (last field, skipped when None): the newer published version of a Yerd-managed, installed tool, matching PhpPoolStatus::update_available. Separately, the cloudflared status carried by Response::Tunnels (CloudflaredStatus) gained the same update_available field, set only for the Yerd-managed binary; a cloudflared found on PATH always omits it. Both are served from a daemon cache that a notify-only poll refreshes every 12 hours, so ListTools and TunnelStatus never touch the network. Same additive, no-bump pattern as external_path.
The mail payloads gained read/unread fields additively
For read/unread tracking, MailSummary gained a read: bool (last field) and MailStatus gained an unread: u32 (last field), both #[serde(default)]. A missing key decodes to false/0, so old daemons and old clients interoperate without a PROTOCOL_VERSION bump; the goldens grew a ,"read":false / ,"unread":0 suffix. The matching mutator is the additive Request::MarkMailsRead { ids }.
Mail attribution on MailSummary
MailSummary gained site: Option<String> (last field, skipped when None): the site the mail was attributed to from the host the sender announced in SMTP EHLO/HELO, resolved through the daemon's live router exactly like an HTTP Host: header. It is absent when the host does not match a site, for example a mailer that sends [127.0.0.1]. The value is stored in the capture store's index.json, so older indexes decode it as absent. Same additive, no-bump pattern as read.
AvailablePhp and DumpExtStatus gained a legacy field additively
Response::AvailablePhp gained legacy: Vec<PhpVersion> (last field, #[serde(default)], skipped when empty) - the installable legacy minors from php-legacy.json, ascending. Separately, dump.rs's DumpExtStatus gained legacy: bool (same #[serde(default, skip_serializing_if = "std::ops::Not::not")] convention, false/omitted for supported versions and older daemons) marking whether a PHP version's extension-presence row is a legacy version, so the Dumps view can flag it as unsupported without a second round-trip. Same additive, no-PROTOCOL_VERSION-bump pattern as web_subpath.
Reverse proxies are additive requests plus their own response variant
The proxy feature adds four mutators - AddProxy { name, url }, RemoveProxy { name }, AddProxyRule { site, prefix, url }, RemoveProxyRule { site, prefix } (all reply with the generic Ok) - and one query, ListProxies. Because a whole-host proxy is not a Site, it can't ride Response::Sites/SiteEntry; ListProxies gets a dedicated Response::Proxies { proxies: Vec<ProxyEntry>, rules: Vec<ProxyRuleEntry> } instead, where ProxyEntry { name, target, secure, primary_domain, domains } and ProxyRuleEntry { site, prefix, target, managed_by } (managed_by names the per-site service that owns the rule, omitted otherwise) are built from plain String/bool/Option<String>/Vec<String>, so they satisfy the PartialEq that Response derives (see above: Response is PartialEq only, never Eq). New variants are additive by serde tag, so existing pins are byte-identical and no PROTOCOL_VERSION bump is needed. url stays a String on the wire; the daemon parses and validates it (returning a typed error) rather than the client.
ProxyEntry later gained primary_domain: Option<String> and domains: Vec<String> (FQDNs) so a proxy can carry the extra domains, subdomains and wildcards yerd domain now gives it. Both use #[serde(default, skip_serializing_if = ...)] and are populated only for a customised proxy, so an uncustomised one serialises to the original three-field byte shape and an older client decodes it unchanged - the same additive, no-PROTOCOL_VERSION-bump pattern as web_subpath and supports_overrides. A proxy the router never inserted (one name-shadowed by a site) reports both as empty rather than the shadowing site's domains.
Routing rules are a separate surface from proxy rules
Per-site routing rules add three variants - AddRouteRule { site, prefix, target } and RemoveRouteRule { site, prefix } (both reply with the generic Ok) plus the ListRoutes query, which gets its own Response::Routes { rules: Vec<RouteRuleEntry> }.
RouteRuleEntry { site, prefix, target } is field-identical to ProxyRuleEntry and is deliberately not the same struct: yerd-ipc is a byte-pinned contract, so coupling two features' wire evolution to one type would make either one hard to change. The semantic difference is what the target is - a proxy rule's target is an HTTP upstream URL, a routing rule's target is a path relative to the site's served root (a nested api/index.php, or index.html for an SPA). The daemon validates it as a safe relative path; an absolute path or one containing .. is refused.
All three variants are additive by serde tag, so existing pins are byte-identical and no PROTOCOL_VERSION bump was needed.
Node version management
Alongside InstallNode { version } and SetNodeVersion { version, site }, six additive requests back the GUI's Node page and site Node row (the CLI also uses InstallNodeStreamed for yerd install tool node <selector>, UninstallNode for yerd node uninstall, and ClearNodeVersion for yerd node unset): ListNode, AvailableNode, InstallNodeStreamed { version, update }, UninstallNode { version }, ClearNodeVersion { site }, and NodeSite { site }.
NodeVersions { installed }carries oneNodeRelease { version, lts, codename, default, uninstall_blocked, clears_preferences, update }per installed release, newest first.defaultmarks the release the effective global default resolves to;uninstall_blockedandclears_preferences(a list ofNodePreferenceRef { root, site },siteset when a registered site has that root) are the daemon's uninstall plan, so the GUI never reimplements the rule.update(omitted when none) is the newer patch of that major from the daemon's cached release-index check, set only on the highest installed patch; the cache is refreshed every 12 hours with the PHP update poll, by everyAvailableNode, and by every Node install (from the index the installer already fetched).StatusReport.node_updates(omitted when0) counts those releases for the sidebar badge and the tray.AvailableNode { majors }is a list ofyerd_core::node::MajorLine { major, latest, codename, eol, installed_latest, update_available }, re-exported fromyerd-corelikePhpVersion.eolis absent when the release schedule couldn't be fetched. Majors below 9 and releases without a build for the host are never listed.NodeSite { preference, project_file, effective, source, error, missing }reports a site's saved preference, itsNodeProjectFile { kind, selector }, and the effective version with itsNodeSource. A resolution failure (unknown site, invalid project file, release not installed) is theerrorfield, not aResponse::Error; when the chosen selector (project file, preference, or default) simply isn't installed,missingnames it so the GUI can offer to install it.NodeSourceserialises kebab-case:nvmrc,node-version,site,default, the same stringsyerd which --jsonprints.NodeProjectFile.kindis only evernvmrcornode-version.InstallNodeStreamed'supdateflag (skipped whenfalse) only controls whether the global default moves to the new patch: it moves when the default currently resolves to an older patch of that major. Site preferences are never repointed.UninstallNodeis refused withErrorCode::InvalidPath(the same codeuninstall_phpuses for the default) when other releases remain but the default selector would no longer resolve to any of them - for example an exact default pinned to the release being removed; a partial default such as22that still matches another 22.x is fine. An unknown or malformed version isNotFound.
Fields marked skip_serializing_if are omitted when empty: NodeRelease.codename, .clears_preferences and .update, NodePreferenceRef.site, the MajorLine options (codename, eol, installed_latest), every NodeSite field, InstallNodeStreamed.update (when false), LaravelOptions.node, and StatusReport.node_updates (when 0). Others always serialise: NodeVersions.installed is [] when nothing is installed, and SetNodeVersion.site is null for the global default. No PROTOCOL_VERSION bump.
Response headers mirror routing rules
Per-site response headers follow the same pattern: SetResponseHeader { site, name, value } and RemoveResponseHeader { site, name } (both reply with the generic Ok) plus the ListResponseHeaders query, answered by Response::ResponseHeaders { headers: Vec<ResponseHeaderEntry> } where ResponseHeaderEntry is { site, name, value }. The daemon validates the name and value with yerd_core::ResponseHeader and replies Error for a malformed or reserved header. These are additive too, with no PROTOCOL_VERSION bump.
Outbound proxy settings
GetNetworkSettings and SetNetworkSettings { mode, http_proxy?, https_proxy?, no_proxy? } both reply Response::NetworkSettings { settings: NetworkSettings } (mode, the redacted manual http_proxy / https_proxy, no_proxy, and effective: Option<EffectiveProxy> - the mode, ProxySource, redacted URLs and bypass list actually in use). TestNetwork replies Response::NetworkTest { result: NetworkTestResult } (ok, url, status?, error?, via?, source). In SetNetworkSettings an omitted field keeps the stored value and an empty one clears it; a URL whose password is the redacted *** keeps the stored password only while scheme, user, host and port are unchanged, otherwise the daemon replies ErrorCode::InvalidPath ("re-enter the proxy password"). Every URL on the wire is redacted, and OutboundProxyMode / ProxySource are yerd_core::network enums serialised snake_case. DiagnosisCode gained OutboundProxyUnreachable and OutboundProxyPacUnsupported; reachability and PAC state are a Doctor side channel, not StatusReport fields. All additive, no PROTOCOL_VERSION bump.
Bundled Xdebug: SetXdebug and two PhpVersions fields
SetXdebug is one shared operation behind yerd xdebug on|off, the GUI's Xdebug section and the MCP set_xdebug tool. version (skipped when None, meaning the daemon's default PHP), modes (a list of debug / develop / coverage / profile / trace / gcstats, never off or empty) and start ("always" or "trigger") are all optional, and so is enabled: an omitted or nullenabled keeps the version's current on/off state, which is what the GUI's Apply sends (with only the fields the user edited), while the switch and the CLI send an explicit true/false. MCP's set_xdebug passes enabled through when the agent gives it and omits it otherwise. The reply is the same PhpVersions as ListPhp, which gained two boxed, skip-if-empty fields: xdebug (a version → {enabled, modes, start} map holding only the versions whose settings differ from the default; an absent version is off) and xdebug_versions (installed versions with a bundled Xdebug published for this host). Errors: LegacyRestricted for enabling on a legacy version, XdebugUnavailable when nothing is published for the version/platform or the download fails, AlreadyExists when a hand-registered Xdebug extension is loaded for that version, ExtensionLoadFailed when the load-probe fails, NotFound for a version that isn't installed, and InvalidSetting for a rejected setting such as an empty mode list. The download and load-probe run under a 90-second deadline; on expiry the daemon replies XdebugUnavailable ("timed out …, nothing changed") without saving, publishing or restarting anything. The desktop app's bridge waits up to 120 seconds for the reply and reloads the PHP state after a timeout. A request that changes nothing replies without saving or restarting. AddPhpExtension also refuses an Xdebug .so with AlreadyExists while that version's managed Xdebug is on. All additive, no PROTOCOL_VERSION bump.
ErrorCode
Failures are a Response::Error { code, message } where code is machine-readable and message is for human display:
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ErrorCode {
NotFound, // "not_found"
AlreadyExists, // "already_exists"
InvalidPath, // "invalid_path"
PortInUse, // "port_in_use"
ExtensionLoadFailed, // "extension_load_failed" - a valid path whose .so failed its load-probe
LegacyRestricted, // "legacy_restricted" - a legacy version used somewhere it's disallowed
XdebugUnavailable, // "xdebug_unavailable" - no bundled Xdebug for that version/platform, or its download failed or timed out
InvalidSetting, // "invalid_setting" - a setting value failed validation (e.g. an empty Xdebug mode list)
Internal, // "internal" - catch-all; expand the enum, don't overload this
}LegacyRestricted is returned when a request tries to do something an out-of-support legacy version (7.4 / 8.0 / 8.1) can't: setting it as the global default, or installing it without confirm_legacy: true, or turning on Xdebug for it.
There is deliberately no #[serde(other)] catch-all. An unknown code from a newer daemon fails closed as IpcError::Decode rather than silently downgrading - the same signal as an unknown type tag, and the placeholder for a real version mismatch until a handshake lands.
Status & doctor payloads
status.rs holds the nested payloads carried inside the status/doctor, service/database, and mail responses: StatusReport, PortStatus, CaStatus, SiteCounts, PhpPoolStatus, PoolRunState, ServiceStatus, ServiceRunState, ServiceAvailability, DatabaseSummary, Diagnosis, Severity, DiagnosisCode, FixReport, FixResult, and the mail-capture types MailStatus, MailSummary, MailHeader, and MailDetail. Same contract rules apply. StatusReport also carries an additive services: Vec<ServiceStatus> field alongside the PHP pools, plus an additive mail: Option<MailStatus>.
ServiceStatus gained supports_overrides: bool (last field, #[serde(default, skip_serializing_if = "std::ops::Not::not")]) - whether the engine accepts the free-form configuration overrides that SetServiceOverrides writes. It gates the GUI's Override settings dialog the way supports_databases gates "Create Database", and is true only for the config-backed engines (mysql, mariadb, postgres, redis); Meilisearch and Reverb are argv/env driven, so both override requests are refused for them with ErrorCode::InvalidPath. Skipped on the wire when false and defaulted on decode, so the byte shape is unchanged for the services that don't and an older daemon's status reads as "no overrides" rather than failing - the same additive, no-PROTOCOL_VERSION-bump pattern as web_subpath. DiagnosisCode separately gained ServiceOverrideInvalid ("service_override_invalid"), the Warn yerd doctor raises per bad line of a hand-edited 50-local.<ext> file.
StatusReport is also how the MCP gate is read back: mcp_enabled: bool (additive, #[serde(default)], always emitted) reports whether SetMcpEnabled has been turned on. The daemon runs no MCP server itself - it persists the flag and reports it here, and each yerd mcp session reads it to decide whether to serve tools. See yerd-mcp.
dump.rs holds the dump-telemetry payloads carried inside the Dumps / DumpsStatus responses: DumpCategory (the per-tab category enum), DumpEvent (one buffered event; its payload is an opaque serde_json::Value), DumpCounts (per-category buffered counts), and DumpExtStatus (per-PHP-version extension presence). Same contract rules apply.
Integer-encoded scalars (the load average)
Request derives Eq, but Response does not - the Dumps response carries arbitrary JSON dump payloads (a serde_json::Value, which may hold floats), so an Eq derive is impossible there. That float escape hatch is confined to opaque dump payloads, though: the daemon never interprets them. The daemon's own status scalars are still integer-encoded so they stay exact and comparable. The system load average therefore crosses as integer hundredths - StatusReport::load_avg is Option<[u32; 3]>, each value load × 100 - and the CLI renders it back to x.xx.
Errors
Two layers, by design:
FrameError- pure framing error,Clone + Eq. Variants:TooLarge { size, max }andPayloadOverflowsLengthPrefix { size }.IpcError- top-level, wraps framing and serde errors. Variants:Encode,Decode,Frame(FrameError),UnexpectedEof { bytes }, andIo { kind: std::io::ErrorKind }. It is notClone/Eqbecauseserde_json::Erroris not.
For GUI/Tauri command returns that need Clone + Eq, call IpcError::kind() to get the shadow enum IpcErrorKind, which mirrors every variant (dropping the non-cloneable serde_json::Error detail) and carries std::io::ErrorKind (which is Copy + Eq). A frame_error_to_kind_is_exhaustive test enforces that every FrameError variant has a paired IpcErrorKind, with a FrameOther { description } catch-all guarding against drift.
EOF is split from framing: the pure codec never synthesises EOF. The transport read_frame returns Ok(None) on a clean EOF with an empty buffer, and Err(IpcError::UnexpectedEof { bytes }) on EOF mid-frame. I/O failures map to IpcError::Io { kind }, preserving only the OS error category.
Transport helpers
With --features transport, three async helpers in transport.rs glue the codec to a tokio stream:
pub async fn write_message<W, T>(writer: &mut W, value: &T, max: usize) -> Result<(), IpcError>;
pub async fn read_frame<R>(reader: &mut R, decoder: &mut FrameDecoder)
-> Result<Option<Vec<u8>>, IpcError>;
pub async fn read_message<R, T>(reader: &mut R, decoder: &mut FrameDecoder)
-> Result<Option<T>, IpcError>;read_frame loops: try decoder.next_frame(), and on None read another chunk (a 4 KiB scratch buffer) into the decoder. It returns the raw payload so a caller can inspect the type tag before fully decoding. read_message is read_frame then decode_message. The daemon's per-client loop drives exactly these (bin/yerdd/src/ipc_server.rs):
let mut decoder = FrameDecoder::new();
loop {
let req = match read_message::<_, Request>(&mut reader, &mut decoder).await {
Ok(Some(r)) => r,
Ok(None) => return, // clean EOF - client hung up
Err(_) => return, // decode/EOF error - close quietly
};
let resp = dispatch(req, &state).await;
write_message(&mut writer, &resp, DEFAULT_MAX_FRAME).await?;
}A decode error (unknown type, unknown ErrorCode, malformed JSON) closes the connection quietly at debug level - that is the common signature of a mismatched-version client.
Wire-stability tests
The JSON shapes are the published contract, pinned three ways so a rename or reshape cannot land silently:
tests/wire_stability.rsasserts byte-exact JSON for everyRequest,Response,ErrorCode, and status sub-type, e.g.rustassert_eq!(serde_json::to_string(&Request::SetPhp { name: "foo".into(), version: PhpVersion::new(8, 3), }).unwrap(), r#"{"type":"set_php","name":"foo","version":"8.3"}"#);It also pins additive back-compat:
Response::Infodecodes legacy daemons that omithttp_port/https_port(they default to 0), andResponse::PhpVersionsskips an emptyupdates/settings/version_settings/directives/pool/ffi_versions/xdebug/xdebug_versionsand an absentlibvips_foundon the wire so the bytes match the pre-field shape.Inline
variant_name_pinningmodules inrequest.rsandresponse.rscontain exhaustivematcharms over the (in-crate, so matchable despite#[non_exhaustive]) enums. A renamed Rust variant fails to compile there - integration tests can't catch this across the crate boundary.A CI grep gate forbids per-field
#[serde(rename = "...")]incrates/yerd-ipc/src/. Casing is owned entirely byrename_all = "snake_case". Pairing the no-rename rule with the byte pins means a Rust rename trips both the wire pin (changed JSON) and the compile-time match - you cannot mask a rename with aserdeattribute.
tests/roundtrip.rs additionally pins an encode_message ∘ decode_message identity plus the deliberate envelope/inner asymmetry: the outer Request/Response envelope accepts unknown JSON fields (so additive changes stay compatible), while an inner Site is strict (deny_unknown_fields). So {"type":"ping","__extra":42} decodes as Request::Ping, but an unknown field on a Site inside Response::Sites is rejected.
Contract rules
The invariants that keep the protocol forward-compatible:
Additive only. Add variants and fields; never rename or remove a variant, field, or
ErrorCode.#[non_exhaustive]keeps additions out of the breaking-change category.No per-field serde renames. Let
rename_allhandle casing; the grep gate enforces it.Expand
ErrorCode, don't overloadInternal. New typed failure categories get their own variant rather than collapsing into the catch-all.Fail closed. Unknown
typetags and unknownErrorCodes surface asIpcError::Decode, not a silentUnknowndowngrade.Versioning.
PROTOCOL_VERSION(currently1) is exposed but is effectively dead until aHello/Welcomehandshake lands; bump it only alongside that handshake.rust/// The current IPC protocol version. Bump on any breaking change; /// add a handshake before doing so. pub const PROTOCOL_VERSION: u32 = 1;Until then, a newer client talking to an older daemon is detected only when an unknown tag arrives mid-conversation - adding the handshake is the roadmap for proper version negotiation.