Skip to main content

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

IMPLEMENTED:

  • Provider/factory registrations stored in ApplicationState (DebugState)
  • Active session tracking via DebugState::DebugSessions map
  • Executable adapter spawning with stdin/stdout/stderr pipes
  • DAP frame parsing (Content-Length header + JSON body) on adapter stdout
  • Stdout messages emitted on sky://debug/dap-message for renderer pickup
  • SendCommand serialises DAP request → writes framed bytes to stdin
  • StopDebugging sends DAP disconnect request then unregisters session

FOLLOWUP:

  • server / pipeServer adapter connection (TCP / named-pipe)
  • Reverse-RPC $sendDAPRequest Cocoon handler for inline-impl adapters
  • Per-session request_seq allocation (currently caller-supplied)
  • Adapter crash detection: when stdout EOFs unexpectedly, emit $onDidTerminateDebugSession so the workbench tears down its session view (today the user sees a stale session row)
  • Debug console / variable inspection integration
  • Telemetry for adapter spawn duration, session length, exit codes

MODULE CONTENTS:

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