Inter-Component Protocol

This document specifies the communication protocols used between Land components. It covers the gRPC service definitions (Vine protocol), the Tauri IPC mechanism, the Spine extension coordination protocol, and the connection lifecycle management.

Table of Contents

1. Protocol Overview
2. Tauri IPC
3. Vine gRPC Protocol
4. Spine Extension Protocol
5. Connection Lifecycle
6. Health Monitoring
7. Protocol Buffer Definitions
8. Security
9. Related Documentation

Protocol Overview 🔌

Land uses three communication protocols operating at different abstraction levels:

Protocol Stack

graph BT
    subgraph Transport[Transport Layer]
        TCP[TCP localhost]
        IPC[IPC pipes]
    end

    subgraph TauriIPC[Tauri IPC]
        Commands[In-process command/event transport]
    end

    subgraph VinegRPC[Vine gRPC Protocol]
        Proto[Service contracts defined in .proto files]
    end

    subgraph SpineProto[Spine Protocol]
        ActionResp[Extension action/response pattern]
    end

    TCP --> Commands
    IPC --> Commands
    TCP --> Proto
    IPC --> Proto
    Commands --> ActionResp
    Proto --> ActionResp

    style Transport fill:#f0f0f0,stroke:#333
    style SpineProto fill:#e8f8e8,stroke:#363

Tauri IPC 🎮

TierIPC Runtime Routing

The TierIPC environment variable controls how Wind and Output route Tauri IPC calls at runtime. No rebuild is required to switch tiers.

Individual subsystems have their own tier constants (e.g. TierTerminal, TierStorage, TierSearch) baked at compile time from .env.Land. A runtime shell export (e.g. export TierStorage=Node) overrides the baked value without a rebuild. The active tier for each subsystem is logged at boot by Mountain/Source/LandFixTier.rs.

Commands (Request-Response)

Wind invokes Mountain handlers through @tauri-apps/api invoke(). Each command maps to a registered Rust handler in Mountain.

Wind-side invocation:

import { invoke } from "@tauri-apps/api/core";

const content: Uint8Array = await invoke("read_file", {
	path: "/Users/user/Documents/example.ts",
});

Mountain-side handler:

use tauri;

#[tauri::command]
async fn read_file(
    path: String,
    state: State<'_, AppState>
) -> Result<Vec<u8>, String> {
    let fs = state.file_system();
    fs.read_file(std::path::Path::new(&path))
        .await
        .map_err(|e| e.to_string())
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![read_file])
        .run(tauri::generate_context!());
}

Command Catalog

All commands are dispatched through the single Tauri command MountainIPCInvoke with { method: string, params: any[] }. The method string corresponds to the channel wire name defined in Common/Source/IPC/Channel.rs.

Encryption

The encryption key is derived once per process in Encryption/Key.rs using SHA-256("Land-Encryption-v1" + machine_id). Returns an empty string on failure rather than throwing, so callers treat a corrupt blob as “no stored secret”.

File System

file:open / file:close are classified as high-frequency and short-circuit the Echo scheduler.

Terminal

NativeHost

Language

Other Core Commands

The full channel enum is defined in Common/Source/IPC/Channel.rs (Rust) and mirrored in Wind/Source/IPC/Channel.ts (TypeScript). Both must be kept in lockstep — adding a channel to one requires adding it to the other.

Events (Push from Mountain)

Mountain emits events that Wind/Sky listen to via @tauri-apps/api/event:

import { listen } from "@tauri-apps/api/event";

const unlisten = await listen("configuration-changed", (event) => {
	// event.payload contains the changed configuration keys
	updateLocalConfiguration(event.payload);
});

Event Catalog

Serialization

Tauri IPC uses JSON serialization with the following conventions:

• Strings are UTF-8 encoded
• Numbers are JSON numbers (f64), deserialized to appropriate Rust types
• Binary data is Vec<u8> / Uint8Array, serialized as JSON number arrays for small payloads, or via custom serializer for large files
• Complex types are serialized through serde Serialize/Deserialize traits

Vine gRPC Protocol 🏔️

Vine defines the gRPC service contracts for Mountain-Cocoon and Mountain-Air communication. The canonical definition lives at Element/Vine/Proto/Vine.proto. Mountain keeps a local sync’d copy at Element/Mountain/Proto/Vine.proto which its build.rs compiles directly.

Service Definitions

syntax = "proto3";

package Vine;

