[Feature] DebugAdapterInlineImplementation

[okwasniewski]

Problem Statement

Hey,

I want to write a nvim-dap adapter in Lua that communicates with a WebSocket server and reports events back to nvim-dap.

Namely, an adapter for the React Native Debugger (https://github.com/facebook/react-native/tree/main/packages/dev-middleware), here is an implementation for VSCode: https://github.com/software-mansion/radon-ide/blob/main/packages/vscode-extension/src/debugging/DebugAdapter.ts

Possible Solutions

Quoting vscode issue (https://github.com/microsoft/vscode/issues/85544)

Currently we have extension API to run a debug adapter session:

as an external process:

vscode.debug.registerDebugAdapterDescriptorFactory('mock', {
  createDebugAdapterDescriptor: (_session) => {
    return new vscode.DebugAdapterExecutable('mockDebug.exe');
  }
});

as a network session:

vscode.debug.registerDebugAdapterDescriptorFactory('mock', {
  createDebugAdapterDescriptor: (_session) => {
    return new vscode.DebugAdapterServer(12345, 'localhost');
  }
});

With this API request we want to add a third option where an 'inline' implementation can be provided:

vscode.debug.registerDebugAdapterDescriptorFactory('mock', {
  createDebugAdapterDescriptor: (_session) => {
    return new vscode.DebugAdapterImplementation(new MockDebugSession());
  }
});

VSCode docs: https://vscode-api.js.org/classes/vscode.DebugAdapterInlineImplementation.html

Considered Alternatives

Implementing it without the DebugAdapterInlineImplementation

AdapterFactory passes in the Dap.Session:

---@alias Dap.AdapterFactory fun(callback: fun(adapter: dap.Adapter), config: dap.Configuration, parent?: dap.Session)

This could be a potential solution but I couldn't get this to work. But the parent parameter was nil for me. And Im not sure if this is the best approach

Thanks in advance for suggestions on how to implement this.

[mfussenegger]

You'd have to implement an adapter that either talks via tcp or pipe. The test suite actually contains a stub adapter implementation: https://github.com/mfussenegger/nvim-dap/blob/master/spec/server.lua

Example usages are here:

https://github.com/mfussenegger/nvim-dap/blob/master/spec/integration_spec.lua

So the client adapter configuration would end up looking like either:

local adapter = {
  type = "server",
  host = "127.0.0.1",
  port = 1234,
  options = {
    disconnect_timeout_sec = 0.1
  }
}

Or a variant with type = "pipe".

---

That said, if you implement it in Lua I'd actually recommend not depending on any nvim/nvim-dap functionality and make sure that it is a standalone application to make it usable for other editors too. Users should ideally be able to use the executable/stdio client-adapter configuration. There are various SDKs available to help creating debug adapters.

[okwasniewski]

@mfussenegger Thank you for the hint! I guess making the DAP adapter reusable is a better idea.

Closing this 🙏