Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Test Ports Attributes API #183547

Closed
2 tasks done
alexr00 opened this issue May 26, 2023 · 3 comments
Closed
2 tasks done

Test Ports Attributes API #183547

alexr00 opened this issue May 26, 2023 · 3 comments

Comments

@alexr00
Copy link
Member

alexr00 commented May 26, 2023

Refs: #115616

Complexity: 5

Create Issue


Background

We are getting ready to finalize the ports attributes API. This API was added to allow extension that run processes to provide an "action" to take when VS Code notices their port for auto forwarding.

Here's are a few examples of how a ports attributes provider could work:

  1. Opening the preview browser
    When connected to a remote, the extension starts a process at localhost:3000 (on the remote). When this process starts, the extension wants to open the preview browser to https://localhost:3000. This extension could use a ports attributes provider to cause the preview browser to open ever time port 3000 is auto forwarded.

  2. Extension internals
    The extension always starts a server that listens on a random port between 5050 and 5100, which is used only for internal extension communication. When running locally, the user never knows about the server (unless they're watching their task manager or other list of running processes). When running in a remote, this port always gets auto forwarded, which not only forwards the port so it shows in the Ports view, but also disrupts the user with a notification. This extension could use a ports attributes provider to cause it's ports to be ignored entirely from auto forwarding.

Pointers

I tried to assign testers who work on extensions that could benefit from having a ports attributes provider. If you have any questions, please let me know!

You'll need to register a provider:

/**
* If your extension listens on ports, consider registering a PortAttributesProvider to provide information
* about the ports. For example, a debug extension may know about debug ports in it's debuggee. By providing
* this information with a PortAttributesProvider the extension can tell the editor that these ports should be
* ignored, since they don't need to be user facing.
*
* The results of the PortAttributesProvider are merged with the user setting `remote.portsAttributes`. If the values conflict, the user setting takes precedence.
*
* @param portSelector It is best practice to specify a port selector to avoid unnecessary calls to your provider.
* If you don't specify a port selector your provider will be called for every port, which will result in slower port forwarding for the user.
* @param provider The {@link PortAttributesProvider PortAttributesProvider}.
*/
export function registerPortAttributesProvider(portSelector: PortAttributesSelector, provider: PortAttributesProvider): Disposable;

And specify a selector in the provider:

/**
* A selector that will be used to filter which {@link PortAttributesProvider} should be called for each port.
*/
export interface PortAttributesSelector {
/**
* Specifying a port range will cause your provider to only be called for ports within the range.
*/
portRange?: [number, number];
/**
* Specifying a command pattern will cause your provider to only be called for processes whose command line matches the pattern.
*/
commandPattern?: RegExp;
}

Things to verify

After you have implemented your provider, run your extension when connected to a remote. On the remote, run a process that listens on a port and verify the following:

  • Verify that your provider only gets called for ports that match your selector.
  • Verify that the action you provide is respected. Try some other actions and verify that they all work as expected.
  • Set the remote.portsAttributes setting with a value that conflicts with what your provider returns. Verify that the setting wins.
  • Verify that the JS doc comments make sense.
  • If you can't use a selector, please comment with why.
@TylerLeonhardt
Copy link
Member

Had some issues trying to test this in Codespaces so I really didn't get started. Feel free to steal from me or I'll do it first thing tomorrow morning.

@alexr00
Copy link
Member Author

alexr00 commented May 31, 2023

@TylerLeonhardt thanks for trying to test this! Given that this is proposed API and I think @paulacamargo25 will be testing the API anyway for the Python extension at some point in the next couple weeks, I'm ok with you leaving this for @paulacamargo25 for later. If you do want to test it then that is also great!

@paulacamargo25
Copy link
Contributor

I will test the issue today, thanks @TylerLeonhardt for trying. :)

@github-actions github-actions bot locked and limited conversation to collaborators Jul 16, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants