@pbvision/fastify-firestore-service 0.0.48 → 0.0.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pbvision/fastify-firestore-service",
-  "version": "0.0.48",
+  "version": "0.0.49",
   "description": "Web Framework using Fastify and Firestore ORM",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,11 +10,11 @@
   "exports": "./src/index.js",
   "scripts": {
     "build-doc": "./docs/build.sh",
-    "debug": "INDEBUGGER=1 ./node_modules/nodemon/bin/nodemon.js --no-lazy --legacy-watch --watch ./src --watch ./examples --watch ./test --inspect=9229 --experimental-vm-modules ./node_modules/jest/bin/jest.js --coverage --config=./jest.config.json --runInBand",
+    "debug": "GCLOUD_PROJECT=localhost-emulator INDEBUGGER=1 ./node_modules/nodemon/bin/nodemon.js --no-lazy --legacy-watch --watch ./src --watch ./examples --watch ./test --inspect=9229 --experimental-vm-modules ./node_modules/jest/bin/jest.js --coverage --config=./jest.config.json --runInBand",
     "setup": "yarn install --frozen-lockfile && pip install -r requirements.txt",
     "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 --experimental-vm-modules ./node_modules/jest/bin/jest.js --config=./jest.config.json --coverage"
+    "test-without-starting-db": "GCLOUD_PROJECT=localhost-emulator node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config=./jest.config.json --coverage"
   },
   "contributors": [
     "David Underhill",
@@ -42,7 +42,7 @@
     "@fastify/static": "^6.12",
     "@fastify/swagger": "^8.1.0",
     "@fastify/swagger-ui": "^2.0.1",
-    "@pbvision/firestore-orm": "^0.0.21",
+    "@pbvision/firestore-orm": "^0.0.22",
     "@sentry/node": "^7.91.0",
     "fastify": "^4.10.0",
     "fastify-plugin": "^4.5.1",

package/src/api/exception.js

@@ -181,6 +181,28 @@ class RequestError extends __RequestDone {
       data: this.data
     }
   }
