@better-forge/runtime 0.1.0 → 0.1.1

package/src/health.ts

@@ -1,109 +1,109 @@
-import type { FastifyInstance } from 'fastify'
-import { sql } from 'drizzle-orm'
-import type { SqliteDatabase } from '@better-forge/db'
-import type { LatestRelease } from './updateCheck.js'
-
-/** `GET /health` (the process is up) and `GET /ready` (set up and the database answers), for load balancers and probes. */
-export function createHealthRoutes(options: { db: SqliteDatabase; isSetupComplete: () => boolean }) {
-  return async function healthRoutes(app: FastifyInstance) {
-    app.get('/health', async () => ({ status: 'ok' }))
-
-    app.get('/ready', async (_req, reply) => {
-      if (!options.isSetupComplete()) {
-        return reply.code(503).send({ status: 'not_ready' })
-      }
-      try {
-        await options.db.run(sql`SELECT 1`)
-        return { status: 'ready' }
-      } catch {
-        return reply.code(503).send({ status: 'not_ready' })
-      }
-    })
-  }
-}
-
-export type ComponentStatus = 'ok' | 'attention' | 'error' | 'disabled'
-
-/** One part of the system the report describes. Its `status` is what the overall status is decided by. */
-export type HealthSection = { status: ComponentStatus } & Record<string, unknown>
-
-export interface HealthContributor {
-  /** The key of the section in the report. */
-  key: string
-  /**
-   * When true, a section in the `error` status makes the whole report `degraded`; otherwise it is only shown.
-   */
-  critical: boolean
-  /** Builds the section. Called after the database was probed; `now` is the time the report is made for. */
-  collect(context: { now: number; databaseOk: boolean }): Promise<HealthSection> | HealthSection
-}
-
-export interface SystemHealthReport {
-  status: 'healthy' | 'degraded'
-  generatedAt: number
-  application: {
-    status: 'ok'
-    version: string
-    uptimeSeconds: number
-    /** A newer published release, or null when up to date, unknown or the update check is off. */
-    update: LatestRelease | null
-  }
-  database: {
-    status: 'ok' | 'error'
-    responseMs: number | null
-  }
-  /** The sections of the contributors, by key. */
-  [section: string]: unknown
-}
-
-/**
- * The protected report of how the instance is doing: the process, the database, and one section per contributor the
- * application registers (a scheduler, a queue, backups, ...). Exposes state, not raw errors.
- */
-export function createSystemHealth(options: {
-  db: SqliteDatabase
-  version: () => string
-  update: () => LatestRelease | null
-  contributors: readonly HealthContributor[]
-}) {
-  async function getSystemHealthReport(now = Date.now()): Promise<SystemHealthReport> {
-    const databaseStartedAt = Date.now()
-    let database: SystemHealthReport['database'] = { status: 'error', responseMs: null }
-    try {
-      await options.db.run(sql`SELECT 1`)
-      database = { status: 'ok', responseMs: Date.now() - databaseStartedAt }
-    } catch {
-      // The protected report deliberately exposes state, not raw database errors.
-    }
-
-    const sections: Record<string, HealthSection> = {}
-    for (const contributor of options.contributors) {
-      sections[contributor.key] = await contributor.collect({ now, databaseOk: database.status === 'ok' })
-    }
-    const failing = options.contributors.some((contributor) => contributor.critical && sections[contributor.key]!.status === 'error')
-
-    return {
-      status: database.status === 'ok' && !failing ? 'healthy' : 'degraded',
-      generatedAt: now,
-      application: { status: 'ok', version: options.version(), uptimeSeconds: Math.floor(process.uptime()), update: options.update() },
-      database,
-      ...sections,
-    }
-  }
-
-  /** Routes: the report at `/` and, at `/update`, only the running version and a newer release, if any. */
-  async function systemHealthRoutes(app: FastifyInstance) {
-    app.get('/', async (_request, reply) => {
-      reply.header('Cache-Control', 'no-store')
-      return getSystemHealthReport()
-    })
-
-    /** Cheap enough for a dashboard to ask on every visit. */
-    app.get('/update', async (_request, reply) => {
-      reply.header('Cache-Control', 'no-store')
-      return { version: options.version(), update: options.update() }
-    })
-  }
-
-  return { getSystemHealthReport, systemHealthRoutes }
-}
+import type { FastifyInstance } from 'fastify'
+import { sql } from 'drizzle-orm'
+import type { SqliteDatabase } from '@better-forge/db'
+import type { LatestRelease } from './updateCheck.js'
+
+/** `GET /health` (the process is up) and `GET /ready` (set up and the database answers), for load balancers and probes. */
+export function createHealthRoutes(options: { db: SqliteDatabase; isSetupComplete: () => boolean }) {
+  return async function healthRoutes(app: FastifyInstance) {
+    app.get('/health', async () => ({ status: 'ok' }))
+
+    app.get('/ready', async (_req, reply) => {
+      if (!options.isSetupComplete()) {
+        return reply.code(503).send({ status: 'not_ready' })
+      }
+      try {
+        await options.db.run(sql`SELECT 1`)
+        return { status: 'ready' }
+      } catch {
+        return reply.code(503).send({ status: 'not_ready' })
+      }
+    })
+  }
+}
+
+export type ComponentStatus = 'ok' | 'attention' | 'error' | 'disabled'
+
+/** One part of the system the report describes. Its `status` is what the overall status is decided by. */
+export type HealthSection = { status: ComponentStatus } & Record<string, unknown>
+
+export interface HealthContributor {
+  /** The key of the section in the report. */
+  key: string
+  /**
+   * When true, a section in the `error` status makes the whole report `degraded`; otherwise it is only shown.
+   */
+  critical: boolean
+  /** Builds the section. Called after the database was probed; `now` is the time the report is made for. */
+  collect(context: { now: number; databaseOk: boolean }): Promise<HealthSection> | HealthSection
+}
+
+export interface SystemHealthReport {
+  status: 'healthy' | 'degraded'
+  generatedAt: number
+  application: {
+    status: 'ok'
+    version: string
+    uptimeSeconds: number
+    /** A newer published release, or null when up to date, unknown or the update check is off. */
+    update: LatestRelease | null
+  }
+  database: {
+    status: 'ok' | 'error'
+    responseMs: number | null
+  }
+  /** The sections of the contributors, by key. */
+  [section: string]: unknown
+}
+
+/**
+ * The protected report of how the instance is doing: the process, the database, and one section per contributor the
+ * application registers (a scheduler, a queue, backups, ...). Exposes state, not raw errors.
+ */
+export function createSystemHealth(options: {
+  db: SqliteDatabase
+  version: () => string
+  update: () => LatestRelease | null
+  contributors: readonly HealthContributor[]
+}) {
+  async function getSystemHealthReport(now = Date.now()): Promise<SystemHealthReport> {
+    const databaseStartedAt = Date.now()
+    let database: SystemHealthReport['database'] = { status: 'error', responseMs: null }
+    try {
+      await options.db.run(sql`SELECT 1`)
+      database = { status: 'ok', responseMs: Date.now() - databaseStartedAt }
+    } catch {
+      // The protected report deliberately exposes state, not raw database errors.
+    }
+
+    const sections: Record<string, HealthSection> = {}
+    for (const contributor of options.contributors) {
+      sections[contributor.key] = await contributor.collect({ now, databaseOk: database.status === 'ok' })
+    }
+    const failing = options.contributors.some((contributor) => contributor.critical && sections[contributor.key]!.status === 'error')
+
+    return {
+      status: database.status === 'ok' && !failing ? 'healthy' : 'degraded',
+      generatedAt: now,
+      application: { status: 'ok', version: options.version(), uptimeSeconds: Math.floor(process.uptime()), update: options.update() },
+      database,
+      ...sections,
+    }
+  }
+
+  /** Routes: the report at `/` and, at `/update`, only the running version and a newer release, if any. */
+  async function systemHealthRoutes(app: FastifyInstance) {
+    app.get('/', async (_request, reply) => {
+      reply.header('Cache-Control', 'no-store')
+      return getSystemHealthReport()
+    })
+
+    /** Cheap enough for a dashboard to ask on every visit. */
+    app.get('/update', async (_request, reply) => {
+      reply.header('Cache-Control', 'no-store')
+      return { version: options.version(), update: options.update() }
+    })
+  }
+
+  return { getSystemHealthReport, systemHealthRoutes }
+}

package/src/index.ts

@@ -1,14 +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'
+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

@@ -1,31 +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)
-}
+/** 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

@@ -1,20 +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
-}
+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

@@ -1,26 +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 ''
-  }
-}
+/**
+ * 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

@@ -1,20 +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`
-}
+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

@@ -1,49 +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}`
-}
+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}`
+}