@better-forge/runtime 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,14 @@
+export { backupDir, dataDir, databasePath, isSetupComplete, setupConfigPath, writeSetupComplete } from './dataPaths.js'
+export { resolveTrustProxy, type TrustProxy } from './proxy.js'
+export { rateLimitKey } from './rateLimitKey.js'
+export { createPublicUrlResolver } from './publicUrl.js'
+export { errorHandler } from './errorHandler.js'
+export { createAppLock } from './appLock.js'
+export { isOwnerAlive, isProcessAlive, currentProcessOwner, PROCESS_STARTED_AT, type ProcessOwner } from './processLiveness.js'
+export { createRuntimeShutdown, type RuntimeShutdown, type ShutdownSteps } from './shutdown.js'
+export { createSse, type ClientInfo, type EventStreamOptions, type SseFilter, type SseLimits } from './sse.js'
+export { createUpdateCheck, isNewerVersion, updateCheckEnabled, type LatestRelease } from './updateCheck.js'
+export { createHealthRoutes, createSystemHealth, type ComponentStatus, type HealthContributor, type HealthSection, type SystemHealthReport } from './health.js'
+export { resolveAppVersion } from './version.js'
+export { createBetterApp, JWT_EXPIRES_IN, resolveJwtSecret, type BetterApp, type BetterAppOptions } from './createBetterApp.js'
+export { redactUrl, type UrlRedaction } from './redactUrl.js'

package/src/processLiveness.ts

@@ -0,0 +1,31 @@
+/** Wall-clock start of this process; identical in the main thread and in worker threads. */
+export const PROCESS_STARTED_AT = Math.round(Date.now() - process.uptime() * 1000)
+
+/** Signal 0 checks existence only; EPERM still means the process exists under another user. */
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+export interface ProcessOwner { pid: number; processStartedAt: number }
+
+export function currentProcessOwner(): ProcessOwner {
+  return { pid: process.pid, processStartedAt: PROCESS_STARTED_AT }
+}
+
+/**
+ * Whether the recorded owner may still be running. The start time distinguishes a crashed
+ * earlier incarnation that reused our pid (containers restart as the same pid) from us.
+ */
+export function isOwnerAlive(owner: Partial<ProcessOwner>): boolean {
+  if (typeof owner.pid !== 'number') return false
+  if (owner.pid === process.pid) {
+    return typeof owner.processStartedAt === 'number' && Math.abs(owner.processStartedAt - PROCESS_STARTED_AT) < 1_000
+  }
+  return isProcessAlive(owner.pid)
+}

package/src/proxy.ts

@@ -0,0 +1,20 @@
+import type { FastifyServerOptions } from 'fastify'
+
+export type TrustProxy = NonNullable<FastifyServerOptions['trustProxy']>
+
+export function resolveTrustProxy(raw = process.env['TRUST_PROXY']): TrustProxy {
+  const value = raw?.trim()
+  if (!value || value.toLowerCase() === 'false') return false
+  if (value.toLowerCase() === 'true') return true
+  if (/^\d+$/.test(value)) {
+    // Hop-count-only trust can't validate the immediate peer, so @fastify/proxy-addr
+    // no longer supports it (it always fails closed). Treat a numeric value as "trust a
+    // proxy on this host or on a private network": loopback covers a proxy on the same
+    // host, uniquelocal (10/8, 172.16/12, 192.168/16, fc00::/7) covers one reaching the
+    // app over a Docker bridge network. Use an explicit address/CIDR list to narrow it.
+    return ['loopback', 'uniquelocal']
+  }
+  const addresses = value.split(',').map((address) => address.trim()).filter(Boolean)
+  if (addresses.length === 0) return false
+  return addresses.length === 1 ? addresses[0]! : addresses
+}

package/src/publicUrl.ts

