|
|
|
The Pure Abstract Foundation for LandβποΈ
VS Code's codebase imports concrete implementations directly. Testing a single component means mocking entire subsystems. There is no dependency injection at the architecture level.
"Mock any service and test any element in isolation, no running editor required."
Rust API Documentationβπ
Common is the architectural core of the Land Code Editor's native backend.
It provides a pure, abstract foundation with no concrete implementations -
defining the application's "language" through async traits per service domain,
an ActionEffect declarative system, Data Transfer Objects (DTOs) for IPC, a
unified CommonError enum, a transport-agnostic communication layer, and a
telemetry dual-pipe.
The entire Mountain backend and any future native components are built by
implementing the traits and consuming the effects defined in this crate. By
defining all application capabilities as abstract traits, it enforces clean
architectural boundaries, maximizes testability through mock implementations,
and ensures consistent data contracts across the entire native ecosystem.
Common is engineered to:
- Define Pure Abstractions - Every application capability is expressed as
an
async traitwith zero concrete implementation logic. - Enable Compile-Time DI - The
EnvironmentandRequirestraits allow components to declare service needs without coupling to specific implementations. - Stabilize Data Contracts - All
serde-compatible DTOs and error types form the stable IPC contract betweenMountainβ°οΈ,Cocoonπ¦,Groveπ³, and all sidecars. - Provide Transport-Agnostic Communication - The
Transportlayer defines aTransportStrategytrait implemented by concrete transports inGrove.
Declarative ActionEffect System - Operations are treated as data
structures rather than direct function calls. Effects are constructed as values
that describe the desired side effect and are then passed to an
ApplicationRunTime for execution. This enables composition, testing, and
controlled execution in a single unified pattern. Instead of writing a function
that immediately performs I/O, you call a function that returns a description
of that effect.
Compile-Time Dependency Injection - The Environment and Requires traits
handle DI at compile time. Components declare their service needs without
coupling to specific implementations. All core application services are defined
as async traits, enforcing an asynchronous-first architecture across the
entire system.
DTO Library for IPC - Every data structure used for IPC communication with
Cocoon and internal state management in Mountain is defined here. All types
are serde-compatible, forming the stable contract between all Land components.
Unified Error Handling - A single CommonError enum covers every possible
failure across all service domains - FileSystem, Terminal, SCM,
LanguageFeature, Transport, and more. Error handling is consistent and
predictable everywhere.
Transport-Agnostic Communication - The Transport/ layer defines a
TransportStrategy trait. Concrete implementations (gRPCTransport,
IPCTransport, WASMTransport, MistTransport) live in Grove.
Dual-Pipe Telemetry - The Telemetry/ module provides a shared PostHog +
OTLP emit surface consumed by all Rust sidecars.
Minimal Dependencies - This crate depends only on serde, tokio,
async-trait, and a handful of foundational crates. It has zero knowledge of
Tauri, gRPC, or any specific application logic.
| Principle | Description | Key Components |
|---|---|---|
| Abstraction | Define every application capability as an abstract async trait. Never include concrete implementation logic. |
All *Provider.rs and *Manager.rs files |
| Declarativism | Represent every operation as an ActionEffect value. The crate provides constructor functions for these effects. |
Effect/*, all effect constructor files |
| Composability | The ActionEffect system and trait-based DI are designed to be composed, allowing complex workflows to be built from simple, reusable pieces. |
Environment/*, Effect/* |
| Contract-First | Define all data structures (DTO/*) and error types (Error/*) first. These form the stable contract for all other components. |
DTO/, Error/ |
| Purity | This crate has minimal dependencies and is completely independent of Tauri, gRPC, or any specific application logic. |
Cargo.toml |
graph LR
classDef common fill:#d4f5d4,stroke:#27ae60,stroke-width:2px,color:#0a3a0a;
classDef mountain fill:#f0d0ff,stroke:#9b59b6,stroke-width:2px,color:#2c0050;
classDef consumer fill:#cce8ff,stroke:#2980b9,stroke-width:1px,color:#00304a;
classDef transport fill:#fff3c0,stroke:#f39c12,stroke-width:1px,stroke-dasharray:5 5,color:#5a3e00;
subgraph COMMON["Common - Pure Abstract Foundation (no Tauri / gRPC deps)"]
direction TB
subgraph CORE["Effect System"]
Traits["async trait per service domain\nFileSystem Β· Terminal Β· SCM Β· Storage\nUI Β· Search Β· Document Β· TreeViewβ¦"]:::common
Effects["ActionEffect - operations as values\nConstructors per domain"]:::common
Effects -. depends on .-> Traits
end
subgraph DATA["Data Layer"]
DTOs["DTO/ - serde-compatible structs\nfor IPC + internal state"]:::common
Errors["CommonError - unified error enum"]:::common
end
subgraph INFRA["Infrastructure"]
Transport["Transport/ - TransportStrategy\ntrait + config types"]:::transport
Telemetry["Telemetry/ - PostHog + OTLP\ndual-pipe emit surface"]:::common
Env["Environment/ + Effect/\nApplicationRunTime trait\nDI via Requires / HasEnvironment"]:::common
end
end
subgraph MOUNTAIN["Mountain β°οΈ - Primary Consumer"]
MountainEnv["Environment/ Providers\n(concrete trait impls)"]:::mountain
AppRunTime["ApplicationRunTime\n(executes ActionEffects)"]:::mountain
MountainEnv -.implements.-> Traits
AppRunTime -.executes.-> Effects
AppRunTime -.uses.-> DTOs
end
subgraph TESTS["Tests"]
MockImpls["Mock trait implementations"]:::consumer
MockImpls -.mocks.-> Traits
end
Air["Air πͺ daemon\n(uses Transport + Telemetry)"]:::consumer
Air -.uses.-> Transport
Air -.uses.-> Telemetry
Connection paths:
| Path | Relationship | Use Case |
|---|---|---|
Mountain β Common |
Implements traits, consumes effects | Primary consumer of all service definitions |
Grove β Common transport layer |
Implements TransportStrategy |
gRPC, IPC, WASM, Mist transports |
Air β Common transport + telemetry |
Uses Transport and Telemetry modules |
Background daemon communication |
Sidecars β Common telemetry |
Consumes PostHog + OTLP emit surface |
Shared telemetry across all Rust sidecars |
Mock tests β Common traits |
Implements mock providers | Fast, isolated unit tests |
Cocoon β Common |
Shares DTOs via serde |
IPC data contract compatibility |
| Component | Path | Description |
|---|---|---|
| Library Root | Source/Library.rs |
Crate root, declares all modules. |
| Environment | Source/Environment/ |
The core DI system (Environment, Requires, HasEnvironment traits). |
| Effect | Source/Effect/ |
The ActionEffect system (ActionEffect, ApplicationRunTime traits). |
| Error | Source/Error/ |
The universal CommonError enum. |
| DTO | Source/DTO/ |
Shared Data Transfer Objects (re-exports from service modules). |
| Utility | Source/Utility/ |
Utility functions (e.g., Serialization). |
| Command | Source/Command/ |
Command management service. |
| Configuration | Source/Configuration/ |
Configuration provider service. |
| CustomEditor | Source/CustomEditor/ |
Custom editor provider service. |
| Debug | Source/Debug/ |
Debug service. |
| Diagnostic | Source/Diagnostic/ |
Diagnostic manager service. |
| Document | Source/Document/ |
Document provider service. |
| ExtensionManagement | Source/ExtensionManagement/ |
Extension management service. |
| FileSystem | Source/FileSystem/ |
File system read/write service. |
| IPC | Source/IPC/ |
Inter-process communication service. |
| Keybinding | Source/Keybinding/ |
Keybinding provider service. |
| LanguageFeature | Source/LanguageFeature/ |
Language feature provider registry. |
| Output | Source/Output/ |
Output channel manager service. |
| Search | Source/Search/ |
Search provider service. |
| Secret | Source/Secret/ |
Secret storage provider service. |
| SourceControlManagement | Source/SourceControlManagement/ |
Source control management service. |
| StatusBar | Source/StatusBar/ |
Status bar provider service. |
| Storage | Source/Storage/ |
Storage provider service. |
| Synchronization | Source/Synchronization/ |
Synchronization provider service. |
| Telemetry | Source/Telemetry/ |
Telemetry service (dual-pipe PostHog + OTLP). |
| Terminal | Source/Terminal/ |
Terminal provider service. |
| Testing | Source/Testing/ |
Test controller service. |
| Transport | Source/Transport/ |
Transport-agnostic communication layer. |
| TreeView | Source/TreeView/ |
Tree view provider service. |
| UserInterface | Source/UserInterface/ |
User interface provider service. |
| Webview | Source/Webview/ |
Webview provider service. |
| Workspace | Source/Workspace/ |
Workspace provider service. |
Element/Common/
βββ Source/
β βββ Library.rs # Crate root, declares all modules
β βββ Command/ # Command management service
β β βββ mod.rs
β β βββ CommandExecutor.rs
β β βββ ExecuteCommand.rs
β β βββ GetAllCommands.rs
β β βββ RegisterCommand.rs
β β βββ UnregisterCommand.rs
β βββ Configuration/ # Configuration provider service
β β βββ mod.rs
β β βββ ConfigurationProvider.rs
β β βββ ConfigurationInspector.rs
β β βββ GetConfiguration.rs
β β βββ InspectConfiguration.rs
β β βββ UpdateConfiguration.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ ConfigurationInitializationDTO.rs
β β βββ ConfigurationOverridesDTO.rs
β β βββ ConfigurationScope.rs
β β βββ ConfigurationTarget.rs
β β βββ InspectResultDataDTO.rs
β βββ CustomEditor/ # Custom editor provider service
β β βββ mod.rs
β β βββ CustomEditorProvider.rs
β βββ Debug/ # Debug service
β β βββ mod.rs
β β βββ DebugService.rs
β βββ Diagnostic/ # Diagnostic manager service
β β βββ mod.rs
β β βββ DiagnosticManager.rs
β β βββ ClearDiagnostics.rs
β β βββ GetAllDiagnostics.rs
β β βββ SetDiagnostics.rs
β βββ Document/ # Document provider service
β β βββ mod.rs
β β βββ DocumentProvider.rs
β β βββ ApplyDocumentChanges.rs
β β βββ OpenDocument.rs
β β βββ SaveAllDocuments.rs
β β βββ SaveDocument.rs
β β βββ SaveDocumentAs.rs
β βββ DTO/ # Shared Data Transfer Objects
β β βββ mod.rs
β β βββ WorkspaceEditDTO.rs
β βββ Effect/ # ActionEffect system
β β βββ mod.rs
β β βββ ActionEffect.rs
β β βββ ApplicationRunTime.rs
β β βββ ExecuteEffect.rs
β βββ Environment/ # Dependency injection system
β β βββ mod.rs
β β βββ Environment.rs
β β βββ HasEnvironment.rs
β β βββ Requires.rs
β βββ Error/ # Unified error handling
β β βββ mod.rs
β β βββ CommonError.rs
β βββ ExtensionManagement/ # Extension management service
β β βββ mod.rs
β β βββ ExtensionManagementService.rs
β βββ FileSystem/ # File system read/write service
β β βββ mod.rs
β β βββ FileSystemReader.rs
β β βββ FileSystemWriter.rs
β β βββ FileWatcherProvider.rs
β β βββ Copy.rs
β β βββ CreateDirectory.rs
β β βββ CreateFile.rs
β β βββ Delete.rs
β β βββ ReadDirectory.rs
β β βββ ReadFile.rs
β β βββ Rename.rs
β β βββ StatFile.rs
β β βββ WriteFileBytes.rs
β β βββ WriteFileString.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ FileSystemStatDTO.rs
β β βββ FileTypeDTO.rs
β βββ IPC/ # Inter-process communication service
β β βββ mod.rs
β β βββ Channel.rs
β β βββ IPCProvider.rs
β β βββ EstablishHostConnection.rs
β β βββ ProxyCallToSideCar.rs
β β βββ SendNotificationToSideCar.rs
β β βββ SendRequestToSideCar.rs
β β βββ SkyEvent.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ ProxyTarget.rs
β βββ Keybinding/ # Keybinding provider service
β β βββ mod.rs
β β βββ KeybindingProvider.rs
β βββ LanguageFeature/ # Language feature provider registry
β β βββ mod.rs
β β βββ LanguageFeatureProviderRegistry.rs
β β βββ RegisterProvider.rs
β β βββ UnregisterProvider.rs
β β βββ ProvideCallHierarchy.rs
β β βββ ProvideCodeActions.rs
β β βββ ProvideCodeLenses.rs
β β βββ ProvideCompletions.rs
β β βββ ProvideDefinition.rs
β β βββ ProvideDocumentFormatting.rs
β β βββ ProvideDocumentHighlights.rs
β β βββ ProvideDocumentSymbols.rs
β β βββ ProvideFoldingRanges.rs
β β βββ ProvideHover.rs
β β βββ ProvideInlayHints.rs
β β βββ ProvideLinkedEditingRanges.rs
β β βββ ProvideOnTypeFormatting.rs
β β βββ ProvideReferences.rs
β β βββ ProvideRenameEdits.rs
β β βββ ProvideSelectionRanges.rs
β β βββ ProvideSemanticTokens.rs
β β βββ ProvideSignatureHelp.rs
β β βββ ProvideTypeHierarchy.rs
β β βββ ProvideWorkspaceSymbols.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ CompletionContextDTO.rs
β β βββ CompletionItemDTO.rs
β β βββ CompletionListDTO.rs
β β βββ HoverResultDTO.rs
β β βββ IMarkdownStringDTO.rs
β β βββ LocationDTO.rs
β β βββ PositionDTO.rs
β β βββ ProviderType.rs
β β βββ RangeDTO.rs
β β βββ TextEditDTO.rs
β βββ Output/ # Output channel manager service
β β βββ mod.rs
β β βββ OutputChannelManager.rs
β β βββ AppendToOutputChannel.rs
β β βββ ClearOutputChannel.rs
β β βββ CloseOutputChannelView.rs
β β βββ DisposeOutputChannel.rs
β β βββ RegisterOutputChannel.rs
β β βββ ReplaceOutputChannelContent.rs
β β βββ RevealOutputChannel.rs
β βββ Search/ # Search provider service
β β βββ mod.rs
β β βββ SearchProvider.rs
β βββ Secret/ # Secret storage provider service
β β βββ mod.rs
β β βββ SecretProvider.rs
β β βββ DeleteSecret.rs
β β βββ GetSecret.rs
β β βββ StoreSecret.rs
β βββ SourceControlManagement/ # Source control management service
β β βββ mod.rs
β β βββ SourceControlManagementProvider.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ SourceControlCreateDTO.rs
β β βββ SourceControlGroupUpdateDTO.rs
β β βββ SourceControlInputBoxDTO.rs
β β βββ SourceControlManagementGroupDTO.rs
β β βββ SourceControlManagementProviderDTO.rs
β β βββ SourceControlManagementResourceDTO.rs
β β βββ SourceControlUpdateDTO.rs
β βββ StatusBar/ # Status bar provider service
β β βββ mod.rs
β β βββ StatusBarProvider.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ StatusBarEntryDTO.rs
β βββ Storage/ # Storage provider service
β β βββ mod.rs
β β βββ StorageProvider.rs
β β βββ GetStorageItem.rs
β β βββ SetStorageItem.rs
β βββ Synchronization/ # Synchronization provider service
β β βββ mod.rs
β β βββ SynchronizationProvider.rs
β βββ Telemetry/ # Telemetry service (PostHog + OTLP)
β β βββ mod.rs
β β βββ CaptureError.rs
β β βββ CaptureEvent.rs
β β βββ CaptureSession.rs
β β βββ Client.rs
β β βββ Configuration.rs
β β βββ DistinctId.rs
β β βββ EmitOTLPSpan.rs
β β βββ Initialize.rs
β β βββ IsAllowed.rs
β β βββ Tier.rs
β β βββ Traceparent.rs
β βββ Terminal/ # Terminal provider service
β β βββ mod.rs
β β βββ TerminalProvider.rs
β β βββ CreateTerminal.rs
β βββ Testing/ # Test controller service
β β βββ mod.rs
β β βββ TestController.rs
β βββ Transport/ # Transport-agnostic communication layer
β β βββ mod.rs
β β βββ TransportStrategy.rs
β β βββ TransportConfig.rs
β β βββ TransportError.rs
β β βββ CircuitBreaker.rs
β β βββ Metrics.rs
β β βββ Retry.rs
β β βββ UnifiedRequest.rs
β β βββ UnifiedResponse.rs
β β βββ gRPC.rs
β β βββ IPC.rs
β β βββ WASM.rs
β β βββ Common/
β β β βββ mod.rs
β β βββ Registry/
β β β βββ mod.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ Correlation.rs
β β βββ TransportError.rs
β β βββ UnifiedRequest.rs
β β βββ UnifiedResponse.rs
β βββ TreeView/ # Tree view provider service
β β βββ mod.rs
β β βββ TreeViewProvider.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ TreeItemDTO.rs
β β βββ TreeViewOptionsDTO.rs
β βββ UserInterface/ # User interface provider service
β β βββ mod.rs
β β βββ UserInterfaceProvider.rs
β β βββ ShowInputBox.rs
β β βββ ShowMessage.rs
β β βββ ShowOpenDialog.rs
β β βββ ShowQuickPick.rs
β β βββ ShowSaveDialog.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ DialogOptionsDTO.rs
β β βββ FileFilterDTO.rs
β β βββ InputBoxOptionsDTO.rs
β β βββ MessageOptionsDTO.rs
β β βββ MessageSeverity.rs
β β βββ OpenDialogOptionsDTO.rs
β β βββ QuickPickItemDTO.rs
β β βββ QuickPickOptionsDTO.rs
β β βββ SaveDialogOptionsDTO.rs
β βββ Utility/ # Utility functions
β β βββ mod.rs
β β βββ Serialization.rs
β βββ Webview/ # Webview provider service
β β βββ mod.rs
β β βββ WebviewProvider.rs
β β βββ DTO/
β β βββ mod.rs
β β βββ WebviewContentOptionsDTO.rs
β βββ Workspace/ # Workspace provider service
β β βββ mod.rs
β β βββ WorkspaceProvider.rs
β β βββ WorkspaceEditApplier.rs
β β βββ ApplyWorkspaceEdit.rs
β β βββ FindFilesInWorkspace.rs
β β βββ GetWorkspaceConfigurationPath.rs
β β βββ GetWorkspaceFolderInfo.rs
β β βββ GetWorkspaceFoldersInfo.rs
β β βββ GetWorkspaceName.rs
β β βββ IsWorkspaceTrusted.rs
β β βββ OpenFile.rs
β β βββ RequestWorkspaceTrust.rs
β βββ Container.ts # DI container (TypeScript)
β βββ EffectSmol.ts # Lightweight effect runtime (TypeScript)
β βββ Errors.ts # Error types (TypeScript)
β βββ PubSub.ts # Pub/sub bus (TypeScript)
β βββ Ref.ts # Mutable references (TypeScript)
β βββ Result.ts # Result type (TypeScript)
βββ TypeScript/
β βββ Function/ # Effect constructors (TypeScript)
β βββ Interface/ # Service interfaces (TypeScript)
βββ Documentation/
β βββ GitHub/
β βββ Architecture.md # Internal architecture overview
β βββ DeepDive.md # ActionEffect system deep dive
βββ build.rs # Cargo build script
βββ Cargo.toml
βββ CHANGELOG.md
βββ LICENSE
βββ README.md
Common is the foundational layer upon which the entire native backend is
built. It has no knowledge of its consumers, but they are entirely dependent on
it.
| Element | Relationship | Description |
|---|---|---|
| Mountain β°οΈ | Primary consumer | Implements traits with concrete Environment/ providers, executes ActionEffects via ApplicationRunTime |
| Grove π³ | Transport consumer | Implements TransportStrategy trait for gRPC, IPC, WASM, Mist transports |
| Cocoon π¦ | DTO consumer | Shares DTOs via serde for IPC data contract compatibility |
| Air πͺ | Module consumer | Uses Transport and Telemetry modules for daemon communication |
| Echo π£ | Telemetry consumer | Consumes the shared PostHog + OTLP telemetry pipe |
| Tests | Mock consumer | Implements mock trait providers for fast, isolated unit testing |
Rust1.85 or later
Common is intended to be used as a local path dependency within the Land
workspace. In Mountain's Cargo.toml:
[dependencies]
Common = { path = "../Common" }- Implement a Trait: In
Mountain/Source/Environment/, provide the concrete implementation for aCommontrait.
// In Mountain/Source/Environment/FileSystemProvider.rs
use CommonLibrary::FileSystem::{FileSystemReader, FileSystemWriter};
#[async_trait]
impl FileSystemReader for MountainEnvironment {
async fn ReadFile(&self, Path: &PathBuf) -> Result<Vec<u8>, CommonError> {
// ... actual tokio::fs call ...
}
// ...
}- Create and Execute an Effect: In business logic, create and run an effect.
// In a Mountain service or command
use CommonLibrary::FileSystem;
use CommonLibrary::Effect::ApplicationRunTime;
async fn SomeLogic(Runtime: Arc<impl ApplicationRunTime>) {
let Path = PathBuf::from("/my/file.txt");
let ReadEffect = FileSystem::ReadFile(Path);
match Runtime.Run(ReadEffect).await {
Ok(Content) => info!("File content length: {}", Content.len()),
Err(Error) => error!("Failed to read file: {:?}", Error),
}
}| Crate | Purpose |
|---|---|
serde |
Serialization/deserialization for all DTOs |
tokio |
Async runtime for trait definitions |
async-trait |
Enables async fn in trait definitions |
thiserror |
Derive macro for CommonError |
posthog-rs |
Shared PostHog telemetry client |
uuid |
Transport correlation IDs |
prometheus |
Transport metrics |
Common enforces security at the architectural level:
| Layer | Mechanism |
|---|---|
| Architecture | No concrete implementations - consumers cannot bypass trait boundaries |
| Type system | All capabilities are abstract async traits with explicit type signatures |
| Error model | Single CommonError enum prevents information leakage through ad-hoc error types |
| Dependencies | Zero dependency on Tauri, gRPC, or any networking crate - no ambient authority |
| Testing | Mock implementations allow security-critical paths to be tested in isolation |
| Data contracts | serde-compatible DTOs with explicit schemas prevent deserialization attacks |
Common is designed to be compatible with:
| Target | Integration |
|---|---|
| Mountain β°οΈ | Primary consumer - implements all traits, executes effects |
| Grove π³ | Implements TransportStrategy trait for gRPC, IPC, WASM, Mist transports |
| Cocoon π¦ | Shares DTOs via serde for IPC data contract compatibility |
| Air πͺ | Consumes Transport and Telemetry modules for daemon communication |
| Sidecars | All Rust sidecars consume the shared PostHog + OTLP telemetry pipe |
| Tests | Mock implementations of all traits enable fast, isolated unit testing |
- Rust API Documentationβπ
- Architecture Overview
- Deep Dive - The
ActionEffectsystem, trait-based DI model, and guide for adding new services
- Architecture Overview - Internal module structure
- Deep Dive - In-depth technical details
- Land Documentation - Complete documentation index
Mountain- Primary consumer implementing Common traitsEcho- Work-stealing schedulerAir- Background daemon- Why Rust
CHANGELOG.md- History of changes specific to Common
This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program, under grant agreement No 101135429.
The project is operated by PlayForm, based in Sofia, Bulgaria. PlayForm acts as the open-source steward for Code Editor Land under the NGI0 Commons Fund grant.
|
|
|
|
|