Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/worker/src/admin-server.ts
T

193 lines
7.0 KiB
TypeScript

/**
* 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<string, unknown>, msg: string) => void; info?: (fields: Record<string, unknown>, msg: string) => void };
buildStatus: () => Promise<WorkerStatusReport> | WorkerStatusReport;
};
export type WorkerAdminServerHandle = {
close: () => Promise<void>;
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<WorkerAdminServerOptions, "port" | "host">) {
return async function handler(req: IncomingMessage, res: ServerResponse): Promise<void> {
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<void>((resolve) => {
server.close(() => {
resolve();
});
}),
};
}
async function respondStatus(res: ServerResponse, deps: Omit<WorkerAdminServerOptions, "port" | "host">): Promise<void> {
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<WorkerAdminServerOptions, "port" | "host">): Promise<void> {
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;