@pbvision/fastify-firestore-service 0.0.3

package/src/make-logger.js

@@ -0,0 +1,119 @@
+// istanbul ignore file
+import querystring from 'node:querystring'
+
+import pino from 'pino'
+import wrap from 'word-wrap'
+
+// for unit testing, output to the console INSTEAD of to stdout
+// via pino (so that jest captures the output and groups it with the right test
+// suite)
+function getUnitTestLogFormatOverrides () {
+  const prefixText = '/' + process.env.SERVICE + '/src/'
+  function prettifier () {
+    return (obj) => {
+      if (obj.req) {
+        const indent = ''
+        if (!obj.status) {
+          console.log(indent, obj.req.method, obj.req.path)
+        } else {
+          // output the status code and (if any) error message
+          const msgs = wrap(obj.msg || '', { width: 80, indent }).split('\n')
+          console.log(indent, ' \u2514 HTTP', obj.status, msgs[0])
+          msgs.slice(1).forEach(msg => {
+            console.log(indent, msg)
+          })
+          if (obj.error && obj.status >= 500) {
+            console.log(`${indent}Error: ${JSON.stringify(obj.error, null, 2)}`)
+          }
+          if (obj.stack) {
+            for (let i = 0; i < obj.stack.length; i++) {
+              console.log('  ', obj.stack[i])
+            }
+          }
+        }
+      } else {
+        // 1) Get the filename and line number the log message is from
+        // the index of the first non-pino line may change in future versions
+        // of fastify or pino; might be better to search each line until we
+        // find /<service>/src (if present)
+        const firstNonPinoLine = (new Error()).stack.split('\n')[5]
+        const appFolderIdx = firstNonPinoLine.indexOf(prefixText)
+        let prefix = ''
+        if (appFolderIdx !== -1) {
+          // prefix log message with filename and line number when logs
+          // originated in our app's source code
+          prefix = firstNonPinoLine.substring(
+            appFolderIdx + 9,
+            firstNonPinoLine.lastIndexOf(':')) + '  '
+        }
+
+        // 2) Create the logm msg: file, line, log message and log object
+        const indent = '  \u2502 '
+        const logObj = {}
+        const ignoredKeys = ['level', 'msg', 'reqId', 'time', 'v']
+        Object.getOwnPropertyNames(obj).forEach(key => {
+          if (ignoredKeys.indexOf(key) === -1) {
+            logObj[key] = obj[key]
+          }
+        })
+        let msg = indent + prefix + (obj.msg || '')
+        if (Object.keys(logObj).length) {
+          msg += (obj.msg ? ' ' : '') + JSON.stringify(logObj)
+        }
+        if (obj.level < 30) {
+          console.debug(msg)
+        } else if (obj.level >= 50) {
+          console.error(msg)
+        } else if (obj.level >= 40) {
+          console.warn(msg)
+        } else {
+          console.log(msg)
+        }
+      }
+      return '' // skip pino logging
+    }
+  }
+  return {
+    prettifier,
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true
+      }
+    }
+  }
+}
+
+export default function makeCustomLogger (useUnitTestLogFormat) {
+  function serializeReq (req) {
+    const q = req.query
+    if (req.raw) {
+      req = req.raw
+    }
+    const path = req.path
+    const qs = req.qs
+    return {
+      app: req.headers['x-app'] || '',
+      uid: req.headers['x-uid'] || '',
+      method: req.method,
+      ua: req.headers['user-agent'] || '',
+      path,
+      q: q || querystring.decode(qs)
+    }
+  }
+  const options = {
+    base: null, // omit pino default fields like pid and hostname
+    level: (process.env.NODE_ENV === 'prod') ? 'info' : 'debug',
+    serializers: {
+      req: serializeReq,
+      res: (res) => {
+        return { status: res.statusCode, req: serializeReq(res.req) }
+      }
+    }
+  }
+  // on localhost, we customize the logs to optimize for console-based debugging
+  if (useUnitTestLogFormat) {
+    Object.assign(options, getUnitTestLogFormatOverrides())
+  }
+  return pino(options)
+}

