Functions SDK v4 (#1161)

### Breaking Changes

- Deprecated `allowInvalidAppCheckToken` option. Instead use`enforceAppCheck`.
- App Check enforcement on callable functions is disabled by default in v4.
- Requests containing invalid App Check tokens won't be denied unless you
- explicitly enable App Check enforcement using the new `enforceAppCheck` option.
- Furthermore, when enforcement is enabled, callable functions will deny
- all requests without App Check tokens.

- Dropped support for Node.js versions 8, 10, and 12.
- Dropped support for Admin SDK versions 8 and 9.
- Removed the `functions.handler` namespace.
- `DataSnapshot` passed to the Firebase Realtime Database trigger now
  matches the `DataSnapshot` returned by the Admin SDK, with null values
  removed.
- Removed `__trigger` object on function handlers.
- Reorganized source code location. This affects only apps that directly import files instead of using the recommend entry points specified in the
- Reworked the `apps` library and removed `lodash` as a runtime dependency.
- Unspecified function configuration value will be reset to platform default. Use `preserveExternalChanges` to prevent this behavior.

### Enhancements

- Logs created with the `functions.logger` package in v2 functions
  are now annotated with each request's trace ID, making it easy to correlate
  log entries with the incoming request. Trace IDs are especially useful for
  cases where 2nd gen's concurrency feature permits a function
  to handle multiple requests at any given time. See
  [Correlate log entries](https://cloud.google.com/logging/docs/view/correlate-logs) to learn more.
- `functions.logger.error` now always outputs an error object and is included in Google Cloud Error Reporting.
- The logging severity of Auth/App Check token validation has changed from `info` to `debug` level.
- Event parameters for 2nd generation functions are now strongly typed, permitting stronger TypeScript types for matched parameters.
- Add new params package to support parameterized environment configuration. See https://firebase.google.com/docs/functions/config-env for more information.
- Add new `functions.RESET_VALUE` and `functions.v2.options.RESET_VALUE` sentinel value for explicitly resetting function configuration to platform default.
- Add new `preserveExternalChanges` option to prevent Firebase CLI from resetting unspecified configuration option to platform default

Author: taeold

.eslintignore

@@ -0,0 +1,11 @@
+lib
+dev
+node_modules
+/coverage/
+/docgen/
+/v1/
+/v2/
+/logger/
+/dist/
+/spec/fixtures
+/scripts/**/*.js

.eslintrc.js

@@ -0,0 +1,70 @@
+module.exports = {
+  env: {
+    es6: true,
+    node: true,
+  },
+  extends: [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/recommended-requiring-type-checking",
+    "plugin:jsdoc/recommended",
+    "google",
+    "prettier",
+  ],
+  rules: {
+    "jsdoc/newline-after-description": "off",
+    "jsdoc/require-jsdoc": ["warn", { publicOnly: true }],
+    "no-restricted-globals": ["error", "name", "length"],
+    "prefer-arrow-callback": "error",
+    "prettier/prettier": "error",
+    "require-atomic-updates": "off", // This rule is so noisy and isn't useful: https://github.com/eslint/eslint/issues/11899
+    "require-jsdoc": "off", // This rule is deprecated and superseded by jsdoc/require-jsdoc.
+    "valid-jsdoc": "off", // This is deprecated but included in recommended configs.
+
+    "no-prototype-builtins": "warn",
+    "no-useless-escape": "warn",
+    "prefer-promise-reject-errors": "warn",
+  },
+  overrides: [
+    {
+      files: ["*.ts"],
+      rules: {
+        "jsdoc/require-param-type": "off",
+        "jsdoc/require-returns-type": "off",
+
+        // Google style guide allows us to omit trivial parameters and returns
+        "jsdoc/require-param": "off",
+        "jsdoc/require-returns": "off",
+
+        "@typescript-eslint/no-invalid-this": "error",
+        "@typescript-eslint/no-unused-vars": "error", // Unused vars should not exist.
+        "@typescript-eslint/no-misused-promises": "warn", // rule does not work with async handlers for express.
+        "no-invalid-this": "off", // Turned off in favor of @typescript-eslint/no-invalid-this.
+        "no-unused-vars": "off", // Off in favor of @typescript-eslint/no-unused-vars.
+        eqeqeq: ["error", "always", { null: "ignore" }],
+        camelcase: ["error", { properties: "never" }], // snake_case allowed in properties iif to satisfy an external contract / style
+
+        // Ideally, all these warning should be error - let's fix them in  the future.
+        "@typescript-eslint/no-unsafe-argument": "warn",
+        "@typescript-eslint/no-unsafe-assignment": "warn",
+        "@typescript-eslint/no-unsafe-call": "warn",
+        "@typescript-eslint/no-unsafe-member-access": "warn",
+        "@typescript-eslint/no-unsafe-return": "warn",
+        "@typescript-eslint/restrict-template-expressions": "warn",
+      },
+    },
+    {
+      files: ["*.spec.*"],
+      env: {
+        mocha: true,
+      },
+      rules: {},
+    },
+  ],
+  globals: {},
+  parserOptions: {
+    project: "tsconfig.json",
+  },
+  plugins: ["prettier", "@typescript-eslint", "jsdoc"],
+  parser: "@typescript-eslint/parser",
+};

.github/ISSUE_TEMPLATE/---report-a-bug.md

@@ -1,9 +1,9 @@
 ---
-name: '⚠️ Report a Bug'
+name: "⚠️ Report a Bug"
 about: Think you found a bug in the firebase-functions SDK? Report it here. Please do not use this form if your function is deployed successfully but not working as you expected.
-title: ''
-labels: ''
-assignees: ''
+title: ""
+labels: ""
+assignees: ""
 ---
 
 <!-- DO NOT DELETE

.github/workflows/postmerge.yaml

@@ -16,7 +16,7 @@ name: Post-merge tests
 on:
   workflow_dispatch:
   workflow_run:
-    workflows: ['CI Tests']
+    workflows: ["CI Tests"]
     types: [completed]
     branches: [master]
 
@@ -38,16 +38,16 @@ jobs:
 
       - uses: google-github-actions/auth@v0
         with:
-          credentials_json: '${{ secrets.CF3_INTEGRATION_TEST_GOOGLE_CREDENTIALS }}'
+          credentials_json: "${{ secrets.CF3_INTEGRATION_TEST_GOOGLE_CREDENTIALS }}"
           create_credentials_file: true
 
-      - name: 'Set up Cloud SDK'
+      - name: "Set up Cloud SDK"
         uses: google-github-actions/setup-gcloud@v0
 
-      - name: 'Setup Firebase CLI'
+      - name: "Setup Firebase CLI"
         run: npm i -g firebase-tools
 
-      - name: 'Run integration test'
+      - name: "Run integration test"
         run: npm run test:postmerge
 
       - name: Print debug logs

.github/workflows/test.yaml

@@ -8,50 +8,59 @@ env:
   CI: true
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    strategy:
+      matrix:
+        node-version:
+          - "16"
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
   unit:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         node-version:
-          - 10.x
-          - 12.x
           - 14.x
           - 16.x
     steps:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
           node-version: ${{ matrix.node-version }}
-
       - name: Cache npm
         uses: actions/cache@v1
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('**/package-lock.json') }}
-
       - run: npm ci
