hirefire-resource 1.0.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+No changes since release yet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 HireFire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+## HireFire Integration Library for Node.js Applications
+
+This library integrates Node.js applications with HireFire's Dyno Managers (Heroku Dyno Autoscalers). Instructions specific to supported web frameworks and worker libraries are provided during the setup process.
+
+**Supported web frameworks:**
+
+- Express
+- Koa
+- Connect
+- Sails
+- Nest
+
+**Supported worker libraries:**
+
+- BullMQ
+
+---
+
+Since 2011, over 1,000 companies have trusted [HireFire] to autoscale more than 5,000 applications hosted on [Heroku], managing over 10,000 web and worker dynos.
+
+HireFire is distinguished by its support for both web and worker dynos, extending autoscaling capabilities to Standard-tier dynos. It provides fine-grained control over scaling behavior and improves scaling accuracy by monitoring more reliable metrics at the application level. These metrics include request queue time (web), job queue latency (worker), and job queue size (worker), which contribute to making more effective scaling decisions.
+
+For more information, visit our [home page][HireFire].
+
+---
+
+## Development
+
+- Run `bin/setup` to prepare the environment.
+- See `npm run` for common tasks.
+
+## Release
+
+1. Update the version in `package.json` using `npm version <patch|minor|major>`.
+2. Ensure that `CHANGELOG.md` is up-to-date.
+3. Commit changes with `git commit`.
+4. Create a `git tag` matching the new version (e.g., `v1.0.0`).
+5. Push the new git tag. Continuous Integration will handle the distribution process.
+
+## License
+
+This package is licensed under the terms of the MIT license.
+
+[HireFire]: https://hirefire.io/
+[Heroku]: https://heroku.com/

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "hirefire-resource",
+  "version": "1.0.0",
+  "description": "HireFire integration library for Node.js applications",
+  "keywords": [
+    "hirefire",
+    "heroku",
+    "autoscale",
+    "autoscaling",
+    "autoscaler",
+    "web",
+    "worker",
+    "dyno"
+  ],
+  "homepage": "https://hirefire.io",
+  "author": "Michael van Rooijen <support@hirefire.io>",
+  "license": "MIT",
+  "files": [
+    "CHANGELOG.md",
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./middleware/connect": "./src/middleware/connect.js",
+    "./middleware/express": "./src/middleware/express.js",
+    "./middleware/koa": "./src/middleware/koa.js",
+    "./macro/bullmq": "./src/macro/bullmq.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hirefire/hirefire-resource-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hirefire/hirefire-resource-node/issues"
+  },
+  "scripts": {
+    "test": "jest --silent --coverage --coverageReporters=html",
+    "check": "prettier --check --no-semi .",
+    "format": "prettier --write --no-semi .",
+    "doc": "jsdoc"
+  },
+  "engines": {
+    "node": ">=16.0.0 <22.0.0"
+  },
+  "dependencies": {
+    "async-mutex": "<1"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.2.8",
+    "@nestjs/platform-express": "^10.2.8",
+    "@nestjs/testing": "^10.2.8",
+    "bullmq": "^4.13.2",
+    "connect": "^3.7.0",
+    "express": "^4.18.2",
+    "jest": "^29.3.1",
+    "jsdoc": "^4.0.2",
+    "koa": "^2.14.2",
+    "nock": "^13.3.0",
+    "prettier": "^3.1.0",
+    "sails": "^1.5.8",
+    "sinon": "^17.0.1",
+    "supertest": "^6.3.3"
+  }
+}

package/src/configuration.js

@@ -0,0 +1,20 @@
+const { Web } = require("./web")
+const { Worker } = require("./worker")
+
+class Configuration {
+  constructor() {
+    this.web = null
+    this.workers = []
+    this.logger = console
+  }
+
+  dyno(name, fn) {
+    if (name === "web") {
+      this.web = new Web(this)
+    } else {
+      this.workers.push(new Worker(name, fn))
+    }
+  }
+}
+
+module.exports = Configuration

package/src/errors.js

