microship 0.1.1

package/README.md

@@ -0,0 +1,26 @@
+# microship
+
+Readiness, liveness, and graceful shutdown for a Node process on Kubernetes.
+
+`/ready` and `/live` run on a [worker thread](https://nodejs.org/api/worker_threads.html). A busy event loop stays ready. `/live` returns 500 after the loop has not run for 15 seconds. Shutdown marks the process not ready, waits `shutdownDelay` so the kubelet observes it, runs the shutdown handler, then exits.
+
+Outside Kubernetes the probe binds a random port, so a local process does not take 3001.
+
+```js
+const { createMicroship } = require('microship')
+
+const ship = await createMicroship({
+  port: 3001,
+  shutdownDelay: 1000,
+  shutdownHandlerTimeout: 90000,
+  terminate: () => process.exit(0)
+})
+
+ship.registerShutdownHandler(async () => {
+  // drain in-flight work
+})
+
+ship.signalReady()
+```
+
+`shutdownHandlerTimeout` forces `terminate` when the handler does not finish. Signals are `SIGTERM`, `SIGHUP`, and `SIGINT`.

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "microship",
+  "description": "Readiness, liveness, and graceful shutdown for a Node process on Kubernetes.",
+  "homepage": "https://github.com/Kikobeats/microship",
+  "version": "0.1.1",
+  "main": "src/index.js",
+  "author": {
+    "email": "josefrancisco.verdu@gmail.com",
+    "name": "Kiko Beats",
+    "url": "https://github.com/Kikobeats"
+  },
+  "contributors": [],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kikobeats/microship.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Kikobeats/microship/issues"
+  },
+  "keywords": [
+    "kubernetes",
+    "liveness",
+    "readiness",
+    "shutdown"
+  ],
+  "devDependencies": {
+    "@commitlint/cli": "latest",
+    "@commitlint/config-conventional": "latest",
+    "c8": "latest",
+    "ci-publish": "latest",
+    "conventional-changelog": "latest",
+    "finepack": "latest",
+    "git-authors-cli": "latest",
+    "github-generate-release": "latest",
+    "nano-staged": "latest",
+    "simple-git-hooks": "latest",
+    "standard": "latest",
+    "standard-version": "latest"
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "contributors": "git-authors-cli && finepack && git add package.json && (git diff --cached --quiet || git commit -m 'build: contributors' --no-verify)",
+    "lint": "standard",
+    "postrelease": "pnpm release:tags && pnpm release:github && (ci-publish || pnpm publish --access=public)",
+    "release": "pnpm release:version && pnpm release:changelog && pnpm release:commit && pnpm release:tag",
+    "release:changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md",
+    "release:commit": "git add package.json CHANGELOG.md && git commit -m \"chore(release): $(node -p \"require('./package.json').version\")\"",
+    "release:github": "github-generate-release",
+    "release:tag": "git tag -a v$(node -p \"require('./package.json').version\") -m \"v$(node -p \"require('./package.json').version\")\"",
+    "release:tags": "git push origin HEAD:master --follow-tags",
+    "release:version": "standard-version --skip.changelog --skip.commit --skip.tag",
+    "test": "c8 node --test"
+  },
+  "license": "MIT",
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "nano-staged": {
+    "*.js": [
+      "npx @kikobeats/prettier-standard",
+      "standard --fix"
+    ],
+    "package.json": [
+      "finepack"
+    ]
+  },
+  "simple-git-hooks": {
+    "commit-msg": "npx commitlint --edit",
+    "pre-commit": "npx nano-staged"
+  }
+}

package/src/index.js