-      - run: npm run lint
-      - run: npm run format
       - run: npm run test
   integration:
+    needs: "unit"
     runs-on: ubuntu-latest
     strategy:
       matrix:
         node-version:
-          - 12.x
           - 14.x
           - 16.x
     steps:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
           node-version: ${{ matrix.node-version }}
-
       - name: Cache npm
         uses: actions/cache@v1
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('**/package-lock.json') }}
-
-      - run: npm install
+      - run: npm ci
       - run: npm run test:bin

.mocharc.yaml

@@ -4,5 +4,5 @@ extension:
 package: ./package.json
 reporter: spec
 require:
-  - 'ts-node/register'
-  - 'source-map-support/register'
+  - "ts-node/register"
+  - "source-map-support/register"

.prettierignore

@@ -1,3 +1,4 @@
-lib
-package.json
-spec/fixtures/credential/unparsable.key.json
+/node_modules
+/lib/**/*
+/CONTRIBUTING.md
+/docgen

.prettierrc

@@ -0,0 +1,3 @@
+module.exports = {
+  printWidth: 100,
+};

.prettierrc.js

@@ -0,0 +1,32 @@
+### Breaking Changes
+
+- Deprecated `allowInvalidAppCheckToken` option. Instead use
+  `enforceAppCheck`.
+
+> App Check enforcement on callable functions is disabled by default in v4.
+> Requests containing invalid App Check tokens won't be denied unless you
+> explicitly enable App Check enforcement using the new `enforceAppCheck` option.
+> Furthermore, when enforcement is enabled, callable functions will deny
+> all requests without App Check tokens.
+
+- Dropped support for Node.js versions 8, 10, and 12.
+- Dropped support for Admin SDK versions 8 and 9.
+- Removed the `functions.handler` namespace.
+- `DataSnapshot` passed to the Firebase Realtime Database trigger now
+  matches the `DataSnapshot` returned by the Admin SDK, with null values
+  removed.
+- Removed `__trigger` object on function handlers.
+- Reorganized source code location. This affects only apps that directly import files instead of using the recommend entry points specified in the
+- Reworked the `apps` library and removed `lodash` as a runtime dependency.
+
+### Enhancements
+
+- Logs created with the `functions.logger` package in v2 functions
+  are now annotated with each request's trace ID, making it easy to correlate
+  log entries with the incoming request. Trace IDs are especially useful for
+  cases where 2nd gen's concurrency feature permits a function
+  to handle multiple requests at any given time. See
+  [Correlate log entries](https://cloud.google.com/logging/docs/view/correlate-logs) to learn more.
+- `functions.logger.error` now always outputs an error object and is included in Google Cloud Error Reporting.
+- The logging severity of Auth/App Check token validation has changed from `info` to `debug` level.
+- Event parameters for 2nd generation functions are now strongly typed, permitting stronger TypeScript types for matched parameters.

CHANGELOG.md

@@ -23,15 +23,13 @@ _Please avoid double posting across multiple channels!_
 
 ```js
 // functions/index.js
-const functions = require('firebase-functions');
-const notifyUsers = require('./notify-users');
-
-exports.newPost = functions.database
-  .ref('/posts/{postId}')
-  .onCreate((snapshot, context) => {
-    functions.logger.info('Received new post with ID:', context.params.postId);
-    return notifyUsers(snapshot.val());
-  });
+const functions = require("firebase-functions");
+const notifyUsers = require("./notify-users");
+
+exports.newPost = functions.database.ref("/posts/{postId}").onCreate((snapshot, context) => {
+  functions.logger.info("Received new post with ID:", context.params.postId);
+  return notifyUsers(snapshot.val());
+});
 ```
 
 ## Contributing