Vscode: Support Named Pipe & Unix Domain Sockets as debug adapter entry point

[TylerLeonhardt]

@weinand asked me to open this here.

With the vscode API there is a type called DebugAdapterDescriptorFactory - there is even a dynamic registry for it.

AFAIK, this is good for:

• starting up a _new_ process for the debug adapter
• connecting to an existing adapter over a TCP port

In the PowerShell Debug Adapter, we use a named pipe/unix domain socket to talk to vscode via LSP and DAP so unfortunately, we have to maintain a stdio bridge that bridges stdio to our named pipe.

Can we allow DebugAdapterDescriptorFactory to accept a net.Socket or similar as the stream used to send messages to/from the server?

Or allow DebugAdapterServer to take in a pipe name/path?

That's basically what we're using in the bridge.

net.Socket would support both named pipes and TCP sockets all in one.

Just for context, we chose a named pipe/unix domain socket because:

• We couldn't go the stdio route because PowerShell Editor Services is both a language server and a debug adapter that share state.
• It's _much_ easier to secure a glorified file (aka named pipe) than a TCP socket. ACL the file and you're done. (Makes me think if there are language servers out there that are exposing insecure TCP sockets...)

[TylerLeonhardt]

would love to see Named Pipe & Unix Domain Sockets the (2nd) preferred LSP communication protocol over TCP which is very tricky to lock down.

[weinand]

You should be able to implement this yourself with the (fairly) new DebugAdapter and the DebugAdapterInlineImplementation.

[TylerLeonhardt]

@weinand thanks! There's one piece that's missing... I need a utility to turn vscode.DebugProtocolMessage into the message format that the DAP expects... and the reverse (takes a raw buffer and parses it into a vscode.DebugProtocolMessage.

VS Code must be doing this because my current solution simply routes messages from stdio into the named pipe... the question is if there's an API available to do this conversion already.

[weinand]

@TylerLeonhardt you can find the code that sends and receives vscode.DebugProtocolMessage over the wire here as part of the StreamDebugAdapter. The DebugProtocol.ProtocolMessage is the internal type that corresponds the public API vscode.DebugProtocolMessage.

The code implements what is specified under "Base protocol" in the official DAP spec.

[TylerLeonhardt]

It's funny because a public version of StreamDebugAdapter was kinda the original ask here.

Anyway, I've taken the code from that type and have a functioning NamedPipeDebugAdapter. I still would love to see this implemented in-product and encouraged over TCP... otherwise they will suffer the same fate as us...
https://portal.msrc.microsoft.com/en-US/security-guidance/advisory/CVE-2018-8327

[weinand]

Yes, there is no public version of a StreamDebugAdapter because the only use case for that is probably the NamedPipeDebugAdapter ;-)
But you are invited to submit a PR for a built-in NamedPipeDebugAdapter either as a new class similar to the DebugAdapterServer or as another constructor for the DebugAdapterServer.

[weinand]

I've added the api-proposal label and @TylerLeonhardt will represent this in the API sync call.

@TylerLeonhardt could you please create another PR for Mock Debug that shows how to use the DebugAdapterNamedPipeServer. You'll need to add a new selector namedPipeServer here: https://github.com/microsoft/vscode-mock-debug/blob/dc3ccfeb2195a1d2e5876f40fc9436b3b6f58a40/src/extension.ts#L16

and add another case Here: https://github.com/microsoft/vscode-mock-debug/blob/dc3ccfeb2195a1d2e5876f40fc9436b3b6f58a40/src/extension.ts#L83-L98

and a namedPipe variant of https://github.com/microsoft/vscode-mock-debug/blob/dc3ccfeb2195a1d2e5876f40fc9436b3b6f58a40/src/extension.ts#L177-L201.

[TylerLeonhardt]

PR for vscode-mock-debug: https://github.com/microsoft/vscode-mock-debug/pull/46

[weinand]

@TylerLeonhardt was this API addition discussed in the API sync call?
If yes, what was the outcome?

[TylerLeonhardt]

It's funny, I emailed @connor4312 this morning asking if the Sync call happened/if I could be added to the meeting to see this feature through :)

[connor4312]

I'll forward you the invite for next week. I didn't think there would be one last week due to the hackathon, but there was and unfortunately I didn't discover that until the morning of.

[weinand]

Ok, I will move this issue and the corresponding PR to August...

[weinand]

I've released the PR.

Please note: the API request is still proposed but since the API cannot live in vscode.proposed.d.ts the API is already in vscode.d.ts (see new class DebugAdapterNamedPipeServer and modified OR-type)

This API is now ready for finalisation on August 25.

[weinand]

The API is now ready for finalisation.

Here is the new descriptor class for named pipe based DAs:

https://github.com/microsoft/vscode/blob/b0f0a1bf81b876e8f400b29fa88aa5e3413d67cd/src/vs/vscode.d.ts#L10903-L10916

And here the extended descriptor OR type:

https://github.com/microsoft/vscode/blob/b0f0a1bf81b876e8f400b29fa88aa5e3413d67cd/src/vs/vscode.d.ts#L10955-L10957

[weinand]

This API has been finalised.

@TylerLeonhardt could you please plan for writing a test plan item and the release notes text.