Repository navigation
Consider adopting the proposed Port Attributes API #21292
Description
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.
Activity
alexr00 commentedon May 24, 2023
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 commentedon Jun 6, 2023
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
debugpyteam, 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:
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.
debugpy connect mode: In this mode VS Code directly connects to
debugpywhich is running in server mode. This is another case where typically it is a container or a remoter server that is runningdebugpyin 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,flasketc. There are two possibilities here: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.
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?
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
alexr00 commentedon Jun 7, 2023
The debugger scenarios sound reasonable to me.
For the web app scenarios:
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.
Yes, the port will be automatically forwarded.
If you want to have the port forwarded in this case then you shouldn't have to do anything.
alexr00 commentedon Aug 16, 2023
Paula (@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?
karthiknadig commentedon Aug 16, 2023
Alex Ross (@alexr00) This is planned for September Milestone.
Adding debugger owners to provide any input they have. Pavel Minaev (@int19h) Adam Yoblick (@AdamYoblick)
int19h commentedon Aug 16, 2023
Alex Ross (@alexr00) I had a look, and my main concern is the inherent asynchrony between the debugger processes and VSCode. For internal ports, to avoid clashing with anything else, the debugger typically does
listen(0)to let the OS allocate an ephemeral port - so it doesn't actually know the port number until it starts listening. On the other hand, it needs to communicate that port number back to the Python extension for the latter to be able to respond toprovidePortAttributescorrectly. We can communicate it using a custom DAP message or through some other mechanism, but the problem is that, so far as I can tell, there's no guarantee thatprovidePortAttributescall is scheduled after that custom message has been parsed. I would expect similar issues with any out-of-proc DAP implementation that uses sockets internally to communicate between its own components.alexr00 commentedon Aug 17, 2023
Pavel Minaev (@int19h) thank you for looking at the API and providing feedback! You are correct that there's no guarantee that
providePortAttributeswill happen after your custom message. However, this will likely not be an issue because VS Code will not be very quick to callprovidePortAttributes:providePortAttributeswill always be a round trip cross-process, and depending on where the extension is running it could add round trip network latency again, so that will also add delay. This last one is why we have theportSelector, so that we can prevent this round trip for every port attribute providing extension.Given these inherent delays, which can easily be > 1 second, and will almost always be hundreds of milliseconds, I don't think we should let perfect be the enemy of better here.