@pbvision/fastify-firestore-service 0.0.3

package/src/api/db-api.js

@@ -0,0 +1,108 @@
+import db from 'firestore-orm'
+
+import API from './api.js'
+
+/**
+ * Thrown to avoid committing a transaction when an error occurs.
+ * @access private
+ */
+class TransactionAborted extends Error {
+  constructor (respData) {
+    super()
+    this.respData = respData
+    this.retryable = false
+  }
+}
+
+/**
+ * An API whose response is computed inside a transaction.
+ * @public
+ * @class
+ */
+class DatabaseAPI extends API {
+  /**
+   * Whether this API can only read from Firestore. If false, the API's
+   * computeResponse() method will run in a Firestore transaction.
+   * @public
+   */
+  static IS_READ_ONLY = true
+
+  /**
+   * Options to pass the Firestore db.Context which wraps computeResponse().
+   * @public
+   */
+  static CONTEXT_OPTIONS = {}
+
+  async _computeResponse () {
+    await this.preTxStart()
+
+    let ret
+    try {
+      const opts = {
+        ...this.constructor.CONTEXT_OPTIONS,
+        readOnly: this.constructor.IS_READ_ONLY
+      }
+      ret = await db.Context.run(opts, async tx => {
+        this.tx = tx
+        this.req.tx = tx
+        let respData = await super._computeResponse()
+        if (this.__reply.statusCode < 400) {
+          // pre-commit hook may change the response data (and status code!)
+          respData = await this._callAndHandleRequestDone(
+            this.preCommit, respData)
+        }
+        // if the response code indicates an error, then don't commit
+        if (this.__reply.statusCode >= 400) {
+          throw new TransactionAborted(respData)
+        }
+        return respData
+      })
+    } catch (e) {
+      if (e instanceof TransactionAborted) {
+        return e.respData
+      } else {
+        throw e
+      }
+    } finally {
+      delete this.tx
+      delete this.req.tx
+    }
+
+    // _computeResponse() is called within _callAndHandleRequestDone; so we
+    // don't need to wrap this call to postCommit() in it (redundant)
+    return this.postCommit(ret)
+  }
+
+  /**
+   * Called just before the transaction starts. Useful to do async computation
+   * outside the transaction (reducing the window for contention).
+   * @protected
+   */
+  async preTxStart () {}
+
+  /**
+   * Called just before the transaction ATTEMPTS to commit. May alter the
+   * response by returning a new response value, or throwing RequestDone.
+   * Throwing an error will be propagated and handled by Transaction.run(),
+   * and will prevent the transaction from committing (unless the error is
+   * retryable).
+   *
+   * @param {*} respData the response data
+   * @returns {*} the (possibly updated) response data
+   * @protected
+   */
+  async preCommit (respData) { return respData }
+
+  /**
+   * Called after the transaction commits (and ONLY if it commits
+   * successfully). May alter the response by returning a new response value,
+   * or throwing RequestDone.
+   *
+   * @param {*} respData the response data
+   * @returns {*} the (possibly updated) response data
+   * @protected
+   */
+  async postCommit (respData) { return respData }
+}
+
+export default DatabaseAPI

package/src/api/exception.js

