@pbvision/cloud-run-service 0.0.1

package/.dockerignore

@@ -0,0 +1,10 @@
+.dockerignore
+.eslintrc.json
+.gcloudignore
+.git/
+.gitignore
+babel.config.cjs
+jest.config.json
+node_modules/
+README.md
+.vscode/

package/.eslintrc.json

@@ -0,0 +1,50 @@
+{
+    "root": true,
+    "env": {
+        "es2023": true,
+        "browser": false,
+        "commonjs": true,
+        "jest": true,
+        "node": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "standard",
+        "plugin:import/recommended",
+        "plugin:import/errors",
+        "plugin:import/warnings"
+    ],
+    "plugins": [
+        "import"
+    ],
+    "parser": "@babel/eslint-parser",
+    "rules": {
+        "import/order": [
+            "error",
+            {
+                "groups": [
+                    "builtin",
+                    "external",
+                    "parent",
+                    "sibling",
+                    "index"
+                ],
+                "alphabetize": {
+                    "order": "asc",
+                    "caseInsensitive": true
+                },
+                "newlines-between": "always"
+            }
+        ],
+        "no-var": "error",
+        "multiline-ternary": 1,
+        "object-shorthand": "error",
+        "import/no-unresolved": ["error", { "commonjs": true }]
+    },
+    "settings": {
+        "import/resolver": {
+            "node": {},
+            "webpack": {}
+        }
+    }
+}

package/.gcloudignore

@@ -0,0 +1,9 @@
+.eslintrc.json
+.gcloudignore
+.git/
+.gitignore
+.npmrc
+babel.config.cjs
+jest.config.json
+node_modules/
+.vscode/

package/.github/workflows/check-pr.yml

@@ -0,0 +1,35 @@
+name: Check PR
+on:
+  pull_request
+jobs:
+  check_pr:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: yarn install --frozen-lockfile
+        shell: bash
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - run: yarn lint
+        shell: bash
+      - name: 'Setup Firestore Emulator'
+        run: |
+          echo '{ "projects": { "default": "fake-for-testing-only" } }' > ./.firebaserc
+          echo '{ "firestore": {} }' > ./firebase.json
+          npm install -g firebase-tools
+          firebase setup:emulators:firestore
+        shell: bash
+      - name: 'Run unit tests'
+        run: |
+          echo 'yarn test-without-starting-db' > ./test.sh
+          chmod u+x ./test.sh
+          echo "process.env.FIRESTORE_EMULATOR_HOST = 'localhost:8080'" >> ./node_modules/@pbvision/firestore-orm/environment.js
+          firebase emulators:exec --only firestore ./test.sh
+        shell: bash

package/.github/workflows/publish-to-github-npm.yml

@@ -0,0 +1,42 @@
+name: Publish to PUBLIC NPM Package Registry
+on:
+  push:
+    branches: [main]
+jobs:
+  publish:
+    if: github.repository == 'pbv-public/cloud-run-service'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@pbvision'
+      - name: Publish
+        run: |
+          before=${{ github.event.before }}
+          after=${{ github.event.after }}
+          echo from ${before} to ${after}
+          zero='0000000000000000000000000000000000000000'
+          if [ "$before" = "$zero" ]; then
+            changed=1  # first push to this branch — always publish
+          else
+            git diff ${before} ${after} -- package.json | fgrep '"version": "' && changed=1 || changed=0
+          fi
+          if [ "$changed" = "1" ]; then
+            pkg=$(node -p "require('./package.json').name")
+            ver=$(node -p "require('./package.json').version")
+            if curl -fsS "https://registry.npmjs.org/${pkg}/${ver}" >/dev/null 2>&1; then
+              echo "${pkg}@${ver} already on npmjs, skipping publish"
+            else
+              npm publish --access public
+            fi
+          else
+            echo 'version was not changed; nothing to publish'
+          fi
+        shell: bash
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "standard.vscode-standard",
+        "streetsidesoftware.code-spell-checker",
+        "yzhang.markdown-all-in-one"
+    ]
+}

package/.vscode/settings.json

@@ -0,0 +1,36 @@
+{
+  "[javascript]": {
+    "editor.formatOnSave": false,
+    "editor.tabSize": 2
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.tabSize": 2
+  },
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.formatOnPaste": true
+  },
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.fixAll.markdownlint": "explicit"
+  },
+  "editor.rulers": [79],
+  "eslint.validate": ["javascript"],
+  "files.eol": "\n",
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+  "standard.autoFixOnSave": true,
+  "standard.usePackageJson": true,
+  "cSpell.words": [
+    "cloudtasks",
+    "esbenp",
+    "fastify",
+    "firestore",
+    "gserviceaccount",
+    "INDEBUGGER",
+    "oidc",
+    "pino"
+  ]
+}