@@ -0,0 +1,23 @@
+class MissingQueueError extends Error {
+  constructor() {
+    super("No queue was specified. Please specify at least one queue.")
+    this.name = "MissingQueueError"
+  }
+}
+
+class JobQueueLatencyUnsupportedError extends Error {
+  constructor(name) {
+    super(`${name} currently does not support job queue latency measurements.`)
+    this.name = "JobQueueLatencyUnsupportedError"
+  }
+}
+
+function jobQueueLatencyUnsupported(name) {
+  throw new JobQueueLatencyUnsupportedError(name)
+}
+
+module.exports = {
+  MissingQueueError,
+  JobQueueLatencyUnsupportedError,
+  jobQueueLatencyUnsupported,
+}

package/src/hirefire.js

@@ -0,0 +1,13 @@
+const Configuration = require("./configuration")
+
+class HireFire {
+  constructor() {
+    this.configuration = new Configuration()
+  }
+
+  configure(fn) {
+    fn(this.configuration)
+  }
+}
+
+module.exports = HireFire

package/src/index.js

@@ -0,0 +1,3 @@
+const HireFire = require("./hirefire")
+
+module.exports = new HireFire()

package/src/macro/bullmq.js

@@ -0,0 +1,110 @@
+const IORedis = require("ioredis")
+const { unpack } = require("../utility")
+const { jobQueueLatencyUnsupported } = require("../errors")
+
+/**
+ * Measures job queue latency. Currently, this functionality is not supported for BullMQ.
+ *
+ * @async
+ * @param {...any} args - Any number of arguments (ignored in function).
+ * @throws {JobQueueLatencyUnsupportedError} - Indicates that the module does not support job queue latency measurements.
+ * @returns {Promise<void>} - The function is asynchronous, but its return value is not used.
+ */
+async function jobQueueLatency(...args) {
+  jobQueueLatencyUnsupported("BullMQ")
+}
+
+/**
+ * Calculates the total job queue size across specified queues.
+ *
+ * @async
+ * @param {...string} queues - Names of the queues for size measurement.
+ * @param {object} [options] - Optional options object. The options object can include a
+ *                             `connection` property, which is passed to IORedis and is compatible
+ *                             with its connection options. If no connection is provided, the
+ *                             function will use the value of the `REDIS_TLS_URL`, `REDIS_URL`,
+ *                             `REDISTOGO_URL`, `REDISCLOUD_URL`, `OPENREDIS_URL` environment
+ *                             variables, in the order specified. If none of these environment
+ *                             variables are set, it defaults to `redis://localhost:6379/0`.
+ * @returns {Promise<number>} Cumulative job queue size across the specified queues.
+ * @example
+ * // Calculate size across all queues
+ * await jobQueueSize()
+ * @example
+ * // Calculate size for the "default" queue
+ * await jobQueueSize("default")
+ * @example
+ * // Calculate size across "default" and "mailer" queues
+ * await jobQueueSize("default", "mailer")
+ * @example
+ * // Calculate Size using the options.connection property
+ * await jobQueueSize("default", { connection: "redis://localhost:6379/0" })
+ */
+async function jobQueueSize(...args) {
+  let { queues, options } = unpack(args)
+
+  const redis = new IORedis(
+    options.connection ||
+      process.env.REDIS_TLS_URL ||
+      process.env.REDIS_URL ||
+      process.env.REDISTOGO_URL ||
+      process.env.REDISCLOUD_URL ||
+      process.env.OPENREDIS_URL ||
+      "redis://localhost:6379/0",
+  )
+
+  if (queues.length === 0) {
+    const pipeline = redis.pipeline()
+    pipeline.keys("bull:*:wait")
+    pipeline.keys("bull:*:active")
+    pipeline.keys("bull:*:delayed")
+
+    const results = await pipeline.exec()
+    const keys = results.flatMap(([err, result]) => result || [])
+    const uniqueQueueNames = new Set()
+
+    keys.forEach((key) => {
+      const match = key.match(/^bull:(.*):(wait|active|delayed)$/)
+      if (match) {
+        uniqueQueueNames.add(match[1])
+      }
+    })
+
+    queues = Array.from(uniqueQueueNames)
+  }
+
+  let totalCount = 0
+
+  try {
+    const pipeline = redis.pipeline()
+    const now = Date.now() * 0x1000 // Match BullMQ's delayed job timestamp score encoding.
+
+    for (const queue of queues) {
+      pipeline.lindex(`bull:${queue}:wait`, -1)
+      pipeline.llen(`bull:${queue}:wait`)
+      pipeline.llen(`bull:${queue}:active`)
+      pipeline.zcount(`bull:${queue}:delayed`, "-inf", now)
+    }
+
+    const results = await pipeline.exec()
+
+    for (let i = 0; i < results.length; i += 4) {
+      const lastWaitJob = results[i][1]
+      const waitCount = results[i + 1][1] || 0
+      const activeCount = results[i + 2][1] || 0
+      const delayedCount = results[i + 3][1] || 0
+
+      totalCount += waitCount + activeCount + delayedCount
+
+      if (lastWaitJob && lastWaitJob.startsWith("0:")) {
+        totalCount -= 1
+      }
+    }
+  } finally {
+    await redis.quit()
+  }
+
+  return totalCount
+}
+
+module.exports = { jobQueueLatency, jobQueueSize }