@@ -0,0 +1,288 @@
+import assert from 'node:assert'
+
+import S from '@pbvision/schema'
+
+import RESPONSES from './response.js'
+
+/**
+ * @namespace Exceptions
+ * @public
+ */
+/**
+ * Thrown to shortcut request handling.
+ *
+ * {@link API} will catch this exception and send the HTTP response code
+ * and (optional) data. This is useful to immediately stop request processing,
+ * especially from deeply nested locations in the call stack where it would
+ * be cumbersome to pass return information (especially errors) all the way
+ * back up the call stack.
+ *
+ * Typically, users should throw {@link RequestError} for error responses or
+ * @see RequestOkay for non-error responses (not @this).
+ *
+ * @arg {Number} httpCode The HTTP status code to respond with.
+ * @arg {String|Object} [respData=''] The object (to JSON.stringify()) or
+ *   string to send in the HTTP response body.
+ * @package
+ * @memberof Exceptions
+ */
+class __RequestDone extends Error {
+  static STATUS = undefined
+  static SCHEMA = RESPONSES.NO_OUTPUT
+
+  static get schemaValidator () {
+    const cacheKey = '_CACHED_SCHEMA_VALIDATOR'
+    if (!Object.prototype.hasOwnProperty.call(this, cacheKey)) {
+      this[cacheKey] = this.schema.compile(`data input to ${this.name}`)
+    }
+    return this[cacheKey]
+  }
+
+  /**
+   * Gets a Todea Schema object.
+   */
+  static get schema () {
+    let schema = this.SCHEMA
+    if (!schema.isTodeaSchema) {
+      schema = S.obj(schema)
+    }
+    return schema
+  }
+
+  /**
+   * Create an exception.
+   * @param {String} message An error message
+   * @param {Object} data A JSON object containing additional data
+   * @param {Integer} code An optional code to override exception's default
+   *   STATUS
+   */
+  constructor (message, data = {}, code = undefined) {
+    super(message)
+    this.httpCode = code ?? this.constructor.STATUS
+    assert(this.httpCode !== undefined, 'Status must be defined')
+    assert(this.constructor.SCHEMA !== undefined, 'Schema must be defined')
+    this.constructor.schemaValidator(data)
+    this.data = data
+  }
+}
+
+/**
+ * Concrete class to indicate request is completed ok.
+ * @public
+ * @memberof Exceptions
+ */
+class RequestDone extends __RequestDone {
+  static STATUS = 200
+  static SCHEMA = S.obj().optional()
+
+  /**
+   * Return data to return to caller.
+   */
+  get respData () {
+    return this.data
+  }
+
+  /**
+   * Create a success response. Status must be smaller than 400.
+   * @param {Object} data Data to return to caller
+   * @param {Integer} code A status to override default status.
+   */
+  constructor (data, code = undefined) {
+    super(undefined, data, code)
+    assert(this.httpCode < 300, 'Status code must be less than 300')
+  }
+}
+
+/**
+ * Thrown to shortcut request handling and return an HTTP success code (200).
+ *
+ * @arg {String|Object} [respData=''] The object (to JSON.stringify()) or
+ *   string to send in the HTTP response body.
+ * @public
+ * @memberof Exceptions
+ * @see RequestDone
+ */
+class RequestOkay extends RequestDone {
+  static STATUS = 200
+}
+
+/**
+ * Thrown to shortcut request handling and return an HTTP error.
+ *
+ * @arg {String} message The human-readable error message to send back in the
+ *   JSON response data (in the "error" key).
+ * @arg {Object} [data={}] Optional additional JSON data to send back
+ *   in the error response body.
+ * @arg {Number} [code=400] The HTTP status code to respond with; defaults
+ *   to STATUS
+ * @public
+ * @memberof Exceptions
+ * @see RequestDone
+ */
+class RequestError extends __RequestDone {
+  static SCHEMA = S.obj()
+
+  constructor (message, data = {}, code = undefined) {
+    super(message, data, code)
+    assert(this.httpCode >= 300, 'Status code must be at least 300')
+  }
+
+  /**
+   * Schema to use on returned data
+   */
+  static get respSchema () {
+    return S.obj({
+      code: S.str,
+      message: S.str.optional(),
+      data: S.obj() // Data is validated in constructor, don't validate again.
+    })
+  }
+
+  /**
+   * Data to return to the caller
+   */
+  get respData () {
+    return {
+      code: this.constructor.name,
+      message: this.message,
+      data: this.data
+    }
+  }
+}
+
+/**
+ * Thrown when a redirect is required.
+ * @public
+ * @memberof Exceptions
+ */
+class RedirectException extends RequestError {
+  static STATUS = 302
+  static SCHEMA = S.str.max(0)
+
+  constructor (url, code) {
+    super('', '', code)
+    assert(this.httpCode < 400, 'Status code must be less than 400')
+    assert(typeof url === 'string' && url.length)
+    this.url = url
+  }
+}
+
+/**
+ * Thrown when a error is induced by client.
+ * @public
+ * @memberof Exceptions
+ */
+class BadRequestException extends RequestError {
+  static STATUS = 400
+}
+
+/**
+ * Wraps Request Validation failures into a RequestError object for processing.
+ * @public
+ * @memberof Exceptions
+ */
+class InvalidInputException extends BadRequestException {
+  static STATUS = 400
+  static __ERROR_PREFIX = {
+    headers: 'Header Validation Failure',
+    body: 'Body Validation Failure',
+    querystring: 'Query Validation Failure',
+    params: 'Path Validation Failure'
+  }
+
+  constructor (schemaError) {
+    const prefixMap = InvalidInputException.__ERROR_PREFIX
+    const prefix = prefixMap[schemaError.validationContext] ??
+      'Unknown Validation Failure'
+    super(`${prefix}: ${schemaError.message}`)
+    this.name = this.constructor.name
+    // istanbul ignore else
+    if (process.env.NODE_ENV !== 'prod' && schemaError.validation) {
+      for (const err of schemaError.validation) {
+        console.log(JSON.stringify(err))
+      }
+    }
+  }
+}
+
+/**
+ * Thrown when a client is not authorized to access the requested resource. For
+ * example, user is trying to log in using invalid credentials.
+ * @public
+ * @memberof Exceptions
+ */
+class UnauthorizedException extends RequestError {
+  static STATUS = 401
+
+  constructor (message = 'access denied') {
+    super(message)
+  }
+}
+
+/**
+ * Thrown when an authenticated client does not have enough privilege to access
+ * the requested resource. For example, a user tries to change other user's
+ * data.
+ * @public
+ * @memberof Exceptions
+ */
+class ForbiddenException extends RequestError {
+  static STATUS = 403
+
+  constructor (message = 'access denied') {
+    super(message)
+  }
+}
+
+/**
+ * Thrown when the requested resource is not found, or should be hidden.
+ * @public
+ * @memberof Exceptions
+ */
+class NotFoundException extends RequestError {
+  static STATUS = 404
+
+  constructor () {
+    super('Not found')
+  }
+}
+
+/**
+ * Thrown when an error is induced by a server bug.
+ * @public
+ * @memberof Exceptions
+ */
+class InternalFailureException extends RequestError {
+  static STATUS = 500
+}
+
+/**
+ * Thrown when server is temporarily unable to serve the request, due to
+ * internal timeouts or service outage.
+ * @public
+ * @memberof Exceptions
+ */
+class ServiceUnavailableException extends RequestError {
+  static STATUS = 503
+}
+
+export {
+  // Base exceptions
+  RequestError,
+  RequestDone,
+
+  // Success
+  RequestOkay,
+
+  // Redirect
+  RedirectException,
+
+  // Error
+  BadRequestException,
+  InvalidInputException,
+  ForbiddenException,
+  InternalFailureException,
+  NotFoundException,
+  ServiceUnavailableException,
+  UnauthorizedException
+}

