Module Client 

Vine client - thread-safe gRPC client for a Cocoon sidecar process. Pool of CocoonClient connections keyed by identifier, automatic reconnect with exponential back-off, per-connection health metadata, per-call timeouts, message-size validation, and a broadcast fan-out of every observed notification.

Atomized layout (one entry-point per file):

• MarkShutdown::Fn / IsShuttingDown::Fn - process-wide flag.
• NotificationFrame::Struct - broadcast payload.
• SubscribeNotifications::Fn / SubscriberCount::Fn - fan-out access.
• ConnectToSideCar::Fn / DisconnectFromSideCar::Fn - pool lifecycle. Driven by TryConnectSingle::Fn (single attempt).
• IsClientConnected::Fn / WaitForClientConnection::Fn - boot-race-friendly readiness checks.
• CheckSideCarHealth::Fn - pool + metadata health summary.
• SendRequest::Fn / SendNotification::Fn - wire dispatch with optional streaming-multiplexer fast path under LAND_VINE_STREAMING=1.
• PublishNotification::Fn (private) and PublishNotificationFromMux::Fn (pub(crate)) - broadcast publishers.
• Shared - module-private state (statics, helpers, constants).

Modules

CheckSideCarHealth

Health check: connection exists in the pool, last activity within HEALTH_CHECK_INTERVAL_MS, and failure count below the retry threshold.

ConnectToSideCar

Establish a gRPC connection to a Cocoon sidecar with exponential back-off retry. On success initialises the per-connection metadata tracked by Shared::CONNECTION_METADATA.

DisconnectFromSideCar

Disconnect from a sidecar process. Removes the entry from both the connection pool and the metadata tracker.

IsClientConnected

Whether the named sidecar currently has a live entry in the connection pool. Cheap read of the shared map; no RPC issued. Useful for boot-race callers that need to know whether SendRequest would short-circuit before paying the serialization + lock-acquire cost.

IsShuttingDown

Whether the Vine client has been marked shutting down.

MarkShutdown

Flip the global Vine-client shutdown flag. Called from RunTime::Shutdown::ShutdownCocoonWithRetry immediately before HardKillCocoon so any inflight notification attempted after the SIGKILL window returns silently with Ok(()) instead of logging a Connection refused error.

NotificationFrame

One observed notification frame fanned out from SendNotification (or, once the streaming-channel multiplexer is live, from Multiplexer). Subscribers consume frames from the broadcast channel managed by Shared::NOTIFICATION_BROADCAST.

PublishNotification 🔒

Internal: publish a notification to the broadcast. Called from SendNotification::Fn after the wire send succeeds, and from the streaming multiplexer once it lands. try_send semantics - no awaiting, no failure surfaced (a slow subscriber must not stall the producer).

PublishNotificationFromMux

Public-crate alias for PublishNotification::Fn so Vine::Multiplexer can fan out notifications received over the streaming channel through the same broadcast subscribers consume from.

SendNotification

Fire-and-forget notification to a sidecar. No response, no per-call timeout. Prefers the streaming multiplexer under LAND_VINE_STREAMING=1; falls through to unary on any failure. After a successful wire send, fans out via PublishNotification::Fn so broadcast subscribers (Effect-TS fibers, OTel emitters, future Mist-WS bridge, dev log) can observe the same flow concurrently.

SendRequest

Send a request and await a response. Validates method-name length and message size, prefers the streaming multiplexer when LAND_VINE_STREAMING=1 is on (falls through to unary on any failure except the authoritative streaming-path timeout), enforces a per-call timeout via tokio::time::timeout, and updates per-connection activity / failure metadata on completion.

Shared 🔒

Module-private state for the Vine client: connection pool, per- connection metadata, the broadcast fan-out, the shutdown flag, plus the constants and message-size validator that every entry-point shares.

SubscribeNotifications

Subscribe to the global notification fan-out. Each call returns a fresh receiver that observes every notification fanned out AFTER subscribe time (broadcast semantics; no historical replay). Drop the receiver to unsubscribe.

SubscriberCount

Number of currently-active broadcast subscribers. Diagnostic; useful for validating that subscribers haven’t leaked.

TryConnectSingle 🔒

Single connection attempt without retry logic. Tunes h2 transport windows for loopback-to-Cocoon traffic (4 MB stream / 16 MB connection) so a single rust-analyzer diagnostic emit (200-500 KB) doesn’t cause WINDOW_UPDATE ping-pong.

WaitForClientConnection

Poll IsClientConnected every 50 ms until the sidecar appears in the pool or the budget runs out. BudgetMilliseconds is a soft upper bound; user-facing call paths should keep it under ~1500 ms.