feat: support for Edge Functions debugging (#4615)

* feat: support for Edge Functions debugging

Co-authored-by: jackiewmacharia <jackiewmacharia@users.noreply.github.com>
Co-authored-by: Eduardo Bouças <mail@eduardoboucas.com>

Author: jackiewmacharia

Diff for: docs/commands/dev.md

@@ -19,6 +19,8 @@ netlify dev
 
 - `command` (*string*) - command to run
 - `dir` (*string*) - dir with static files
+- `edgeInspect` (*string*) - enable the V8 Inspector Protocol for Edge Functions, with an optional address in the host:port format
+- `edgeInspectBrk` (*string*) - enable the V8 Inspector Protocol for Edge Functions and pause execution on the first line of code, with an optional address in the host:port format
 - `framework` (*string*) - framework to use. Defaults to #auto which automatically detects a framework
 - `functions` (*string*) - specify a functions folder to serve
 - `functionsPort` (*string*) - port of functions server
@@ -43,6 +45,10 @@ netlify dev
 netlify dev -d public
 netlify dev -c "hugo server -w" --targetPort 1313
 netlify dev --graph
+netlify dev --edgeInspect
+netlify dev --edgeInspect=127.0.0.1:9229
+netlify dev --edgeInspectBrk
+netlify dev --edgeInspectBrk=127.0.0.1:9229
 BROWSER=none netlify dev # disable browser auto opening
 ```
 

Diff for: package.json

@@ -122,6 +122,7 @@
     "Tim Perry (https://twitter.com/pimterry)",
     "Tim Trautman (timtrautman.com)",
     "Tom Dyson (https://wagtail.io/)",
+    "Tom Hu (https://twitter.com/thomasrockhu)",
     "Travis Horn <travis@travishorn.com> (https://twitter.com/horn_travis)",
     "Try Ajitiono <ballinst@gmail.com> (https://twitter.com/Ajiballinst)",
     "Victor Dadfar",

Diff for: src/commands/dev/dev.js

@@ -27,6 +27,7 @@ const {
   readGraphQLOperationsSourceFile,
 } = require('../../lib/one-graph/cli-netlify-graph')
 const {
+  BANG,
   NETLIFYDEV,
   NETLIFYDEVERR,
   NETLIFYDEVLOG,
@@ -195,11 +196,19 @@ const startFrameworkServer = async function ({ settings }) {
 // 10 minutes
 const FRAMEWORK_PORT_TIMEOUT = 6e5
 
+/**
+ * @typedef {Object} InspectSettings
+ * @property {boolean} enabled - Inspect enabled
+ * @property {boolean} pause - Pause on breakpoints
+ * @property {string|undefined} address - Host/port override (optional)
+ */
+
 /**
  *
  * @param {object} params
  * @param {*} params.addonsUrls
  * @param {import('../base-command').NetlifyOptions["config"]} params.config
+ * @param {InspectSettings} params.inspectSettings
  * @param {() => Promise<object>} params.getUpdatedConfig
  * @param {string} params.geolocationMode
  * @param {*} params.settings
@@ -213,6 +222,7 @@ const startProxyServer = async ({
   config,
   geolocationMode,
   getUpdatedConfig,
+  inspectSettings,
   offline,
   settings,
   site,
@@ -224,6 +234,7 @@ const startProxyServer = async ({
     configPath: site.configPath,
     geolocationMode,
     getUpdatedConfig,
+    inspectSettings,
     offline,
     projectDir: site.root,
     settings,
@@ -312,6 +323,46 @@ const startPollingForAPIAuthentication = async function (options) {
   await helper(siteInfo)
 }
 
+/**
+ * @param {boolean|string} edgeInspect
+ * @param {boolean|string} edgeInspectBrk
+ * @returns {InspectSettings}
+ */
+const generateInspectSettings = (edgeInspect, edgeInspectBrk) => {
+  const enabled = Boolean(edgeInspect) || Boolean(edgeInspectBrk)
+  const pause = Boolean(edgeInspectBrk)
+  const getAddress = () => {
+    if (edgeInspect) {
+      return typeof edgeInspect === 'string' ? edgeInspect : undefined
+    }
+    if (edgeInspectBrk) {
+      return typeof edgeInspectBrk === 'string' ? edgeInspectBrk : undefined
+    }
+  }
+
+  return {
+    enabled,
+    pause,
+    address: getAddress(),
+  }
+}
+
+const validateShortFlagArgs = (args) => {
+  if (args.startsWith('=')) {
+    throw new Error(
+      `Short flag options like -e or -E don't support the '=' sign
+ ${chalk.red(BANG)}   Supported formats:
+      netlify dev -e
+      netlify dev -e 127.0.0.1:9229
+      netlify dev -e127.0.0.1:9229
+      netlify dev -E
+      netlify dev -E 127.0.0.1:9229
+      netlify dev -E127.0.0.1:9229`,
+    )
+  }
+  return args
+}
+
 /**
  * The dev command
  * @param {import('commander').OptionValues} options
@@ -380,11 +431,14 @@ const dev = async (options, command) => {
     return normalizedNewConfig
   }
 
+  const inspectSettings = generateInspectSettings(options.edgeInspect, options.edgeInspectBrk)
+
   let url = await startProxyServer({
     addonsUrls,
     config,
     geolocationMode: options.geo,
     getUpdatedConfig,
+    inspectSettings,
     offline: options.offline,
     settings,
     site,
@@ -522,11 +576,31 @@ const createDevCommand = (program) => {
         .hideHelp(),
     )
     .addOption(new Option('--graph', 'enable Netlify Graph support').hideHelp())
+    .addOption(
+      new Option(
+        '-e, --edgeInspect [address]',
+        'enable the V8 Inspector Protocol for Edge Functions, with an optional address in the host:port format',
+      )
+        .conflicts('edgeInspectBrk')
+        .argParser(validateShortFlagArgs),
+    )
+    .addOption(
+      new Option(
+        '-E, --edgeInspectBrk [address]',
+        'enable the V8 Inspector Protocol for Edge Functions and pause execution on the first line of code, with an optional address in the host:port format',
+      )
+        .conflicts('edgeInspect')
+        .argParser(validateShortFlagArgs),
+    )
     .addExamples([
       'netlify dev',
       'netlify dev -d public',
       'netlify dev -c "hugo server -w" --targetPort 1313',
       'netlify dev --graph',
+      'netlify dev --edgeInspect',
+      'netlify dev --edgeInspect=127.0.0.1:9229',
+      'netlify dev --edgeInspectBrk',
+      'netlify dev --edgeInspectBrk=127.0.0.1:9229',
       'BROWSER=none netlify dev # disable browser auto opening',
     ])
     .action(dev)

Diff for: src/lib/edge-functions/proxy.js

@@ -47,6 +47,7 @@ const initializeProxy = async ({
   configPath,
   geolocationMode,
   getUpdatedConfig,
+  inspectSettings,
   offline,
   projectDir,
   settings,
@@ -67,6 +68,7 @@ const initializeProxy = async ({
     directories: [internalFunctionsPath, userFunctionsPath].filter(Boolean),
     getUpdatedConfig,
     importMaps: [importMap].filter(Boolean),
+    inspectSettings,
     internalFunctions,
     port: isolatePort,
     projectDir,
@@ -133,6 +135,7 @@ const prepareServer = async ({
   directories,
   getUpdatedConfig,
   importMaps,
+  inspectSettings,
   internalFunctions,
   port,
   projectDir,
@@ -150,6 +153,7 @@ const prepareServer = async ({
       )}. The file does not seem to have a function as the default export.`,
     formatImportError: (name) => `${NETLIFYDEVERR} ${chalk.red('Failed')} to run Edge Function ${chalk.yellow(name)}:`,
     importMaps,
+    inspectSettings,
     port,
   })
   const registry = new EdgeFunctionsRegistry({

Diff for: src/utils/proxy.js

@@ -467,6 +467,7 @@ const startProxy = async function ({
   configPath,
   geolocationMode,
   getUpdatedConfig,
+  inspectSettings,
   offline,
   projectDir,
   settings,
@@ -478,6 +479,7 @@ const startProxy = async function ({
     configPath,
     geolocationMode,
     getUpdatedConfig,
+    inspectSettings,
     offline,
     projectDir,
     settings,