package/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-slim
+
+WORKDIR /app
+
+# install production packages first
+COPY .npmrc package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --production
+
+ARG PROJECT
+ENV PROJECT=${PROJECT}
+ARG GIT_HASH
+ENV GIT_HASH=${GIT_HASH}
+
+# copy source files second (after dependencies are installed so rebuilds are
+# super fast whenever only the source code changes)
+COPY src ./src/
+RUN rm ./src/placeholder.js
+ENTRYPOINT [ "node", "src/main.js" ]

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,42 @@
+# Cloud Run Service library
+
+## Setup
+
+1. `yarn setup`
+1. Install recommended vscode extensions
+   - Open the Extensions tab in vscode
+   - In the filter box, type "@recommended" and press enter to search
+   - Make sure all recommended extensions are installed
+
+## Requirements
+
+- Must run with a service account named
+  `cr-${process.env.SERVICE}@${process.env.PROJECT}.iam.gserviceaccount.com`
+  with at least these permissions (along with whatever else your service
+  requires):
+  - `roles/run.invoker` - if the service needs to call other services
+  - `cloudtasks.tasks.create` - if the service needs to enqueue tasks
+    - roles/iam.serviceAccountUser - if the tasks need to be able to invoke an
+      internal cloud run service (i.e., one which restricts invokers to
+      specific service accounts, to include this service's account)
+
+- Environment variables:
+  - Required:
+    - `GIT_HASH` - the commit from which the current code was generated
+    - `K_REVISION` - provided by cloud run (the revision ID)
+      - Can be `localhost`
+    - `NODE_ENV`
+      - If this is `localhost` then `isLocalhost()` will return true.
+      - If this is `dev` then `isDev()` will return true.
+      - If this is `prod` then `isProd()` will return true.
+    - `PROJECT` - the project ID this service is running in
+      - Other endings are not allowed.
+    - `REGION` - the region this service's cloud run is located in
+    - `SERVICE` - the name of this service
+  - Optional:
+    - `CLOUD_RUN_HOSTNAME_SUFFIX` - the hostname of our cloud run instances in
+      this region, excluding the `SERVICE` name portion at the beginning. Only
+      required if using the `callServiceAPI()` function.
+    - `COOKIE_SECRET` - used to sign cookie data (cookies are disabled if omitted)
+    - `PORT` - defaults to 8080 if omitted
+    - `SENTRY_DSN` - the Sentry URL to report errors to (not used on localhost)

package/babel.config.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+  presets: [
+    [
+      '@babel/preset-env',
+      {
+        targets: {
+          node: '20'
+        }
+      }
+    ]
+  ]
+}

package/docs/cloudbuild/preview.example.yaml

@@ -0,0 +1,76 @@
+steps:
+  - id: set up npmrc for private package access
+    name: bash
+    args: ['-c', 'echo -e "//npm.pkg.github.com/:_authToken=$$GITHUB_TOKEN\n@your-org:registry=https://npm.pkg.github.com/" > .npmrc']
+    secretEnv: ['GITHUB_TOKEN']
+
+  - id: "build image"
+    name: "gcr.io/cloud-builders/docker"
+    args:
+      [
+        "build",
+        "--build-arg",
+        "PROJECT=$PROJECT_ID",
+        "--build-arg",
+        "GIT_HASH=$COMMIT_SHA",
+        "--tag",
+        "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/service-$_SERVICE_NAME:$_PR_NUMBER-$SHORT_SHA",
+        ".",
+      ]
+
+  - id: "push image"
+    name: "gcr.io/cloud-builders/docker"
+    args:
+      [
+        "push",
+        "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/service-$_SERVICE_NAME",
+        "--all-tags",
+      ]
+
+  - id: "deploy revision with tag"
+    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
+    entrypoint: "gcloud"
+    args:
+      [
+        "run",
+        "deploy",
+        "$_SERVICE_NAME",
+        "--platform",
+        "managed",
+        "--region",
+        "$_REGION",
+        "--tag",
+        "pr-$_PR_NUMBER",
+        "--allow-unauthenticated",
+        "--image",
+        "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/service-$_SERVICE_NAME:$_PR_NUMBER-$SHORT_SHA",
+        "--no-traffic",
+      ]
+
+  - id: "link revision on pull request"
+    name: "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/deployment-previews"
+    secretEnv: ["GITHUB_TOKEN"]
+    args:
+      [
+        "set",
+        "--project-id",
+        "${PROJECT_ID}",
+        "--region",
+        "$_REGION",
+        "--service",
+        "$_SERVICE_NAME",
+        "--pull-request",
+        "$_PR_NUMBER",
+        "--repo-name",
+        "$REPO_FULL_NAME",
+        "--commit-sha",
+        "$SHORT_SHA",
+      ]
+
+options:
+  logging: CLOUD_LOGGING_ONLY
+
+availableSecrets:
+  secretManager:
+    - versionName: projects/$PROJECT_ID/secrets/github_token/versions/latest
+      env: "GITHUB_TOKEN"

