Debugger: support remote debugging by mapping local paths to server paths

This feature is VS Code specific

• VS Code specific

Use case

The goal is to be able to debug a Ruby process that is run on a different machine than the current one.

Description

To do that, there must be a mechanism to translate server paths to local paths.

1. Set up socket forwarding: ssh -L /tmp/ruby-lsp-debug-sockets/ruby-debug-worldmodern-0.sock:/tmp/ruby.sock user@server
2. Start Ruby on the remote server: bundle exec rdbg --open --command --sock-path=/tmp/ruby.sock -- puma
3. Attach a debugger (request=attach) as if it's a local server.

This works. However, no breakpoint will trip because breakpoints are set as /home/nowaker/projects/worldmodern/app/controllers/whatever_controller.rb:123 but the server sees it as /var/www/worldmodern/app/controllers/whatever_controller.rb:123.

We need a way to define path mappings, similar to how other VS Code debuggers support it (see PHP):

    {
      "name": "Rails (attach)",
      "type": "ruby_lsp",
      "request": "attach",
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/var/www/worldmodern"
        },
        {
          "localRoot": "${env:GEM_HOME}",
          "remoteRoot": "/home/ec2-user/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0"
        }
      ]
    },

Mappings for project directory and gem directory are a must-have to make it work.

NOTE: Debugging as such works. Nothing needs fixing here. I can pause (F6) and I'll see wherever Puma was processing a request. I can them step over, continue, etc no problem.

It's just the path mapping that needs to be provided to visually set up breakpoints locally, and make them trip on the server.

Implementation

• https://github.com/xdebug/vscode-php-debug/blob/3025d1f01b5b7725e7c1c213d63f3de45f0534b3/src/phpDebug.ts#L855
• https://github.com/xdebug/vscode-php-debug/blob/3025d1f01b5b7725e7c1c213d63f3de45f0534b3/src/paths.ts#L7

Start by reviewing the linked vscode-php-debug examples in src/phpDebug.ts and src/paths.ts, then trace the Ruby LSP debugger attach and breakpoint path handling. Define how localRoot and remoteRoot mappings should be configured for project and gem directories, and verify that local breakpoints are translated to server paths and trip during remote debugging.