package/src/plugins/compress.js

@@ -0,0 +1,28 @@
+// eslint babel made changes to chained expressions which is breaking ast-types
+// https://github.com/babel/babel/issues/11908
+
+// ast-types has a fix, but it is not yet in a versioned release
+// https://github.com/benjamn/ast-types/pull/399
+
+// to circumvent problems caused by importing zlib, we do it in a separate file
+// so we can ignore it in linting
+import zlib from 'node:zlib'
+
+import { fastifyCompress } from '@fastify/compress'
+import fp from 'fastify-plugin'
+
+// TODO: fine tune configurations once we have a reliable usage pattern
+export default fp(function (fastify, options, next) {
+  fastify.register(fastifyCompress, {
+    threshold: 20,
+    brotliOptions: {
+      params: {
+        [zlib.constants.BROTLI_PARAM_QUALITY]: 4
+      }
+    }
+  })
+  next()
+}, {
+  fastify: '>=3.x',
+  name: 'compress'
+})

package/src/plugins/content-parser.js

@@ -0,0 +1,21 @@
+import fp from 'fastify-plugin'
+
+function addContentParser (fastify, options, next) {
+  fastify.addContentTypeParser('application/json',
+    { parseAs: 'string' },
+    function (req, body, done) {
+      try {
+        const json = JSON.parse(body || '{}')
+        done(null, json)
+      } catch (err) {
+        err.statusCode = 400
+        done(err, undefined)
+      }
+    })
+  next()
+}
+
+export default fp(addContentParser, {
+  fastify: '>=3.x',
+  name: 'content-parser'
+})

package/src/plugins/cookie.js

@@ -0,0 +1,17 @@
+import cookiePlugin from '@fastify/cookie'
+import fp from 'fastify-plugin'
+
+function addCookiePlugin (fastify, options, next) {
+  // istanbul ignore if
+  if (options.cookie.disabled) {
+    next()
+    return
+  }
+  fastify.register(cookiePlugin, { secret: options.cookie.secret })
+  next()
+}
+
+export default fp(addCookiePlugin, {
+  fastify: '>=3.x',
+  name: 'content-parser'
+})

package/src/plugins/error-handler.js