package/docs/cloudbuild/release.example.yaml

@@ -0,0 +1,74 @@
+steps:
+  - id: set up npmrc for private package access
+    name: bash
+    args: ['-c', 'echo -e "//npm.pkg.github.com/:_authToken=$$GITHUB_TOKEN\n@your-org:registry=https://npm.pkg.github.com/" > .npmrc']
+    secretEnv: ['GITHUB_TOKEN']
+
+  - id: "build image"
+    name: "gcr.io/cloud-builders/docker"
+    args:
+      [
+        "build",
+        "--build-arg",
+        "PROJECT=$PROJECT_ID",
+        "--build-arg",
+        "GIT_HASH=$COMMIT_SHA",
+        "--tag",
+        "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/service-$_SERVICE_NAME:$COMMIT_SHA",
+        "--tag",
+        "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/service-$_SERVICE_NAME:latest",
+        ".",
+      ]
+
+  - id: "push image"
+    name: "gcr.io/cloud-builders/docker"
+    args:
+      [
+        "push",
+        "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/service-$_SERVICE_NAME",
+        "--all-tags",
+      ]
+
+  - id: "deploy revision with tag"
+    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
+    entrypoint: "gcloud"
+    args:
+      [
+        "run",
+        "deploy",
+        "$_SERVICE_NAME",
+        "--platform",
+        "managed",
+        "--region",
+        "$_REGION",
+        "--tag",
+        "sha-$SHORT_SHA",
+        "--allow-unauthenticated",
+        "--image",
+        "$_REGION-docker.pkg.dev/$PROJECT_ID/docker-repo/service-$_SERVICE_NAME:$COMMIT_SHA",
+      ]
+
+  # Force the new revision to serve 100% of traffic.
+  - id: "ensure prod service live"
+    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
+    entrypoint: "gcloud"
+    args:
+      [
+        "run",
+        "services",
+        "update-traffic",
+        "$_SERVICE_NAME",
+        "--to-latest",
+        "--platform",
+        "managed",
+        "--region",
+        "$_REGION",
+      ]
+
+options:
+  logging: CLOUD_LOGGING_ONLY
+
+availableSecrets:
+  secretManager:
+    - versionName: projects/$PROJECT_ID/secrets/github_token/versions/latest
+      env: "GITHUB_TOKEN"

package/jest.config.json

