feat: add support for manifest file (#601)

* feat: add support for manifest file

* chore: add `manifest` to README

* chore: update README

* refactor: make path property absolute

* chore: fix test

* chore: doh

* refactor: propagate errors from manifest creation

* refactor: conditionally create manifest

README.md

@@ -138,6 +138,22 @@ The following properties are accepted:
 
 See [feature flags](#feature-flags).
 
+#### `manifest`
+
+- _Type_: `string`
+- _Default value_: `undefined`
+
+Defines the path for a manifest file to be created with the results of the functions bundling. This file is a
+JSON-formatted string with the following properties:
+
+- `functions`: An array with the functions created, in the same format as returned by `zipFunctions`
+- `system.arch`: The operating system CPU architecture, as returned by
+  [`process.arch`](https://nodejs.org/api/process.html#process_process_arch)
+- `system.platform`: The operating system, as returned by
+  [`process.platform`](https://nodejs.org/api/process.html#process_process_platform)
+- `timestamp`: The timestamp (in milliseconds) at the time of the functions bundling process
+- `version`: The version of the manifest file (current version is `1`)
+
 #### `parallelLimit`
 
 - _Type_: `number`\

src/bin.js

@@ -35,6 +35,10 @@ const OPTIONS = {
     describe:
       'An object matching glob-like expressions to objects containing configuration properties. Whenever a function name matches one of the expressions, it inherits the configuration properties',
   },
+  manifest: {
+    string: true,
+    describe: 'If a manifest file is to be created, specifies its path',
+  },
   'parallel-limit': {
     number: true,
     describe: 'Maximum number of Functions to bundle at the same time',

src/manifest.js

@@ -0,0 +1,22 @@
+const { resolve } = require('path')
+const { arch, platform } = require('process')
+
+const { writeFile } = require('./utils/fs')
+
+const MANIFEST_VERSION = 1
+
+const createManifest = async ({ functions, path }) => {
+  const formattedFunctions = functions.map(formatFunction)
+  const payload = {
+    functions: formattedFunctions,
+    system: { arch, platform },
+    timestamp: Date.now(),
+    version: MANIFEST_VERSION,
+  }
+
+  await writeFile(path, JSON.stringify(payload))
+}
+
+const formatFunction = (fn) => ({ ...fn, path: resolve(fn.path) })
+
+module.exports = { createManifest }

src/utils/fs.js

@@ -1,11 +1,12 @@
-const { lstat, readdir, readFile, unlink } = require('fs')
+const { lstat, readdir, readFile, unlink, writeFile } = require('fs')
 const { format, join, parse, resolve } = require('path')
 const { promisify } = require('util')
 
 const pLstat = promisify(lstat)
 const pReaddir = promisify(readdir)
 const pReadFile = promisify(readFile)
 const pUnlink = promisify(unlink)
+const pWriteFile = promisify(writeFile)
 
 // This caches multiple FS calls to the same path. It creates a cache key with
 // the name of the function and the path (e.g. "readdir:/some/directory").
@@ -83,4 +84,5 @@ module.exports = {
   listFunctionsDirectory,
   resolveFunctionsDirectories,
   safeUnlink,
+  writeFile: pWriteFile,
 }

src/zip.js

@@ -4,6 +4,7 @@ const makeDir = require('make-dir')
 const pMap = require('p-map')
 
 const { getFlags } = require('./feature_flags')
+const { createManifest } = require('./manifest')
 const { getPluginsModulesPath } = require('./node_dependencies')
 const { getFunctionsFromPaths } = require('./runtimes')
 const { ARCHIVE_FORMAT_NONE, ARCHIVE_FORMAT_ZIP } = require('./utils/consts')
@@ -59,6 +60,7 @@ const zipFunctions = async function (
     basePath,
     config = {},
     featureFlags: inputFeatureFlags,
+    manifest,
     parallelLimit = DEFAULT_PARALLEL_LIMIT,
   } = {},
 ) {
@@ -75,7 +77,7 @@ const zipFunctions = async function (
     // source directories.
     getPluginsModulesPath(srcFolders[0]),
   ])
-  const zipped = await pMap(
+  const results = await pMap(
     functions.values(),
     async (func) => {
       const zipResult = await func.runtime.zipFunction({
@@ -100,7 +102,13 @@ const zipFunctions = async function (
       concurrency: parallelLimit,
     },
   )
-  return zipped.filter(Boolean).map(formatZipResult)
+  const formattedResults = results.filter(Boolean).map(formatZipResult)
+
+  if (manifest !== undefined) {
+    await createManifest({ functions: formattedResults, path: resolve(manifest) })
+  }
+
+  return formattedResults
 }
 
 const zipFunction = async function (

tests/main.js

@@ -1,7 +1,7 @@
 const { readFile, chmod, symlink, unlink, rename, stat, writeFile } = require('fs')
 const { tmpdir } = require('os')
-const { dirname, join, normalize, resolve, sep } = require('path')
-const { env, platform } = require('process')
+const { dirname, isAbsolute, join, normalize, resolve, sep } = require('path')
+const { arch, env, platform } = require('process')
 const { promisify } = require('util')
 
 const test = require('ava')
@@ -1748,3 +1748,25 @@ if (platform !== 'win32') {
     )
   })
 }
+
+test('Creates a manifest file with the list of created functions if the `manifest` property is supplied', async (t) => {
+  const FUNCTIONS_COUNT = 6
+  const { path: tmpDir } = await getTmpDir({ prefix: 'zip-it-test' })
+  const manifestPath = join(tmpDir, 'manifest.json')
+  const { files } = await zipNode(t, 'many-functions', {
+    length: FUNCTIONS_COUNT,
+    opts: { manifest: manifestPath },
+  })
+
+  // eslint-disable-next-line import/no-dynamic-require, node/global-require
+  const manifest = require(manifestPath)
+
+  t.deepEqual(files, manifest.functions)
+  t.is(manifest.version, 1)
+  t.is(manifest.system.arch, arch)
+  t.is(manifest.system.platform, platform)
+  t.is(typeof manifest.timestamp, 'number')
+
+  // The `path` property of each function must be an absolute path.
+  manifest.functions.every(({ path }) => isAbsolute(path))
+})