@@ -0,0 +1,113 @@
+'use strict'
+
+const { Worker } = require('worker_threads')
+const path = require('path')
+
+const { STALE_MS } = require('./status')
+
+const SIGNALS = ['SIGTERM', 'SIGHUP', 'SIGINT']
+const EXIT_DELAY = 1000
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+const inKubernetes = () => Boolean(process.env.KUBERNETES_SERVICE_HOST)
+
+const createMicroship = async ({
+  detectKubernetes = true,
+  port = 3001,
+  shutdownDelay,
+  shutdownHandlerTimeout = 5000,
+  signals = SIGNALS,
+  staleMs = STALE_MS,
+  terminate = () => process.exit(0)
+} = {}) => {
+  const local = detectKubernetes && !inKubernetes()
+  const probePort = local ? 0 : port
+  const delay = shutdownDelay === undefined ? (local ? 0 : 5000) : shutdownDelay
+
+  let ready = false
+  let shuttingDown = false
+  const handlers = []
+  const view = new Int32Array(new SharedArrayBuffer(12))
+
+  const publish = () => {
+    Atomics.store(view, 0, ready && !shuttingDown ? 1 : 0)
+    Atomics.store(view, 1, shuttingDown ? 1 : 0)
+  }
+
+  const worker = new Worker(path.join(__dirname, 'worker.js'), {
+    workerData: { port: probePort, sab: view.buffer, staleMs }
+  })
+  worker.unref()
+
+  const bound = await new Promise((resolve, reject) => {
+    worker.once('message', message => {
+      if (message.error) reject(new Error(message.error))
+      else resolve(message.port)
+    })
+    worker.once('error', reject)
+  })
+
+  const beat = setInterval(() => {
+    publish()
+    Atomics.add(view, 2, 1)
+  }, 500)
+  beat.unref()
+
+  const signalReady = () => {
+    if (shuttingDown) return
+    ready = true
+    publish()
+  }
+
+  const signalNotReady = () => {
+    ready = false
+    publish()
+  }
+
+  const shutdown = async () => {
+    if (shuttingDown) return
+    ready = false
+    shuttingDown = true
+    publish()
+    if (delay) await sleep(delay)
+
+    let forced = false
+    const timer = setTimeout(() => {
+      forced = true
+      terminate()
+    }, shutdownHandlerTimeout)
+    timer.unref()
+
+    try {
+      for (const handler of handlers) await handler()
+    } catch (_) {}
+
+    clearTimeout(timer)
+    if (!forced) setTimeout(terminate, EXIT_DELAY).unref()
+  }
+
+  const onSignal = () => {
+    shutdown().catch(() => {})
+  }
+  for (const signal of signals) process.on(signal, onSignal)
+
+  return {
+    port: bound,
+    isServerReady: () => ready && !shuttingDown,
+    isServerShuttingDown: () => shuttingDown,
+    registerShutdownHandler: handler => {
+      handlers.push(handler)
+    },
+    shutdown,
+    signalNotReady,
+    signalReady,
+    stop: async () => {
+      clearInterval(beat)
+      for (const signal of signals) process.off(signal, onSignal)
+      await worker.terminate()
+    }
+  }
+}
+
+module.exports = { createMicroship, STALE_MS }

package/src/status.js

@@ -0,0 +1,25 @@
+'use strict'
+
+const STALE_MS = 15000
+
+const createState = () => ({ lastBeat: 0, lastBeatAt: 0 })
+
+const beatAge = (view, state, now) => {
+  const beat = Atomics.load(view, 2)
+  if (state.lastBeatAt === 0 || beat !== state.lastBeat) {
+    state.lastBeat = beat
+    state.lastBeatAt = now
+  }
+  return now - state.lastBeatAt
+}
+
+const statusFor = (view, state, url, now, staleMs = STALE_MS) => {
+  const shuttingDown = Atomics.load(view, 1) === 1
+  const ready = Atomics.load(view, 0) === 1 && !shuttingDown
+  const live = !shuttingDown && beatAge(view, state, now) < staleMs
+  if (url === '/live') return live ? 200 : 500
+  if (url === '/ready') return ready ? 200 : 500
+  return 404
+}
+
+module.exports = { STALE_MS, createState, statusFor }

package/src/worker.js

@@ -0,0 +1,24 @@
+'use strict'
+
+const { parentPort, workerData } = require('worker_threads')
+const http = require('http')
+
+const { createState, statusFor } = require('./status')
+
+const view = new Int32Array(workerData.sab)
+const state = createState()
+
+const server = http.createServer((req, res) => {
+  const url = (req.url || '/').split('?')[0]
+  const code = statusFor(view, state, url, Date.now(), workerData.staleMs)
+  res.writeHead(code, { 'content-type': 'text/plain' })
+  res.end()
+})
+
+server.on('error', error => {
+  parentPort.postMessage({ error: error.message })
+})
+
+server.listen(workerData.port, '0.0.0.0', () => {
+  parentPort.postMessage({ port: server.address().port })
+})