@@ -0,0 +1,24 @@
+{
+  "collectCoverageFrom": ["<rootDir>/src/**/*.js"],
+  "coverageDirectory": "/tmp/coverage",
+  "coverageReporters": ["lcov", "text", "json"],
+  "coverageThreshold": {
+    "global": {
+      "branches": 100,
+      "functions": 100,
+      "lines": 100,
+      "statements": 100
+    }
+  },
+  "roots": ["<rootDir>/src", "<rootDir>/test"],
+  "modulePathIgnorePatterns": ["node_modules"],
+  "testPathIgnorePatterns": ["node_modules"],
+  "testMatch": ["<rootDir>/test/*(*/)unit-test*.js"],
+  "reporters": [
+    "@pbvision/jest-unit-test/src/custom-reporter.js",
+    "@pbvision/jest-unit-test/src/summary-reporter.js"
+  ],
+  "watchPathIgnorePatterns": ["node_modules"],
+  "verbose": false,
+  "noStackTrace": false
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@pbvision/cloud-run-service",
+  "version": "0.0.1",
+  "description": "fastify-firestore-service Web Framework on Cloud Run",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": "./src/index.js",
+  "scripts": {
+    "coverage": "yarn -s start-local-db && yarn -s test --coverage",
+    "debug": "yarn -s start-local-db && INDEBUGGER=1 NODE_ENV=localhost PORT=8080 K_REVISION=unittest REGION=us-central1 PROJECT=xyz-dev GIT_HASH=`git rev-parse HEAD` SERVICE=tbd ./node_modules/nodemon/bin/nodemon.js --no-lazy --legacy-watch --watch ./src --watch ./test --inspect=9229 node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config=./jest.config.json --runInBand",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
+    "setup": "yarn install --frozen-lockfile",
+    "start-docker": "wd=`pwd`; tag=`basename $wd`; docker build --build-arg PROJECT=xyz-dev --build-arg GIT_HASH=`git rev-parse HEAD` . --tag $tag && docker run -p 127.0.0.1:8080:8080/tcp --env REGION us-central1 --env PORT=8080 --env K_REVISION=localhost --env SERVICE=tbd $tag:latest",
+    "start-local-db": "./node_modules/@pbvision/firestore-orm/scripts/start-local-db.sh",
+    "test": "yarn -s start-local-db && yarn -s test-without-starting-db",
+    "test-without-starting-db": "NODE_ENV=localhost PORT=8080 K_REVISION='unittest' REGION=us-central1 PROJECT=xyz-dev GIT_HASH=`git rev-parse HEAD` SERVICE=tbd node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config=./jest.config.json",
+    "start-local": "yarn -s start-local-db && FIRESTORE_EMULATOR_HOST=[::1]:8404 NODE_ENV=localhost PROJECT=xyz-dev REGION=us-central1 PORT=8080 K_REVISION=localhost PROJECT=xyz-dev GIT_HASH=`git rev-parse HEAD` node src/main.js",
+    "watch": "yarn -s test --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pbv-public/cloud-run-service"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@google-cloud/tasks": "^4.0.1",
+    "@pbvision/fastify-firestore-service": "^0.0.19",
+    "google-auth-library": "^9.4.2"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.17.12",
+    "@babel/eslint-parser": "^7.17.0",
+    "@babel/preset-env": "^7.17.12",
+    "@pbvision/jest-unit-test": "^0.2.3",
+    "babel-loader": "^9.1.3",
+    "eslint": "^8.22.0",
+    "eslint-config-standard": "17.1.0",
+    "eslint-import-resolver-webpack": "^0.13.8",
+    "eslint-plugin-import": "^2.22.0",
+    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^6.0.0",
+    "jest": "^29.7.0",
+    "standard": "^17.1.0",
+    "superagent": "^8",
+    "superagent-defaults": "^0.1.14",
+    "supertest": "^6.3.4",
+    "webpack": "^5.89.0"
+  },
+  "standard": {
+    "envs": [
+      "jest"
+    ],
+    "globals": [
+      "fail"
+    ],
+    "ignore": [
+      "**/node_modules/**"
+    ],
+    "parser": "@babel/eslint-parser"
+  }
+}

package/src/app.js

@@ -0,0 +1,32 @@
+import { makeService } from '@pbvision/fastify-firestore-service'
+
+import { port } from './port.js'
+import { isProd } from './utils.js'
+
+export async function makePBVService (components, customizePinoOpts) {
+  const isProdEnv = isProd()
+  return makeService({
+    service: process.env.SERVICE,
+    components,
+    cookie: {
+      secret: process.env.COOKIE_SECRET
+    },
+    healthCheck: {
+      path: '/_healthcheck'
+    },
+    latencyTracker: {
+      disabled: isProdEnv
+    },
+    logging: {
+      customizePinoOpts,
+      reportErrorDetail: !isProdEnv,
+      reportAllErrors: true,
+      sentryDSN: process.env.sentryDSN
+    },
+    swagger: {
+      disabled: isProdEnv,
+      servers: [`http://localhost:${port}`],
+      routePrefix: '/app/docs'
+    }
+  })
+}

package/src/call-service-api.js

@@ -0,0 +1,27 @@
+// add helper method to call APIs on this or other services; if the service is
+// internal then we'll make the request with our authorization token (only
+// works if this service has been granted access to the target service!)
+import { GoogleAuth } from 'google-auth-library'
+
+import { getServiceHost } from './utils.js'
+
+const auth = new GoogleAuth()
+
+// This function will be added to the API class.
+export async function callServiceAPI ({
+  path, service: serviceName,
+  body = undefined, qsParams = undefined,
+  method = 'POST', headers = {}, isServiceInternal = true
+}) {
+  const host = getServiceHost(serviceName)
+  // istanbul ignore next
+  const protocol = host === 'localhost' ? 'https' : 'http'
+  const url = `${protocol}://${host}${path}`
+  if (isServiceInternal) {
+    const targetAudience = `https://${host}/`
+    const client = await auth.getIdTokenClient(targetAudience)
+    const token = await client.idTokenProvider.fetchIdToken(targetAudience)
+    headers.Authorization = `Bearer ${token}`
+  }
+  return this.callAPI({ method, headers, url, body, qsParams })
+}

package/src/index.js

@@ -0,0 +1,9 @@
+import { runService } from './main.js'
+import { enqueueCloudTask } from './tasks.js'
+import * as utils from './utils.js'
+
+export {
+  enqueueCloudTask,
+  runService,
+  utils
+}

package/src/main.js

