/** * Tiny HTTP admin server for the worker process. * * Exposes `/status` (public, JSON, 200/503) and `/metrics` (token-protected, * Prom text-format) so Prometheus + Uptime monitors can scrape the worker * the same way they scrape the API. The worker has no Hono app today and we * don't want to pull in one just for two endpoints — node's built-in * `http.createServer` is plenty. * * The server only listens when `METRICS_ENABLED=true`. Otherwise this module * is a no-op so dev / Sentry-less staging environments keep a single open * file descriptor budget. */ import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"; import { isMetricsEnabled, validateMetricsTokenAuth, type MetricsRegistry } from "@hivegrid/metrics"; export type WorkerStatusCheckOutcome = "ok" | "down" | "disabled"; export type WorkerStatusReport = { status: "ok" | "down"; service: "worker"; checks: { runtime: WorkerStatusCheckOutcome; outboxDispatcher?: WorkerStatusCheckOutcome; workflowTrigger?: WorkerStatusCheckOutcome; pluginHookFanout?: WorkerStatusCheckOutcome; transactionalMailOutbox?: WorkerStatusCheckOutcome; portalStatusMail?: WorkerStatusCheckOutcome; emailSequences?: WorkerStatusCheckOutcome; chatLinkPreview?: WorkerStatusCheckOutcome; }; // Resolved WORKFLOW_TRIGGER_EXECUTOR_MODE for this worker. Only present when the // workflow-trigger subscriber runs on this worker (i.e. the check is not "disabled"), // so operators can see whether queued workflows execute over the HTTP bridge, the // native runner, or the hybrid fallback path. workflowTriggerExecutorMode?: "http" | "native" | "hybrid"; version: string; uptime_seconds: number; region: string; }; export type WorkerAdminServerOptions = { enabled: boolean; token: string | undefined; registry: MetricsRegistry; port: number; host?: string; logger?: { error?: (fields: Record, msg: string) => void; info?: (fields: Record, msg: string) => void }; buildStatus: () => Promise | WorkerStatusReport; }; export type WorkerAdminServerHandle = { close: () => Promise; port: number; }; // Health-server (apps/worker/src/health-server.ts) defaults to 9100. Admin // metrics-server must default to a different port to avoid EADDRINUSE in the // container — both servers bind to 0.0.0.0 inside the same process. export const DEFAULT_WORKER_ADMIN_PORT = 9101; export function createWorkerAdminHandler(deps: Omit) { return async function handler(req: IncomingMessage, res: ServerResponse): Promise { const url = req.url ?? "/"; if (url === "/status" || url === "/status/") { await respondStatus(res, deps); return; } if (url === "/metrics" || url === "/metrics/") { await respondMetrics(req, res, deps); return; } res.statusCode = 404; res.setHeader("content-type", "application/json"); res.end(JSON.stringify({ error: { code: "not_found", message: "Endpoint not found." } })); }; } export function startWorkerAdminServer(options: WorkerAdminServerOptions): WorkerAdminServerHandle | undefined { if (!options.enabled) { return undefined; } const handler = createWorkerAdminHandler({ enabled: options.enabled, token: options.token, registry: options.registry, buildStatus: options.buildStatus, ...(options.logger ? { logger: options.logger } : {}), }); const server: Server = createServer((req, res) => { void handler(req, res).catch((error: unknown) => { options.logger?.error?.({ error: serialiseError(error) }, "worker admin server handler failed"); if (!res.headersSent) { res.statusCode = 500; res.setHeader("content-type", "application/json"); res.end(JSON.stringify({ error: { code: "internal", message: "Internal server error." } })); } else { res.end(); } }); }); server.listen(options.port, options.host ?? "0.0.0.0"); options.logger?.info?.({ port: options.port, host: options.host ?? "0.0.0.0" }, "worker admin server listening"); return { port: options.port, close: () => new Promise((resolve) => { server.close(() => { resolve(); }); }), }; } async function respondStatus(res: ServerResponse, deps: Omit): Promise { let report: WorkerStatusReport; try { report = await deps.buildStatus(); } catch (error) { deps.logger?.error?.({ error: serialiseError(error) }, "worker admin status build failed"); report = { status: "down", service: "worker", checks: { runtime: "down" }, version: process.env.APP_REVISION?.trim() || "unknown", uptime_seconds: Math.round(process.uptime()), region: process.env.APP_REGION?.trim() || "unknown", }; } res.statusCode = report.status === "ok" ? 200 : 503; res.setHeader("content-type", "application/json"); res.end(JSON.stringify(report)); } async function respondMetrics(req: IncomingMessage, res: ServerResponse, deps: Omit): Promise { if (!deps.enabled) { res.statusCode = 404; res.setHeader("content-type", "application/json"); res.end(JSON.stringify({ error: { code: "not_found", message: "Endpoint not enabled." } })); return; } const auth = validateMetricsTokenAuth({ metricsEnabled: true, configuredToken: deps.token, authorizationHeader: pickAuthorizationHeader(req), }); if (!auth.ok) { if (auth.status === 500) { res.statusCode = 500; res.setHeader("content-type", "application/json"); res.end(JSON.stringify({ error: { code: "token_misconfigured", message: "Metrics token not configured." } })); return; } if (auth.status === 403) { res.statusCode = 404; res.setHeader("content-type", "application/json"); res.end(JSON.stringify({ error: { code: "not_found", message: "Endpoint not enabled." } })); return; } res.statusCode = 401; res.setHeader("content-type", "application/json"); res.end(JSON.stringify({ error: { code: auth.code, message: "Authentication required." } })); return; } const text = await deps.registry.metrics(); res.statusCode = 200; res.setHeader("content-type", deps.registry.contentType); res.setHeader("cache-control", "no-store"); res.end(text); } function pickAuthorizationHeader(req: IncomingMessage): string | undefined { const raw = req.headers.authorization; if (Array.isArray(raw)) { return raw[0]; } return raw; } function serialiseError(error: unknown): { name: string; message: string } { if (error instanceof Error) { return { name: error.name, message: error.message.slice(0, 200) }; } return { name: "UnknownError", message: String(error).slice(0, 200) }; } /** * Reads `METRICS_ENABLED` for the worker. Re-exported so callers don't import * the env helper from a different package than the admin server. */ export const isWorkerMetricsEnabled = isMetricsEnabled;