feat: add 'cascadeTerminateToConfigurations' for better self-host tea…

…rdown

See microsoft/vscode#100368

OPTIONS.md

@@ -5,7 +5,8 @@
 <details><h4>address</h4><p>TCP/IP address of process to be debugged. Default is &#39;localhost&#39;.</p>
 <h5>Default value:</h4><pre><code>"localhost"</pre></code><h4>attachExistingChildren</h4><p>Whether to attempt to attach to already-spawned child processes.</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>autoAttachChildProcesses</h4><p>Attach debugger to new child processes automatically.</p>
-<h5>Default value:</h4><pre><code>true</pre></code><h4>continueOnAttach</h4><p>If true, we&#39;ll automatically resume programs launched and waiting on <code>--inspect-brk</code></p>
+<h5>Default value:</h4><pre><code>true</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>continueOnAttach</h4><p>If true, we&#39;ll automatically resume programs launched and waiting on <code>--inspect-brk</code></p>
 <h5>Default value:</h4><pre><code>false</pre></code><h4>cwd</h4><p>Absolute path to the working directory of the program being debugged.</p>
 <h5>Default value:</h4><pre><code>"${workspaceFolder}"</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>env</h4><p>Environment variables passed to the program. The value <code>null</code> removes the variable from the environment.</p>
@@ -46,7 +47,8 @@
 <details><h4>args</h4><p>Command line arguments passed to the program.</p>
 <h5>Default value:</h4><pre><code>[]</pre></code><h4>attachSimplePort</h4><p>If set, attaches to the process via the given port. This is generally no longer necessary for Node.js programs and loses the ability to debug child processes, but can be useful in more esoteric scenarios such as with Deno and Docker launches. If set to 0, a random port will be chosen and --inspect-brk added to the launch arguments automatically.</p>
 <h5>Default value:</h4><pre><code>null</pre></code><h4>autoAttachChildProcesses</h4><p>Attach debugger to new child processes automatically.</p>
-<h5>Default value:</h4><pre><code>true</pre></code><h4>console</h4><p>Where to launch the debug target.</p>
+<h5>Default value:</h4><pre><code>true</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>console</h4><p>Where to launch the debug target.</p>
 <h5>Default value:</h4><pre><code>"internalConsole"</pre></code><h4>cwd</h4><p>Absolute path to the working directory of the program being debugged.</p>
 <h5>Default value:</h4><pre><code>"${workspaceFolder}"</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>env</h4><p>Environment variables passed to the program. The value <code>null</code> removes the variable from the environment.</p>
@@ -89,7 +91,8 @@
 ### node-terminal: launch
 
 <details><h4>autoAttachChildProcesses</h4><p>Attach debugger to new child processes automatically.</p>
-<h5>Default value:</h4><pre><code>true</pre></code><h4>command</h4><p>Command to run in the launched terminal. If not provided, the terminal will open without launching a program.</p>
+<h5>Default value:</h4><pre><code>true</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>command</h4><p>Command to run in the launched terminal. If not provided, the terminal will open without launching a program.</p>
 <h5>Default value:</h4><pre><code>undefined</pre></code><h4>cwd</h4><p>Absolute path to the working directory of the program being debugged.</p>
 <h5>Default value:</h4><pre><code>"${workspaceFolder}"</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>env</h4><p>Environment variables passed to the program. The value <code>null</code> removes the variable from the environment.</p>
@@ -130,7 +133,8 @@
 <h5>Default value:</h4><pre><code>[
   "--extensionDevelopmentPath=${workspaceFolder}"
 ]</pre></code><h4>autoAttachChildProcesses</h4><p>Attach debugger to new child processes automatically.</p>