@@ -0,0 +1,140 @@
+import S from '@pbvision/schema'
+import * as Sentry from '@sentry/node'
+import fp from 'fastify-plugin'
+
+import { InvalidInputException } from '../api/exception.js'
+
+export default fp(function (fastify, options, next) {
+  const isLocalhost = process.env.NODE_ENV === 'localhost'
+  const sentryDSN = options.errorHandler.sentryDSN
+  // istanbul ignore next
+  const isSentryEnabled = sentryDSN && !isLocalhost
+  Sentry.init({
+    dsn: sentryDSN,
+    enabled: isSentryEnabled,
+    environment: process.env.NODE_ENV,
+    release: process.env.GIT_HASH,
+    serverName: options.errorHandler.serverName
+  })
+
+  const returnErrorDetail = options.errorHandler.returnErrorDetail
+  // log any exception which occurs
+  fastify.setErrorHandler(async (error, req, reply) => {
+    // extract the relevant bit of the traceback: remove fastify lines
+    const traceback = error.stack.split('\n')
+    const errorMessage = error.message.split('\n')
+    traceback.splice(0, errorMessage.length)
+    let removeFromIdx
+    if (error instanceof InvalidInputException) {
+      removeFromIdx = 1
+    } else {
+      for (let i = traceback.length - 1; i > 0; i--) {
+        const tbLine = traceback[i]
+        if (tbLine.indexOf('/fastify/lib') !== -1) {
+          removeFromIdx = i + 1
+          break
+        }
+      }
+    }
+    removeFromIdx = removeFromIdx ?? traceback.length
+
+    traceback.splice(removeFromIdx, traceback.length - removeFromIdx)
+
+    const response = reply.raw
+    /* istanbul ignore next */
+    const message = error.message || 'empty error message'
+    const statusCode = error.httpCode ?? error.statusCode ?? 500
+    reply.code(statusCode)
+    const errInfo = {
+      msg: message,
+      req,
+      status: statusCode,
+      stack: traceback
+    }
+
+    // improve the error emitted from bad requests (invalid input)
+    const isCrash = errInfo.status >= 500
+    let customFingerprint = false
+    if (!isCrash) {
+      const firstTB = traceback[0]
+      /* istanbul ignore else */
+      if (firstTB) {
+        /* istanbul ignore else */
+        if (firstTB.indexOf('fastify/lib/contentTypeParser.js') !== -1) {
+          customFingerprint = 'Content-Type Not Permitted'
+        } else if (error instanceof S.ValidationError) {
+          customFingerprint = message
+        }
+        /* istanbul ignore next */
+        if (customFingerprint) {
+          if (customFingerprint.indexOf(errInfo.msg) === -1) {
+            // prefix the error message with the custom fingerprint text if the
+            // fingerprint didn't already contain all of the error message text
+            errInfo.msg = customFingerprint + ': ' + errInfo.msg
+          }
+          // changing the error name results in a cleaner description on the
+          // Sentry dashboard
+          error.name = customFingerprint
+        }
+      }
+    }
+
+    Object.getOwnPropertyNames(error).forEach(key => {
+      if (key !== 'stack' && key !== 'message') {
+        if (!errInfo.error) {
+          errInfo.error = {}
+        }
+        errInfo.error[key] = error[key]
+      }
+    })
+    response.logged = true // don't double-log
+    if (statusCode >= 500) {
+      reply.log.error(errInfo)
+    } else {
+      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)
+      scope.setTags({
+        method: req.method,
+        url: req.url,
+        status: errInfo.status
+      })
+      scope.setExtras({
+        msg: errInfo.message,
+        reqId: req.id,
+        userAgent: req.headers['user-agent'] ?? 'not set'
+      })
+      Sentry.captureException(error)
+    })
+
+    const errorData = error.respData ?? {
+      code: error.constructor.name,
+      message: customFingerprint || error.message
+    }
+
+    // istanbul ignore else
+    if (returnErrorDetail && !error.respData) {
+      errorData.detail = errInfo.msg
+      errorData.stack = errInfo.stack
+    }
+
+    await reply.header('Content-Type', 'application/json; charset=utf-8')
+      .serializer(o => JSON.stringify(o, null, 2))
+      .send(errorData)
+  })
+
+  next()
+})

package/src/plugins/health-check.js

@@ -0,0 +1,19 @@
+import fp from 'fastify-plugin'
+
+export default fp(function (fastify, options, next) {
+  // istanbul ignore if
+  if (options.healthCheck.disabled) {
+    next()
+    return
+  }
+  // istanbul ignore next
+  const path = options.healthCheck.path ?? '/'
+  fastify.get(path, { schema: { hide: true } },
+    async (req, reply) => {
+      await reply.send()
+    })
+  next()
+}, {
+  fastify: '>=3.x',
+  name: 'healthCheck'
+})

package/src/plugins/latency-tracker.js