// Service running on the Mountain host, listening for requests from Cocoon.
service MountainService {
  // Generic request-response: Cocoon -> Mountain.
  rpc ProcessCocoonRequest(GenericRequest) returns (GenericResponse);
  // Fire-and-forget notification: Cocoon -> Mountain.
  rpc SendCocoonNotification(GenericNotification) returns (Empty);
  // Cancel a long-running operation.
  rpc CancelOperation(CancelOperationRequest) returns (Empty);
  // LAND-PATCH B7-S6 P2: bidirectional streaming channel.
  rpc OpenChannelFromCocoon(stream Envelope) returns (stream Envelope);
}

// Service running on the Cocoon sidecar, listening for requests from Mountain.
service CocoonService {
  // A generic request-response method for Mountain to call a function on Cocoon.
  rpc ProcessMountainRequest(GenericRequest) returns (GenericResponse);

  // A generic fire-and-forget method for Mountain to send a notification to Cocoon.
  rpc SendMountainNotification(GenericNotification) returns (Empty);

  // A method for Mountain to request that Cocoon cancel a long-running operation.
  rpc CancelOperation(CancelOperationRequest) returns (Empty);

  // LAND-PATCH B7-S6 P2: bidirectional streaming channel (mirror of
  // MountainService::OpenChannelFromCocoon). Mountain opens this
  // stream once per Cocoon connection; all subsequent traffic
  // multiplexes over it.
  rpc OpenChannelFromMountain(stream Envelope) returns (stream Envelope);

  // ==================== Initialization ====================

  // Handshake - Called by Cocoon to signal readiness
  rpc InitialHandshake(Empty) returns (Empty);

  // Initialize Extension Host - Mountain sends initialization data to Cocoon
  rpc InitExtensionHost(InitExtensionHostRequest) returns (Empty);

  // ==================== Commands ====================

  // Register Command - Cocoon registers an extension command
  rpc RegisterCommand(RegisterCommandRequest) returns (Empty);

  // Execute Contributed Command - Mountain executes an extension command
  rpc ExecuteContributedCommand(ExecuteCommandRequest) returns (ExecuteCommandResponse);

  // Unregister Command - Unregister a previously registered command
  rpc UnregisterCommand(UnregisterCommandRequest) returns (Empty);

  // ==================== Language Features ====================

  // Register Hover Provider - Register a hover provider
  rpc RegisterHoverProvider(RegisterProviderRequest) returns (Empty);

  // Provide Hover - Request hover information
  rpc ProvideHover(ProvideHoverRequest) returns (ProvideHoverResponse);

  // Register Completion Item Provider - Register a completion provider
  rpc RegisterCompletionItemProvider(RegisterProviderRequest) returns (Empty);

  // Provide Completion Items - Request completion items
  rpc ProvideCompletionItems(ProvideCompletionItemsRequest) returns (ProvideCompletionItemsResponse);

  // Register Definition Provider - Register a definition provider
  rpc RegisterDefinitionProvider(RegisterProviderRequest) returns (Empty);

  // Provide Definition - Request definition location
  rpc ProvideDefinition(ProvideDefinitionRequest) returns (ProvideDefinitionResponse);

  // Register Reference Provider - Register a reference provider
  rpc RegisterReferenceProvider(RegisterProviderRequest) returns (Empty);

  // Provide References - Request references
  rpc ProvideReferences(ProvideReferencesRequest) returns (ProvideReferencesResponse);

  // Register Code Actions Provider - Register code actions provider
  rpc RegisterCodeActionsProvider(RegisterProviderRequest) returns (Empty);

  // Provide Code Actions - Request code actions
  rpc ProvideCodeActions(ProvideCodeActionsRequest) returns (ProvideCodeActionsResponse);

  // ==================== Language Features (Extended) ====================

  // Register Document Highlight Provider
  rpc RegisterDocumentHighlightProvider(RegisterProviderRequest) returns (Empty);

  // Provide Document Highlights
  rpc ProvideDocumentHighlights(ProvideDocumentHighlightsRequest) returns (ProvideDocumentHighlightsResponse);

  // Register Document Symbol Provider
  rpc RegisterDocumentSymbolProvider(RegisterProviderRequest) returns (Empty);

  // Provide Document Symbols
  rpc ProvideDocumentSymbols(ProvideDocumentSymbolsRequest) returns (ProvideDocumentSymbolsResponse);

  // Register Workspace Symbol Provider
  rpc RegisterWorkspaceSymbolProvider(RegisterProviderRequest) returns (Empty);

  // Provide Workspace Symbols
  rpc ProvideWorkspaceSymbols(ProvideWorkspaceSymbolsRequest) returns (ProvideWorkspaceSymbolsResponse);

  // Register Rename Provider
  rpc RegisterRenameProvider(RegisterProviderRequest) returns (Empty);

  // Provide Rename Edits
  rpc ProvideRenameEdits(ProvideRenameEditsRequest) returns (ProvideRenameEditsResponse);

  // Register Document Formatting Provider
  rpc RegisterDocumentFormattingProvider(RegisterProviderRequest) returns (Empty);

  // Provide Document Formatting
  rpc ProvideDocumentFormatting(ProvideDocumentFormattingRequest) returns (ProvideDocumentFormattingResponse);

  // Register Document Range Formatting Provider
  rpc RegisterDocumentRangeFormattingProvider(RegisterProviderRequest) returns (Empty);

  // Provide Document Range Formatting
  rpc ProvideDocumentRangeFormatting(ProvideDocumentRangeFormattingRequest) returns (ProvideDocumentRangeFormattingResponse);

  // Register On Type Formatting Provider
  rpc RegisterOnTypeFormattingProvider(RegisterOnTypeFormattingProviderRequest) returns (Empty);

  // Provide On Type Formatting
  rpc ProvideOnTypeFormatting(ProvideOnTypeFormattingRequest) returns (ProvideOnTypeFormattingResponse);

  // Register Signature Help Provider
  rpc RegisterSignatureHelpProvider(RegisterSignatureHelpProviderRequest) returns (Empty);

  // Provide Signature Help
  rpc ProvideSignatureHelp(ProvideSignatureHelpRequest) returns (ProvideSignatureHelpResponse);

  // Register Code Lens Provider
  rpc RegisterCodeLensProvider(RegisterProviderRequest) returns (Empty);

  // Provide Code Lenses
  rpc ProvideCodeLenses(ProvideCodeLensesRequest) returns (ProvideCodeLensesResponse);

  // Register Folding Range Provider
  rpc RegisterFoldingRangeProvider(RegisterProviderRequest) returns (Empty);

  // Provide Folding Ranges
  rpc ProvideFoldingRanges(ProvideFoldingRangesRequest) returns (ProvideFoldingRangesResponse);

  // Register Selection Range Provider
  rpc RegisterSelectionRangeProvider(RegisterProviderRequest) returns (Empty);

  // Provide Selection Ranges
  rpc ProvideSelectionRanges(ProvideSelectionRangesRequest) returns (ProvideSelectionRangesResponse);

  // Register Semantic Tokens Provider
  rpc RegisterSemanticTokensProvider(RegisterSemanticTokensProviderRequest) returns (Empty);

  // Provide Semantic Tokens Full
  rpc ProvideSemanticTokensFull(ProvideSemanticTokensRequest) returns (ProvideSemanticTokensResponse);

  // Register Inlay Hints Provider
  rpc RegisterInlayHintsProvider(RegisterProviderRequest) returns (Empty);

  // Provide Inlay Hints
  rpc ProvideInlayHints(ProvideInlayHintsRequest) returns (ProvideInlayHintsResponse);

  // Register Type Hierarchy Provider
  rpc RegisterTypeHierarchyProvider(RegisterProviderRequest) returns (Empty);

  // Provide Type Hierarchy Supertypes
  rpc ProvideTypeHierarchySupertypes(ProvideTypeHierarchyRequest) returns (ProvideTypeHierarchyResponse);

  // Provide Type Hierarchy Subtypes
  rpc ProvideTypeHierarchySubtypes(ProvideTypeHierarchyRequest) returns (ProvideTypeHierarchyResponse);

  // Register Call Hierarchy Provider
  rpc RegisterCallHierarchyProvider(RegisterProviderRequest) returns (Empty);

  // Provide Call Hierarchy Incoming Calls
  rpc ProvideCallHierarchyIncomingCalls(ProvideCallHierarchyRequest) returns (ProvideCallHierarchyResponse);

  // Provide Call Hierarchy Outgoing Calls
  rpc ProvideCallHierarchyOutgoingCalls(ProvideCallHierarchyRequest) returns (ProvideCallHierarchyResponse);

  // Register Linked Editing Range Provider
  rpc RegisterLinkedEditingRangeProvider(RegisterProviderRequest) returns (Empty);

  // Provide Linked Editing Ranges
  rpc ProvideLinkedEditingRanges(ProvideLinkedEditingRangesRequest) returns (ProvideLinkedEditingRangesResponse);
}

