Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,22 @@
{
"name": "@toolctrl/metrics",
"version": "0.0.0",
"private": true,
"type": "module",
"sideEffects": false,
"exports": {
".": "./src/index.ts"
},
"scripts": {
"test": "vitest run src",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"prom-client": "^15.1.3"
},
"devDependencies": {
"@types/node": "^25.6.0",
"typescript": "^5.3.2",
"vitest": "^3.2.4"
}
}
@@ -0,0 +1,102 @@
import { describe, it, expect } from "vitest";
import { isMetricsEnabled, redactMetricsToken, validateMetricsTokenAuth } from "./auth.js";
describe("isMetricsEnabled", () => {
it("treats literal 'true' as enabled", () => {
expect(isMetricsEnabled({ METRICS_ENABLED: "true" })).toBe(true);
expect(isMetricsEnabled({ METRICS_ENABLED: "false" })).toBe(false);
expect(isMetricsEnabled({ METRICS_ENABLED: undefined })).toBe(false);
expect(isMetricsEnabled({ METRICS_ENABLED: " true " })).toBe(false); // strict literal
});
});
describe("validateMetricsTokenAuth", () => {
const token = "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789";
it("returns 403 when metrics are disabled", () => {
expect(
validateMetricsTokenAuth({
metricsEnabled: false,
configuredToken: token,
authorizationHeader: `Bearer ${token}`,
}),
).toEqual({ ok: false, status: 403, code: "metrics_disabled" });
});
it("returns 500 when metrics are enabled but no token configured", () => {
expect(
validateMetricsTokenAuth({
metricsEnabled: true,
configuredToken: " ",
authorizationHeader: `Bearer x`,
}),
).toEqual({ ok: false, status: 500, code: "token_misconfigured" });
});
it("returns 401 missing_token when header is absent", () => {
expect(
validateMetricsTokenAuth({
metricsEnabled: true,
configuredToken: token,
authorizationHeader: undefined,
}),
).toEqual({ ok: false, status: 401, code: "missing_token" });
});
it("returns 401 missing_token for malformed bearer header", () => {
expect(
validateMetricsTokenAuth({
metricsEnabled: true,
configuredToken: token,
authorizationHeader: "Basic something",
}),
).toEqual({ ok: false, status: 401, code: "missing_token" });
});
it("returns 401 invalid_token for wrong bearer value", () => {
expect(
validateMetricsTokenAuth({
metricsEnabled: true,
configuredToken: token,
authorizationHeader: `Bearer ${"x".repeat(token.length)}`,
}),
).toEqual({ ok: false, status: 401, code: "invalid_token" });
});
it("returns ok for matching bearer", () => {
expect(
validateMetricsTokenAuth({
metricsEnabled: true,
configuredToken: token,
authorizationHeader: `Bearer ${token}`,
}),
).toEqual({ ok: true });
});
it("rejects tokens differing in length without leaking which side is longer", () => {
const result = validateMetricsTokenAuth({
metricsEnabled: true,
configuredToken: token,
authorizationHeader: `Bearer ${token}abc`,
});
expect(result).toEqual({ ok: false, status: 401, code: "invalid_token" });
});
});
describe("redactMetricsToken", () => {
it("renders unset for empty / whitespace tokens", () => {
expect(redactMetricsToken(undefined)).toBe("<unset>");
expect(redactMetricsToken(null)).toBe("<unset>");
expect(redactMetricsToken("")).toBe("<unset>");
expect(redactMetricsToken(" ")).toBe("<unset>");
});
it("masks short tokens entirely", () => {
expect(redactMetricsToken("short")).toBe("***");
expect(redactMetricsToken("12345678")).toBe("***");
});
it("masks long tokens but keeps a short prefix/suffix", () => {
expect(redactMetricsToken("abcdef1234567890abcdef")).toBe("abcd…ef");
});
});
+104
View File
@@ -0,0 +1,104 @@
export type MetricsTokenAuthResult =
| { ok: true }
| { ok: false; status: 401; code: "missing_token" | "invalid_token" }
| { ok: false; status: 403; code: "metrics_disabled" }
| { ok: false; status: 500; code: "token_misconfigured" };
export type MetricsTokenAuthOptions = {
/** The raw value of the `Authorization` header, if any. */
authorizationHeader?: string | null | undefined;
/** The configured metrics token. When empty + enabled => 500 (operator must configure). */
configuredToken?: string | null | undefined;
/** Master switch; mirrors `METRICS_ENABLED=true`. */
metricsEnabled: boolean;
};
/**
* Reads `METRICS_ENABLED` from a plain env record. Mirrors the existing
* project convention of treating the literal string "true" as enabled.
*/
export function isMetricsEnabled(env: Record<string, string | undefined>): boolean {
return env.METRICS_ENABLED === "true";
}
/**
* Constant-time check that the inbound bearer token matches the configured
* token. Returns a discriminated result that callers map onto framework-
* specific responses (Hono context, React Router Response).
*
* Security notes:
* - Empty / whitespace tokens are rejected.
* - The comparison is timing-safe (`crypto.timingSafeEqual`).
* - The token MUST NEVER be logged. See `redactMetricsToken` for the
* audit-safe representation.
*/
export function validateMetricsTokenAuth(options: MetricsTokenAuthOptions): MetricsTokenAuthResult {
if (!options.metricsEnabled) {
return { ok: false, status: 403, code: "metrics_disabled" };
}
const configured = options.configuredToken?.trim() ?? "";
if (configured.length === 0) {
return { ok: false, status: 500, code: "token_misconfigured" };
}
const presented = extractBearerToken(options.authorizationHeader);
if (!presented) {
return { ok: false, status: 401, code: "missing_token" };
}
if (!timingSafeEqualStrings(presented, configured)) {
return { ok: false, status: 401, code: "invalid_token" };
}
return { ok: true };
}
/**
* Returns an audit-safe, non-reversible representation of a metrics token for
* logging. Empty / missing tokens render as `"<unset>"`.
*/
export function redactMetricsToken(token: string | undefined | null): string {
if (!token) {
return "<unset>";
}
const trimmed = token.trim();
if (trimmed.length === 0) {
return "<unset>";
}
if (trimmed.length <= 8) {
return "***";
}
return `${trimmed.slice(0, 4)}…${trimmed.slice(-2)}`;
}
function extractBearerToken(header: string | null | undefined): string | undefined {
if (!header) {
return undefined;
}
const match = /^Bearer\s+(\S+)\s*$/i.exec(header.trim());
if (!match) {
return undefined;
}
const candidate = match[1]?.trim() ?? "";
return candidate.length > 0 ? candidate : undefined;
}
function timingSafeEqualStrings(a: string, b: string): boolean {
if (a.length !== b.length) {
return false;
}
// Encode as utf8 first so multi-byte tokens compare correctly without
// relying on the Buffer code path which is not always available in
// edge-runtime targets.
const aBytes = new TextEncoder().encode(a);
const bBytes = new TextEncoder().encode(b);
if (aBytes.length !== bBytes.length) {
return false;
}
let diff = 0;
for (let i = 0; i < aBytes.length; i += 1) {
diff |= aBytes[i]! ^ bBytes[i]!;
}
return diff === 0;
}
@@ -0,0 +1,64 @@
import { describe, it, expect } from "vitest";
import { HISTOGRAM_BUCKETS_SECONDS, createDefaultMetrics } from "./defaults.js";
import { createMetricsRegistry } from "./registry.js";
describe("createDefaultMetrics", () => {
it("registers every canonical metric on the registry", async () => {
const registry = createMetricsRegistry({ serviceName: "api", collectDefaultProcessMetrics: false });
const metrics = createDefaultMetrics(registry);
// Touch each metric so the registry has at least one sample to render.
metrics.httpRequestsTotal.labels({ method: "GET", route: "/v1/x", status: "200" }).inc();
metrics.httpRequestDurationSeconds.labels({ method: "GET", route: "/v1/x", status: "200" }).observe(0.05);
metrics.prismaQueryDurationSeconds.labels({ model: "User", action: "findMany" }).observe(0.01);
metrics.redisCommandDurationSeconds.labels({ command: "GET" }).observe(0.001);
metrics.queueJobsActive.labels({ queue: "email" }).set(2);
metrics.queueJobsWaiting.labels({ queue: "email" }).set(5);
metrics.queueJobsEnqueuedTotal.labels({ queue: "email", priority: "critical" }).inc();
metrics.queueJobsCompletedTotal.labels({ queue: "email", job_name: "send" }).inc();
metrics.queueJobsFailedTotal.labels({ queue: "email", job_name: "send", error_type: "Error" }).inc();
metrics.queueJobDurationSeconds.labels({ queue: "email", job_name: "send" }).observe(0.5);
metrics.outboxDispatchTotal.labels({ event_type: "workflow.trigger.event", status: "ok" }).inc();
metrics.webSsrLoaderDurationSeconds.labels({ route: "root", status: "ok" }).observe(0.02);
metrics.aiTokensConsumedTotal.labels({ provider: "openai", model: "gpt-4", tenant_bucket: "other" }).inc(1234);
metrics.stripeWebhookEventsTotal.labels({ event_type: "invoice.paid", status: "received" }).inc();
metrics.mailSentTotal.labels({ provider: "mailjet", status: "delivered" }).inc();
metrics.webhookDeliveryAttemptsTotal.labels({ status: "success" }).inc();
metrics.csrfTokenRotationTotal.inc();
metrics.subscriptionActive.labels({ plan_id: "pro" }).set(42);
metrics.activeTenants.set(10);
metrics.activeUsers24h.set(123);
const text = await registry.metrics();
const expected = [
"http_requests_total",
"http_request_duration_seconds",
"prisma_query_duration_seconds",
"redis_command_duration_seconds",
"queue_jobs_active",
"queue_jobs_waiting",
"queue_jobs_enqueued_total",
"queue_jobs_completed_total",
"queue_jobs_failed_total",
"queue_job_duration_seconds",
"outbox_dispatch_total",
"web_ssr_loader_duration_seconds",
"ai_tokens_consumed_total",
"stripe_webhook_events_total",
"mail_sent_total",
"webhook_delivery_attempts_total",
"csrf_token_rotation_total",
"subscription_active",
"active_tenants",
"active_users_24h",
];
for (const name of expected) {
expect(text).toContain(name);
}
});
it("uses the shared histogram bucket spread for latency metrics", () => {
expect(HISTOGRAM_BUCKETS_SECONDS[0]).toBe(0.005);
expect(HISTOGRAM_BUCKETS_SECONDS[HISTOGRAM_BUCKETS_SECONDS.length - 1]).toBe(10);
expect(HISTOGRAM_BUCKETS_SECONDS).toEqual([...HISTOGRAM_BUCKETS_SECONDS].sort((a, b) => a - b));
});
});
@@ -0,0 +1,174 @@
import { Counter, Gauge, Histogram } from "prom-client";
import type { MetricsRegistry } from "./registry.js";
/**
* Latency-histogram buckets in seconds. The spread covers 5ms - 10s, which is
* the realistic range for both HTTP requests (top of bucket: timeout / 504)
* and queue jobs (top of bucket: slow exports). Keep them in sync across the
* api + worker + web registries so Grafana panels can mix them.
*/
export const HISTOGRAM_BUCKETS_SECONDS: readonly number[] = [
0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
] as const;
export type LatencyHistogramOptions = {
name: string;
help: string;
labelNames: readonly string[];
buckets?: readonly number[];
};
export type DefaultMetrics = {
httpRequestsTotal: Counter<"method" | "route" | "status">;
httpRequestDurationSeconds: Histogram<"method" | "route" | "status">;
prismaQueryDurationSeconds: Histogram<"model" | "action">;
redisCommandDurationSeconds: Histogram<"command">;
queueJobsActive: Gauge<"queue">;
queueJobsWaiting: Gauge<"queue">;
queueJobsEnqueuedTotal: Counter<"queue" | "priority">;
queueJobsCompletedTotal: Counter<"queue" | "job_name">;
queueJobsFailedTotal: Counter<"queue" | "job_name" | "error_type">;
queueJobDurationSeconds: Histogram<"queue" | "job_name">;
outboxDispatchTotal: Counter<"event_type" | "status">;
webSsrLoaderDurationSeconds: Histogram<"route" | "status">;
aiTokensConsumedTotal: Counter<"provider" | "model" | "tenant_bucket">;
stripeWebhookEventsTotal: Counter<"event_type" | "status">;
mailSentTotal: Counter<"provider" | "status">;
webhookDeliveryAttemptsTotal: Counter<"status">;
csrfTokenRotationTotal: Counter<string>;
subscriptionActive: Gauge<"plan_id">;
activeTenants: Gauge<string>;
activeUsers24h: Gauge<string>;
};
/**
* Registers the canonical metric set for any service registry. Calling this
* twice on the same registry would throw — callers wire the result into a
* service-scoped singleton.
*/
export function createDefaultMetrics(registry: MetricsRegistry): DefaultMetrics {
return {
httpRequestsTotal: new Counter({
name: "http_requests_total",
help: "Total HTTP requests served by this service.",
labelNames: ["method", "route", "status"] as const,
registers: [registry],
}),
httpRequestDurationSeconds: new Histogram({
name: "http_request_duration_seconds",
help: "HTTP request duration in seconds.",
labelNames: ["method", "route", "status"] as const,
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
registers: [registry],
}),
prismaQueryDurationSeconds: new Histogram({
name: "prisma_query_duration_seconds",
help: "Prisma query duration in seconds.",
labelNames: ["model", "action"] as const,
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
registers: [registry],
}),
redisCommandDurationSeconds: new Histogram({
name: "redis_command_duration_seconds",
help: "Redis command duration in seconds.",
labelNames: ["command"] as const,
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
registers: [registry],
}),
queueJobsActive: new Gauge({
name: "queue_jobs_active",
help: "BullMQ jobs currently being processed per queue.",
labelNames: ["queue"] as const,
registers: [registry],
}),
queueJobsWaiting: new Gauge({
name: "queue_jobs_waiting",
help: "BullMQ jobs waiting to be processed per queue.",
labelNames: ["queue"] as const,
registers: [registry],
}),
queueJobsEnqueuedTotal: new Counter({
name: "queue_jobs_enqueued_total",
help: "BullMQ jobs enqueued per queue / priority (critical|high|normal|low|other).",
labelNames: ["queue", "priority"] as const,
registers: [registry],
}),
queueJobsCompletedTotal: new Counter({
name: "queue_jobs_completed_total",
help: "BullMQ jobs that completed successfully per queue / job_name.",
labelNames: ["queue", "job_name"] as const,
registers: [registry],
}),
queueJobsFailedTotal: new Counter({
name: "queue_jobs_failed_total",
help: "BullMQ jobs that failed terminally per queue / job_name / error_type.",
labelNames: ["queue", "job_name", "error_type"] as const,
registers: [registry],
}),
queueJobDurationSeconds: new Histogram({
name: "queue_job_duration_seconds",
help: "BullMQ job duration in seconds.",
labelNames: ["queue", "job_name"] as const,
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
registers: [registry],
}),
outboxDispatchTotal: new Counter({
name: "outbox_dispatch_total",
help: "Transactional outbox dispatch attempts per event_type / status.",
labelNames: ["event_type", "status"] as const,
registers: [registry],
}),
webSsrLoaderDurationSeconds: new Histogram({
name: "web_ssr_loader_duration_seconds",
help: "React Router SSR loader duration in seconds.",
labelNames: ["route", "status"] as const,
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
registers: [registry],
}),
aiTokensConsumedTotal: new Counter({
name: "ai_tokens_consumed_total",
help: "AI provider tokens consumed. tenant_bucket holds the top-N tenant id or 'other' to cap cardinality.",
labelNames: ["provider", "model", "tenant_bucket"] as const,
registers: [registry],
}),
stripeWebhookEventsTotal: new Counter({
name: "stripe_webhook_events_total",
help: "Stripe webhook events processed per event_type / status.",
labelNames: ["event_type", "status"] as const,
registers: [registry],
}),
mailSentTotal: new Counter({
name: "mail_sent_total",
help: "Mail-provider send attempts per provider / status.",
labelNames: ["provider", "status"] as const,
registers: [registry],
}),
webhookDeliveryAttemptsTotal: new Counter({
name: "webhook_delivery_attempts_total",
help: "Outbound webhook delivery attempts per status (success / retry / dlq).",
labelNames: ["status"] as const,
registers: [registry],
}),
csrfTokenRotationTotal: new Counter({
name: "csrf_token_rotation_total",
help: "CSRF token rotations performed.",
registers: [registry],
}),
subscriptionActive: new Gauge({
name: "subscription_active",
help: "Active subscriptions per plan_id.",
labelNames: ["plan_id"] as const,
registers: [registry],
}),
activeTenants: new Gauge({
name: "active_tenants",
help: "Total active (non-deleted) tenants.",
registers: [registry],
}),
activeUsers24h: new Gauge({
name: "active_users_24h",
help: "Unique users that signed in within the last 24 hours.",
registers: [registry],
}),
};
}
@@ -0,0 +1,14 @@
export {
type DefaultMetrics,
type LatencyHistogramOptions,
HISTOGRAM_BUCKETS_SECONDS,
createDefaultMetrics,
} from "./defaults.js";
export { type MetricsRegistry, createMetricsRegistry } from "./registry.js";
export {
type MetricsTokenAuthResult,
type MetricsTokenAuthOptions,
isMetricsEnabled,
validateMetricsTokenAuth,
redactMetricsToken,
} from "./auth.js";
@@ -0,0 +1,35 @@
import { describe, it, expect } from "vitest";
import { createMetricsRegistry } from "./registry.js";
import { createDefaultMetrics } from "./defaults.js";
describe("createMetricsRegistry", () => {
it("attaches the service default label", async () => {
const registry = createMetricsRegistry({ serviceName: "api", collectDefaultProcessMetrics: false });
expect(registry.serviceName).toBe("api");
expect(registry.defaultMetricsAttached).toBe(false);
const metrics = createDefaultMetrics(registry);
metrics.httpRequestsTotal.labels({ method: "GET", route: "/v1/foo", status: "200" }).inc();
const text = await registry.metrics();
expect(text).toContain('http_requests_total{method="GET",route="/v1/foo",status="200",service="api"} 1');
});
it("emits prom-client default process metrics when enabled", async () => {
const registry = createMetricsRegistry({ serviceName: "worker", collectDefaultProcessMetrics: true });
expect(registry.defaultMetricsAttached).toBe(true);
const text = await registry.metrics();
expect(text).toMatch(/process_cpu_seconds_total/);
expect(text).toMatch(/service="worker"/);
});
it("merges custom default labels with service", async () => {
const registry = createMetricsRegistry({
serviceName: "web",
collectDefaultProcessMetrics: false,
defaultLabels: { revision: "abc123" },
});
const metrics = createDefaultMetrics(registry);
metrics.activeTenants.set(7);
const text = await registry.metrics();
expect(text).toContain('active_tenants{service="web",revision="abc123"} 7');
});
});
@@ -0,0 +1,54 @@
import { Registry, collectDefaultMetrics } from "prom-client";
export type MetricsRegistry = Registry & {
readonly serviceName: string;
/**
* Indicates whether the prom-client default Node.js process metrics
* (`process_cpu_seconds_total`, `process_resident_memory_bytes`, etc.) have
* been attached to this registry. Tests rely on this flag to assert that
* each service registers default metrics exactly once.
*/
readonly defaultMetricsAttached: boolean;
};
export type CreateMetricsRegistryOptions = {
serviceName: string;
/**
* When true (default), enables prom-client's `collectDefaultMetrics()` which
* adds standard Node.js process metrics. Pass `false` in unit tests when you
* want a deterministic registry without GC / event-loop noise.
*/
collectDefaultProcessMetrics?: boolean;
/**
* Extra constant labels applied to every metric on this registry. Use
* sparingly — high-cardinality labels (request id, tenant id) MUST NOT be
* set here. Service name + revision is the intended use.
*/
defaultLabels?: Record<string, string | number>;
};
/**
* Returns a service-scoped Prometheus registry with default labels.
*
* Each app (api / worker / web SSR) creates its own registry so metric
* collisions between services are impossible and so a single Prometheus job
* can scrape any one endpoint without leakage from the others.
*/
export function createMetricsRegistry(options: CreateMetricsRegistryOptions): MetricsRegistry {
const { serviceName, collectDefaultProcessMetrics = true, defaultLabels } = options;
const registry = new Registry();
registry.setDefaultLabels({
service: serviceName,
...defaultLabels,
});
if (collectDefaultProcessMetrics) {
collectDefaultMetrics({ register: registry, prefix: "" });
}
return Object.assign(registry, {
serviceName,
defaultMetricsAttached: collectDefaultProcessMetrics,
});
}
@@ -0,0 +1,13 @@
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"allowJs": false,
"allowImportingTsExtensions": false,
"lib": ["ES2022"],
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"types": ["node"]
},
"include": ["src/**/*.ts"]
}