@@ -0,0 +1,82 @@
+import assert from 'node:assert'
+
+import { API } from '@pbvision/fastify-firestore-service'
+
+import { makePBVService } from './app.js'
+import { callServiceAPI } from './call-service-api.js'
+import { port } from './port.js'
+
+API.prototype.callServiceAPI = callServiceAPI
+
+let service
+const project = process.env.PROJECT
+
+function verifyEnvironmentVariables () {
+  const requiredEnvKeys = [
+    'GIT_HASH', 'K_REVISION', 'NODE_ENV', 'PROJECT', 'REGION', 'SERVICE']
+  for (const k of requiredEnvKeys) {
+    assert(process.env[k], `${k} environment variable must be set`)
+  }
+  assert(['localhost', 'dev', 'prod'].indexOf(process.env.NODE_ENV) !== -1,
+    `invalid NODE_ENV: ${process.env.NODE_ENV}`)
+}
+
+function makeCustomizeLoggingOptionsFunction () {
+  return options => {
+    options.formatters = {
+      level (label) {
+        return { severity: label }
+      },
+      // set messageKey to "message" for automatic parsing by GCP logs
+      messageKey: 'message'
+    }
+    const originalReqSerializer = options.serializers.req
+    options.serializers.req = req => {
+      const reqLog = originalReqSerializer(req)
+
+      // include the trace ID so logging can coordinate multiple logs from the
+      // same request per: https://github.com/GoogleCloudPlatform/cloud-run-microservice-template-nodejs/blob/main/utils/logging.js
+      const traceHeader = req.headers['X-Cloud-Trace-Context']
+      let trace
+      // istanbul ignore if
+      if (traceHeader) {
+        const [traceId] = traceHeader.split('/')
+        trace = `projects/${project}/traces/${traceId}`
+        reqLog['logging.googleapis.com/trace'] = trace
+      }
+      return reqLog
+    }
+    return options
+  }
+}
+
+export async function makeService (components = {}) {
+  verifyEnvironmentVariables()
+  return makePBVService(components, makeCustomizeLoggingOptionsFunction())
+}
+
+// istanbul ignore next
+export async function runService (components) {
+  if (process.env.K_REVISION !== 'unittest') {
+    // if the instance tells us it will shutdown, try to shut down gracefully (for
+    // example flushing logs)
+    process.on('SIGTERM', () => {
+      if (!service) {
+        return
+      }
+      // cloud run sends SIGTERM 10sec before killing the instance, so give the
+      // instance a little more time to finish any current requests then close
+      // the fastify instance (which kills any remaining requests, and should
+      // flush the logs and other clean up, if time permits)
+      setTimeout(() =>
+        service.close().then(() => {
+          console.log('successfully closed!')
+        }, (err) => {
+          console.log('an error happened', err)
+        }), 7000)
+    })
+    // start the server
+    service = await makeService(components)
+    service.listen({ port, host: '0.0.0.0' })
+  }
+}

package/src/placeholder.js

@@ -0,0 +1,37 @@
+// APIs in this file are not included in Docker builds so they never are
+// shipped to Cloud Run. They only exist for local testing.
+import assert from 'node:assert'
+
+import { API } from '@pbvision/fastify-firestore-service'
+import S from '@pbvision/schema'
+
+import { isUnitTesting, now } from './utils.js'
+
+export class TestAPI extends API {
+  static METHOD = 'GET'
+  static PATH = '/time'
+  static DESC = 'Just for testing'
+  static RESPONSE = {
+    epoch: S.int
+  }
+
+  async computeResponse () {
+    return { epoch: now() }
+  }
+}
+
+export class TestCallServiceAPI extends API {
+  static PATH = '/callService'
+  static DESC = 'This is used by unit tests only to test callServiceAPI.'
+  static BODY = S.obj()
+  static RESPONSE = { code: S.int, body: S.str }
+
+  async computeResponse () {
+    assert(isUnitTesting())
+    const resp = await this.callServiceAPI(this.req.body)
+    return {
+      code: resp.code,
+      body: typeof resp.data === 'object' ? JSON.stringify(resp.data) : (resp.data ?? '')
+    }
+  }
+}

package/src/port.js

@@ -0,0 +1,2 @@
+// istanbul ignore next
+export const port = process.env.PORT ?? 8080

package/src/tasks.js

