Skip to content

CodeEditorLand/Common

Commonβ€πŸ§©

Last-commit
Issues
Star
Downloads

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."

License: CC0-1.0 Rust Crates.io Rust Rust Version

Rust API Documentationβ€πŸ“–


Overview

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:

  1. Define Pure Abstractions - Every application capability is expressed as an async trait with zero concrete implementation logic.
  2. Enable Compile-Time DI - The Environment and Requires traits allow components to declare service needs without coupling to specific implementations.
  3. Stabilize Data Contracts - All serde-compatible DTOs and error types form the stable IPC contract between Mountain ⛰️, Cocoon πŸ¦‹, Grove 🌳, and all sidecars.
  4. Provide Transport-Agnostic Communication - The Transport layer defines a TransportStrategy trait implemented by concrete transports in Grove.

Key Featuresβ€βš™οΈ

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.


Core Architecture Principlesβ€πŸ—οΈ

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

System Architecture 

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
Loading

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

Key Components

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.

Project Structureβ€πŸ—ΊοΈ

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

In the Land Project

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

Getting Startedβ€πŸš€

Prerequisites

  • Rust 1.85 or later

Build

Common is intended to be used as a local path dependency within the Land workspace. In Mountain's Cargo.toml:

[dependencies]
Common = { path = "../Common" }

Usage

  1. Implement a Trait: In Mountain/Source/Environment/, provide the concrete implementation for a Common trait.
// 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 ...
    }
    // ...
}
  1. 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),
    }
}

Key Dependencies

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

Securityβ€πŸ”’

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

Compatibility

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

API Reference


Related Documentation


Funding & Acknowledgementsβ€πŸ™πŸ»

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.

Land PlayForm NLnet NGI0 Commons Fund

About

Commonβ€πŸ§‘πŸ»β€πŸ­β€+ Editorβ€πŸžοΈ

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors