Module DebugProvider

Mountain::Environment

Module DebugProvider 

Source
Expand description

§DebugProvider (Environment)

RESPONSIBILITIES:

  • Implements DebugService for MountainEnvironment
  • Manages complete debugging session lifecycle from configuration to termination
  • Orchestrates between extension host (Cocoon), debug adapter, and UI
  • Handles DAP (Debug Adapter Protocol) message mediation

ARCHITECTURAL ROLE:

  • Core provider for debugging functionality, analogous to VSCode’s debug service
  • Uses two-stage registration: configuration providers and adapter descriptor factories
  • Each debug type (node, java, rust) can have its own configuration and adapter
  • Integrates with IPCProvider for RPC to Cocoon

DEBUG SESSION FLOW:

  1. UI calls StartDebugging with folder URI and configuration
  2. Mountain RPCs to Cocoon to resolve debug configuration (variable substitution)
  3. Mountain RPCs to Cocoon to create debug adapter descriptor
  4. Mountain spawns debug adapter process or connects to TCP server
  5. Mountain mediates DAP messages between UI and debug adapter
  6. UI sends DAP commands via SendCommand which forwards to adapter
  7. Debug adapter sends DAP events/notifications back through Mountain to UI
  8. Session ends on stop request or adapter process exit

ERROR HANDLING:

  • Uses CommonError for all operations
  • Validates debug type is non-empty (InvalidArgument error)
  • TODO: Implement proper session lookup, timeout handling, and error recovery

PERFORMANCE:

  • Debug adapter spawning should be async with timeout protection (5000ms in current RPC)
  • DAP message routing needs efficient session lookup (TODO: O(1) hash map)
  • Multiple simultaneous debug sessions require careful resource management

VS CODE REFERENCE:

  • vs/workbench/contrib/debug/browser/debugService.ts - debug service main logic
  • vs/workbench/contrib/debug/common/debug.ts - debug interfaces and models
  • vs/workbench/contrib/debug/browser/adapter/descriptorFactory.ts - adapter descriptor factories
  • vs/debugAdapter/common/debugProtocol.ts - DAP protocol specification

TODO:

  • Store debug adapter registrations in ApplicationState
  • Implement proper debug session tracking and management
  • Add debug adapter process spawning and lifecycle management
  • Implement proper DAP message routing and serialization
  • Add debug session state persistence across UI reloads
  • Implement debug console and variable inspection integration
  • Add support for multiple simultaneous debug sessions
  • Implement debug adapter termination and cleanup
  • Add debug session metrics and telemetry
  • Consider implementing debug configuration validation
  • Add support for debug adapters that communicate via TCP sockets
  • Implement debug adapter crash detection and recovery

MODULE CONTENTS:

  • DebugService implementation:
  • RegisterDebugConfigurationProvider - register config resolver
  • RegisterDebugAdapterDescriptorFactory - register adapter factory
  • StartDebugging - start debug session (partial)
  • SendCommand - send DAP command to adapter (stub)