feat: Add skipEntryPaths to immediately detach a debug session depending on entry path (#911)

* feat: Add skipEntryPaths to immediately detach a debug session depending on entry file

* Document skipEntryPaths.

* Handle invalid init packet.

* Test case for skip entry paths and fix for old max conn test.

Author: zobo

README.md

@@ -78,6 +78,7 @@ More general information on debugging with VS Code can be found on https://code.
 - `ignore`: An optional array of glob patterns that errors should be ignored from (for example `**/vendor/**/*.php`)
 - `ignoreExceptions`: An optional array of exception class names that should be ignored (for example `BaseException`, `\NS1\Exception`, `\*\Exception` or `\**\Exception*`)
 - `skipFiles`: An array of glob patterns, to skip when debugging. Star patterns and negations are allowed, for example, `**/vendor/**` or `!**/vendor/my-module/**`.
+- `skipEntryPaths`: An array of glob patterns, to immediately detach from and ignore for debugging if the entry script matches (example `**/ajax.php`).
 - `maxConnections`: Accept only this number of parallel debugging sessions. Additional connections will be dropped and their execution will continue without debugging.
 - `proxy`: DBGp Proxy settings
   - `enable`: To enable proxy registration set to `true` (default is `false).

package.json

@@ -283,6 +283,11 @@
                 "items": "string",
                 "description": "An array of exception class names that should be ignored."
               },
+              "skipEntryPaths": {
+                "type": "array",
+                "items": "string",
+                "description": "An array of glob pattern to skip if the initial entry file is matched."
+              },
               "log": {
                 "type": "boolean",
                 "description": "If true, will log all communication between VS Code and the adapter"

src/phpDebug.ts

@@ -79,6 +79,8 @@ export interface LaunchRequestArguments extends VSCodeDebugProtocol.LaunchReques
     ignore?: string[]
     /** Array of glob patterns that exceptions should be ignored from */
     ignoreExceptions?: string[]
+    /** An array of glob pattern to skip if the initial entry file is matched. */
+    skipEntryPaths?: string[]
     /** Array of glob patterns that debugger should not step in */
     skipFiles?: string[]
     /** Xdebug configuration */
@@ -487,6 +489,26 @@ class PhpDebugSession extends vscode.DebugSession {
     private async initializeConnection(connection: xdebug.Connection): Promise<void> {
         const initPacket = await connection.waitForInitPacket()
 
+        // check if this connection should be skipped
+        if (
+            this._args.skipEntryPaths &&
+            isPositiveMatchInGlobs(
+                convertDebuggerPathToClient(initPacket.fileUri).replace(/\\/g, '/'),
+                this._args.skipEntryPaths
+            )
+        ) {
+            this.sendEvent(
+                new vscode.OutputEvent(
+                    `skipping entry point ${convertDebuggerPathToClient(initPacket.fileUri).replace(
+                        /\\/g,
+                        '/'
+                    )} on connection ${connection.id}\n`
+                )
+            )
+            this.disposeConnection(connection)
+            return
+        }
+
         // support for breakpoints
         let feat: xdebug.FeatureGetResponse
         const supportedEngine =

src/test/adapter.ts

@@ -827,7 +827,12 @@ describe('PHP Debug Adapter', () => {
             await Promise.all([client.launch({ maxConnections: 1, log: true }), client.configurationSequence()])
 
             const s1 = net.createConnection({ port: 9003 })
-            await client.assertOutput('console', 'new connection 1 from ')
+            const o1 = await client.assertOutput('console', 'new connection')
+            assert.match(
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                o1.body.output as string,
+                /^new connection \d+ from/
+            )
             net.createConnection({ port: 9003 })
             const o = await client.waitForEvent('output')
             assert.match(
@@ -860,5 +865,14 @@ describe('PHP Debug Adapter', () => {
             assert.equal(response2.body.stackFrames[1].name, 'depth1')
             assert.equal(response2.body.stackFrames[2].name, '{main}')
         })
+        it('skip entry paths', async () => {
+            const program = path.join(TEST_PROJECT, 'variables.php')
+
+            await client.launch({ program, skipEntryPaths: ['**/variables.php'] })
+            await client.setBreakpointsRequest({ source: { path: program }, breakpoints: [{ line: 19 }] })
+            await client.configurationDoneRequest()
+
+            await client.assertOutput('console', 'skipping entry point')
+        })
     })
 })

src/xdebugConnection.ts

@@ -28,8 +28,8 @@ export class InitPacket {
         this.language = documentElement.getAttribute('language')!
         this.protocolVersion = documentElement.getAttribute('protocol_version')!
         this.ideKey = documentElement.getAttribute('idekey')!
-        this.engineVersion = documentElement.getElementsByTagName('engine')[0].getAttribute('version')!
-        this.engineName = documentElement.getElementsByTagName('engine')[0].textContent ?? ''
+        this.engineVersion = documentElement.getElementsByTagName('engine').item(0)?.getAttribute('version') ?? ''
+        this.engineName = documentElement.getElementsByTagName('engine').item(0)?.textContent ?? ''
         this.connection = connection
     }
 }