Service: MountainService

Used for Cocoon -> Mountain communication:

Service: CocoonService

Used for Mountain -> Cocoon communication:

Message Formats

// A generic request / response envelope shared across all RPCs.
message GenericRequest {
  uint64 RequestIdentifier = 1;
  string Method = 2;              // JSON-serialized parameters
  bytes Parameter = 3;
}

message GenericResponse {
  uint64 RequestIdentifier = 1;
  bytes Result = 2;               // JSON-serialized success payload
  optional RPCError error = 3;   // JSON-RPC-style error object
}

message GenericNotification {
  string Method = 1;
  bytes Parameter = 2;           // JSON-serialized
}

message RPCError {
  int32 Code = 1;
  string Message = 2;
  bytes Data = 3;
}

message CancelOperationRequest {
  uint64 RequestIdentifierToCancel = 1;
}

message Empty {}

Common types used across messages:

message Position {
  uint32 Line = 1;
  uint32 Character = 2;
}

message Range {
  Position Start = 1;
  Position End = 2;
}

message Uri {
  string Value = 1;
}

message WorkspaceFolder {
  Uri Uri = 1;
  string Name = 2;
}

message CompletionItem { /* ... */ }
message Location { /* ... */ }

Port Allocation

All listeners bind to [::1] (not 0.0.0.0). Environment overrides are described in Vine/Source/Library.rs.