-<h5>Default value:</h4><pre><code>false</pre></code><h4>cwd</h4><p>Absolute path to the working directory of the program being debugged.</p>
+<h5>Default value:</h4><pre><code>false</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>cwd</h4><p>Absolute path to the working directory of the program being debugged.</p>
 <h5>Default value:</h4><pre><code>"${workspaceFolder}"</pre></code><h4>debugWebviews</h4><p>Configures whether we should try to attach to webviews in the launched VS Code instance. <strong>Note:</strong> at the moment this requires the setting <code>&quot;webview.experimental.useExternalEndpoint&quot;: true</code> to work properly, and will only work in desktop VS Code.</p>
 <h5>Default value:</h4><pre><code>false</pre></code><h4>debugWebWorkerHost</h4><p>Configures whether we should try to attach to the web worker extension host.</p>
 <h5>Default value:</h4><pre><code>false</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
@@ -168,7 +172,8 @@
 ### pwa-chrome: launch
 
 <details><h4>browserLaunchLocation</h4><p>Forces the browser to be launched in one location. In a remote workspace (through ssh or WSL, for example) this can be used to open the browser on the remote machine rather than locally.</p>
-<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>cleanUp</h4><p>What clean-up to do after the debugging session finishes. Close only the tab being debug, vs. close the whole browser.</p>
+<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>cleanUp</h4><p>What clean-up to do after the debugging session finishes. Close only the tab being debug, vs. close the whole browser.</p>
 <h5>Default value:</h4><pre><code>"wholeBrowser"</pre></code><h4>cwd</h4><p>Optional working directory for the runtime executable.</p>
 <h5>Default value:</h4><pre><code>null</pre></code><h4>disableNetworkCache</h4><p>Controls whether to skip the network cache for each request</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
@@ -214,7 +219,8 @@
 
 <details><h4>address</h4><p>IP address or hostname the debugged browser is listening on.</p>
 <h5>Default value:</h4><pre><code>"localhost"</pre></code><h4>browserAttachLocation</h4><p>Forces the browser to attach in one location. In a remote workspace (through ssh or WSL, for example) this can be used to attach to a browser on the remote machine rather than locally.</p>
-<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>disableNetworkCache</h4><p>Controls whether to skip the network cache for each request</p>
+<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>disableNetworkCache</h4><p>Controls whether to skip the network cache for each request</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>inspectUri</h4><p>Format to use to rewrite the inspectUri: It&#39;s a template string that interpolates keys in <code>{curlyBraces}</code>. Available keys are:<br> - <code>url.*</code> is the parsed address of the running application. For instance, <code>{url.port}</code>, <code>{url.hostname}</code><br> - <code>port</code> is the debug port that Chrome is listening on.<br> - <code>browserInspectUri</code> is the inspector URI on the launched browser<br> - <code>wsProtocol</code> is the hinted websocket protocol. This is set to <code>wss</code> if the original URL is <code>https</code>, or <code>ws</code> otherwise.<br></p>
 <h5>Default value:</h4><pre><code>undefined</pre></code><h4>outFiles</h4><p>If source maps are enabled, these glob patterns specify the generated JavaScript files. If a pattern starts with <code>!</code> the files are excluded. If not specified, the generated code is expected in the same directory as its source.</p>
@@ -253,7 +259,8 @@
 
 <details><h4>address</h4><p>When debugging webviews, the IP address or hostname the webview is listening on. Will be automatically discovered if not set.</p>
 <h5>Default value:</h4><pre><code>"localhost"</pre></code><h4>browserLaunchLocation</h4><p>Forces the browser to be launched in one location. In a remote workspace (through ssh or WSL, for example) this can be used to open the browser on the remote machine rather than locally.</p>
-<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>cleanUp</h4><p>What clean-up to do after the debugging session finishes. Close only the tab being debug, vs. close the whole browser.</p>
+<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>cleanUp</h4><p>What clean-up to do after the debugging session finishes. Close only the tab being debug, vs. close the whole browser.</p>
 <h5>Default value:</h4><pre><code>"wholeBrowser"</pre></code><h4>cwd</h4><p>Optional working directory for the runtime executable.</p>
 <h5>Default value:</h4><pre><code>null</pre></code><h4>disableNetworkCache</h4><p>Controls whether to skip the network cache for each request</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
