zoryn network¶
Read live build status across local and remote builders.
Experimental
Mesh networking is disabled by default. To enable it, add this top-level setting to ~/.zoryn, before any [section]:
The default is zoryn_network = "off". When off, zoryn skips mesh publication, discovery, permission repairs and mesh SSH connections. network status reports the disabled setting and exits successfully without looking up a builder.
zoryn network status¶
Without BUILDER, the command reads catalogs from local endpoints, including relayed remote records and fallback cached builder views. It does not start SSH or query every configured builder. A child worker serves each endpoint, receives state updates over IPC and refreshes remote status about every five seconds. Blocked build commands and slow remote queries do not stop endpoint service. The published PID identifies the build process, not the worker. Remote builders still receive the endpoint through SSH forwarding. Builds start only after the endpoint and required forwarding are ready. Remote records are visible only if a local endpoint has learned them or retained a fallback view. Duplicate endpoints appear once. Refresh failures and cached views older than fifteen seconds produce warnings. With BUILDER, the command queries that exact builder directly.
Each reachable endpoint reports its builder, originating user, UID, PID, state, current package, phase and pending queue. The queue includes the current package. It belongs to one build process, not the whole builder. While waiting for a busy builder, the process publishes state=starting, phase=waiting-builder and its own PID, current package and planned queue (current package first). When polling alternatives, the wait endpoint uses the first candidate not reported unavailable, in list order (including its SSH destination), not every candidate. The endpoint keeps its ID when the selected build starts. One build-owning process keeps one worker and ID throughout its sequential build cycle, including waits and changes of builder or host. Previously used publications remain available until the cycle ends. Parallel build children have separate IDs; an idle dispatcher creates no endpoint. Batch and task rebuild loops include their remaining planned packages in execution order, excluding explicit skips. Sequential test-rebuild runs include pending packages for the current architecture, with ready retries before new packages. Parallel test-rebuild workers publish only their assigned package; the dispatcher's unassigned work is not a process-local queue. Plans can change after later checks. Other members of hashman can read these values.
The command reports unavailable, unsafe or malformed endpoints as warnings without discarding healthy responses. Socket warnings include HOST:/path/to/socket: the local hostname or the configured SSH destination for a remote query. Newly collected remote caches retain this host; older caches may still omit it. With BUILDER, a builder discovery failure exits with code 1. Local discovery and per-endpoint warnings do not change the exit code. The command does not remove stale sockets or change queues. During discovery, it repairs its own UID directory to group hashman and mode 2750, when permitted. It repairs its own sockets to mode 0770 only if their group is already hashman. It rejects symlinks, checks device and inode after repairs, and never modifies another UID's objects or /var/tmp. Failed repairs remain warnings; --debug reports successful repairs.
Catalog protocol¶
Endpoints also accept get_catalog (catalog version 1), with pages up to 1 MiB. If the cached extension would exceed the 1 MiB get_status limit, the response keeps the endpoint's own status and replaces the cache with an omission warning. If even that warning cannot fit, it returns only the own status. Catalog pages remain available. The worker exchanges catalogs with verified local sockets and the remote builders used by the session. network status reads and merges paged catalogs from the discovered endpoints. It shows endpoint and age, reports equal-version conflicts instead of choosing a status, and hides known expired or LEAVE records. A failed page keeps validated results and produces an incomplete-catalog warning. This is a reachable view, not proof of a complete network census. Direct statuses and cached views remain a fallback where no catalog version is known, with age=unknown (status-only); they have no catalog TTL guarantee. Known catalog versions, including removals, take precedence. Old endpoints rejecting get_catalog remain supported. Exchange runs independently of builds, with up to eight concurrent catalog requests, a ten-second request timeout and a 25-second deadline per neighbor starting at its first request, not at discovery. Idle rounds start every four to six seconds. Addresses inside records are never connection targets. Validated pages are merged as they arrive. A later page failure retains learned records and is reported in the build's debug log; it is not treated as a completed traversal. Older endpoints remain visible through status polling without synthesized catalog versions. Multi-page snapshots keep their membership and versions across state updates. Up to four snapshots share an 8 MiB encoded-record budget and expire after 30 seconds. Unknown or expired cursors and exhausted budgets return an error, not a partial success. Workers renew their own catalog record every five seconds, even without IPC updates. Relaying a record never renews its age. Active records expire after 60 seconds without a new owner version; replay guards last 300 seconds. After guard expiry or restart, replay protection is best-effort. On normal shutdown, the worker sends a newer LEAVE record to discovered neighbors with a shared one-second delivery budget. Recipients relay the tombstone through catalog pages for up to 300 seconds. Lost LEAVE messages and crashes fall back to TTL; delivery is not guaranteed. get_status is unchanged. Catalog exchange trusts participants: records and LEAVE messages are not signed. Participants can forge them, and relaying can expose status beyond the original socket ACL.
Options¶
| Option | Description |
|---|---|
-d, --debug | Trace discovery, cache sources, socket metadata and executed commands |
-C DIR | Change directory before the query |
--help | Show help |
Debug output goes to stderr. Without BUILDER, it traces local discovery and cached views without SSH. Specify a builder to inspect current remote socket metadata and executed SSH commands.
Examples¶
Builds automatically create /var/tmp/zoryn-mesh-<uid> and set group hashman and mode 2750 on their own directory. Build users must belong to hashman. No administrator-created mesh directory is needed. See builder configuration.