feat: add support for custom routes (#1523)

* feat: add support for custom routes

* chore: fix tests

* refactor: restructure code

* refactor: gracefully handle invalid `URLPattern` instances

package.json

@@ -84,6 +84,7 @@
     "tmp-promise": "^3.0.2",
     "toml": "^3.0.0",
     "unixify": "^1.0.0",
+    "urlpattern-polyfill": "8.0.2",
     "yargs": "^17.0.0"
   },
   "devDependencies": {

src/manifest.ts

@@ -5,12 +5,14 @@ import { arch, platform } from 'process'
 import type { FeatureFlags } from './feature_flags.js'
 import type { InvocationMode } from './function.js'
 import type { FunctionResult } from './utils/format_result.js'
+import type { Route } from './utils/routes.js'
 
 interface ManifestFunction {
   invocationMode?: InvocationMode
   mainFile: string
   name: string
   path: string
+  routes?: Route[]
   runtime: string
   runtimeVersion?: string
   schedule?: string
@@ -60,20 +62,29 @@ const formatFunctionForManifest = (
     mainFile,
     name,
     path,
+    routes,
     runtime,
     runtimeVersion,
     schedule,
   }: FunctionResult,
   featureFlags: FeatureFlags,
-): ManifestFunction => ({
-  bundler,
-  displayName,
-  generator,
-  invocationMode,
-  mainFile,
-  name,
-  runtimeVersion: featureFlags.functions_inherit_build_nodejs_version ? runtimeVersion : undefined,
-  path: resolve(path),
-  runtime,
-  schedule,
-})
+): ManifestFunction => {
+  const manifestFunction: ManifestFunction = {
+    bundler,
+    displayName,
+    generator,
+    invocationMode,
+    mainFile,
+    name,
+    runtimeVersion: featureFlags.functions_inherit_build_nodejs_version ? runtimeVersion : undefined,
+    path: resolve(path),
+    runtime,
+    schedule,
+  }
+
+  if (routes?.length !== 0) {
+    manifestFunction.routes = routes
+  }
+
+  return manifestFunction
+}

src/runtimes/node/in_source_config/index.ts

@@ -5,6 +5,7 @@ import { InvocationMode, INVOCATION_MODE } from '../../../function.js'
 import { FunctionBundlingUserError } from '../../../utils/error.js'
 import { Logger } from '../../../utils/logger.js'
 import { nonNullable } from '../../../utils/non_nullable.js'
+import { getRoutesFromPath, Route } from '../../../utils/routes.js'
 import { RUNTIME } from '../../runtime.js'
 import { createBindingsMethod } from '../parser/bindings.js'
 import { getExports } from '../parser/exports.js'
@@ -17,6 +18,7 @@ export const IN_SOURCE_CONFIG_MODULE = '@netlify/functions'
 
 export type ISCValues = {
   invocationMode?: InvocationMode
+  routes?: Route[]
   runtimeAPIVersion?: number
   schedule?: string
 }
