Introduce a debugSessionEnds event

[weinand]

Currently it is easy to track newly created debug sessions in an extension but it is not possible to track when a session ends.

things to consider:

• we need a session ID for this because VS Code supports concurrent sessions
• we should not only solve the "debugSessionEnds" problem but broaden the solution for all kind of debug session related events (e.g. loadedScript events from the DA).
• probably related: Extension API - How to determine debug state #10077

[isidorn]

The idea here is that vscode extensions can listen on this event? Should this then be part of the vscode api? I feel this makes sense but what is the use case?

Instead of using a session ID we can just use the name of the launch config, since we use that as a sort of an ID.
Currently we have support for commands depending on this with the debugState context key.

[isidorn]

To conform with our current API we could go with something like the following.
I guess we should think if we want to surface additional stuff which makes sense for the initial debug namespace.
A very first step proposal:

export namespace debug {

  export const onDidEndDebugSession<DebugSessionData>;
  export const onDidChangeDebugState<string>;

}

[weinand]

Instead of "DebugSessionData" we need a type (interface) DebugSession (and we would promote the current "workbench.customDebugRequest" command to become a first class method customRequest on it).

Since VS Code supports concurrent debug sessions, I don't think that "debug state" changes make a lot of sense without debug sessions. So the DebugSessionStateChangeEvent combines a "DebugSession" with details about the state change.

So my proposal:

export namespace debug {
  export const onDidEndDebugSession: Event<DebugSession>;
  export const onDidChangeDebugState: Event<DebugSessionStateChangeEvent>;
}

export interface DebugSession {
   readonly name: string;
   customRequest(requestName: string, args: any): Thenable<DebugRequestResult>;
}

export interface DebugSessionStateChangeEvent {
  debugSession: DebugSession;
  newState: string;
}

[isidorn]

Currently on the vscode implementation side just a newState being a string makes sense since everything is a slave to the focused session. Though I agree that the API is nicer without this implicit knowledge.

DebugRequestResult in this case is just empty, or should we also sketch it up?

We can always start minimal as you already proposed.

I will sync up with Joh on monday to get his thoughts on this.

[weinand]

Relying on an implicit "focused debug session" is neither robust nor easy to use. Extension code would have to figure out what the "focused debug session" is in order to know where the state change has happened. Due to race conditions there is no guarantee that the "focused debug session" is still the one for which the state change event was delivered. So it is better to keep them together.

BTW, we probably need an activeDebugSession variable on the debug namespace.

[weinand]

We will now continue the discussion about the general debug API in #28500.
This feature request is only for the debugSessionEnds event.

[brendandburns]

Regarding the use case. I'm writing an extension (vs-kubernetes) which does some debugger setup work (setups port-forwarding) and then makes a call to an existing debugger (e.g. the nodejs debugger).

The nodejs debugger (which I didn't write) spins up and debugs my app.

But, when the user terminates the debugger, I want to tear down the port forwarding, but I don't have an event I can listen to, to trigger this tear down.

I know that I could write my own debugger that wraps the node debugger and get this interface, but that really shouldn't be necesary (and is a support burden since I want to support so many different langauges...)

[weinand]

@brendandburns Is it correct that you call into an existing debugger by using the vscode.startDebug command (similar to what node-debug is using here: https://github.com/Microsoft/vscode-node-debug/blob/master/src/node/extension/extension.ts#L393)?

If we give you a onDidTerminateDebugSession event, you will have to somehow map this event to your session so that you can tear down the correct port forwarding.

Our current thinking is that the onDidTerminateDebugSession event has the debug session object which has a name and a type (both from the corresponding values from the launch config). By using those two attributes you could find the port forwarding that you need to tear down.

Alternatively you can replace the vscode.startDebug command that you might be using by debug.createDebugSession(...) that returns the debug session and you could remember that and compare it later with the debug session received as part of the onDidTerminateDebugSession event.

[weinand]

BTW, for May I've explored something that looks similar to the issue you are trying to solve: #26205

[weinand]

@brendandburns I've added proposed API for tracking termination of debug sessions. You can find the API here: https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.proposed.d.ts#L472
Tomorrows insiders build should have the new API.

See my comment from above for the two possible approaches to use the API.

In order to use proposed API, you must opt into it by adding a "enableProposedApi": true, to the package.json of your extension. And you'll have to copy the "vscode.proposed.d.ts" from VS Code into your extension project.

/cc @chrisdias