Crate Air

Crate Air 

Source
Expand description

§Air Binary Entry Point

§Overview

Air 🪁 is the persistent background daemon that handles resource-intensive operations for the Land code editor. It runs as a standalone process alongside Mountain, communicating via the Vine (gRPC) protocol to offload tasks like updates, downloads, authentication, and file indexing.

§Architecture & Connections

Air serves as the background services hub in the Land ecosystem:

  • Wind (Effect-TS): Provides functional programming patterns and type-safe effects that Air uses for predictable state management and error handling

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

  • Mountain (Tauri bundler): The main desktop application bundle that packages the Rust backend with the Electron/Node.js frontend. Mountain receives work from Air through Vine (gRPC) and orchestrates the bundling process.

  • Vine (gRPC protocol): The communication layer connecting all components. Air hosts the Vine gRPC server on port 50053, receiving requests from Mountain and responding with results from background operations.

§VSCode Architecture References

Air’s architecture draws inspiration from VSCode’s background service model:

  • Update Service: Reference Microsoft/Dependency/Editor/src/vs/platform/update

    • AbstractUpdateService: Base class for platform-specific update handling
    • UpdateService: Manages update checks, downloads, and installations
    • Similar to Air’s UpdateManager component

  • Lifecycle Management: Reference Microsoft/Dependency/Editor/src/vs/base/common/lifecycle

    • Disposable pattern for resource cleanup
    • Event emission and handling
    • Graceful shutdown coordination similar to Air’s shutdown logic

  • Background Services: VSCode’s extension host and language server model

    • Independent processes with IPC communication
    • Health monitoring and automatic restart
    • Similar to Air’s daemon management approach

§Core Responsibilities

§1. gRPC Server (Vine Protocol)

  • Hosts the Vine gRPC server on port 50053
  • Receives work requests from Mountain
  • Streams results and progress updates
  • Manages connection lifecycle and cleanup
  • Handles multiple concurrent connections

§2. Authentication Service

  • Manages user authentication tokens
  • Handles cryptographic operations (signing, encryption)
  • Token refresh and validation
  • Secure storage management

§3. Update Management

  • Checks for application updates
  • Downloads update packages
  • Verifies checksums and signatures
  • Coordinates update installation with Mountain

§4. Download Manager

  • Downloads extensions and dependencies
  • Resumable downloads with retry logic
  • Bandwidth management and throttling
  • Progress tracking and reporting

§5. File Indexing

  • Background file system scanning
  • Maintains searchable index
  • Supports code navigation features
  • Incremental updates and change detection

§6. Resource Monitoring

  • CPU and memory usage tracking
  • Connection pool management
  • Background task lifecycle
  • Performance metrics collection

§Protocol Details

Vine Protocol (gRPC)

  • Version: 1
  • Port: 50053 (Air), 50052 (Cocoon)
  • Transport: HTTP/2 with TLS (optional)
  • Serialization: Protocol Buffers

§Protocol Messages

  • DownloadRequest: Request to download a file/extension
  • DownloadResponse: Progress updates and completion
  • AuthRequest: Authentication/token operations
  • AuthResponse: Token data and status
  • UpdateRequest: Update check and download
  • UpdateResponse: Update availability and progress
  • IndexRequest: File indexing operations
  • IndexResponse: Index status and results
  • HealthRequest: Health check queries
  • HealthResponse: Service health and metrics

§TODO: Missing Functionality

§High Priority

  • Complete CLI command implementations (all placeholders)
  • Add TLS/mTLS support for gRPC connections
  • Implement connection authentication/authorization
  • Add metrics endpoint (/metrics) HTTP server
  • Implement proper configuration hot-reload
  • Add comprehensive integration tests

§Medium Priority

  • Add prometheus metrics export (currently partial)
  • Implement grace period for shutdown (pending operations)
  • Add connection rate limiting
  • Implement request prioritization
  • Add audit logging for sensitive operations
  • Implement plugin/hot-reload system

§Low Priority

  • Add structured logging with correlation IDs
  • Implement distributed tracing integration
  • Add health check endpoint for load balancers
  • Implement connection pooling optimizations
  • Add telemetry/observability export
  • Implement A/B testing for features

§Error Handling Strategy

All public functions use defensive coding:

  • Input validation with descriptive errors
  • Timeout handling with cancellation
  • Resource cleanup via Drop and explicit cleanup
  • Circuit breaker for external dependencies
  • Retry logic with exponential backoff
  • Metrics recording for all operations

§Shutdown Sequence

  1. Accept shutdown signal (SIGTERM, SIGINT)
  2. Stop accepting new requests
  3. Wait for in-flight requests (with timeout)
  4. Stop background services
  5. Cancel pending background tasks
  6. Release daemon lock
  7. Log final statistics
  8. Exit cleanly

§Port Allocation

  • 50052: Cocoon (NodeJS host) - Frontend/web services
  • 50053: Air (this daemon) - Background services
  • 50054: Reserved for future use (e.g., SideCar service)
  • 50055: Reserved for future metrics endpoints

Macros§

Trace 🔒
Logs a checkpoint message at debug level with context tracking

Functions§

HandleCommand 🔒
Handle CLI commands with comprehensive implementation
HandleMetricsRequest 🔒
Handler for /metrics endpoint - returns Prometheus format metrics
InitializeLogging 🔒
Initialize logging based on environment variables
Main 🔒
The main asynchronous function that sets up and runs the Air daemon
ParseArguments 🔒
Parse command line arguments into daemon config or CLI command
WaitForShutdownSignal 🔒
Shutdown signal handler for graceful termination
attempt_daemon_connection 🔒
Attempt to connect to the running daemon
main 🔒
validate_command 🔒
Validate command parameters to prevent invalid inputs
validate_configuration 🔒
Validate critical configuration values
validate_environment 🔒
Validate the runtime environment before starting the daemon