Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -28,10 +28,14 @@ export function resetWebMetricsForTests(): void {
function buildWebMetrics(): WebMetricsBundle {
const revision = process.env.APP_REVISION?.trim() ?? "";
const runtimeSurface = resolveMetricsRuntimeSurface(process.env);
const registry = createMetricsRegistry({
serviceName: "web",
collectDefaultProcessMetrics: true,
...(revision ? { defaultLabels: { revision } } : {}),
defaultLabels: {
runtime_surface: runtimeSurface,
...(revision ? { revision } : {}),
},
});
const metrics = createDefaultMetrics(registry);
// Wire BullMQ enqueue events into queue_jobs_enqueued_total. See
@@ -41,3 +45,14 @@ function buildWebMetrics(): WebMetricsBundle {
});
return { registry, metrics };
}
function resolveMetricsRuntimeSurface(env: Readonly<{ NODE_ENV?: string; VITEST?: string; WEB_RUNTIME_SURFACE?: string }>): "core" | "admin" | "portal" {
const surface = env.WEB_RUNTIME_SURFACE;
if (surface === "core" || surface === "admin" || surface === "portal") {
return surface;
}
if (surface === undefined && (env.NODE_ENV === "test" || env.VITEST === "true")) {
return "core";
}
throw new Error("WEB_RUNTIME_SURFACE must be explicitly set to core, admin, or portal before web metrics initialization");
}
@@ -0,0 +1,84 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import { getWebMetrics, resetWebMetricsForTests } from "./registry.js";
import { recordAuthorizedStorageDownload } from "./storage-traffic.js";
beforeEach(() => {
resetWebMetricsForTests();
});
describe("recordAuthorizedStorageDownload", () => {
it("records a bounded authorization count and known whole-object bytes", async () => {
recordAuthorizedStorageDownload({
surface: "files",
delivery: "signed_redirect",
objectSizeBytes: 1_048_576,
});
const text = await getWebMetrics().registry.metrics();
expect(text).toContain(
'storage_authorized_downloads_total{surface="files",delivery="signed_redirect",size_known="known",service="web",runtime_surface="core"} 1'
);
expect(text).toContain(
'storage_authorized_download_object_bytes_total{surface="files",delivery="signed_redirect",service="web",runtime_surface="core"} 1048576'
);
});
it.each([undefined, null, -1, Number.NaN, 1.5])("records an unknown size without inventing byte volume for %s", async (objectSizeBytes) => {
recordAuthorizedStorageDownload({ surface: "portal_document", delivery: "signed_redirect", objectSizeBytes });
const text = await getWebMetrics().registry.metrics();
expect(text).toContain(
'storage_authorized_downloads_total{surface="portal_document",delivery="signed_redirect",size_known="unknown",service="web",runtime_surface="core"} 1'
);
expect(text).not.toContain("storage_authorized_download_object_bytes_total{");
});
it("separates portal download counters from the Core runtime", async () => {
const previousSurface = process.env.WEB_RUNTIME_SURFACE;
process.env.WEB_RUNTIME_SURFACE = "portal";
resetWebMetricsForTests();
try {
recordAuthorizedStorageDownload({ surface: "portal_document", delivery: "signed_redirect", objectSizeBytes: 512 });
const text = await getWebMetrics().registry.metrics();
expect(text).toContain('runtime_surface="portal"');
expect(text).not.toContain('runtime_surface="core"');
} finally {
if (previousSurface === undefined) delete process.env.WEB_RUNTIME_SURFACE;
else process.env.WEB_RUNTIME_SURFACE = previousSurface;
resetWebMetricsForTests();
}
});
it("folds impossible runtime label values into other and never exports them", async () => {
recordAuthorizedStorageDownload({
surface: "tenant-secret" as "files",
delivery: "https://objects.example.test/signed" as "signed_redirect",
objectSizeBytes: 10,
});
const text = await getWebMetrics().registry.metrics();
expect(text).toContain('delivery="other"');
expect(text).toContain('surface="other"');
expect(text).not.toContain("tenant-secret");
expect(text).not.toContain("objects.example.test");
});
it("stays fail-open when either counter rejects an observation", () => {
const throwingCounter = {
labels: vi.fn(() => ({
inc: vi.fn(() => {
throw new Error("metrics down");
}),
})),
};
const metrics = {
storageAuthorizedDownloadsTotal: throwingCounter,
storageAuthorizedDownloadObjectBytesTotal: throwingCounter,
} as unknown as NonNullable<Parameters<typeof recordAuthorizedStorageDownload>[1]>["metrics"];
expect(() => recordAuthorizedStorageDownload({ surface: "files", delivery: "signed_redirect", objectSizeBytes: 42 }, { metrics })).not.toThrow();
expect(throwingCounter.labels).toHaveBeenCalledTimes(2);
});
});
@@ -0,0 +1,74 @@
/**
* Low-cardinality storage-delivery telemetry for BILL-25.
*
* The counters deliberately describe an authorization/delivery decision, not
* provider egress: a presigned URL can remain unused, be reused before expiry,
* or serve byte ranges without another application request. Never add tenant,
* file, object-key, filename, or URL labels here.
*/
import type { DefaultMetrics } from "@hivegrid/metrics";
import { getWebMetrics } from "./registry.js";
const STORAGE_DOWNLOAD_SURFACES = ["files", "portal_document"] as const;
const STORAGE_DOWNLOAD_DELIVERIES = ["signed_redirect"] as const;
export type StorageDownloadSurface = (typeof STORAGE_DOWNLOAD_SURFACES)[number];
export type StorageDownloadDelivery = (typeof STORAGE_DOWNLOAD_DELIVERIES)[number];
type StorageTrafficMetrics = Pick<
DefaultMetrics,
"storageAuthorizedDownloadsTotal" | "storageAuthorizedDownloadObjectBytesTotal"
>;
export type AuthorizedStorageDownloadInput = {
readonly surface: StorageDownloadSurface;
readonly delivery: StorageDownloadDelivery;
/** Whole-object size when the authorization boundary has a trustworthy value. */
readonly objectSizeBytes?: number | null;
};
type RecordAuthorizedStorageDownloadOptions = {
/** Test seam; production always uses the web service-scoped registry. */
readonly metrics?: StorageTrafficMetrics;
};
export function recordAuthorizedStorageDownload(
input: AuthorizedStorageDownloadInput,
options: RecordAuthorizedStorageDownloadOptions = {}
): void {
let metrics: StorageTrafficMetrics;
try {
metrics = options.metrics ?? getWebMetrics().metrics;
} catch {
return;
}
const surface = boundedLabel(input.surface, STORAGE_DOWNLOAD_SURFACES);
const delivery = boundedLabel(input.delivery, STORAGE_DOWNLOAD_DELIVERIES);
const objectSizeBytes = knownObjectSize(input.objectSizeBytes);
try {
metrics.storageAuthorizedDownloadsTotal
.labels({ surface, delivery, size_known: objectSizeBytes === null ? "unknown" : "known" })
.inc();
} catch {
// Observability must never block a valid download.
}
if (objectSizeBytes !== null) {
try {
metrics.storageAuthorizedDownloadObjectBytesTotal.labels({ surface, delivery }).inc(objectSizeBytes);
} catch {
// Keep the authorization path fail-open even when one metric is broken.
}
}
}
function boundedLabel<TValue extends string>(value: TValue, allowed: readonly TValue[]): TValue | "other" {
return allowed.includes(value) ? value : "other";
}
function knownObjectSize(value: number | null | undefined): number | null {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
}