chore: change config shape

Author: ascorbic

demos/default/pages/api/hello-background.ts

@@ -5,5 +5,5 @@ export default (req, res) => {
 }
 
 export const config = {
-  background: true,
+  type: 'experimental-background',
 }

demos/default/pages/api/hello-scheduled.js

@@ -5,5 +5,6 @@ export default (req, res) => {
 }
 
 export const config = {
+  type: 'experimental-scheduled',
   schedule: '@hourly',
 }

plugin/src/helpers/analysis.ts

@@ -4,24 +4,100 @@ import { relative } from 'path'
 import { extractExportedConstValue, UnsupportedValueError } from 'next/dist/build/analysis/extract-const-value'
 import { parseModule } from 'next/dist/build/analysis/parse-module'
 
-export interface ApiConfig {
-  runtime?: 'node' | 'experimental-edge'
-  background?: boolean
-  schedule?: string
+export interface ApiStandardConfig {
+  type?: never
+  runtime?: 'nodejs' | 'experimental-edge'
+  schedule?: never
 }
 
+export interface ApiScheduledConfig {
+  type: 'experimental-scheduled'
+  runtime?: 'nodejs'
+  schedule: string
+}
+
+export interface ApiBackgroundConfig {
+  type: 'experimental-background'
+  runtime?: 'nodejs'
+  schedule?: never
+}
+
+export type ApiConfig = ApiStandardConfig | ApiScheduledConfig | ApiBackgroundConfig
+
+export const validateConfigValue = (config: ApiConfig, apiFilePath: string): config is ApiConfig => {
+  if (config.type === 'experimental-scheduled') {
+    if (!config.schedule) {
+      console.error(
+        `Invalid config value in ${relative(
+          process.cwd(),
+          apiFilePath,
+        )}: schedule is required when type is "experimental-scheduled"`,
+      )
+      return false
+    }
+    if ((config as ApiConfig).runtime === 'experimental-edge') {
+      console.error(
+        `Invalid config value in ${relative(
+          process.cwd(),
+          apiFilePath,
+        )}: edge runtime is not supported for scheduled functions`,
+      )
+      return false
+    }
+    return true
+  }
+
+  if (!config.type || config.type === 'experimental-background') {
+    if (config.schedule) {
+      console.error(
+        `Invalid config value in ${relative(
+          process.cwd(),
+          apiFilePath,
+        )}: schedule is not allowed unless type is "experimental-scheduled"`,
+      )
+      return false
+    }
+    if (config.type && (config as ApiConfig).runtime === 'experimental-edge') {
+      console.error(
+        `Invalid config value in ${relative(
+          process.cwd(),
+          apiFilePath,
+        )}: edge runtime is not supported for background functions`,
+      )
+      return false
+    }
+    return true
+  }
+  console.error(
+    `Invalid config value in ${relative(process.cwd(), apiFilePath)}: type ${
+      (config as ApiConfig).type
+    } is not supported`,
+  )
+  return false
+}
+
+/**
+ * Uses Next's swc static analysis to extract the config values from a file.
+ */
 export const extractConfigFromFile = async (apiFilePath: string): Promise<ApiConfig> => {
   const fileContent = await fs.promises.readFile(apiFilePath, 'utf8')
+  // No need to parse if there's no "config"
   if (!fileContent.includes('config')) {
     return {}
   }
   const ast = await parseModule(apiFilePath, fileContent)
+
+  let config: ApiConfig
   try {
-    return extractExportedConstValue(ast, 'config')
+    config = extractExportedConstValue(ast, 'config')
   } catch (error) {
     if (error instanceof UnsupportedValueError) {
       console.warn(`Unsupported config value in ${relative(process.cwd(), apiFilePath)}`)
     }
     return {}
   }
+  if (validateConfigValue(config, apiFilePath)) {
+    return config
+  }
+  throw new Error(`Unsupported config value in ${relative(process.cwd(), apiFilePath)}`)
 }

plugin/src/helpers/files.ts

@@ -325,6 +325,9 @@ const getServerFile = (root: string, includeBase = true) => {
   return findModuleFromBase({ candidates, paths: [root] })
 }
 
+/**
+ * Find the source file for a given page route
+ */
 export const getSourceFileForPage = (page: string, root: string) => {
   for (const extension of ['ts', 'js']) {
     const file = join(root, `${page}.${extension}`)
@@ -334,6 +337,9 @@ export const getSourceFileForPage = (page: string, root: string) => {
   }
 }
 
+/**
+ * Reads the node file trace file for a given file, and resolves the dependencies
+ */
 export const getDependenciesOfFile = async (file: string) => {
   const nft = `${file}.nft.json`
   if (!existsSync(nft)) {

plugin/src/helpers/functions.ts

@@ -31,8 +31,11 @@ export const generateFunctions = async (
   const publishDir = relative(functionDir, publish)
 
   for (const { route, config, compiled } of apiRoutes) {
-    const apiHandlerSource = await getApiHandler({ page: route, schedule: config.schedule })
-    const functionName = getFunctionNameForPage(route, config.background)
+    const apiHandlerSource = await getApiHandler({
+      page: route,
+      config,
+    })
+    const functionName = getFunctionNameForPage(route, config.type === 'experimental-background')
     await ensureDir(join(functionsDir, functionName))
     await writeFile(join(functionsDir, functionName, `${functionName}.js`), apiHandlerSource)
     await copyFile(bridgeFile, join(functionsDir, functionName, 'bridge.js'))
@@ -137,6 +140,9 @@ export const setupImageFunction = async ({
   }
 }
 
+/**
+ * Look for API routes, and extract the config from the source file.
+ */
 export const getApiRouteConfigs = async (publish: string, baseDir: string): Promise<Array<ApiRouteConfig>> => {
   const pages = await readJSON(join(publish, 'server', 'pages-manifest.json'))
   const apiRoutes = Object.keys(pages).filter((page) => page.startsWith('/api/'))

plugin/src/helpers/utils.ts

@@ -10,15 +10,11 @@ import { I18n } from './types'
 
 const RESERVED_FILENAME = /[^\w_-]/g
 
-//
-//    // Replace catch-all, e.g., [...slug]
-//    .replace(CATCH_ALL_REGEX, '/:$1/*')
-//    // Replace optional catch-all, e.g., [[...slug]]
-//    .replace(OPTIONAL_CATCH_ALL_REGEX, '/*')
-//    // Replace dynamic parameters, e.g., [id]
-//    .replace(DYNAMIC_PARAMETER_REGEX, '/:$1'),
-//
-
+/**
+ * Given a Next route, generates a valid Netlify function name.
+ * If "background" is true then the function name will have `-background`
+ * appended to it, meaning that it is executed as a background function.
+ */
 export const getFunctionNameForPage = (page: string, background = false) =>
   `${page
     .replace(CATCH_ALL_REGEX, '_$1-SPLAT')
@@ -141,13 +137,16 @@ export const getApiRewrites = (basePath: string, apiRoutes: Array<ApiRouteConfig
   const apiRewrites = apiRoutes.map((apiRoute) => {
     const [from] = toNetlifyRoute(`${basePath}${apiRoute.route}`)
 
-    // Scheduled functions can't be invoked directly
-    if (apiRoute.config.schedule) {
+    // Scheduled functions can't be invoked directly, so we 404 them.
+    if (apiRoute.config.type === 'experimental-scheduled') {
       return { from, to: '/404.html', status: 404 }
     }
     return {
       from,
-      to: `/.netlify/functions/${getFunctionNameForPage(apiRoute.route, apiRoute.config.background)}`,
+      to: `/.netlify/functions/${getFunctionNameForPage(
+        apiRoute.route,
+        apiRoute.config.type === 'experimental-background',
+      )}`,
       status: 200,
     }
   })

plugin/src/templates/getApiHandler.ts

@@ -3,6 +3,7 @@ import type { Bridge as NodeBridge } from '@vercel/node-bridge/bridge'
 // Aliasing like this means the editor may be able to syntax-highlight the string
 import { outdent as javascript } from 'outdent'
 
+import { ApiConfig } from '../helpers/analysis'
 import type { NextConfig } from '../helpers/config'
 
 import type { NextServerType } from './handlerUtils'
@@ -111,21 +112,36 @@ const makeHandler = (conf: NextConfig, app, pageRoot, page) => {
   }
 }
 
-export const getApiHandler = ({ page, schedule, publishDir = '../../../.next', appDir = '../../..' }): string =>
+/**
+ * Handlers for API routes are simpler than page routes, but they each have a separate one
+ */
+export const getApiHandler = ({
+  page,
+  config,
+  publishDir = '../../../.next',
+  appDir = '../../..',
+}: {
+  page: string
+  config: ApiConfig
+  publishDir?: string
+  appDir?: string
+}): string =>
   // This is a string, but if you have the right editor plugin it should format as js
   javascript/* javascript */ `
   const { Server } = require("http");
   // We copy the file here rather than requiring from the node module
   const { Bridge } = require("./bridge");
   const { getMaxAge, getMultiValueHeaders, getNextServer } = require('./handlerUtils')
 
-  ${schedule ? `const { schedule } = require("@netlify/functions")` : ''}
+  ${config.type === 'experimental-scheduled' ? `const { schedule } = require("@netlify/functions")` : ''}
 
 
   const { config }  = require("${publishDir}/required-server-files.json")
   let staticManifest
   const path = require("path");
   const pageRoot = path.resolve(path.join(__dirname, "${publishDir}", "serverless", "pages"));
   const handler = (${makeHandler.toString()})(config, "${appDir}", pageRoot, ${JSON.stringify(page)})
-  exports.handler = ${schedule ? `schedule(${JSON.stringify(schedule)}, handler);` : 'handler'}
+  exports.handler = ${
+    config.type === 'experimental-scheduled' ? `schedule(${JSON.stringify(config.schedule)}, handler);` : 'handler'
+  }
 `

plugin/src/templates/getPageResolver.ts

@@ -33,6 +33,10 @@ export const getPageResolver = async ({ publish, target }: { publish: string; ta
   `
 }
 
+/**
+ * API routes only need the dependencies for a single entrypoint, so we use the
+ * NFT trace file to get the dependencies.
+ */
 export const getSinglePageResolver = async ({
   functionsDir,
   sourceFile,

test/analysis.spec.ts

@@ -2,16 +2,24 @@ import { extractConfigFromFile } from '../plugin/src/helpers/analysis'
 import { resolve } from 'path'
 import { getDependenciesOfFile } from '../plugin/src/helpers/files'
 describe('static source analysis', () => {
+  beforeEach(() => {
+    //  Spy on console.error
+    jest.spyOn(console, 'error').mockImplementation(() => {})
+  })
+  afterEach(() => {
+    //  Restore console.error
+    ;(console.error as jest.Mock).mockRestore()
+  })
   it('should extract config values from a source file', async () => {
     const config = await extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/background.js'))
     expect(config).toEqual({
-      background: true,
+      type: 'experimental-background',
     })
   })
   it('should extract config values from a TypeScript source file', async () => {
     const config = await extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/background.ts'))
     expect(config).toEqual({
-      background: true,
+      type: 'experimental-background',
     })
   })
   it('should return an empty config if not defined', async () => {
@@ -27,9 +35,50 @@ describe('static source analysis', () => {
   it('should extract schedule values from a source file', async () => {
     const config = await extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/scheduled.ts'))
     expect(config).toEqual({
+      type: 'experimental-scheduled',
       schedule: '@daily',
     })
   })
+  it('should throw if schedule is provided when type is background', async () => {
+    await expect(extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/background-schedule.ts'))).rejects.toThrow(
+      'Unsupported config value in test/fixtures/analysis/background-schedule.ts',
+    )
+    expect(console.error).toHaveBeenCalledWith(
+      `Invalid config value in test/fixtures/analysis/background-schedule.ts: schedule is not allowed unless type is "experimental-scheduled"`,
+    )
+  })
+  it('should throw if schedule is provided when type is default', async () => {
+    await expect(extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/default-schedule.ts'))).rejects.toThrow(
+      'Unsupported config value in test/fixtures/analysis/default-schedule.ts',
+    )
+    expect(console.error).toHaveBeenCalledWith(
+      `Invalid config value in test/fixtures/analysis/default-schedule.ts: schedule is not allowed unless type is "experimental-scheduled"`,
+    )
+  })
+  it('should throw if schedule is not provided when type is scheduled', async () => {
+    await expect(extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/missing-schedule.ts'))).rejects.toThrow(
+      'Unsupported config value in test/fixtures/analysis/missing-schedule.ts',
+    )
+    expect(console.error).toHaveBeenCalledWith(
+      `Invalid config value in test/fixtures/analysis/missing-schedule.ts: schedule is required when type is "experimental-scheduled"`,
+    )
+  })
+  it('should throw if edge runtime is specified for scheduled functions', async () => {
+    await expect(extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/scheduled-edge.ts'))).rejects.toThrow(
+      'Unsupported config value in test/fixtures/analysis/scheduled-edge.ts',
+    )
+    expect(console.error).toHaveBeenCalledWith(
+      `Invalid config value in test/fixtures/analysis/scheduled-edge.ts: edge runtime is not supported for scheduled functions`,
+    )
+  })
+  it('should throw if edge runtime is specified for background functions', async () => {
+    await expect(extractConfigFromFile(resolve(__dirname, 'fixtures/analysis/background-edge.ts'))).rejects.toThrow(
+      'Unsupported config value in test/fixtures/analysis/background-edge.ts',
+    )
+    expect(console.error).toHaveBeenCalledWith(
+      `Invalid config value in test/fixtures/analysis/background-edge.ts: edge runtime is not supported for background functions`,
+    )
+  })
 })
 
 describe('dependency tracing', () => {

test/fixtures/analysis/background-edge.ts

@@ -0,0 +1,10 @@
+export default (req, res) => {
+  res.setHeader('Content-Type', 'application/json')
+  res.status(200)
+  res.json({ message: 'hello world :)' })
+}
+
+export const config = {
+  type: 'experimental-background',
+  runtime: 'experimental-edge',
+}

test/fixtures/analysis/background-schedule.ts

@@ -0,0 +1,11 @@
+export default (req, res) => {
+  res.setHeader('Content-Type', 'application/json')
+  res.status(200)
+  res.json({ message: 'hello world :)' })
+}
+
+export const config = {
+  type: 'experimental-background',
+  // INVALID
+  schedule: '@daily',
+}

test/fixtures/analysis/background.js

@@ -5,5 +5,5 @@ export default (req, res) => {
 }
 
 export const config = {
-  background: true,
+  type: 'experimental-background',
 }

test/fixtures/analysis/background.ts

@@ -5,5 +5,5 @@ export default (req, res) => {
 }
 
 export const config = {
-  background: true,
+  type: 'experimental-background',
 }

test/fixtures/analysis/default-schedule.ts

@@ -0,0 +1,10 @@
+export default (req, res) => {
+  res.setHeader('Content-Type', 'application/json')
+  res.status(200)
+  res.json({ message: 'hello world :)' })
+}
+
+export const config = {
+  // INVALID
+  schedule: '@daily',
+}

test/fixtures/analysis/missing-schedule.ts

@@ -0,0 +1,9 @@
+export default (req, res) => {
+  res.setHeader('Content-Type', 'application/json')
+  res.status(200)
+  res.json({ message: 'hello world :)' })
+}
+
+export const config = {
+  type: 'experimental-scheduled',
+}