+
+  /**
+   * Mark this error for rate-limited Sentry reporting. Useful when a known
+   * dependency outage causes the same error to fire repeatedly -- Cloud Tasks
+   * retries, etc. The HTTP response and logs are unaffected; only the Sentry
+   * report is throttled so the error budget doesn't get exhausted during the
+   * outage. Returns `this`, so it can be chained at the throw site:
+   *
+   *     throw new RequestError('failed to send email', { err }, 550)
+   *       .rateLimitSentry()
+   *
+   * Rate-limit keying follows the Sentry fingerprint we'd have used anyway
+   * (so Sentry grouping and our suppression agree on what "the same error" is).
+   *
+   * @param {Number} [windowMs=300000] rate-limit window in ms; at most one
+   *   Sentry report is sent per window per key (default 5 minutes).
+   * @returns {RequestError} this
+   */
+  rateLimitSentry (windowMs = 5 * 60 * 1000) {
+    this._sentryRateLimitMs = windowMs
+    return this
+  }
 }
 
 /**

package/src/make-app.js

@@ -31,6 +31,10 @@ const COOKIE_CONFIG = {
  *   of an error. Recommend to keep it off for remote testing, on for local
  *   testing.
  * @property {String} [sentryDSN] The Sentry DSN to report errors to
+ * @property {Object} [sentryRateLimiter] Optional rate limiter instance (from
+ *   {@link createSentryRateLimiter}) to control Sentry reporting for errors
+ *   flagged via `RequestError.rateLimitSentry()`. Defaults to a fresh limiter
+ *   using the real clock; tests inject one with a controllable clock.
  * @property {function} [customizePinoOpts] An optional function customize the
  *   arguments to pass to Pino. Takes as input the options that will be sent
  *   to be Pino by default (can be modified). Return the new options.
@@ -39,7 +43,8 @@ const LOGGING_CONFIG = {
   customizePinoOpts: null,
   reportAllErrors: false,
   reportErrorDetail: false,
-  sentryDSN: null
+  sentryDSN: null,
+  sentryRateLimiter: null
 }
 
 /**
@@ -205,6 +210,7 @@ export default async function makeService (params = {}) {
       errorHandler: {
         returnErrorDetail: logging.reportErrorDetail,
         sentryDSN: logging.sentryDSN,
+        sentryRateLimiter: logging.sentryRateLimiter,
         serverName: fastifyServerId,
         service
       }

package/src/plugins/error-handler.js

@@ -3,6 +3,7 @@ import * as Sentry from '@sentry/node'
 import fp from 'fastify-plugin'
 
 import { InvalidInputException, __RequestDone } from '../api/exception.js'
+import { createSentryRateLimiter } from './sentry-rate-limit.js'
 
 export default fp(function (fastify, options, next) {
   const isLocalhost = process.env.NODE_ENV === 'localhost'
@@ -17,6 +18,11 @@ export default fp(function (fastify, options, next) {
     serverName: options.errorHandler.serverName
   })
 
+  // Opt-in rate limiter: only errors flagged via RequestError.rateLimitSentry()
+  // consult this. See sentry-rate-limit.js for details.
+  const sentryRateLimiter = options.errorHandler.sentryRateLimiter ??
+    createSentryRateLimiter()
+
   const returnErrorDetail = options.errorHandler.returnErrorDetail
   // log any exception which occurs
   fastify.setErrorHandler(async (error, req, reply) => {
@@ -96,43 +102,63 @@ export default fp(function (fastify, options, next) {
       reply.log.info(errInfo)
     }
 
-    Sentry.withScope(function (scope) {
-      if (customFingerprint) {
-        scope.setFingerprint(customFingerprint)
-      }
-      const user = {}
-      // istanbul ignore if
-      if (req.headers['x-uid']) {
-        user.id = req.headers['x-uid']
-      } else {
-        user.ip = req.ip
-      }
-      scope.setLevel(isCrash ? 'error' : 'warning')
-      scope.setUser({
-        ...user,
-        ...(req.__sentry?.userInfo ?? {})
-      })
-      scope.setTags({
-        ...(req.__sentry?.tags ?? {}),
-        method: req.method,
-        url: req.url,
-        status: errInfo.status
+    // Check if this error is opted in to Sentry rate limiting; if so and we're
+    // inside the window, skip Sentry.captureException entirely. The HTTP
+    // response and logs are unaffected regardless.
+    let shouldCaptureToSentry = true
+    let suppressedCount = 0
+    const rateLimitMs = error._sentryRateLimitMs
+    if (rateLimitMs) {
+      const rlKey = customFingerprint || message
+      const rlResult = sentryRateLimiter.shouldReport(rlKey, rateLimitMs)
+      shouldCaptureToSentry = rlResult.report
+      suppressedCount = rlResult.suppressedCount
+    }
+
+    if (shouldCaptureToSentry) {
+      Sentry.withScope(function (scope) {
+        if (customFingerprint) {
+          scope.setFingerprint(customFingerprint)
+        }
+        const user = {}
+        // istanbul ignore if
+        if (req.headers['x-uid']) {
+          user.id = req.headers['x-uid']
+        } else {
+          user.ip = req.ip
+        }
+        scope.setLevel(isCrash ? 'error' : 'warning')
+        scope.setUser({
+          ...user,
+          ...(req.__sentry?.userInfo ?? {})
+        })
+        scope.setTags({
+          ...(req.__sentry?.tags ?? {}),
+          method: req.method,
+          url: req.url,
+          status: errInfo.status,
+          // Tag -- not extra -- so operators can filter Sentry for "issues
+          // where rate-limiting kicked in" during an outage.
+          ...(suppressedCount > 0
+            ? { suppressedSimilarEvents: String(suppressedCount) }
+            : {})
+        })
+        const customContexts = req.__sentry?.context ?? {}
+        for (const [k, v] of Object.entries(customContexts)) {
+          scope.setContext(k, v)
+        }
+        const extras = {
+          msg: errInfo.message,
+          reqId: req.id,
+          userAgent: req.headers['user-agent'] ?? 'not set'
+        }
+        if (error instanceof __RequestDone) {
+          extras.data = error.data
+        }
+        scope.setExtras(extras)
+        Sentry.captureException(error)
       })
-      const customContexts = req.__sentry?.context ?? {}
-      for (const [k, v] of Object.entries(customContexts)) {
-        scope.setContext(k, v)
-      }
-      const extras = {
-        msg: errInfo.message,
-        reqId: req.id,
-        userAgent: req.headers['user-agent'] ?? 'not set'
-      }
-      if (error instanceof __RequestDone) {
-        extras.data = error.data
-      }
-      scope.setExtras(extras)
-      Sentry.captureException(error)
-    })
+    }
 
     const errorData = error.respData ?? {
       code: error.constructor.name,

package/src/plugins/sentry-rate-limit.js

@@ -0,0 +1,37 @@
+/**
+ * Creates a rate limiter for Sentry event reporting, keyed by an arbitrary
+ * string (typically the Sentry fingerprint or error message). State lives in
+ * a Map per rate limiter instance: one instance per process is the expected
+ * usage.
+ *
+ * @param {Function} [nowFn=Date.now] clock function (injectable for tests)
+ * @returns {Object} rate limiter with one method, {@link shouldReport}.
+ */
+export function createSentryRateLimiter (nowFn = Date.now) {
+  const tracking = new Map()
+  return {
+    /**
+     * Record an event and decide whether it should be reported to Sentry.
+     *
+     * @param {String} key rate-limit key; typically the error fingerprint or
+     *   message so that Sentry grouping lines up with our suppression.
+     * @param {Number} windowMs rate-limit window in ms; within this window
+     *   after a report, subsequent events for the same key are suppressed.
+     * @returns {{report: Boolean, suppressedCount: Number}} when `report` is
+     *   true, `suppressedCount` is the number of events suppressed for this
+     *   key since the last report (0 if none were suppressed). When `report`
+     *   is false, `suppressedCount` is 0 (caller should not surface it).
+     */
+    shouldReport (key, windowMs) {
+      const now = nowFn()
+      const state = tracking.get(key)
+      if (state && now - state.lastReported < windowMs) {
+        state.suppressed++
+        return { report: false, suppressedCount: 0 }
+      }
+      const suppressedCount = state?.suppressed ?? 0
+      tracking.set(key, { lastReported: now, suppressed: 0 })
+      return { report: true, suppressedCount }
+    }
+  }
+}