@@ -81,6 +83,7 @@ export const findISCDeclarations = (
 
   if (featureFlags.zisi_functions_api_v2 && isV2API) {
     const config: ISCValues = {
+      routes: getRoutesFromPath(configExport.path, functionName),
       runtimeAPIVersion: 2,
     }
 

src/utils/format_result.ts

@@ -2,8 +2,10 @@ import { FunctionArchive } from '../function.js'
 import { RuntimeName } from '../runtimes/runtime.js'
 
 import { removeUndefined } from './remove_undefined.js'
+import type { Route } from './routes.js'
 
 export type FunctionResult = Omit<FunctionArchive, 'runtime'> & {
+  routes?: Route[]
   runtime: RuntimeName
   schedule?: string
   runtimeAPIVersion?: number
@@ -14,6 +16,7 @@ export const formatZipResult = (archive: FunctionArchive) => {
   const functionResult: FunctionResult = {
     ...archive,
     inSourceConfig: undefined,
+    routes: archive.inSourceConfig?.routes,
     runtime: archive.runtime.name,
     schedule: archive.inSourceConfig?.schedule ?? archive?.config?.schedule,
     runtimeAPIVersion: archive.inSourceConfig?.runtimeAPIVersion,

src/utils/routes.ts

@@ -0,0 +1,62 @@
+import { RUNTIME } from '../runtimes/runtime.js'
+
+import { FunctionBundlingUserError } from './error.js'
+import { ExtendedURLPattern } from './urlpattern.js'
+
+export type Route = { pattern: string } & ({ literal: string } | { expression: string })
+
+// Based on https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API.
+const isExpression = (part: string) =>
+  part.includes('*') || part.startsWith(':') || part.includes('{') || part.includes('[') || part.includes('(')
+
+// Detects whether a path can be represented as a literal or whether it needs
+// a regular expression.
+const isPathLiteral = (path: string) => {
+  const parts = path.split('/')
+
+  return parts.every((part) => !isExpression(part))
+}
+
+export const getRoutesFromPath = (path: unknown, functionName: string): Route[] => {
+  if (!path) {
+    return []
+  }
+
+  if (typeof path !== 'string') {
+    throw new FunctionBundlingUserError(`'path' property must be a string, found '${typeof path}'`, {
+      functionName,
+      runtime: RUNTIME.JAVASCRIPT,
+    })
+  }
+
+  if (!path.startsWith('/')) {
+    throw new FunctionBundlingUserError(`'path' property must start with a '/'`, {
+      functionName,
+      runtime: RUNTIME.JAVASCRIPT,
+    })
+  }
+
+  if (isPathLiteral(path)) {
+    return [{ pattern: path, literal: path }]
+  }
+
+  try {
+    const pattern = new ExtendedURLPattern({ pathname: path })
+
+    // Removing the `^` and `$` delimiters because we'll need to modify what's
+    // between them.
+    const regex = pattern.regexp.pathname.source.slice(1, -1)
+
+    // Wrapping the expression source with `^` and `$`. Also, adding an optional
+    // trailing slash, so that a declaration of `path: "/foo"` matches requests
+    // for both `/foo` and `/foo/`.
+    const normalizedRegex = `^${regex}\\/?$`
+
+    return [{ pattern: path, expression: normalizedRegex }]
+  } catch {
+    throw new FunctionBundlingUserError(`'${path}' is not a valid path according to the URLPattern specification`, {
+      functionName,
+      runtime: RUNTIME.JAVASCRIPT,
+    })
+  }
+}

src/utils/urlpattern.ts

@@ -0,0 +1,7 @@
+import { URLPattern } from 'urlpattern-polyfill'
+
+export class ExtendedURLPattern extends URLPattern {
+  // @ts-expect-error Internal property that the underlying class is using but
+  // not exposing.
+  regexp: Record<string, RegExp>
+}

tests/fixtures-esm/v2-api-with-invalid-path/function.mjs

@@ -0,0 +1,10 @@
+export default async () =>
+  new Response('<h1>Hello world</h1>', {
+    headers: {
+      'content-type': 'text/html',
+    },
+  })
+
+export const config = {
+  path: {},
+}

tests/fixtures-esm/v2-api-with-path/with-literal.mjs

@@ -0,0 +1,10 @@
+export default async () =>
+  new Response('<h1>Hello world</h1>', {
+    headers: {
+      'content-type': 'text/html',
+    },
+  })
+
+export const config = {
+  path: '/products',
+}

tests/fixtures-esm/v2-api-with-path/with-named-group.mjs

@@ -0,0 +1,10 @@
+export default async () =>
+  new Response('<h1>Hello world</h1>', {
+    headers: {
+      'content-type': 'text/html',
+    },
+  })
+
+export const config = {
+  path: '/products/:id',
+}

tests/fixtures-esm/v2-api-with-path/with-regex.mjs

@@ -0,0 +1,10 @@
+export default async () =>
+  new Response('<h1>Hello world</h1>', {
+    headers: {
+      'content-type': 'text/html',
+    },
+  })
+
+export const config = {
+  path: '/numbers/(\\d+)',
+}

tests/helpers/main.ts

@@ -99,8 +99,13 @@ export const zipCheckFunctions = async function (
 
   const files = await zipFunctions(srcFolders, tmpDir, opts)
 
-  expect(Array.isArray(files)).toBe(true)
-  expect(files).toHaveLength(length)
+  if (!Array.isArray(files)) {
+    throw new TypeError(`Expected 'zipFunctions' to return an array, found ${typeof files}`)
+  }
+
+  if (files.length !== length) {
+    throw new Error(`Expected 'zipFunctions' to return ${length} items, found ${files.length}`)
+  }
 
   return { files, tmpDir }
 }

tests/unit/runtimes/node/in_source_config.test.ts

@@ -111,7 +111,7 @@ describe('V2 API', () => {
 
     expect(systemLog).toHaveBeenCalledOnce()
     expect(systemLog).toHaveBeenCalledWith('detected v2 function')
-    expect(isc).toEqual({ runtimeAPIVersion: 2 })
+    expect(isc).toEqual({ routes: [], runtimeAPIVersion: 2 })
   })
 
   test('ESM file with a default export and a `handler` export', () => {
@@ -123,7 +123,7 @@ describe('V2 API', () => {
 
     const isc = findISCDeclarations(source, options)
 
-    expect(isc).toEqual({ runtimeAPIVersion: 2 })
+    expect(isc).toEqual({ routes: [], runtimeAPIVersion: 2 })
   })
 
   test('TypeScript file with a default export and no `handler` export', () => {
@@ -133,7 +133,7 @@ describe('V2 API', () => {
 
     const isc = findISCDeclarations(source, options)
 
-    expect(isc).toEqual({ runtimeAPIVersion: 2 })
+    expect(isc).toEqual({ routes: [], runtimeAPIVersion: 2 })
   })
 
   test('CommonJS file with a default export and a `handler` export', () => {
@@ -169,6 +169,87 @@ describe('V2 API', () => {
 
     const isc = findISCDeclarations(source, options)
 
-    expect(isc).toEqual({ runtimeAPIVersion: 2, schedule: '@daily' })
+    expect(isc).toEqual({ routes: [], runtimeAPIVersion: 2, schedule: '@daily' })
+  })
+
+  describe('`path` property', () => {
+    test('Missing a leading slash', () => {
+      expect.assertions(4)
+
+      try {
+        const source = `export default async () => {
+          return new Response("Hello!")
+        }
+    
+        export const config = {
+          path: "missing-slash"
+        }`
+
+        findISCDeclarations(source, options)
+      } catch (error) {
+        const { customErrorInfo, message } = error
+
+        expect(message).toBe(`'path' property must start with a '/'`)
+        expect(customErrorInfo.type).toBe('functionsBundling')
+        expect(customErrorInfo.location.functionName).toBe('func1')
+        expect(customErrorInfo.location.runtime).toBe('js')
+      }
+    })
+
+    test('With an invalid pattern', () => {
+      expect.assertions(4)
+
+      try {
+        const source = `export default async () => {
+          return new Response("Hello!")
+        }
+    
+        export const config = {
+          path: "/products("
+        }`
+
+        findISCDeclarations(source, options)
+      } catch (error) {
+        const { customErrorInfo, message } = error
+
+        expect(message).toBe(`'/products(' is not a valid path according to the URLPattern specification`)
+        expect(customErrorInfo.type).toBe('functionsBundling')
+        expect(customErrorInfo.location.functionName).toBe('func1')
+        expect(customErrorInfo.location.runtime).toBe('js')
+      }
+    })
+
+    test('Using a literal pattern', () => {
+      const source = `export default async () => {
+        return new Response("Hello!")
+      }
+  
+      export const config = {
+        path: "/products"
+      }`
+
+      const { routes } = findISCDeclarations(source, options)
+
+      expect(routes).toEqual([{ pattern: '/products', literal: '/products' }])
+    })
+
+    test('Using a pattern with named groupd', () => {
+      const source = `export default async () => {
+        return new Response("Hello!")
+      }
+  
+      export const config = {
+        path: "/store/:category/products/:product-id"
+      }`
+
+      const { routes } = findISCDeclarations(source, options)
+
+      expect(routes).toEqual([
+        {
+          pattern: '/store/:category/products/:product-id',
+          expression: '^\\/store(?:\\/([^\\/]+?))\\/products(?:\\/([^\\/]+?))-id\\/?$',
+        },
+      ])
+    })
   })
 })