@@ -0,0 +1,26 @@
+/**
+ * The absolute base URL the application is reached at, from the `PUBLIC_URL` environment variable.
+ *
+ * It is deployment configuration, not an admin setting: links in emails and redirects are built from it, so changing
+ * it must require access to the server — an account in the admin console alone must not be able to point those links
+ * at another domain.
+ *
+ * The returned function reports an invalid value once per distinct value, then keeps answering ''.
+ */
+export function createPublicUrlResolver() {
+  let warnedAbout: string | null = null
+
+  return function resolvePublicUrl(env: NodeJS.ProcessEnv = process.env): string {
+    const raw = (env['PUBLIC_URL'] ?? '').trim().replace(/\/+$/, '')
+    if (!raw) return ''
+    try {
+      const url = new URL(raw)
+      if ((url.protocol === 'https:' || url.protocol === 'http:') && !url.search && !url.hash) return raw
+    } catch { /* reported below */ }
+    if (warnedAbout !== raw) {
+      warnedAbout = raw
+      console.warn(`PUBLIC_URL "${raw}" is not an absolute http(s) URL without query or fragment — ignoring it`)
+    }
+    return ''
+  }
+}

package/src/rateLimitKey.ts

@@ -0,0 +1,20 @@
+import { isIPv6 } from 'node:net'
+
+/**
+ * The key a client is rate limited under. An IPv4 address is its own key; an IPv6 address is
+ * reduced to its /64, because one subscriber is routinely handed a whole /64 and could otherwise
+ * rotate through billions of addresses to dodge a per-address limit.
+ */
+export function rateLimitKey(ip: string): string {
+  const address = ip.split('%')[0] ?? ip
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address)
+  if (mapped) return mapped[1]!
+  if (!isIPv6(address)) return address
+
+  const [head = '', tail] = address.split('::')
+  const front = head ? head.split(':') : []
+  const back = tail ? tail.split(':') : []
+  const groups = tail === undefined ? front : [...front, ...Array<string>(8 - front.length - back.length).fill('0'), ...back]
+  const prefix = groups.slice(0, 4).map((group) => parseInt(group, 16).toString(16))
+  return `${prefix.join(':')}::/64`
+}

package/src/redactUrl.ts

@@ -0,0 +1,49 @@
+export interface UrlRedaction {
+  /** Query parameters whose value is replaced. Names are compared after decoding, ignoring case. */
+  queryParams?: readonly string[] | undefined
+  /** Paths whose next segment is a capability token (`/t/` hides `abc` in `/t/abc?x=1`), matched after percent-decoding as the router does. */
+  pathTokenPrefixes?: readonly string[] | undefined
+}
+
+const REDACTED = '[redacted]'
+
+function decodeName(name: string): string {
+  try { return decodeURIComponent(name.replace(/\+/g, ' ')) } catch { return name }
+}
+
+/**
+ * The router decodes the path before it matches a route (`/%68ook/` reaches `/hook/`), but keeps an encoded slash.
+ * Each segment is decoded on its own, so one malformed sequence leaves only that segment as it was sent.
+ */
+function decodePath(path: string): string {
+  return path.split('/').map((segment) => {
+    try { return decodeURI(segment) } catch { return segment }
+  }).join('/')
+}
+
+/** The URL as it may be logged: capability tokens in the path and the values of secret query parameters are hidden. */
+export function redactUrl(url: string, rules: UrlRedaction): string {
+  const queryAt = url.indexOf('?')
+  let path = queryAt === -1 ? url : url.slice(0, queryAt)
+  let query = queryAt === -1 ? '' : url.slice(queryAt + 1)
+
+  const decoded = decodePath(path)
+  for (const prefix of rules.pathTokenPrefixes ?? []) {
+    // Everything from the token on is dropped: the rest of a path is not decoded text a log should repeat.
+    if (decoded.startsWith(prefix) && decoded.length > prefix.length) {
+      path = `${prefix}${REDACTED}`
+      break
+    }
+  }
+
+  const names = (rules.queryParams ?? []).map((name) => name.toLowerCase())
+  if (names.length > 0 && query) {
+    query = query.split('&').map((pair) => {
+      const equals = pair.indexOf('=')
+      if (equals === -1) return pair
+      return names.includes(decodeName(pair.slice(0, equals)).toLowerCase()) ? `${pair.slice(0, equals + 1)}${REDACTED}` : pair
+    }).join('&')
+  }
+
+  return queryAt === -1 ? path : `${path}?${query}`
+}

package/src/shutdown.ts

