Vine/

Host.rs

//! # Vine::Host
//!
//! [`VineHost`] is the embedder-facing seam between Vine and its consumer
//! runtime. Mountain (Tauri runtime), Air (background daemon), and any
//! Rust-side Cocoon client implement this trait to expose the minimum
//! surface Vine's notification handlers need: application-state access,
//! renderer event emission, and an [`IPCProvider`] handle for cross-channel
//! re-entrancy. Handlers operate on `&dyn VineHost` so a single handler
//! tree can be hosted against any embedder runtime.
//!
//! ## Design notes
//!
//! - [`ApplicationState`](VineHost::ApplicationState) returns `&dyn
//!   ApplicationStateAccess`. Vine treats application state as opaque;
//!   embedders decide what their state exposes via embedder-local sub-traits
//!   and downcasting.
//! - [`EmitToRenderer`](VineHost::EmitToRenderer) is the single entry point for
//!   "send a value to the workbench / Sky window." Mountain wires it to
//!   `tauri::WebviewWindow::emit`; Air leaves it as a no-op (no renderer).
//! - [`IPCProvider`](VineHost::IPCProvider) returns `Arc<dyn IPCProvider>` for
//!   handlers that need to re-enter the IPC bus.
//!
//! ## Stability
//!
//! Adding methods to [`VineHost`] is a compatible change so long as every
//! impl is updated in the same revision. Removing a method requires
//! sweeping every consumer.

use std::sync::Arc;

use serde_json::Value;

/// Opaque application-state handle exposed to Vine handlers.
///
/// Embedders downcast or call sub-trait methods declared in their own crate.
/// Vine itself never reaches into the state; handlers do.
pub trait ApplicationStateAccess: Send + Sync {
	/// Returns the embedder name (e.g. "Mountain", "Air"). Useful for
	/// diagnostic logs that fan in from multiple hosts.
	fn EmbedderName(&self) -> &'static str;
}

/// Cross-channel IPC provider abstraction.
///
/// Mirrors the shape of `CommonLibrary::IPC::IPCProvider` so consumers can
/// swap between the two with a single `use` change. Kept local to Vine to
/// avoid pulling `CommonLibrary` into the dependency graph.
pub trait IPCProvider: Send + Sync {
	/// Sends a request on the named channel and waits for a JSON response.
	fn SendRequest(&self, Channel:&str, Payload:Value) -> futures::future::BoxFuture<'_, crate::Error::Result<Value>>;

	/// Fire-and-forget notification on the named channel.
	/// `Method` is the gRPC method name inside the channel (e.g.
	/// `"$onDidChangeBreakpoints"`).
	fn SendNotification(&self, Channel:&str, Method:&str, Payload:Value);
}

/// Cheap-to-clone renderer event sink.
///
/// Handlers with long-lived flushers (the channel-drain coalescers used by
/// `ProgressReport`, `DecorationTypeLifecycle`, `OutputChannelCoalesce`)
/// capture an `Arc<dyn RendererEmitter>` once and reuse it across awaits.
/// Embedders implement this trait on a tiny struct that holds whatever
/// transport handle is needed (e.g. `tauri::AppHandle`), independent of
/// the full [`VineHost`] surface.
pub trait RendererEmitter: Send + Sync + 'static {
	/// Emits `Payload` on the renderer's `Channel`. Embedders without a
	/// renderer leave this a no-op.
	fn Emit(&self, Channel:&str, Payload:Value);
}

/// The embedder-facing seam between Vine and its host runtime.
///
/// Implementations belong in the embedder crate (Mountain, Air, …), not in
/// Vine.
pub trait VineHost: Send + Sync {
	/// Returns the embedder's application state for handler use.
	fn ApplicationState(&self) -> &dyn ApplicationStateAccess;

	/// Emits a JSON event on the named renderer channel. No-op for embedders
	/// that have no renderer (e.g. Air).
	fn EmitToRenderer(&self, Channel:&str, Payload:Value);

