Module Client 

Vine::Client

Client-side gRPC wrappers for embedders that need to call Vine services (Air talking to Mountain, Cocoon-Rust talking to Mountain, …). 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 when the multiplexer cargo feature is enabled.
• PublishNotification::Fn (private) and [PublishNotificationFromMux::Fn] (pub(crate)) - broadcast publishers.
• Shared - module-private state (statics, helpers, constants).

Behaviours

• 3-attempt exponential backoff (50 ms / 100 ms / 200 ms base schedule) in ConnectToSideCar::Fn.
• Arc<Notify> connection-ready wake-up (no polling) in WaitForClientConnection::Fn.
• 5 000 ms unary default timeout, bounded by crate::DefaultRequestTimeoutMs at 15 000 ms; per-call override on SendRequest::Fn.
• Atomic-counter request IDs (AtomicU64, no SystemTime syscall) in SendRequest::Fn.
• h2 transport tuning (4 MB stream / 16 MB connection windows; LAND_TONIC_TUNED=0 to disable) in TryConnectSingle::Fn.

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. Embedders call this immediately before SIGKILL’ing the sidecar so any inflight notification attempted after the kill 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).

SendNotification

Fire-and-forget notification to a sidecar. No response, no per-call timeout. Prefers the streaming multiplexer under LAND_VINE_STREAMING=1 when the multiplexer cargo feature is enabled; 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 and the multiplexer cargo feature is enabled (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 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

Await Cocoon’s gRPC connection without polling. GetConnectionNotify returns a shared tokio::sync::Notify that ConnectToSideCar fires once the handshake succeeds; WaitForClientConnection simply awaits it under tokio::time::timeout. If the sidecar is already connected when we enter (typical for the second-and-later callers) notified() returns immediately because notify_waiters has already fired.