package/src/middleware/connect.js

@@ -0,0 +1,20 @@
+const { RequestInfo, request } = require("../middleware")
+
+async function HireFireMiddlewareConnect(req, res, next) {
+  const response = await request(
+    new RequestInfo(
+      req.url,
+      req.headers["x-request-start"],
+      req.headers["hirefire-token"],
+    ),
+  )
+
+  if (response) {
+    res.writeHead(response.status, response.headers)
+    res.end(JSON.stringify(response.body))
+  } else {
+    next()
+  }
+}
+
+module.exports = HireFireMiddlewareConnect

package/src/middleware/express.js

@@ -0,0 +1,19 @@
+const { RequestInfo, request } = require("../middleware")
+
+async function HireFireMiddlewareExpress(req, res, next) {
+  const response = await request(
+    new RequestInfo(
+      req.path,
+      req.get("X-Request-Start"),
+      req.get("HireFire-Token"),
+    ),
+  )
+
+  if (response) {
+    res.status(response.status).set(response.headers).json(response.body)
+  } else {
+    next()
+  }
+}
+
+module.exports = HireFireMiddlewareExpress

package/src/middleware/koa.js

@@ -0,0 +1,21 @@
+const { RequestInfo, request } = require("../middleware")
+
+async function HireFireMiddlewareKoa(ctx, next) {
+  const response = await request(
+    new RequestInfo(
+      ctx.path,
+      ctx.get("X-Request-Start"),
+      ctx.get("HireFire-Token"),
+    ),
+  )
+
+  if (response) {
+    ctx.status = response.status
+    ctx.set(response.headers)
+    ctx.body = response.body
+  } else {
+    await next()
+  }
+}
+
+module.exports = HireFireMiddlewareKoa

package/src/middleware.js

@@ -0,0 +1,69 @@
+const HireFire = require(".")
+const VERSION = require("./version")
+
+class RequestInfo {
+  constructor(path, requestStartTime = null, token = null) {
+    this.path = path
+    this.requestStartTime = requestStartTime
+      ? parseInt(requestStartTime, 10)
+      : null
+    this.token = token
+  }
+}
+
+async function request(requestInfo) {
+  await processRequestQueueTime(requestInfo)
+
+  if (matchesHireFirePath(requestInfo) || matchesInfoPath(requestInfo)) {
+    return {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": "must-revalidate, private, max-age=0",
+        "HireFire-Resource": `Node-${VERSION}`,
+      },
+      body: await Promise.all(
+        HireFire.configuration.workers.map(async (worker) => ({
+          name: worker.name,
+          value: await worker.value(),
+        })),
+      ),
+    }
+  }
+
+  return null
+}
+
+function matchesHireFirePath(requestInfo) {
+  return (
+    process.env.HIREFIRE_TOKEN &&
+    requestInfo.path === "/hirefire" &&
+    requestInfo.token === process.env.HIREFIRE_TOKEN
+  )
+}
+
+function matchesInfoPath(requestInfo) {
+  return (
+    process.env.HIREFIRE_TOKEN &&
+    requestInfo.path === `/hirefire/${process.env.HIREFIRE_TOKEN}/info`
+  )
+}
+
+async function processRequestQueueTime(requestInfo) {
+  if (
+    process.env.HIREFIRE_TOKEN &&
+    HireFire.configuration.web &&
+    requestInfo.requestStartTime
+  ) {
+    await HireFire.configuration.web.startDispatcher()
+    await HireFire.configuration.web.addToBuffer(
+      calculateRequestQueueTime(requestInfo),
+    )
+  }
+}
+
+function calculateRequestQueueTime(requestInfo) {
+  return Math.max(Date.now() - requestInfo.requestStartTime, 0)
+}
+
+module.exports = { RequestInfo, request }

