Air: Background Daemon 🪁

The Air background daemon:

• A persistent Rust sidecar process that runs alongside Mountain
• Handles resource-intensive operations to keep the main editor process responsive
• Operations include: update management, file indexing, cryptographic operations, and background downloads

Table of Contents

1. Overview
2. Architecture
3. Module Map
4. Services
5. Data Flow
6. Startup Sequence
7. Configuration
8. Related Documentation

graph TB
    subgraph Air["Air Daemon"]
        GRPC["gRPC Server<br/>(tonic, port 50053)"]
        UM["Update Manager<br/>check / verify / apply"]
        DL["Downloader<br/>resilient pause/resume"]
        AS["Auth Service<br/>crypto / signing"]
        IX["Indexer<br/>file content / search"]
        HC["Health Check<br/>watchdog / metrics"]
        HTTP["HTTP Client<br/>reqwest"]
        MIST["Mist DNS<br/>local resolver"]
        CFG["Configuration<br/>hot-reload"]

        GRPC --> UM
        GRPC --> DL
        GRPC --> AS
        GRPC --> IX
        GRPC --> HC
        DL --> HTTP
        AS --> HTTP
        UM --> HTTP
        HTTP --> MIST
        GRPC -.-> CFG
    end

    MOUNTAIN["Mountain<br/>ProcessManagement"] -->|"gRPC: PerformAction"| GRPC

Overview 📋

Architecture 🏗️

Air is structured around a central gRPC server that receives task delegation from Mountain. Internal modules handle distinct responsibilities.

                    +------------------------------------------+
                    |               Mountain                    |
                    |  ProcessManagement/AirManagement.rs       |
                    |  Sends work via PerformAction gRPC call   |
                    +-------------------+----------------------+
                                        |
                                        | gRPC (port 50053)
                                        v
+----------------------------------------------------------------+
|                        Air Daemon                               |
|                                                                 |
|  +------------------+  +------------------+  +----------------+ |
|  | gRPC Server      |  | Update Manager   |  | Downloader     | |
|  | (tonic)          |  | (check, verify,  |  | (resilient     | |
|  | routes tasks     |  |  apply patches)  |  |  pause/resume) | |
|  +------------------+  +------------------+  +----------------+ |
|                                                                 |
|  +------------------+  +------------------+  +----------------+ |
|  | Auth Service     |  | Indexer          |  | Health Check   | |
|  | (crypto, signing)|  | (file content    |  | (watchdog,     | |
|  |                  |  |  search index)   |  |  metrics)      | |
|  +------------------+  +------------------+  +----------------+ |
|                                                                 |
|  +------------------+  +------------------+  +----------------+ |
|  | HTTP Client      |  | Mist DNS         |  | Configuration | |
|  | (reqwest)        |  | (local resolver) |  | (hot-reload)   | |
|  +------------------+  +------------------+  +----------------+ |
+----------------------------------------------------------------+

Module Map 🗺️

gRPC Service Definition (Vine/Air.proto) 📜

service BackgroundServices {
    // Registration and lifecycle
    rpc Connect(ConnectRequest) returns (ConnectResponse);
    rpc Disconnect(DisconnectRequest) returns (DisconnectResponse);
    rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse);

    // Task execution
    rpc PerformAction(ActionRequest) returns (ActionResponse);
    rpc CancelAction(CancelRequest) returns (CancelResponse);

    // Health
    rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
    rpc GetStatus(StatusRequest) returns (StatusResponse);
}

Services 🔌

Update Manager 🔄

The update manager owns the full lifecycle of application updates:

Download Manager 📥

The resilient download manager handles extension downloads, language server binaries, and dependency fetching:

Indexing Service 🔍

File indexing builds and maintains a searchable content index of the workspace:

1. File system walker discovers files (respecting .gitignore and exclude patterns)
2. Language-aware content extraction (plain text, code tokens, symbols)
3. Inverted index construction for fast text search
4. Incremental indexing on file system change events
5. Index persistence across daemon restarts

Authentication Service 🔐

Manages sensitive cryptographic operations:

• Binary signing for update authenticity verification
• Secure token storage for remote service authentication
• Login flow orchestration for cloud services
• Key generation and rotation for local encryption

Data Flow 📊

Update Check Flow 🔄

Mountain triggers update check
    |
    v
Air gRPC server receives CheckForUpdate
    |
    v
Update Manager sends HTTP GET to update server
    |
    +---> Server responds with release manifest
    |       (version, URL, checksum, signature)
    |
    v
Update Manager verifies response signature
    |
    v
Air returns update metadata to Mountain
    |
    v
Mountain displays update notification to user

Download with Progress Flow 📥

Mountain calls PerformAction(StartDownload { url, target })
    |
    v
Download Manager begins HTTP download with Range support
    |
    +---> Streaming progress events: bytesReceived, totalBytes, speed
    |        Mountain relays progress to Wind (UI progress bar)
    |
    +---> On complete: SHA-256 verification
    +---> On failure: retry with backoff (up to 3 attempts)
    +---> On all retries exhausted: return error to Mountain
    |
    v
Download Manager returns ActionResponse { success, filePath }

Startup Sequence 🚀

1. Mountain spawns Air binary via ProcessManagement
   - Sets environment: VINE_PORT, MIST_PORT, DATA_DIR, LOG_LEVEL
   - Watches process health via heartbeat

2. Air Binary::main() executes
   - Parses CLI arguments
   - Initializes tracing/logging
   - Loads Configuration (with hot-reload)

3. Air starts gRPC server on port 50053
   - Registers BackgroundServices service handlers
   - Begins listening for incoming connections

4. Air sends Connect request to Mountain
   - Registers available services: [updater, indexer, auth, downloader]
   - Exchanges version and capability information

5. Heartbeat monitoring begins
   - Both sides send Heartbeat every 5 seconds
   - Air includes resource usage metrics in heartbeat
   - Mountain detects timeout after 3 missed heartbeats

6. Air signals ready for task processing
   - Mountain begins dispatching background work

Configuration ⚙️

Air reads configuration from environment variables and supports hot-reload via file watching:

Related Documentation 📖

• Common — Abstract core traits
• Mountain — Main backend application
• Mist — DNS isolation server
• Vine — gRPC protocol specification
• BuildPipeline — Build pipeline

Funding 💎

Air is developed as part of the CodeEditorLand project, funded through the NGI0 Commons Fund, a grant programme of the European Commission’s Next Generation Internet initiative.

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