Spine Extension Protocol 🔄

The Spine protocol is the extension host coordination layer built on top of Vine gRPC. It implements an action/response pattern for extension-to-backend communication.

Action/Response Pattern

sequenceDiagram
    participant Extension as Extension code in Cocoon
    participant Shim as Cocoon vscode shim
    participant Spine as Spine protocol
    participant Mountain as Mountain ActionHandler
    participant Trait as Common trait impl

    Extension->>Shim: Call vscode API (e.g., openTextDocument)
    Shim->>Shim: Create ActionEffect
    Shim->>Spine: gRPC PerformAction(ActionRequest)
    Spine->>Mountain: Route to ActionHandler
    Mountain->>Trait: Execute action via Common trait implementation
    Trait-->>Mountain: Action result
    Mountain-->>Spine: ActionResponse { result, error }
    Spine-->>Shim: gRPC response
    Shim-->>Extension: Return result to extension

ActionEffect Types

The Spine protocol encodes all possible extension actions as a discriminated union:

ActionEffect
    +-- ReadFile { path }
    +-- WriteFile { path, content }
    +-- DeleteFile { path }
    +-- ReadDirectory { path }
    +-- CreateDirectory { path }
    +-- Stat { path }
    +-- Rename { from, to }
    +-- Copy { from, to }
    +-- WatchFile { path }
    +-- OpenDialog { options }
    +-- SaveDialog { options }
    +-- ShowMessage { message, options }
    +-- ShowInputBox { options }
    +-- OpenExternal { url }
    +-- ExecuteProcess { command, args }
    +-- ExecuteCommand { command_id, args }
    +-- RegisterCommand { command_id, handler }
    +-- CreateTerminal { options }
    +-- WriteTerminal { id, data }
    +-- ReadClipboard { format }
    +-- WriteClipboard { text }
    +-- GetConfiguration { key }
    +-- SetConfiguration { key, value, target }
    +-- GetSecret { key }
    +-- SetSecret { key, value }
    +-- DeleteSecret { key }
    +-- CreateWebviewPanel { options }
    +-- SendWebviewMessage { id, message }
    // ... 80+ effect variants

Routing

The Cocoon tier router (Cocoon/Source/Services/Handler/VscodeAPI/ROUTING.md) decides per-call whether to:

1. Track A (Stock Node): Handle entirely in-process via unmodified extHost*.ts code
2. Track B (Rust Native): Package as ActionEffect, send via Spine gRPC to Mountain, await native execution
3. Track C (Cocoon Bespoke): Hand-rolled TypeScript implementation in Cocoon (last resort)

Connection Lifecycle 🔄

Mountain-Cocoon Connection

Bootstrap order (critical): Cocoon’s gRPC server (port 50052) must bind before Cocoon attempts to connect to Mountain’s gRPC server (port 50051). The bootstrap stage order is: RPCServer (Stage 5) bind -> MountainConnection (Stage 3) connect. Mountain allows a 30-second connection budget; reversing this order causes Mountain to time out before Cocoon is ready to accept the handshake.

sequenceDiagram
    participant Mountain as Mountain
    participant Server as gRPC Server
    participant Cocoon as Cocoon sidecar
    participant Init as Initialization

    Mountain->>Server: Start gRPC server on port 50051
    Mountain->>Cocoon: Spawn node bootstrap-fork.js
    Cocoon->>Server: Connect gRPC client to 127.0.0.1:50051
    Cocoon->>Server: Send $initialHandshake notification
    Server-->>Mountain: Handshake received
    Mountain->>Mountain: Gather InitData (workspace, extensions, config)
    Mountain->>Cocoon: Send Initialize(InitData)
    Cocoon->>Init: Create InitDataLayer
    Init->>Init: Run FullAppInitialization
    Init->>Init: Install RequireInterceptor
    Init->>Init: Activate startup extensions
    Cocoon->>Server: Send activity ping every 5 seconds
    Server-->>Mountain: Connection established, normal operation

Disconnection and Reconnection

Network failure or Cocoon crash
    |
    v
Mountain detects stale connection (no activity within 30-second check window)
    |
    +---> Option 1: Restart Cocoon (default, up to 3 attempts)
    |       - Kill existing Cocoon process
    |       - Re-spawn from bootstrap-fork.js
    |       - Re-run initialization sequence
    |       - Restored state: configuration, open files
    |       - Lost state: extension-managed data, webview panels
    |
    +---> Option 2: Graceful degradation
            - Show reconnection notification in UI
            - Queue extension API calls
            - Reconnect when Cocoon restarts (user manually)

Mountain-Air Connection

Mountain starts
    |
    v
Mountain spawns Air binary
    |
    v
Air connects gRPC to 127.0.0.1:50053
    |
    +---> Sends Connect { services: [updater, indexer, crypto] }
    |
    v
Mountain registers Air services in AppState
    |
    v
Normal operation:
    - Mountain dispatches background work via PerformAction
    - Air responds with action results
    - Both sides maintain activity tracking
    - Staleness check every 30 seconds

Health Monitoring 💓

Heartbeat Protocol

Both gRPC connections (Mountain-Cocoon, Mountain-Air) implement a health monitoring protocol. Health is tracked via a per-connection ConnectionMetadata struct in Vine/Source/Client/Shared.rs:

Health is determined by three conditions in Vine/Source/Client/CheckSideCarHealth.rs: the connection must be marked IsHealthy, the LastActivity timestamp must not be older than HEALTH_CHECK_INTERVAL_MS (30 seconds), and the FailureCount must not exceed MAX_RETRY_ATTEMPTS (10). Failed connections are recorded via RecordSideCarFailure which increments the counter and sets IsHealthy to false; successful activity resets both via UpdateSideCarActivity.

Diagnostic Logging

All connection state changes are logged via the dev_log! system at Mountain/Source/IPC/DevLog/:

[DEV:Vine] gRPC server listening on [::1]:50051
[DEV:Vine] Cocoon connected, handshake received
[DEV:Vine] Heartbeat OK (seq=142, latency=3ms)
[DEV:Vine] Heartbeat TIMEOUT (last: seq=147, 18s ago)
[DEV:Vine] Cocoon disconnected, restarting (attempt 1/3)

Protocol Buffer Definitions 📁

Current Location

Protocol definitions currently reside in consuming components:

Code Generation

Rust types are generated from .proto files using prost and tonic-build at compile time:

// Mountain/build.rs  (references Vine element's proto)
fn main() {
    tonic_build::configure()
        .compile(&["../Vine/Proto/Vine.proto"], &["../Vine/Proto"])
        .expect("Failed to compile protos");
}

TypeScript types are generated using protoc-gen-ts and checked into the Cocoon source tree as generated artifacts.

Security 🛡️

All gRPC connections are restricted to localhost only ([::1] / 127.0.0.1). No remote connections are accepted.

Related Documentation 📋

• Architecture - System architecture
• BuildPipeline - Build pipeline
• EditorCore - Editor workbench
• Polyfills - Compatibility shims
• RustInfrastructure - Rust backend components
• Building - Build instructions
• Workflow/ApplicationStartupAndHandshake
• Workflow/CreatingAndInteractingWithAWebviewPanel

Project Maintainers: Source Open (Source/[email protected]) | GitHub Repository | Report an Issue