@@ -0,0 +1,45 @@
+import fp from 'fastify-plugin'
+const symbolRequestTime = Symbol('RequestTimer')
+
+export default fp(function (fastify, options, next) {
+  // istanbul ignore if
+  if (options.latencyTracker.disabled) {
+    next()
+    return
+  }
+
+  const header = options.latencyTracker.header
+  fastify.addHook('onRequest', function onRequestHandler (req, reply, done) {
+    // Start the recording of process time
+    req.raw[symbolRequestTime] = process.hrtime.bigint()
+
+    done()
+  })
+
+  fastify.addHook('onSend', async (req, reply, payload) => {
+    const fixedDigits = 3
+    // Calculate the duration, in nanoseconds
+    const hrDuration = process.hrtime.bigint() - req.raw[symbolRequestTime]
+    // convert it to milliseconds
+    const duration = (Number(hrDuration) / 1e6).toFixed(fixedDigits)
+    // add the header to the response
+    reply.header(header, duration)
+    return payload
+  })
+
+  fastify.addHook('onResponse', (req, reply, done) => {
+    // if errored, then it was already logged
+    if (!reply.raw.logged) {
+      req.log.info({
+        req,
+        status: reply.raw.statusCode,
+        latency: reply.getHeader(header)
+      })
+    }
+    done()
+  })
+  next()
+}, {
+  fastify: '>=3.x',
+  name: 'latency-tracker'
+})

package/src/plugins/swagger.js

@@ -0,0 +1,50 @@
+// istanbul ignore file
+import swagger from '@fastify/swagger'
+import swaggerUI from '@fastify/swagger-ui'
+import fp from 'fastify-plugin'
+
+export default fp(function (fastify, options, next) {
+  if (options.swagger.disabled) {
+    next()
+    return
+  }
+
+  const authHeaders = options.swagger.authHeaders
+  fastify.register(swagger, {
+    openapi: {
+      servers: options.swagger.servers.map(x => { return { url: x } }),
+      info: {
+        title: `${options.swagger.service.toUpperCase()} Service`
+      },
+      consumes: ['application/json'],
+      produces: ['application/json'],
+      components: {
+        securitySchemes: authHeaders.reduce((all, c) => {
+          all[c.replace('x-', '')] = {
+            type: 'apiKey',
+            name: c,
+            in: 'header'
+          }
+          return all
+        }, {})
+      }
+    }
+  })
+  fastify.register(swaggerUI, {
+    routePrefix: options.swagger.routePrefix,
+    exposeRoute: true,
+    uiConfig: {
+      docExpansion: 'list',
+      deepLinking: false,
+      filter: true
+    }
+  })
+  // fastify.addHook('onReady', function (done) {
+  //   fastify.swagger()
+  //   done()
+  // })
+  next()
+}, {
+  fastify: '>=3.x',
+  name: 'swagger'
+})

package/test/base-test.js