@@ -0,0 +1,72 @@
+import { CloudTasksClient } from '@google-cloud/tasks'
+
+import { getServiceHost } from './utils.js'
+
+const tasksClient = new CloudTasksClient()
+
+/**
+ * Add a Task to a Cloud Tasks queue.
+ *
+ * The task will be routed to the internal API service on a path that matches
+ * the queue name (with hyphens replaced by underscores).
+ *
+ * @param {Object} task the task to enqueue
+ * @param {string} queue the name of the queue to add the task to
+ * @param {any} payload the data to convert to JSON add send as the task's body
+ * @param {string} [name] if provided, a name that is reused (on the same queue)
+ *   within about an hour will be rejected (TaskNameAlreadyExistsError)
+ * @param {string} [service="internal"] the service name that the task request
+ *   will be routed to
+ * @param {boolean} [ignoreNameAlreadyUsedError=false] if true, no error is
+ *   thrown due to a name already having been used
+ * @returns {boolean} true if a new task was added; false if the task name was
+ *   already recently used (no new task added, but a task was recently added
+ *   with this name)
+ */
+export async function enqueueCloudTask ({
+  queue, payload,
+  service = 'internal',
+  name = undefined, ignoreNameAlreadyUsedError = false
+}) {
+  const parent = tasksClient.queuePath(
+    process.env.PROJECT, process.env.REGION, queue)
+  const task = {
+    httpRequest: {
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      httpMethod: 'POST',
+      url: `https://${getServiceHost(service)}/${queue.replace(/-/g, '_')}`,
+      body: Buffer.from(JSON.stringify(payload)).toString('base64'),
+      oidcToken: {
+        serviceAccountEmail: `cr-${process.env.SERVICE}@${process.env.PROJECT}.iam.gserviceaccount.com`
+      }
+    }
+  }
+  if (name) {
+    const fqName = tasksClient.taskPath(process.env.PROJECT, process.env.REGION, queue, name)
+    task.name = fqName
+  }
+  const request = { parent, task }
+  try {
+    await tasksClient.createTask(request)
+    return true
+  } catch (e) {
+    if (e.code === 6 && e.message.startsWith('6 ALREADY_EXISTS')) {
+      if (ignoreNameAlreadyUsedError) {
+        return false
+      } else {
+        throw new TaskNameAlreadyExistsError(name, e)
+      }
+    }
+    throw e
+  }
+}
+
+export class TaskNameAlreadyExistsError extends Error {
+  constructor (name, e) {
+    super(`task name already used recently: ${name}`)
+    this.taskName = name
+    this.originalError = e
+  }
+}

package/src/utils.js

@@ -0,0 +1,40 @@
+import assert from 'node:assert'
+
+import { port as portForThisService } from './port.js'
+
+export function getServiceHost (serviceName) {
+  if (isLocalhost()) {
+    if (process.env.SERVICE === serviceName) {
+      return `localhost:${portForThisService}`
+    }
+    const portMapping = JSON.parse(process.env.LOCAL_SERVICE_PORT_MAP ?? 'null')
+    const port = portMapping[serviceName]
+    assert(port, `unknown service or missing port for localhost ${serviceName}`)
+    return `localhost:${port}`
+  } else {
+    return serviceName + process.env.CLOUD_RUN_HOSTNAME_SUFFIX
+  }
+}
+
+export function isLocalhost () {
+  assert(process.env.NODE_ENV)
+  return process.env.NODE_ENV === 'localhost'
+}
+
+export function isUnitTesting () {
+  const ret = process.env.K_REVISION === 'unittest'
+  assert(!ret || isLocalhost(), 'must on localhost if in unit tests')
+  return ret
+}
+
+export function isProd () {
+  assert(process.env.NODE_ENV)
+  return process.env.NODE_ENV === 'prod'
+}
+
+export function isDev () {
+  assert(process.env.NODE_ENV)
+  return process.env.NODE_ENV === 'dev'
+}
+
+export const now = () => Math.floor(new Date().getTime() / 1000)

package/test/base-test.js

@@ -0,0 +1,13 @@
+import { BaseAppTest, BaseTest, runTests } from '../node_modules/@pbvision/fastify-firestore-service/test/base-test.js'
+const { TestAPI, TestCallServiceAPI } = await import('../src/placeholder.js')
+
+export {
+  BaseTest, runTests
+}
+
+export class AppTest extends BaseAppTest {
+  async getMakeServiceFunc () {
+    const { makeService } = await import('../src/main.js')
+    return () => makeService({ TestAPI, TestCallServiceAPI })
+  }
+}

package/test/unit-test-call-service-api.js

