Skip to main content

Crate AirLibrary

Crate AirLibrary 

Source
Expand description

§Air: Background Daemon for Code Editor Land

Air runs silently in the background so Land is always up to date and ready to go. It handles updates, downloads, crypto signing, and file indexing without blocking the editor.

§Architecture & Connections

Air is the hub that connects various components in the Land ecosystem:

  • Wind (Effect-TS): Functional programming patterns for state management Air integrates with Wind’s effect system for predictable state transitions and error handling patterns

  • Cocoon (NodeJS host): The Node.js runtime for web components Air communicates with Cocoon through the Vine protocol to deliver web assets and perform frontend build operations. Port: 50052

  • Mountain (Tauri bundler): Main desktop application Mountain receives work from Air through Vine (gRPC) and performs the main application logic. Mountain’s Tauri framework handles the native integration

  • Vine (gRPC protocol): Communication layer connecting all components Air hosts the Vine gRPC server on port 50053, receiving work requests from Mountain

§VSCode Architecture References

§Update Service

Reference: Dependency/Microsoft/Dependency/Editor/src/vs/platform/update/

Air’s UpdateManager is inspired by VSCode’s update architecture:

  • AbstractUpdateService (common/update.ts): Base service defining update interfaces
  • Platform-specific implementations:
    • updateService.darwin.ts - macOS update handling
    • updateService.linux.ts - Linux update handling
    • updateService.snap.ts - Snap package updates
    • updateService.win32.ts - Windows update handling

Air’s UpdateManager abstracts platform differences and provides:

  • Update checking with version comparison
  • Package download with resumable support
  • Checksum verification for integrity
  • Signature validation for security
  • Staged updates for rollback capability

§Lifecycle Management

Reference: Dependency/Microsoft/Dependency/Editor/src/vs/base/common/lifecycle.ts

VSCode’s lifecycle patterns inform Air’s daemon management:

  • Disposable pattern: Resources implement cleanup methods
  • EventEmitter: Async event handling for state changes
  • DisposableStore: Aggregate resource cleanup

Air adapts these patterns with:

  • ApplicationState: Central state management with cleanup
  • DaemonManager: Single-instance lock management
  • Graceful shutdown with resource release

§Module Organization

The Air library is organized into functional modules:

§Core Infrastructure

  • ApplicationState: Central state manager for the daemon
  • Configuration: Configuration loading and validation
  • Daemon: Daemon lifecycle and lock management
  • Logging: Structured logging with filtering
  • Metrics: Prometheus-style metrics collection
  • Tracing: Distributed tracing support

§Services

  • Authentication: Token management and cryptographic operations
  • Updates: Update checking, downloading, and installation
  • Downloader: Background downloads with retry logic
  • Indexing: File system indexing for code navigation

§Communication

  • Vine: gRPC server and client implementation
    • Generated protobuf code in Vine/Generated/
    • Server implementation in Vine/Server/
    • Client utilities in Vine/Client/

§Reliability

  • Resilience: Retry policies, circuit breakers, timeouts
    • RetryPolicy: Configurable retry strategies
    • CircuitBreaker: Fail-fast for external dependencies
    • BulkheadExecutor: Concurrency limiting
    • TimeoutManager: Operation timeout management
  • Security: Rate limiting, checksums, secure storage
  • HealthCheck: Service health monitoring

§Extensibility

  • Plugins: Hot-reloadable plugin system
  • CLI: Command-line interface for daemon control

§Protocol Details

Vine Protocol (gRPC)

  • Version: 1 (Air::ProtocolVersion)
  • Transport: HTTP/2
  • Serialization: Protocol Buffers
  • Ports:
    • 50053: Air (background services) - DefaultBindAddress
    • 50052: Cocoon (NodeJS/web services)

TLS/mTLS support for production security is now available via the mtls feature. See the Mountain module for client TLS configuration.

§FUTURE Enhancements

§High Priority

  • Implement metrics HTTP endpoint (/metrics)
  • Add Prometheus metric export with labels
  • Implement TLS/mTLS for gRPC connections
  • Add connection authentication/authorization
  • Implement configuration hot-reload (SIGHUP)
  • Add comprehensive integration tests
  • Implement graceful shutdown with operation completion

§Medium Priority

  • Implement plugin hot-reload
  • Add structured logging with correlation IDs
  • Implement distributed tracing (OpenTelemetry)
  • Add health check HTTP endpoint for load balancers
  • Implement connection pooling optimizations
  • Add metrics export to external systems
  • Implement telemetry/observability export

§Low Priority

  • Add A/B testing framework for features
  • Implement query optimizer for file index
  • Add caching layer for frequently accessed data
  • Implement adaptive timeout based on load
  • Add predictive scaling based on metrics
  • Implement chaos testing/metrics

§Error Handling Strategy

All modules use defensive coding practices:

  1. Input Validation: All public functions validate inputs with descriptive errors
  2. Timeout Handling: Default timeouts with configuration overrides
  3. Resource Cleanup: Drop trait + explicit cleanup methods
  4. Circuit Breaker: Fail-fast for external dependencies
  5. Retry Logic: Exponential backoff for transient failures
  6. Metrics Recording: All operations record success/failure metrics
  7. Panic Recovery: Catch panics in critical async tasks

§Constants

  • VERSION: Air daemon version from Cargo.toml
  • DefaultConfigFile: Default config filename (Air.toml)
  • DefaultBindAddress: gRPC bind address ([::1]:50053)
  • ProtocolVersion: Vine protocol version (1)

Modules§

ApplicationState
Application State Management
Authentication
Authentication Service
CLI
CLI - Command Line Interface
Configuration
Configuration Management
Daemon
Daemon Lifecycle Management
Downloader
Download Manager Service
HTTP
HTTP Client Module
HealthCheck
Health Check System
Indexing
File Indexing and Search Service
Logging
Structured Logging Module
Metrics
Metrics Collection and Export Module
Mountain
Mountain Client Module
Plugins
Plugin Architecture
Resilience
Resilience Patterns Module
Security
Security Module
Tracing
Distributed Tracing Module
Updates
Update Management Service
Utility
Common utility functions
Vine
Vine Protocol Implementation

Enums§

AirError
Error type for Air operations

Constants§

DefaultBindAddress
Default gRPC bind address for the Vine server
DefaultConfigFile
Default configuration file name
ProtocolVersion
Protocol version for Mountain-Air communication
VERSION
Air Daemon version information

Type Aliases§

Result
Result type for Air operations