@@ -0,0 +1,154 @@
+import zlib from 'node:zlib'
+
+import { jest } from '@jest/globals'
+import { BaseTest, runTests } from '@pbvision/jest-unit-test'
+import superagentDefaults from 'superagent-defaults'
+import supertest from 'supertest'
+
+import makeService from '../src/app.js'
+
+let FASTIFY_CACHE
+
+afterAll(async () => {
+  await FASTIFY_CACHE?.close()
+  FASTIFY_CACHE = undefined
+})
+
+class BaseAppTest extends BaseTest {
+  async beforeAll () {
+    this.fastify = FASTIFY_CACHE ?? await makeService()
+    FASTIFY_CACHE = this.fastify
+
+    await Promise.all([super.beforeAll(), this.fastify.ready()])
+
+    /**
+     * Avoid having to consider compression in unit tests
+     * by removing the `accept-encoding` header,
+     * which is added by default from SuperTest
+     */
+    const superTest = superagentDefaults(supertest(this.fastify.server))
+    superTest.set('accept-encoding', null)
+    this.app = new Proxy(superTest, {
+      get: (target, prop, receiver) => {
+        if (['get', 'post', 'put', 'delete'].includes(prop)) {
+          return (...requestParams) => {
+            const test = target[prop](...requestParams)
+            const originalExpect = test.expect
+            test.expect = async (...expectParams) => {
+              console.log('  \u2502 Expecting', expectParams[0])
+              return originalExpect.call(test, ...expectParams)
+            }
+            return test
+          }
+        } else {
+          return target[prop]
+        }
+      }
+    })
+  }
+}
+
+// the promise input conveniently matches the promise produced by supertest
+// so you can pass the output of app.post(), etc. as the promise here as is
+function makeGotMockValueFromPromise (promise) {
+  const mockValue = new Promise(resolve => {
+    promise.then(desiredHttpResponse => {
+      let body = desiredHttpResponse.text || desiredHttpResponse.body || ''
+      if (typeof body !== 'string') {
+        body = JSON.stringify(body)
+      }
+      mockValue.text = async () => body
+      resolve({ statusCode: desiredHttpResponse.status || 200 })
+    })
+  })
+  return mockValue
+}
+
+function makeGotMockValue (body, statusCode, callback) {
+  const mockValue = new Promise(resolve => {
+    // setTimeout is used so that this promise does not synchronously resolve
+    // because unmocked got will NEVER return synchronously. This ensures
+    // functions which call got() never resolve synchronously (which can
+    // change their behavior... e.g., allow them to throw when called,
+    // instead of only rejecting later when await'ed).
+    // https://github.com/facebook/jest/issues/6028 (since jest 21.x)
+    setTimeout(() => {
+      mockValue.text = async () => {
+        if (callback) {
+          callback()
+        }
+        if (typeof body === 'string') {
+          return body
+        }
+        return JSON.stringify(body)
+      }
+      resolve({ statusCode })
+    }, 0)
+  })
+  mockValue.text = async () => {
+    throw new Error('cannot use text() before calling await() on the response')
+  }
+  return mockValue
+}
+
+function mockGot () {
+  const gotMock = jest.fn().mockImplementation(({ body }) => {
+    expect(body).toEqual(zlib.brotliCompressSync('321'))
+  })
+
+  gotMock.mockResp = (body = '', statusCode = 200, callback) => {
+    gotMock.mockReturnValue(makeGotMockValue(body, statusCode, callback))
+  }
+
+  /**
+   * Determine the mock response to use when the request is made.
+   *
+   * @param  {...function (request)} callbacks a list of callbacks in the order
+   *   to check and see if they have a mock response to use; if no callback,
+   *   provides a mock response then an error will be thrown
+   */
+  gotMock.mockRespWithCallback = (...callbacks) => {
+    gotMock.mockImplementation(request => {
+      for (const callback of callbacks) {
+        const desiredHTTPResponse = callback(request)
+        if (desiredHTTPResponse === true) {
+          const unmockedGot = jest.requireActual('../src/got')
+          return unmockedGot(request)
+        }
+        if (desiredHTTPResponse) {
+          if (desiredHTTPResponse.then) {
+            return makeGotMockValueFromPromise(desiredHTTPResponse)
+          }
+          return makeGotMockValue(
+            // follows the names from supertest
+            desiredHTTPResponse.text || desiredHTTPResponse.body || '',
+            desiredHTTPResponse.status || 200)
+        }
+      }
+      throw new Error(`un-mocked got() request: ${JSON.stringify(request)}`)
+    })
+  }
+
+  // will respond to the next N requests with the specified N responses
+  gotMock.mockRespMulti = (...responses) => {
+    let idx = 0
+    function setupNextResponse () {
+      if (idx < responses.length) {
+        gotMock.mockResp(...responses[idx], setupNextResponse)
+      } else if (idx > responses.length) {
+        // exactly equal means we just got our last callback (okay)
+        throw new Error('more requests made than we had mock responses')
+      }
+      idx += 1
+    }
+    setupNextResponse()
+  }
+  return gotMock
+}
+
+export {
+  BaseAppTest,
+  BaseTest,
+  mockGot,
+  runTests
+}

package/test/environment.js

@@ -0,0 +1,3 @@
+import 'firestore-orm/environment.js'
+
+process.env.NODE_ENV = 'localhost'