package/src/utility.js

@@ -0,0 +1,22 @@
+function unpack(args) {
+  const lastArg = args[args.length - 1]
+  let queues = []
+  let options = {}
+
+  if (
+    typeof lastArg === "object" &&
+    lastArg !== null &&
+    !Array.isArray(lastArg)
+  ) {
+    queues = args.slice(0, -1)
+    options = lastArg
+  } else {
+    queues = args
+  }
+
+  queues = queues.flat()
+
+  return { queues, options }
+}
+
+module.exports = { unpack }

package/src/version.js

@@ -0,0 +1,3 @@
+const pkg = require("../package.json")
+
+module.exports = pkg.version

package/src/web.js

@@ -0,0 +1,216 @@
+const https = require("https")
+const { Mutex } = require("async-mutex")
+const VERSION = require("../src/version")
+
+class DispatchError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "DispatchError"
+  }
+}
+
+class Web {
+  constructor(configuration) {
+    this._buffer = {}
+    this._mutex = new Mutex()
+    this._dispatcherRunning = false
+    this._configuration = configuration
+    this._dispatchInterval = 1
+    this._dispatchTimeout = 5
+    this._bufferTTL = 60
+  }
+
+  async startDispatcher() {
+    const release = await this._mutex.acquire()
+
+    try {
+      if (this._dispatcherRunning) return false
+      this._dispatcherRunning = true
+    } finally {
+      release()
+    }
+
+    this._logger.info("[HireFire] Starting web metrics dispatcher.")
+
+    this.dispatcher = setInterval(
+      this._dispatchBuffer.bind(this),
+      this._dispatchInterval * 1000,
+    )
+
+    return true
+  }
+
+  async stopDispatcher() {
+    const release = await this._mutex.acquire()
+
+    try {
+      if (!this._dispatcherRunning) return false
+      this._dispatcherRunning = false
+      clearInterval(this.dispatcher)
+    } finally {
+      release()
+    }
+
+    await this._flushBuffer()
+
+    this._logger.info("[HireFire] Web metrics dispatcher stopped.")
+
+    return true
+  }
+
+  dispatcherRunning() {
+    return this._dispatcherRunning
+  }
+
+  async addToBuffer(requestQueueTime) {
+    const release = await this._mutex.acquire()
+
+    try {
+      const timestamp = Math.floor(Date.now() / 1000)
+      this._buffer[timestamp] = this._buffer[timestamp] || []
+      this._buffer[timestamp].push(requestQueueTime)
+    } finally {
+      release()
+    }
+  }
+
+  async _flushBuffer() {
+    const release = await this._mutex.acquire()
+
+    try {
+      const currentBuffer = this._buffer
+      this._buffer = {}
+      return currentBuffer
+    } finally {
+      release()
+    }
+  }
+
+  async _dispatchBuffer() {
+    let buffer
+
+    try {
+      buffer = await this._flushBuffer()
+
+      if (Object.keys(buffer).length === 0) {
+        return
+      }
+
+      if (process.env.HIREFIRE_VERBOSE) {
+        this._logger.info(
+          `[HireFire] Dispatching web metrics: ${JSON.stringify(buffer)}`,
+        )
+      }
+
+      await this._submitBuffer(buffer)
+    } catch (error) {
+      await this._repopulateBuffer(buffer)
+      this._logger.error(
+        `[HireFire] Error while dispatching web metrics: ${error.message}`,
+      )
+    }
+  }
+
+  async _repopulateBuffer(buffer) {
+    const release = await this._mutex.acquire()
+
+    try {
+      const now = Math.floor(Date.now() / 1000)
+      Object.entries(buffer).forEach(([timestamp, requestQueueTimes]) => {
+        if (parseInt(timestamp) >= now - this._bufferTTL) {
+          this._buffer[timestamp] = this._buffer[timestamp] || []
+          this._buffer[timestamp].push(...requestQueueTimes)
+        }
+      })
+    } finally {
+      release()
+    }
+  }
+
+  async _submitBuffer(buffer) {
+    const hirefireToken = process.env.HIREFIRE_TOKEN
+
+    if (!hirefireToken) {
+      throw new DispatchError(
+        "The HIREFIRE_TOKEN environment variable is not set. Unable to submit " +
+          "Request Queue Time metric data. The HIREFIRE_TOKEN can be found in " +
+          "the HireFire Web UI in the web dyno manager settings.",
+      )
+    }
+
+    const data = JSON.stringify(buffer)
+    const dispatchUrl = (
+      process.env.HIREFIRE_DISPATCH_URL || "logdrain.hirefire.io"
+    ).replace(/^(https?:\/\/)/, "")
+    const options = {
+      hostname: dispatchUrl,
+      port: 443,
+      path: "/",
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "HireFire-Token": hirefireToken,
+        "HireFire-Resource": `Node-${VERSION}`,
+        "Content-Length": data.length,
+      },
+    }
+
+    return new Promise((resolve, reject) => {
+      const req = https.request(options, (res) => {
+        if (res.statusCode === 200) {
+          this._adjustParameters(res)
+          resolve()
+        } else if (res.statusCode >= 500) {
+          reject(
+            new DispatchError(
+              `Server responded with ${res.statusCode} status.`,
+            ),
+          )
+        } else {
+          reject(
+            new DispatchError(`Unexpected response code ${res.statusCode}.`),
+          )
+        }
+      })
+
+      req.on("error", (e) => {
+        if (e.code === "ETIMEDOUT" || e.code === "ESOCKETTIMEDOUT") {
+          reject(new DispatchError("Request timed out."))
+        } else {
+          reject(new DispatchError(`Network error occurred (${e.message}).`))
+        }
+      })
+
+      req.on("timeout", () => {
+        req.destroy()
+        reject(new DispatchError("Request timed out."))
+      })
+
+      req.setTimeout(this._dispatchTimeout * 1000)
+      req.write(data)
+      req.end()
+    })
+  }
+
+  _adjustParameters(res) {
+    if (res.headers["hirefire-resource-dispatcher-interval"]) {
+      this._dispatchInterval = parseInt(
+        res.headers["hirefire-resource-dispatcher-interval"],
+      )
+    }
+    if (res.headers["hirefire-resource-dispatcher-timeout"]) {
+      this._dispatchTimeout = parseInt(
+        res.headers["hirefire-resource-dispatcher-timeout"],
+      )
+    }
+    if (res.headers["hirefire-resource-buffer-ttl"]) {
+      this._bufferTTL = parseInt(res.headers["hirefire-resource-buffer-ttl"])
+    }
+  }
+
+  get _logger() {
+    return this._configuration.logger
+  }
+}
+
+module.exports = { Web, DispatchError }

package/src/worker.js

@@ -0,0 +1,45 @@
+class InvalidDynoNameError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "InvalidDynoNameError"
+  }
+}
+
+class MissingDynoFnError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "MissingDynoFnError"
+  }
+}
+
+class Worker {
+  static PROCESS_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{0,29}$/
+
+  constructor(name, fn) {
+    this._validate(name, fn)
+    this.name = name
+    this._fn = fn
+  }
+
+  async value() {
+    return this._fn()
+  }
+
+  _validate(name, fn) {
+    if (!Worker.PROCESS_NAME_PATTERN.test(name || "")) {
+      throw new InvalidDynoNameError(
+        `Invalid name for new Worker(${name}, fn). ` +
+          "Ensure it matches the Procfile process name (i.e. web, worker).",
+      )
+    }
+
+    if (!fn || typeof fn !== "function") {
+      throw new MissingDynoFnError(
+        `Missing function for new Worker(${name}, fn). ` +
+          "Ensure that you provide a function that returns the job queue metric.",
+      )
+    }
+  }
+}
+
+module.exports = { Worker, InvalidDynoNameError, MissingDynoFnError }