@@ -0,0 +1,96 @@
+import { jest } from '@jest/globals'
+import { GoogleAuth } from 'google-auth-library'
+
+import { AppTest, runTests } from './base-test.js'
+
+class TestCallServiceAPI extends AppTest {
+  async beforeAll () {
+    await super.beforeAll()
+
+    // mock GoogleAuth because we can't actually get a token during testing
+    this.fetchIdToken = jest.fn().mockReturnValue('fake-token')
+    jest.spyOn(GoogleAuth.prototype, 'getIdTokenClient').mockImplementation(() => ({
+      idTokenProvider: {
+        fetchIdToken: this.fetchIdToken
+      }
+    }))
+  }
+
+  async beforeEach () {
+    await super.beforeEach()
+    // mock using node-fetch to request an API
+    this.fetchMock.mockResp()
+    this.fetchIdToken.mockClear()
+    GoogleAuth.prototype.getIdTokenClient.mockClear()
+  }
+
+  async afterAll () {
+    await super.afterAll()
+    jest.restoreAllMocks()
+  }
+
+  async check (args, respBody = '', expCode = 200, expPort = 8080) {
+    const result = await this.app.post('/callService').send(args).expect(200)
+    const resp = result.body
+    expect(resp.code).toBe(expCode)
+    expect(resp.body).toEqual(respBody)
+
+    const shouldHaveToken = args.isServiceInternal ?? true
+    const expHeaders = args.headers ?? {}
+    if (shouldHaveToken) {
+      expHeaders.Authorization = 'Bearer fake-token'
+    }
+    expect(this.fetchMock).toHaveBeenCalledWith(
+      `http://localhost:${expPort}${args.path}`, {
+        body: args.body,
+        headers: expHeaders,
+        method: args.method ?? 'POST',
+        compress: false
+      })
+
+    // make sure Google Auth was called with appropriate arguments (or not, if
+    // this wasn't an internal call)
+    if (shouldHaveToken) {
+      const targetAudience = `https://localhost:${expPort}/`
+      expect(GoogleAuth.prototype.getIdTokenClient).toHaveBeenCalledWith(targetAudience)
+      expect(this.fetchIdToken).toHaveBeenCalledWith(targetAudience)
+    } else {
+      expect(GoogleAuth.prototype.getIdTokenClient).not.toHaveBeenCalled()
+    }
+  }
+
+  async testServiceCallingItsOwnInternalAPI () {
+    await this.check({
+      service: process.env.SERVICE,
+      path: '/someAPI',
+      isServiceInternal: true
+    })
+  }
+
+  async testServiceCallingItsOwnPublicAPI () {
+    await this.check({
+      service: process.env.SERVICE,
+      path: '/someAPI',
+      isServiceInternal: false
+    })
+  }
+
+  async testServiceCallingAnotherOneOfItsAPIs () {
+    this.fetchMock.mockResp({ x: 3 })
+    await this.check({
+      service: process.env.SERVICE,
+      path: '/x/y/z'
+    }, JSON.stringify({ x: 3 }))
+  }
+
+  async testServiceCallingAnotherService () {
+    process.env.LOCAL_SERVICE_PORT_MAP = JSON.stringify({ notMe: 9999 })
+    this.fetchMock.mockResp('test resp', 222)
+    await this.check({
+      service: 'notMe',
+      path: '/x'
+    }, 'test resp', 222, 9999)
+  }
+}
+
+runTests(TestCallServiceAPI)

package/test/unit-test-placeholder.js

@@ -0,0 +1,10 @@
+import { AppTest, runTests } from './base-test'
+
+class PlaceholderTest extends AppTest {
+  async testTime () {
+    const ret = await this.app.get('/time').expect(200)
+    expect(Object.keys(ret.body)).toEqual(['epoch'])
+  }
+}
+
+runTests(PlaceholderTest)

package/test/unit-test-tasks.js

