debugpy reverse connectivity support

[int19h]

We're making the existing reverse-connection support (when the debugged process connects to the IDE, rather than the other way around - microsoft/ptvsd#1824) officially supported in debugpy to simplify some user scenarios. In ptvsd, it's only used internally for attach-to-PID.

This means that we need to surface it on the IDE side of things - at the mininum, launch.json, and any associated UX. We need to figure out what exactly it should look like, and make the necessary changes on the extension side.

[int19h]

launch.json proposal

Currently, a configuration like this is used for attach:

{
  "request": "attach",
  "host": "127.0.0.1",
  "port": 5678,
}

The direction of the connection in this case is from the IDE to the debug server. Now, we're going to need a way to indicate that the direction is reversed - that the IDE (or rather, the debug adapter) should wait for an incoming connection from the debug server. Furthermore, we want the users to be explicit when choosing the direction - a bad default here can send them down to the path of most resistance to solve their problem.

On the server side, we use --listen and --connect in the CLI, and debugpy.listen() and debugpy.connect() in the API, to indicate the direction of the connection, with connection information passed as an argument. The proposal is to apply the same pattern in JSON thus:

// IDE -> server; same as above
{
  "request": "attach",
  "connect":  {
    "host": "127.0.0.1",
    "port": 5678,
  }
}

// server -> IDE
{
  "request": "attach",
  "listen":  {
    "host": "127.0.0.1",
    "port": 5678,
  }
}

Thus, in any remote attach scenario, it's always "listen" on one end, and "connect" on the other. The objects that have host/port info can have other properties added to them in the future that pertain specifically to connectivity - e.g. if we do implicit SSH port tunneling, this would be where the related settings go.

For backwards compatibility, we should continue to support top-level "host" and "port", and treat them as if they were "connect". However, we should encourage users to update, e.g. by not reflecting that legacy support in launch.json schema.

[int19h]

@luabud, do we need anything else for this, other than launch.json schema changes (which are already done)?

[luabud]

@int19h I think we will want to change our default Remote attach configuration to use it (and perhaps create an issue to remove "host" and "port" from the top-level in the launch.json schema if that wasn't part of the updates?). But I believe these can be tracked as separate items if you think that would make sense 😊

[int19h]

@luabud The debugger still supports top-level "host" and "port" for backwards compatibility. If we remove them from the schema, existing configs will get squiggles (even though they still work). So we probably shouldn't remove those, unless we also add a way to automatically warn about & fix those configs, similar to "pythonPath" treatment.

I suggest that we only change the launch.json templates for now, but keep "host" and "port", to minimize disruption for the users. Then remove it from the schema in the next release, when people are already aware of the new syntax.

[karthiknadig]

This is done right?

[int19h]

Yep.

[chitalian]

Thanks for adding this feature! Is there a way to add a timeout on the listen? Right now its about 5 seconds from what I can tell

[chitalian]

Another cool feature would be able to run a task while listening.

[int19h]

@chitalian There's no way to specify a timeout, and we don't actually implement any timeout logic currently... so if it stops debugging after 5s, I suspect it might be VSCode itself.

For the feature request, can you please file it as a separate issue, and describe it in a bit more detail?