@@ -300,7 +307,8 @@
 
 <details><h4>address</h4><p>IP address or hostname the debugged browser is listening on.</p>
 <h5>Default value:</h4><pre><code>"localhost"</pre></code><h4>browserAttachLocation</h4><p>Forces the browser to attach in one location. In a remote workspace (through ssh or WSL, for example) this can be used to attach to a browser on the remote machine rather than locally.</p>
-<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>disableNetworkCache</h4><p>Controls whether to skip the network cache for each request</p>
+<h5>Default value:</h4><pre><code>"workspace"</pre></code><h4>cascadeTerminateToConfigurations</h4><p>A list of debug sessions which, when this debug session is terminated, will also be stopped.</p>
+<h5>Default value:</h4><pre><code>[]</pre></code><h4>disableNetworkCache</h4><p>Controls whether to skip the network cache for each request</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>enableContentValidation</h4><p>Toggles whether we verify the contents of files on disk match the ones loaded in the runtime. This is useful in a variety of scenarios and required in some, but can cause issues if you have server-side transformation of scripts, for example.</p>
 <h5>Default value:</h4><pre><code>true</pre></code><h4>inspectUri</h4><p>Format to use to rewrite the inspectUri: It&#39;s a template string that interpolates keys in <code>{curlyBraces}</code>. Available keys are:<br> - <code>url.*</code> is the parsed address of the running application. For instance, <code>{url.port}</code>, <code>{url.hostname}</code><br> - <code>port</code> is the debug port that Chrome is listening on.<br> - <code>browserInspectUri</code> is the inspector URI on the launched browser<br> - <code>wsProtocol</code> is the hinted websocket protocol. This is set to <code>wss</code> if the original URL is <code>https</code>, or <code>ws</code> otherwise.<br></p>
 <h5>Default value:</h4><pre><code>undefined</pre></code><h4>outFiles</h4><p>If source maps are enabled, these glob patterns specify the generated JavaScript files. If a pattern starts with <code>!</code> the files are excluded. If not specified, the generated code is expected in the same directory as its source.</p>

src/build/generate-contributions.ts

@@ -259,6 +259,15 @@ const baseConfigurationAttributes: ConfigurationAttributes<IBaseConfiguration> =
     type: 'boolean',
     description: refString('enableContentValidation.description'),
   },
+  cascadeTerminateToConfigurations: {
+    type: 'array',
+    items: {
+      type: 'string',
+      uniqueItems: true,
+    },
+    default: [],
+    description: refString('base.cascadeTerminateToConfigurations.label'),
+  },
 };
 
 /**

src/build/strings.ts

@@ -21,6 +21,9 @@ const strings = {
   'trace.stdio.description':
     'Whether to return trace data from the launched application or browser.',
 
+  'base.cascadeTerminateToConfigurations.label':
+    'A list of debug sessions which, when this debug session is terminated, will also be stopped.',
+
   'extensionHost.label': 'VS Code Extension Development (preview)',
   'extensionHost.launch.config.name': 'Launch Extension',
   'extensionHost.launch.env.description': 'Environment variables passed to the extension host.',

src/configuration.ts

@@ -165,6 +165,12 @@ export interface IBaseConfiguration extends IMandatedConfiguration {
    */
   enableContentValidation: boolean;
 
+  /**
+   * A list of debug sessions which, when this debug session is terminated,
+   * will also be stopped.
+   */
+  cascadeTerminateToConfigurations: string[];
+
   /**
    * The value of the ${workspaceFolder} variable
    */