@@ -0,0 +1,104 @@
+import { CloudTasksClient } from '@google-cloud/tasks'
+import { jest } from '@jest/globals'
+
+import { enqueueCloudTask } from '../src/tasks.js'
+
+import { BaseTest, runTests } from './base-test.js'
+
+class TestTasks extends BaseTest {
+  async beforeAll () {
+    await super.beforeAll()
+
+    process.env.LOCAL_SERVICE_PORT_MAP = JSON.stringify({ internal: 8888 })
+
+    // mock GoogleAuth because we can't actually get a token during testing
+    this.createTaskReturnValue = new Promise(resolve => resolve())
+    jest.spyOn(CloudTasksClient.prototype, 'createTask').mockImplementation(
+      () => this.createTaskReturnValue)
+  }
+
+  async beforeEach () {
+    await super.beforeEach()
+    CloudTasksClient.prototype.createTask.mockClear()
+  }
+
+  async afterAll () {
+    await super.afterAll()
+    jest.restoreAllMocks()
+  }
+
+  async check (args, taskExpectations = {}, expRejectionMsg = null) {
+    const promise = enqueueCloudTask({
+      queue: 'test-queue',
+      ...args
+    })
+    if (expRejectionMsg) {
+      await expect(promise).rejects.toThrow(expRejectionMsg)
+    } else {
+      await promise
+    }
+    expect(CloudTasksClient.prototype.createTask).toHaveBeenCalledWith({
+      // assuming values for project (xyz-dev) and region (us-central1) and
+      // service (tbd)
+      parent: 'projects/xyz-dev/locations/us-central1/queues/test-queue',
+      task: {
+        httpRequest: {
+          body: Buffer.from(JSON.stringify(args.payload)).toString('base64'),
+          headers: { 'Content-Type': 'application/json' },
+          httpMethod: 'POST',
+          oidcToken: {
+            serviceAccountEmail: 'cr-tbd@xyz-dev.iam.gserviceaccount.com'
+          },
+          url: 'https://localhost:8888/test_queue'
+        },
+        ...taskExpectations
+      }
+    })
+  }
+
+  async testEnqueueTask () {
+    await this.check({ payload: { x: 3 } })
+  }
+
+  async testEnqueueTaskWithName () {
+    await this.check(
+      { name: 'x', payload: { x: 3 } },
+      { name: 'projects/xyz-dev/locations/us-central1/queues/test-queue/tasks/x' })
+  }
+
+  async testEnqueueTaskWithNameThatWasRecentlyUsedNOTOkay () {
+    this.createTaskReturnValue = new Promise((resolve, reject) => {
+      const err = new Error('6 ALREADY_EXISTS and other random details')
+      err.code = 6
+      reject(err)
+    })
+    await this.check(
+      { name: 'x', payload: { x: 3 }, ignoreNameAlreadyUsedError: true },
+      { name: 'projects/xyz-dev/locations/us-central1/queues/test-queue/tasks/x' })
+  }
+
+  async testEnqueueTaskWithNameThatWasRecentlyUsedAndThatsOkay () {
+    this.createTaskReturnValue = new Promise((resolve, reject) => {
+      const err = new Error('6 ALREADY_EXISTS and other random details')
+      err.code = 6
+      reject(err)
+    })
+    await this.check(
+      { name: 'x', payload: { x: 3 } },
+      { name: 'projects/xyz-dev/locations/us-central1/queues/test-queue/tasks/x' },
+      'task name already used recently: x')
+  }
+
+  async testEnqueueTaskThrowsUnknownExceptions () {
+    this.createTaskReturnValue = new Promise((resolve, reject) => {
+      const err = new Error('ALREADY_EXISTS but not in right format')
+      reject(err)
+    })
+    await this.check(
+      { name: 'x', payload: { x: 3 } },
+      { name: 'projects/xyz-dev/locations/us-central1/queues/test-queue/tasks/x' },
+      'not in right format')
+  }
+}
+
+runTests(TestTasks)

package/test/unit-test-utils.js

@@ -0,0 +1,51 @@
+import { jest } from '@jest/globals'
+
+import { BaseTest, runTests } from '../node_modules/@pbvision/fastify-firestore-service/test/base-test.js'
+import { port } from '../src/port.js'
+import { getServiceHost, isDev, isLocalhost, isProd } from '../src/utils.js'
+
+const ORIG_ENV = process.env
+
+class TestUtils extends BaseTest {
+  beforeEach () {
+    jest.resetModules()
+    process.env = { ...ORIG_ENV }
+  }
+
+  afterEach () {
+    process.env = ORIG_ENV
+  }
+
+  testEnv () {
+    expect(process.env.K_REVISION).toBe('unittest')
+    expect(process.env.NODE_ENV).toBe('localhost')
+    expect(isLocalhost()).toBe(true)
+    expect(isProd()).toBe(false)
+    expect(isDev()).toBe(false)
+
+    process.env.NODE_ENV = 'dev'
+    expect(isLocalhost()).toBe(false)
+    expect(isProd()).toBe(false)
+    expect(isDev()).toBe(true)
+
+    process.env.NODE_ENV = 'prod'
+    expect(isLocalhost()).toBe(false)
+    expect(isProd()).toBe(true)
+    expect(isDev()).toBe(false)
+  }
+
+  testGetServiceHost () {
+    expect(getServiceHost(process.env.SERVICE)).toBe(`localhost:${port}`)
+    expect(() => getServiceHost('unknown')).toThrow()
+    process.env.LOCAL_SERVICE_PORT_MAP = JSON.stringify({ unknown: 8088 })
+    expect(getServiceHost('unknown')).toBe('localhost:8088')
+    expect(() => getServiceHost('actually_unknown')).toThrow()
+
+    process.env.NODE_ENV = 'dev'
+    const testSuffix = '-tbd-uc.a.run.app'
+    process.env.CLOUD_RUN_HOSTNAME_SUFFIX = testSuffix
+    expect(getServiceHost('unknown')).toBe('unknown' + testSuffix)
+  }
+}
+
+runTests(TestUtils)