Crate ryu_mesh 

Mesh status + Funnel helpers (P5 of the unified-tool-gateway epic, #478).

Extracted from apps/core/src/mesh into its own primitive crate (in-process default preserved — every entry point is a plain function call, never IPC).

Core owns what runs — the optional Tailscale/Headscale daemon (a Sidecar managed by the SidecarManager, apps/core/src/sidecar/tailscale.rs). This crate is the read/shape side: it shapes tailscale status --json into the canonical GET /api/mesh/status contract (Appendix A Contract 6 of docs/unified-tool-gateway-spec.md), resolves the fail-closed shared-mesh-token bearer for GET /api/mesh/peers, and exposes the ensure_funnel/funnel_url primitives P6 consumes for public webhook ingress.

The one kernel coupling — the tailscale/tailscaled process shell-outs — inverts through the narrow MeshHost trait (host shim implemented Core-side in apps/core/src/mesh_host.rs, installed once at boot via set_global_host, mirroring the CryptoHost/RecipesHost precedent). So this crate has ZERO dependency on apps/core.

The mesh is opt-in. The enabled signal is RYU_MESH_ENABLED (env) OR the mesh-enabled pref (seeded by Core at boot into set_pref_enabled — the desktop’s Gateway → Integrations toggle writes the pref through POST /api/mesh/config). The env wins when set (operator override → pref, matching the mesh-login-server/ingress-URL precedence). When off, query_status returns the all-default object (HTTP 200, never 500) WITHOUT touching the host, so a build with no host installed still behaves correctly for the default (mesh-disabled) install.

Structs

MeshHandle

Handle held by Core’s ServerState for the mesh plane. Cheap to clone. Today it is a stateless façade over the env-driven query_status/is_enabled free functions (the daemon itself is a Sidecar managed by the SidecarManager), but giving the server a typed handle keeps the call site stable for when P6 wires Funnel-backed ingress through here.

MeshPeer

A peer node on the tailnet, as surfaced in Contract 6. Carries both the P7 fields (name, host_or_dns) and the P5 fields (magic_dns_name, tailscale_ips, os).

MeshPeerEntry

One peer entry in the GET /api/mesh/peers response.

MeshPeersResponse

The GET /api/mesh/peers response (Contract 6 companion, P7). enabled:false ⇒ empty peers, bearer_source:"none".

MeshStatus

The canonical GET /api/mesh/status superset (Contract 6). snake_case keys; reachable and up are both present and equal. enabled:false ⇒ all-default.

Constants

BEARER_NONE_NOTE

Provisioning guidance returned when no usable bearer exists on this node. Names the EXACT secret a peer must share for the fail-closed check to pass.

BEARER_SOURCE_NONE

BEARER_SOURCE_SHARED

How the offered bearer was derived, surfaced so the desktop (and a human) know whether the token is a real candidate or absent.

Traits

MeshHost

The kernel-side couplings this crate needs but cannot own: the three tailscale/tailscaled process shell-outs (the “what runs” half of the mesh, a Sidecar in Core). Core implements this in apps/core/src/mesh_host.rs and installs it once at boot via set_global_host.

Functions

build_peers_response

Build the peers response from a live MeshStatus and this node’s token.

ensure_funnel

Ensure a Tailscale Funnel is serving port to the public internet, returning the public HTTPS URL. Consumed by P6’s TailscaleFunnelSource.

funnel_url

The public Funnel URL for port if one is active, else None. Cheap read (no mutation) used by P6’s status surface.

is_enabled

Whether the mesh is enabled for this node. Opt-in via RYU_MESH_ENABLED (truthy = anything but empty/0/false/no) OR the mesh-enabled pref (seeded into [MESH_PREF_ENABLED]). The env wins when SET — including an explicit RYU_MESH_ENABLED=0, which overrides the pref — so an operator can always force the mesh off; only when the env is unset does the pref decide. Kept in lockstep with the gateway’s tools::mesh_enabled() so the loopback-trust neutralization (B-9) and Core fail-closed gate agree on the same signal.

is_insecure_auth_token_placeholder

Whether an auth token is a well-known insecure placeholder. This is the canonical home for the node-admittance placeholder check: resolve_mesh_bearer refuses to hand out such a token as a peer bearer (a peer provisioned with a placeholder refuses to start under mesh, so offering it would be a lie), and Core’s enforce_remote_auth startup gate consults the same predicate so both agree on the same signal. Pure + const — no dependency on apps/core.

parse_enabled

Whether a string parses as a truthy mesh-enabled value — the SAME truthiness is_enabled applies to RYU_MESH_ENABLED, exposed so Core can parse its mesh-enabled pref with the identical semantics instead of a second copy.

parse_status_json

Parse the JSON emitted by tailscale status --json into a MeshStatus.

query_status

Query the live mesh status. When the mesh is disabled this returns the all-default object without shelling out (HTTP 200, never 500) and WITHOUT consulting the host. When enabled but the daemon is absent/erroring (or no host is installed), it returns an enabled-but-unreachable object so the desktop can render an amber “configured but down” state.

resolve_mesh_bearer

Resolve the candidate bearer to hand the desktop from this node’s node token (RYU_TOKEN, passed in). Returns None — meaning “no usable bearer” — when the token is absent, empty/whitespace, or a known insecure placeholder (a peer with a placeholder token refuses to start under mesh, so offering it would be a lie).

set_global_host

Install the process-global MeshHost. Idempotent (a second call is a no-op). Called once from Core’s main at boot.

set_pref_enabled

Seed the pref half of the mesh-enabled signal (env wins when set). Mirrors the entitlement / claude-config / untrusted pref seeders in Core’s main. Also called by the runtime POST /api/mesh/config handler so an enable/disable takes effect without a restart.