@@ -0,0 +1,62 @@
+export interface ShutdownSteps {
+  /** Stops producing new work and ends long-lived streams (SSE) so the server can drain. */
+  stopIntake: () => void
+  /** Stops accepting connections and resolves once in-flight requests have finished. */
+  closeServer: () => Promise<void>
+  /** Resolves once background work that started before the stop (a check about to record its result, say) has finished. */
+  drain?: () => Promise<void>
+  /** Closes the DB and releases the app lock — only safe once no request or background work can still use them. */
+  releaseResources: () => void
+  exit: (code: number) => void
+  forceExitMs?: number
+}
+
+export interface RuntimeShutdown {
+  /** Immediate full teardown, for paths where the server never started or has already closed. */
+  cleanup: () => void
+  /** Signal handler: drain the server and the background work first, then release shared resources and exit. */
+  shutdown: () => void
+}
+
+export function createRuntimeShutdown(steps: ShutdownSteps): RuntimeShutdown {
+  let intakeStopped = false
+  let released = false
+  let shuttingDown = false
+  let forceExit: ReturnType<typeof setTimeout> | undefined
+  const stopIntake = () => {
+    if (intakeStopped) return
+    intakeStopped = true
+    steps.stopIntake()
+  }
+  const release = () => {
+    if (released) return
+    released = true
+    steps.releaseResources()
+  }
+  const cleanup = () => {
+    stopIntake()
+    // A signal-driven shutdown releases after the drain; the server's close hook fires before it.
+    if (!shuttingDown) release()
+  }
+  const finish = (code: number) => {
+    clearTimeout(forceExit)
+    release()
+    steps.exit(code)
+  }
+
+  return {
+    cleanup,
+    shutdown: () => {
+      if (shuttingDown) return
+      shuttingDown = true
+      forceExit = setTimeout(() => {
+        release()
+        steps.exit(1)
+      }, steps.forceExitMs ?? 5_000)
+      forceExit.unref()
+      stopIntake()
+      // The forced exit above is the deadline of the drain: work still running by then is left to the next start.
+      steps.closeServer().then(() => steps.drain?.()).then(() => finish(0), () => finish(1))
+    },
+  }
+}

package/src/sse.ts