package/src/api/response.js

@@ -0,0 +1,8 @@
+import S from '@pbvision/schema'
+
+const RESPONSES = {
+  NO_OUTPUT: S.str.max(0).lock(),
+  UNVALIDATED: undefined
+}
+
+export default RESPONSES

package/src/component-registrar.js

@@ -0,0 +1,27 @@
+export default class ComponentRegistrar {
+  apis = []
+
+  constructor (app, service) {
+    this.app = app
+    this.service = service
+  }
+
+  async registerComponents (components) {
+    const promises = []
+    for (const component of Object.values(components)) {
+      if (component.register) {
+        promises.push(component.register(this))
+      }
+    }
+    await Promise.all(promises)
+  }
+
+  async registerAPI (api) {
+    this.apis.push(api)
+    await api.registerAPI(this)
+  }
+
+  async registerModel (model) {
+    // nothing to do here
+  }
+}

package/src/got-wrapper.js

@@ -0,0 +1,34 @@
+import zlib from 'node:zlib'
+
+import realGot from 'got'
+
+function gotWrapper (options, mockedGot) {
+  options = {
+    decompress: true,
+    ...options
+  }
+  if (options.compress) {
+    // make a copy of the headers obj before we make changes to it
+    const headers = {
+      ...options.headers
+    }
+    options.headers = headers
+    if (options.body) {
+      options.body = zlib.brotliCompressSync(options.body)
+    }
+    if (options.json) {
+      headers['content-type'] = 'application/json'
+      options.body = zlib.brotliCompressSync(JSON.stringify(options.json))
+      delete options.json
+    }
+
+    if (options.body) {
+      headers['content-encoding'] = 'br'
+    }
+  }
+  // istanbul ignore next
+  const got = mockedGot ?? gotWrapper.__mocked_got ?? realGot
+  return got(options)
+}
+
+export default gotWrapper