@@ -752,6 +758,7 @@ export const baseDefaults: IBaseConfiguration = {
   outFiles: ['${workspaceFolder}/**/*.js', '!**/node_modules/**'],
   sourceMapPathOverrides: defaultSourceMapPathOverrides('${workspaceFolder}'),
   enableContentValidation: true,
+  cascadeTerminateToConfigurations: [],
   // Should always be determined upstream;
   __workspaceFolder: '',
   __autoExpandGetters: false,

src/extension.ts

@@ -9,6 +9,7 @@ import { extensionId } from './configuration';
 import { createGlobalContainer } from './ioc';
 import { DelegateLauncherFactory } from './targets/delegate/delegateLauncherFactory';
 import { registerAutoAttach } from './ui/autoAttach';
+import { CascadeTerminationTracker } from './ui/cascadeTerminateTracker';
 import { registerCompanionBrowserLaunch } from './ui/companionBrowserLaunch';
 import { IDebugConfigurationProvider, IDebugConfigurationResolver } from './ui/configuration';
 import { registerCustomBreakpointsUI } from './ui/customBreakpointsUI';
@@ -99,6 +100,7 @@ export function activate(context: vscode.ExtensionContext) {
   registerAutoAttach(context, services.get(DelegateLauncherFactory));
   registerRevealPage(context, debugSessionTracker);
   services.get(DebugLinkUi).register(context);
+  services.get(CascadeTerminationTracker).register(context);
 }
 
 export function deactivate() {

src/ui/cascadeTerminateTracker.ts

@@ -0,0 +1,36 @@
+/*---------------------------------------------------------
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------*/
+
+import { inject, injectable } from 'inversify';
+import * as vscode from 'vscode';
+import { DebugSessionTracker } from './debugSessionTracker';
+
+/**
+ * Watches for sessions to be terminated. When they are, it runs cascading
+ * termination if configured.
+ */
+@injectable()
+export class CascadeTerminationTracker {
+  constructor(@inject(DebugSessionTracker) private readonly tracker: DebugSessionTracker) {}
+
+  /**
+   * Registers the tracker for the extension.
+   */
+  public register(context: vscode.ExtensionContext) {
+    context.subscriptions.push(
+      this.tracker.onSessionEnded(session => {
+        const targets: string[] = session.configuration.cascadeTerminateToConfigurations;
+        if (!targets || !(targets instanceof Array)) {
+          return; // may be a nested session
+        }
+
+        for (const configName of targets) {
+          for (const session of this.tracker.getByName(configName)) {
+            vscode.debug.stopDebugging(session);
+          }
+        }
+      }),
+    );
+  }
+}

src/ui/customBreakpointsUI.ts

@@ -4,13 +4,13 @@
 
 import * as vscode from 'vscode';
 import {
-  ICustomBreakpoint,
   CustomBreakpointId,
   customBreakpoints,
+  ICustomBreakpoint,
 } from '../adapter/customBreakpoints';
+import { Commands, Contributions } from '../common/contributionUtils';
 import { EventEmitter } from '../common/events';
 import { DebugSessionTracker } from './debugSessionTracker';
-import { Contributions, Commands } from '../common/contributionUtils';
 
 class Breakpoint {
   id: CustomBreakpointId;
@@ -45,6 +45,10 @@ class BreakpointsDataProvider implements vscode.TreeDataProvider<Breakpoint> {
 
     this._debugSessionTracker = debugSessionTracker;
     debugSessionTracker.onSessionAdded(session => {
+      if (!DebugSessionTracker.isConcreteSession(session)) {
+        return;
+      }
+
       session.customRequest('enableCustomBreakpoints', {
         ids: this.breakpoints.filter(b => b.enabled).map(b => b.id),
       });
@@ -67,7 +71,7 @@ class BreakpointsDataProvider implements vscode.TreeDataProvider<Breakpoint> {
   addBreakpoints(breakpoints: Breakpoint[]) {
     for (const breakpoint of breakpoints) breakpoint.enabled = true;
     const ids = breakpoints.map(b => b.id);
-    for (const session of this._debugSessionTracker.sessions.values())
+    for (const session of this._debugSessionTracker.getConcreteSessions())
       session.customRequest('enableCustomBreakpoints', { ids });
     this._onDidChangeTreeData.fire(undefined);
   }
@@ -77,7 +81,7 @@ class BreakpointsDataProvider implements vscode.TreeDataProvider<Breakpoint> {
     for (const breakpoint of this.breakpoints) {
       if (ids.has(breakpoint.id)) breakpoint.enabled = false;
     }
-    for (const session of this._debugSessionTracker.sessions.values())
+    for (const session of this._debugSessionTracker.getConcreteSessions())
       session.customRequest('disableCustomBreakpoints', { ids: breakpointIds });
     this._onDidChangeTreeData.fire(undefined);
   }