Consider adopting the proposed Port Attributes API

[alexr00]

Original post: microsoft/vscode#115616 (comment)

In a remote environment (Codespaces, Dev Containers, etc.) VS Code will automatically detect and forward ports that it finds processes listening on so that users can access the remote application they're developing from their local machine. This includes debugees, such as a Python program that the user is debugging.

The auto port forwarding can't distinguish between a useful port to forward (ex. the app that you're debugging) and a useless port (ex. the port that the debugger itself uses for communication). This results in noisy extra ports being forwarded. We've seeing this in other extensions, such as the JS Debug extension.

The proposed solution for this is to allow extension to provide port attributes for ports that they know about. The JS Debug extension has done this for the debug ports it uses: https://github.com/microsoft/vscode-js-debug/blob/0d0704da3726653e2d806be528b8ab51fa952cf0/src/ui/portAttributesProvider.ts#L39-L55

We're working on finalizing the port attributes API, so I don't expect too many more changes. In support of finalizing the API, and to remove the port-clutter that comes from forwarding Python extension debug ports, it would be great if the Python extension adopted the proposed port attributes API.

[alexr00]

Python folks, if you want I can specifically assign a Python extension dev to my port attributes test plan item for endgame next week.

[karthiknadig]

Here are few scenarios we are creating ports, and where I think forwarding will be required and where it is not.

Debugger scenarios

I had a discussion with debugpy team, the underlying debugger where we were planning on using this API. The debugger itself communicates with subprocess that it starts over ports, but those don't need to forward. Those are ephemeral and can be ignored for this case.

Cases to consider:

1. debugpy listen mode: In this mode VS Code launches the Debug Adapter with the intent that the Debug adapter will listen for connections from the debugger. This is a scenario where the debugger is installed independently of VS Code or Python extension, say like in a container that the user wants to debug. The client that launched debug adapter will have a port provided by the user that it opens in a listening mode, and the debugger in the container connects to the debugger as an outgoing connection from the container.

2. debugpy connect mode: In this mode VS Code directly connects to debugpy which is running in server mode. This is another case where typically it is a container or a remoter server that is running debugpy in it and may not contain VS Code server in it.

I don't think the above two cases are where the API will be used.

Web app scenarios

These are cases that involve running some web app framework, like django, fastapi, flask etc. There are two possibilities here:

1. Run without debugging/run in terminal case: This is where the web app is run either without debugger or is being run in terminal directly by user or run in terminal using a command. If we can detect the port that is opened by the web app framework then we could provide the right attributes for it to be forwarded.

2. Debugging a web app launched with server ready: Server ready is a VS Code launch json configuration that automatically detects web server string in the terminal using patterns provided by the user. This is often used to trigger browser launch after the server has started. This seems like a case where, VS Code itself should be able to detect and forward the port without requiring input from extension?

3. Debugging a web app launched without out server ready: This is another case where we will have to monitor the content being sent to the terminal, but a key difference here is that debugger can capture stdout and redirect it as a DAP message. So extension can use DAP tracker API from VS Code to monitor and provide port attributes.

Data Science

1. Tensor Board: I think tensor board uses ports in some form so this API could be used there to provide the right attributes.

[alexr00]

The debugger scenarios sound reasonable to me.

For the web app scenarios:

1. Run without debugging/run in terminal case: This is where the web app is run either without debugger or is being run in terminal directly by user or run in terminal using a command. If we can detect the port that is opened by the web app framework then we could provide the right attributes for it to be forwarded.

VS Code will automatically forward this anyway. VS Code detects ports in two possible ways based on what settings the user has: watching the proc filesystem and/or watching terminal/debug output. It sounds like this is also desirable behavior.

2. Debugging a web app launched with server ready: Server ready is a VS Code launch json configuration that automatically detects web server string in the terminal using patterns provided by the user. This is often used to trigger browser launch after the server has started. This seems like a case where, VS Code itself should be able to detect and forward the port without requiring input from extension?

Yes, the port will be automatically forwarded.

3. Debugging a web app launched without out server ready: This is another case where we will have to monitor the content being sent to the terminal, but a key difference here is that debugger can capture stdout and redirect it as a DAP message. So extension can use DAP tracker API from VS Code to monitor and provide port attributes.

If you want to have the port forwarded in this case then you shouldn't have to do anything.

[alexr00]

@paulacamargo25 I'm ready to finalize the port attributes API. I'd love to get feedback from you or someone else on the Python team before I do so. Is adopting this API work that is planned for September?