package/src/index.js

@@ -0,0 +1,12 @@
+import API from './api/api.js'
+import DatabaseAPI from './api/db-api.js'
+import * as EXCEPTIONS from './api/exception.js'
+import RESPONSES from './api/response.js'
+import ComponentRegistrar from './component-registrar.js'
+import makeService from './make-app.js'
+
+export {
+  API, DatabaseAPI, EXCEPTIONS, RESPONSES,
+  makeService,
+  ComponentRegistrar
+}

package/src/make-app.js

@@ -0,0 +1,179 @@
+import fastify from 'fastify'
+import { v4 as uuidv4 } from 'uuid'
+
+import ComponentRegistrar from './component-registrar.js'
+import makeLogger from './make-logger.js'
+import compressPlugin from './plugins/compress.js'
+import contentParserPlugin from './plugins/content-parser.js'
+import cookiePlugin from './plugins/cookie.js'
+import errorHandlerPlugin from './plugins/error-handler.js'
+import healthCheckPlugin from './plugins/health-check.js'
+import latencyTrackerPlugin from './plugins/latency-tracker.js'
+import swaggerPlugin from './plugins/swagger.js'
+
+/**
+ * @typedef {object} CookieConfig
+ * @property {boolean} [disabled=false] Adds fastify-cookie plugin
+ * @property {string} [secret] A secret to use to secure cookie
+ */
+const COOKIE_CONFIG = {
+  disabled: false,
+  secret: undefined
+}
+
+/**
+ * @typedef {object} LoggingConfig
+ * @property {boolean} [useUnitTestLogFormat=false] Whether output logs to console with
+ *   pretty printing
+ * @property {boolean} [reportAllErrors=false] Whether include all API
+ *   validation errors in error logging. Recommend to keep it off for production,
+ *   on for testing.
+ * @property {boolean} [reportErrorDetail=false] Whether include all details
+ *   of an error. Recommend to keep it off for remote testing, on for local
+ *   testing.
+ */
+const LOGGING_CONFIG = {
+  useUnitTestLogFormat: false,
+  reportAllErrors: false,
+  reportErrorDetail: false,
+  sentryDSN: null
+}
+
+/**
+ * @typedef {object} HealthCheckConfig
+ * @property {boolean} [disabled=false] Whether to add a health check endpoint
+ *   that simply returns 200.
+ * @property {string} [path='/'] The path to the health check endpoint.
+ */
+const HEALTH_CHECK_CONFIG = {
+  disabled: false,
+  path: '/'
+}
+
+/**
+ * @typedef {object} SwaggerConfig
+ * @property {boolean} [disabled=false] Whether to disable
+ * @property {Array<string>} [servers=[]] The host endpoint (scheme + domain) to
+ *   send requests to
+ * @property {Array<string>} [authHeaders=[]] Authentication headers
+ * @property {string} [routePrefix='/docs'] Authentication headers
+ */
+const SWAGGER_CONFIG = {
+  disabled: false,
+  servers: [],
+  authHeaders: [],
+  routePrefix: '/docs'
+}
+
+/**
+ * @typedef {object} LatencyTrackerConfig
+ * @property {boolean} [disabled=false] Whether to add a health check endpoint
+ *   that simply returns 200.
+ * @property {string} [path='/'] The path to the health check endpoint.
+ */
+const LATENCY_TRACKER_CONFIG = {
+  disabled: false,
+  header: 'x-latency-ms'
+}
+
+const PARAMS_CONFIG = {
+  service: undefined,
+  components: undefined,
+  RegistrarCls: ComponentRegistrar,
+  cookie: {},
+  healthCheck: {},
+  latencyTracker: {},
+  logging: {},
+  swagger: {}
+}
+
+function loadConfigDefault (config, defaultConfig) {
+  for (const key of Object.keys(config)) {
+    if (!Object.prototype.hasOwnProperty.call(defaultConfig, key)) {
+      throw new Error(`Unknown config ${key}`)
+    }
+  }
+  if (!config.disabled) {
+    for (const [key, defaultValue] of Object.entries(defaultConfig)) {
+      if (defaultValue === undefined && !config[key]) {
+        throw new Error(`Missing required value for ${key}`)
+      }
+    }
+  }
+  Object.assign(config, { ...defaultConfig, ...config })
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.service Name of the service, for example, iam,
+ *   user-id, leaderboard. This affects API's prefixes.
+ * @param {Array<API|Model|component>} params.components A list of
+ *   components.
+ * @param {object} [params.RegistrarCls=ComponentRegistrar] A subclass of
+ *   ComponentRegistrar
+ * @param {CookieConfig} [params.cookie] Configures fastify-cookie.
+ * @param {HealthCheckConfig} [params.healthCheck] Configures health check endpoint.
+ * @param {LatencyTrackerConfig} [params.latencyTracker]
+ * @param {LoggingConfig} [params.logging] Configures logging.
+ * @param {SwaggerConfig} [params.swagger] Configures swagger.
+ * @returns {Promise<server>} fastify app with configured plugins
+ */
+export default async function makeService (params = {}) {
+  const configs = [
+    [() => params, PARAMS_CONFIG],
+    [() => params.cookie, COOKIE_CONFIG],
+    [() => params.healthCheck, HEALTH_CHECK_CONFIG],
+    [() => params.latencyTracker, LATENCY_TRACKER_CONFIG],
+    [() => params.logging, LOGGING_CONFIG],
+    [() => params.swagger, SWAGGER_CONFIG]
+  ]
+  for (const [getter, defaultConfig] of configs) {
+    loadConfigDefault(getter(), defaultConfig)
+  }
+  const {
+    service,
+    components,
+    RegistrarCls,
+    cookie,
+    healthCheck,
+    latencyTracker,
+    logging,
+    swagger
+  } = params
+  const fastifyServerId = uuidv4()
+  let requestCount = 0
+  const app = fastify({
+    ignoreTrailingSlash: true,
+    disableRequestLogging: true,
+    logger: makeLogger(logging.useUnitTestLogFormat),
+    genReqId: () => `${fastifyServerId}-${++requestCount}`,
+    ajv: {
+      customOptions: {
+        removeAdditional: false,
+        allErrors: logging.reportAllErrors,
+        useDefaults: true,
+        strictSchema: false,
+        strictRequired: true
+      }
+    }
+  })
+
+  const registrar = new RegistrarCls(app, service)
+
+  app.register(cookiePlugin, { cookie })
+    .register(compressPlugin)
+    .register(contentParserPlugin)
+    .register(latencyTrackerPlugin, { latencyTracker })
+    .register(errorHandlerPlugin, {
+      errorHandler: {
+        returnErrorDetail: logging.reportErrorDetail,
+        sentryDSN: logging.sentryDSN,
+        serverName: fastifyServerId
+      }
+    })
+    .register(healthCheckPlugin, { healthCheck })
+    .register(swaggerPlugin, { swagger: { service, ...swagger } })
+
+  await registrar.registerComponents(components)
+  return app
+}