@@ -0,0 +1,154 @@
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { rateLimitKey } from './rateLimitKey.js'
+
+type SseClient = FastifyReply
+
+/**
+ * Shapes what one client receives: return the data to send (possibly reduced) or `null` to skip the
+ * event. Clients without a filter receive everything as broadcast.
+ */
+export type SseFilter = (event: string, data: unknown) => { data: unknown } | null
+
+export interface ClientInfo {
+  filter?: SseFilter | undefined
+  /** Set for signed-in streams, so revoking the session can end them. */
+  session?: { sessionId: string; userId: number } | undefined
+  ip?: string | undefined
+}
+
+export interface SseLimits {
+  /** Open anonymous streams in total; further ones are refused with 429. Signed-in streams are not counted. */
+  maxClients: number
+  /** Open anonymous streams from one address (an IPv6 /64 counts as one); further ones are refused with 429. */
+  maxClientsPerIp: number
+  /** A client with more unsent bytes than this is not reading and gets disconnected. */
+  maxBufferedBytes: number
+}
+
+const DEFAULT_LIMITS: SseLimits = { maxClients: 1000, maxClientsPerIp: 10, maxBufferedBytes: 1024 * 1024 }
+
+export interface EventStreamOptions {
+  filter?: SseFilter
+  session?: { sessionId: string; userId: number } | undefined
+  /** Re-checked with every keep-alive ping; the stream ends once it resolves to false. */
+  stillAllowed?: () => Promise<boolean>
+  pingIntervalMs?: number
+}
+
+/** Live event streams (server-sent events) to browsers, with per-client filters and session-bound streams. All state is in the returned closure. */
+export function createSse(limitOptions: Partial<SseLimits> = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...limitOptions }
+  const clients = new Map<SseClient, ClientInfo>()
+
+  const listeners = new Set<(event: string) => void>()
+
+  function end(client: SseClient) {
+    try { client.raw.end() } catch { /* ignore shutdown races */ }
+    try { client.raw.destroy() } catch { /* ignore shutdown races */ }
+    clients.delete(client)
+  }
+
+  /** Writes to one client and drops it when it cannot keep up, so a stalled reader cannot grow the heap. */
+  function send(client: SseClient, chunk: string) {
+    try {
+      client.raw.write(chunk)
+      if (client.raw.writableLength > limits.maxBufferedBytes) end(client)
+    } catch {
+      clients.delete(client)
+    }
+  }
+
+  const sseService = {
+    add(client: SseClient, info: ClientInfo = {}) {
+      clients.set(client, info)
+    },
+
+    remove(client: SseClient) {
+      clients.delete(client)
+    },
+
+    /** Server-side hook for anything that must react to the same events clients receive. */
+    onBroadcast(listener: (event: string) => void): () => void {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+
+    broadcast(event: string, data: unknown) {
+      for (const listener of listeners) listener(event)
+      const format = (value: unknown) => `event: ${event}\ndata: ${JSON.stringify(value)}\n\n`
+      const payload = format(data)
+      for (const [client, { filter }] of clients) {
+        const shaped = filter ? filter(event, data) : { data }
+        if (!shaped) continue
+        send(client, shaped.data === data ? payload : format(shaped.data))
+      }
+    },
+
+    /** Ends the signed-in streams whose session matches, e.g. after the session was revoked. */
+    disconnectSessions(match: (session: { sessionId: string; userId: number }) => boolean) {
+      for (const [client, { session }] of clients) {
+        if (session && match(session)) end(client)
+      }
+    },
+
+    /** Ends every stream opened without signing in, e.g. once access is restricted to signed-in users. */
+    disconnectAnonymous() {
+      for (const [client, { session }] of clients) {
+        if (!session) end(client)
+      }
+    },
+
+    closeAll() {
+      for (const client of clients.keys()) end(client)
+    },
+
+    clientCount() {
+      return clients.size
+    },
+  }
+
+  /** Holds the request open as an event stream until the client disconnects or loses access. */
+  async function serveEventStream(req: FastifyRequest, reply: FastifyReply, options: EventStreamOptions = {}): Promise<void> {
+    // Only anonymous streams are limited: a signed-in one is accountable, and counting it would let
+    // visitors fill the budget the admin stream needs.
+    const ip = rateLimitKey(req.ip)
+    if (!options.session) {
+      let total = 0
+      let fromIp = 0
+      for (const client of clients.values()) {
+        if (client.session) continue
+        total++
+        if (client.ip === ip) fromIp++
+      }
+      if (total >= limits.maxClients || fromIp >= limits.maxClientsPerIp) {
+        return reply.code(429).send({ error: 'Too many open event streams' })
+      }
+    }
+
+    reply.raw.setHeader('Content-Type', 'text/event-stream')
+    reply.raw.setHeader('Cache-Control', 'no-cache')
+    reply.raw.setHeader('Connection', 'keep-alive')
+    reply.raw.setHeader('X-Accel-Buffering', 'no')
+    reply.raw.flushHeaders()
+
+    sseService.add(reply, { filter: options.filter, session: options.session, ip })
+    reply.raw.write('event: ping\ndata: {}\n\n')
+
+    const pingInterval = setInterval(() => {
+      void (async () => {
+        if (options.stillAllowed && !(await options.stillAllowed().catch(() => false))) {
+          clearInterval(pingInterval)
+          end(reply)
+          return
+        }
+        send(reply, `event: ping\ndata: ${JSON.stringify({ ts: Date.now() })}\n\n`)
+        if (!clients.has(reply)) clearInterval(pingInterval)
+      })()
+    }, options.pingIntervalMs ?? 30_000)
+
+    req.raw.on('close', () => { clearInterval(pingInterval); sseService.remove(reply) })
+    await new Promise<void>((resolve) => { req.raw.on('close', resolve) })
+  }
+
+  return { sseService, serveEventStream }
+}

package/src/updateCheck.ts