	/// Returns a cheap-to-clone renderer event sink. Used by handlers
	/// with long-lived flushers that need to emit from a background
	/// task without borrowing the full host.
	fn RendererEmitter(&self) -> Arc<dyn RendererEmitter>;

	/// Returns the cross-channel IPC provider. Used by handlers that need to
	/// re-enter the IPC bus (e.g. tree-view registration that needs to call
	/// `sky:replay-events`).
	fn IPCProvider(&self) -> Arc<dyn IPCProvider>;

	/// Unregisters a provider by handle. Embedders that maintain a provider
	/// registry route this to their `ProviderRegistration` table; embedders
	/// without a registry silently discard.
	fn UnregisterProvider(&self, Handle:u32);

	/// Inserts a proxied command into the embedder's command dispatch registry.
	/// `SideCarIdentifier` is the gRPC sidecar to proxy to (e.g.
	/// `"cocoon-main"`). No-op for embedders without a command registry.
	fn RegisterCommandInRegistry(&self, CommandId:&str, SideCarIdentifier:&str);

	/// Removes a command from the embedder's dispatch registry.
	/// No-op for embedders without a command registry.
	fn UnregisterCommandInRegistry(&self, CommandId:&str);

	// --- Terminal operations ---

	/// Spawns a background task that sends `Text` to the PTY identified by
	/// `TerminalId`. No-op for embedders without terminal support.
	fn SpawnSendTextToTerminal(&self, TerminalId:u64, Text:String);

	/// Spawns a background task that disposes the PTY identified by
	/// `TerminalId`. No-op for embedders without terminal support.
	fn SpawnDisposeTerminal(&self, TerminalId:u64);

	/// Creates a new PTY terminal with the given options JSON and returns
	/// `Some({ "id": u64, "pid": u64, "name": string })` on success, `None`
	/// on failure or for embedders without terminal support.
	fn CreateTerminal<'a>(&'a self, Options:&'a Value) -> futures::future::BoxFuture<'a, Option<Value>>;

	// --- SCM operations ---

	/// Registers an SCM provider in the embedder's `ProviderRegistration`
	/// table. Called once per `vscode.scm.createSourceControl(...)`
	/// invocation.
	fn RegisterScmInRegistry(&self, Handle:u32, ScmId:&str, Label:&str, ExtId:&str);

	/// Forwards a `CreateSourceControl` call to the embedder's
	/// `SourceControlManagementProvider`. Errors are logged internally.
	fn CreateSourceControl<'a>(&'a self, Payload:Value) -> futures::future::BoxFuture<'a, ()>;

	/// Forwards an `UpdateSourceControlGroup` call to the embedder's
	/// `SourceControlManagementProvider`. Errors are logged internally.
	fn UpdateSourceControlGroup<'a>(&'a self, ScmHandle:u32, Payload:Value) -> futures::future::BoxFuture<'a, ()>;

	// --- Language-feature provider registration ---

	/// Registers a language-feature provider by normalised type name.
	/// `TypeName` is the wire method stripped of `register_` prefix and
	/// optional `_provider` suffix (e.g. `"hover"`, `"completion_item"`).
	/// Returns `true` if the type was recognised and the registration was
	/// inserted; `false` for unknown type names (no-op embedders always return
	/// `false`).
	fn RegisterLanguageProvider(&self, Handle:u32, TypeName:&str, Payload:&Value) -> bool;

	/// Persists a resource-state snapshot for an SCM group in the embedder's
	/// SCM marker registry. `ScmHandle` is the provider handle,
	/// `GroupId` identifies the group within that provider, and
	/// `ResourceStates` is the raw JSON array of resource state objects.
	/// No-op for embedders without SCM marker support.
	fn UpdateScmGroupMarkers(&self, ScmHandle:u32, GroupId:&str, ResourceStates:&Value);
}