@@ -0,0 +1,107 @@
+
+
+const REFRESH_MS = 6 * 60 * 60 * 1000
+
+const RETRY_MS = 5 * 60 * 1000
+
+const TIMEOUT_MS = 5_000
+
+export interface LatestRelease {
+  version: string
+  url: string
+}
+
+/** `UPDATE_CHECK=false` keeps the instance from contacting GitHub (air-gapped or privacy-minded installs). */
+export function updateCheckEnabled(environment: { UPDATE_CHECK?: string | undefined } = process.env): boolean {
+  return environment.UPDATE_CHECK?.trim().toLowerCase() !== 'false'
+}
+
+function parseVersion(value: string): [number, number, number] | null {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(value.trim())
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null
+}
+
+/** True when `candidate` is a higher x.y.z than `current`; false when either is not a plain release version. */
+export function isNewerVersion(candidate: string, current: string): boolean {
+  const a = parseVersion(candidate)
+  const b = parseVersion(current)
+  if (!a || !b) return false
+  for (let i = 0; i < 3; i++) {
+    if (a[i]! !== b[i]!) return a[i]! > b[i]!
+  }
+  return false
+}
+
+/**
+ * Asks GitHub which release of `repository` ("owner/name") is newest and remembers it, to point out an update to
+ * whoever runs an older `version()`. All state is in the returned closure.
+ */
+export function createUpdateCheck(options: { name: string; repository: string; version: () => string }) {
+  const RELEASES_API = `https://api.github.com/repos/${options.repository}/releases/latest`
+  const resolveAppVersion = options.version
+
+  let latest: LatestRelease | null = null
+
+  let timer: NodeJS.Timeout | undefined
+
+  /** Bumped by every start and stop, so a check still in flight when the service stops cannot schedule another. */
+  let generation = 0
+
+  /** The newest published release, null when there is none a user should be pointed at; throws when GitHub cannot be asked. */
+  async function fetchLatestRelease(): Promise<LatestRelease | null> {
+    const response = await fetch(RELEASES_API, {
+      headers: { Accept: 'application/vnd.github+json', 'User-Agent': `${options.name}/${resolveAppVersion()}` },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    })
+    if (!response.ok) throw new Error(`GitHub answered ${response.status}`)
+    const body: unknown = await response.json()
+    if (typeof body !== 'object' || body === null) return null
+    const { tag_name: tag, html_url: url, draft, prerelease } = body as Record<string, unknown>
+    if (typeof tag !== 'string' || typeof url !== 'string' || draft === true || prerelease === true) return null
+    if (!parseVersion(tag) || !url.startsWith(`https://github.com/${options.repository}/`)) return null
+    return { version: tag.replace(/^v/, ''), url }
+  }
+
+  /** Asks GitHub once and remembers the answer; true when it could be asked. Never throws. */
+  async function checkForUpdate(): Promise<boolean> {
+    try {
+      latest = await fetchLatestRelease()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /** Checks now, in the background, then every few hours (sooner after a failure). A no-op when `UPDATE_CHECK=false`. */
+  function startUpdateCheck(): void {
+    stopUpdateCheck()
+    if (!updateCheckEnabled()) return
+    const mine = generation
+    const run = async () => {
+      const asked = await checkForUpdate()
+      if (mine !== generation) return
+      timer = setTimeout(() => void run(), asked ? REFRESH_MS : RETRY_MS)
+      timer.unref()
+    }
+    void run()
+  }
+
+  function stopUpdateCheck(): void {
+    generation++
+    clearTimeout(timer)
+    timer = undefined
+  }
+
+  /** The newest release when it is newer than the running version, else null. Reads what the background check found. */
+  function getAvailableUpdate(): LatestRelease | null {
+    if (!updateCheckEnabled() || !latest) return null
+    return isNewerVersion(latest.version, resolveAppVersion()) ? latest : null
+  }
+
+  function resetUpdateCheck(): void {
+    stopUpdateCheck()
+    latest = null
+  }
+
+  return { checkForUpdate, startUpdateCheck, stopUpdateCheck, getAvailableUpdate, resetUpdateCheck }
+}

package/src/version.ts

@@ -0,0 +1,7 @@
+/** The running version: the `APP_VERSION` environment variable (set by the image build), else the version in the package. */
+export function resolveAppVersion(
+  packageVersion: string,
+  environment: { APP_VERSION?: string | undefined } = process.env,
+): string {
+  return environment.APP_VERSION?.trim() || packageVersion
+}