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

@@ -0,0 +1,131 @@
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { ActionFunctionArgs, LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { getUserInfo, validateCSRFToken } from "~/utils/session.server";
import { getUser } from "~/utils/db/users.db.server";
import { listAdminBillingRows, requestManualBillingSync, setTenantBillingPlanSeats } from "~/services/admin/billing-admin.server";
import { action, loader } from "./billing";
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
vi.mock("react-i18next", () => ({
useTranslation: () => ({ t: (key: string, params?: Record<string, string>) => (params?.provider ? `${key}:${params.provider}` : key) }),
}));
vi.mock("~/components/ui/buttons/ButtonPrimary", () => ({ default: () => null }));
vi.mock("~/components/ui/buttons/ButtonSecondary", () => ({ default: () => null }));
vi.mock("~/components/ui/errors/ServerError", () => ({ default: () => null }));
vi.mock("~/components/ui/layouts/EditPageLayout", () => ({ default: () => null }));
vi.mock("~/utils/data/useRootData", () => ({ useRootData: () => ({ csrf: "csrf" }) }));
vi.mock("~/locale/i18next.server", () => ({ getTranslations: vi.fn() }));
vi.mock("~/utils/helpers/.server/PermissionsService", () => ({ verifyUserHasPermission: vi.fn() }));
vi.mock("~/utils/session.server", () => ({ getUserInfo: vi.fn(), validateCSRFToken: vi.fn() }));
vi.mock("~/utils/db/users.db.server", () => ({ getUser: vi.fn() }));
vi.mock("~/services/admin/billing-admin.server", async () => {
const actual = await vi.importActual<typeof import("~/services/admin/billing-admin.server")>("~/services/admin/billing-admin.server");
return {
...actual,
listAdminBillingRows: vi.fn(),
requestManualBillingSync: vi.fn(),
setTenantBillingPlanSeats: vi.fn(),
};
});
function requestWithForm(form: Record<string, string>) {
return new Request("https://admin.example.test/system/billing", {
method: "POST",
body: new URLSearchParams(form),
});
}
describe("admin accounts billing route", () => {
beforeEach(() => {
vi.clearAllMocks();
process.env.APP_NAME = "HiveGrid";
vi.mocked(verifyUserHasPermission).mockResolvedValue(undefined as never);
vi.mocked(getTranslations).mockResolvedValue({
t: (key: string, params?: Record<string, string>) => (params?.provider ? `${key}:${params.provider}` : key),
} as never);
vi.mocked(validateCSRFToken).mockResolvedValue(undefined as never);
vi.mocked(getUserInfo).mockResolvedValue({ userId: "user_1" } as never);
vi.mocked(getUser).mockResolvedValue({ id: "user_1", email: "ops@hivegrid.de" } as never);
vi.mocked(listAdminBillingRows).mockResolvedValue([
{
tenantId: "tenant_1",
tenantName: "Acme",
tenantSlug: "acme",
status: "active",
readOnly: false,
planCode: "starter",
seatQuantity: 3,
lagoCustomerId: "lago_1",
mollieCustomerId: "mollie_1",
lastInvoiceExternalId: "inv_1",
lastPaymentExternalId: "pay_1",
currentPeriodStart: null,
currentPeriodEnd: null,
pastDueSince: null,
frozenAt: null,
cancelledAt: null,
entitlementCount: 1,
},
] as never);
});
it("checks subscription permission before loading billing rows", async () => {
const body = await loader({
request: new Request("https://admin.example.test/system/billing"),
params: {},
context: {},
} as LoaderFunctionArgs);
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.account.subscription");
expect(vi.mocked(verifyUserHasPermission).mock.invocationCallOrder[0]).toBeLessThan(vi.mocked(listAdminBillingRows).mock.invocationCallOrder[0]);
expect(body.vm.status).toBe("ready");
expect(body.vm.data.rows[0].tenantName).toBe("Acme");
});
it("routes plan/seat override actions to the admin service", async () => {
vi.mocked(setTenantBillingPlanSeats).mockImplementationOnce(async () => {
expect(getRlsExecutionContext()?.tenantId).toBe("tenant_1");
});
const response = (await action({
request: requestWithForm({
csrf: "csrf",
action: "set-plan-seats",
tenantId: "tenant_1",
planCode: "pro",
seatQuantity: "7",
reason: "Sonderkunde",
}),
params: {},
context: {},
} as ActionFunctionArgs)) as Response;
await expect(response.json()).resolves.toEqual({ success: "admin.billing.actions.planSeatsUpdated" });
expect(setTenantBillingPlanSeats).toHaveBeenCalledWith(
expect.objectContaining({
tenantId: "tenant_1",
planCode: "pro",
seatQuantity: "7",
reason: "Sonderkunde",
actorUserId: "user_1",
actorEmail: "ops@hivegrid.de",
})
);
});
it("routes manual provider sync actions to the admin service", async () => {
vi.mocked(requestManualBillingSync).mockImplementationOnce(async () => {
expect(getRlsExecutionContext()?.tenantId).toBe("tenant_1");
});
const response = (await action({
request: requestWithForm({ csrf: "csrf", action: "request-sync", tenantId: "tenant_1", provider: "lago" }),
params: {},
context: {},
} as ActionFunctionArgs)) as Response;
await expect(response.json()).resolves.toEqual({ success: "admin.billing.actions.syncRequested:admin.billing.providers.lago" });
expect(requestManualBillingSync).toHaveBeenCalledWith(expect.objectContaining({ tenantId: "tenant_1", provider: "lago", actorUserId: "user_1" }));
});
});
@@ -0,0 +1,88 @@
import { buildAdminBillingVM } from "@hivegrid/view-models";
import { ActionFunctionArgs, LoaderFunctionArgs, MetaFunction, useActionData, useLoaderData, useNavigation } from "react-router";
import { AdminBillingPage } from "~/components/screens/admin/AdminBillingPage";
import ServerError from "~/components/ui/errors/ServerError";
import { getTranslations } from "~/locale/i18next.server";
import { AdminActionInputError } from "~/services/admin/admin-action-audit.server";
import { AdminBillingError, listAdminBillingRows, requestManualBillingSync, setTenantBillingPlanSeats, type BillingSyncProvider } from "~/services/admin/billing-admin.server";
import { useRootData } from "~/utils/data/useRootData";
import { getUser } from "~/utils/db/users.db.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { getUserInfo, validateCSRFToken } from "~/utils/session.server";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
type LoaderData = { title: string; vm: ReturnType<typeof buildAdminBillingVM> };
type ActionData = { success?: string; error?: string };
export const meta: MetaFunction<typeof loader> = ({ data }) => [{ title: data?.title }];
export const loader = async ({ request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, "admin.account.subscription");
const { t } = await getTranslations(request);
return { title: `${t("admin.billing.title")} | ${process.env.APP_NAME}`, vm: buildAdminBillingVM({ rows: await listAdminBillingRows() }) } satisfies LoaderData;
};
function badRequest(data: ActionData) {
return Response.json(data, { status: 400 });
}
function billingErrorKey(error: unknown): string {
if (error instanceof AdminBillingError || error instanceof AdminActionInputError) return error.i18nKey;
return "admin.billing.errors.UNKNOWN";
}
export const action = async ({ request }: ActionFunctionArgs) => {
await verifyUserHasPermission(request, "admin.account.subscription");
const { t } = await getTranslations(request);
await validateCSRFToken(request);
const form = await request.formData();
const actionName = form.get("action")?.toString() ?? "";
const tenantId = form.get("tenantId")?.toString() ?? "";
const userInfo = await getUserInfo(request);
const actor = await getUser(userInfo.userId);
try {
if (actionName === "set-plan-seats") {
await runWithRlsContext({ tenantId }, () =>
setTenantBillingPlanSeats({
tenantId,
planCode: form.get("planCode")?.toString() ?? "",
seatQuantity: form.get("seatQuantity")?.toString() ?? "",
reason: form.get("reason")?.toString() ?? "",
actorUserId: userInfo.userId,
actorEmail: actor?.email ?? null,
request,
})
);
return Response.json({ success: t("admin.billing.actions.planSeatsUpdated") } satisfies ActionData);
}
if (actionName === "request-sync") {
const provider = form.get("provider")?.toString() as BillingSyncProvider;
if (provider !== "lago" && provider !== "mollie") return badRequest({ error: t("shared.invalidForm") });
await runWithRlsContext({ tenantId }, () =>
requestManualBillingSync({ tenantId, provider, actorUserId: userInfo.userId, actorEmail: actor?.email ?? null, request })
);
return Response.json({ success: t("admin.billing.actions.syncRequested", { provider: t(`admin.billing.providers.${provider}`) }) } satisfies ActionData);
}
return badRequest({ error: t("shared.invalidForm") });
} catch (error) {
return badRequest({ error: t(billingErrorKey(error)) });
}
};
export default function AdminBillingRoute() {
const data = useLoaderData<LoaderData>();
const rootData = useRootData();
return (
<AdminBillingPage
vm={data.vm}
csrf={rootData.csrf ?? ""}
submitting={useNavigation().state === "submitting"}
feedback={useActionData<ActionData>()}
/>
);
}
export function ErrorBoundary() {
return <ServerError />;
}
@@ -0,0 +1,66 @@
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import { getDeployAdminSnapshot } from "~/services/admin/deploy-admin.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { loader, shortenRevision } from "./deploys";
vi.mock("react-i18next", () => ({ useTranslation: () => ({ t: (key: string) => key }) }));
vi.mock("~/components/ui/layouts/EditPageLayout", () => ({ default: () => null }));
vi.mock("~/locale/i18next.server", () => ({ getTranslations: vi.fn() }));
vi.mock("~/services/admin/deploy-admin.server", () => ({ getDeployAdminSnapshot: vi.fn() }));
vi.mock("~/utils/helpers/.server/PermissionsService", () => ({ verifyUserHasPermission: vi.fn() }));
function callLoader(url = "https://admin.example.test/system/deploys") {
return loader({ request: new Request(url), params: {}, context: {} } as LoaderFunctionArgs);
}
describe("admin deploys route", () => {
beforeEach(() => {
vi.clearAllMocks();
process.env.APP_NAME = "HiveGrid";
vi.mocked(verifyUserHasPermission).mockResolvedValue(undefined as never);
vi.mocked(getTranslations).mockResolvedValue({ t: (key: string) => key } as never);
vi.mocked(getDeployAdminSnapshot).mockResolvedValue({
migrationDbReachable: true,
metadata: {
environment: "staging",
nodeEnv: "production",
release: "abc123",
revision: "abc123",
branch: "main",
image: "hivegrid-web:abc123",
buildTime: "2026-07-09T00:00:00.000Z",
},
migrations: [{ name: "20260701000000_init", state: "applied", appliedAt: "2026-07-09T00:00:00.000Z" }],
} as never);
});
it("requires metrics permission and builds deploy data", async () => {
const data = await callLoader();
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.metrics.view");
expect(getDeployAdminSnapshot).toHaveBeenCalledOnce();
expect(data.vm.status).toBe("ready");
if (data.vm.status !== "ready") return;
expect(data.vm.data.metadata.release).toBe("abc123");
expect(data.vm.data.migrationSummary.applied).toBe(1);
});
});
describe("shortenRevision", () => {
it("shortens a full commit hash so it stops overflowing its card", () => {
// The 40-char hash pushed the value column past the card and ran over the
// neighbouring rows (admin audit 2026-07-26, P0-07).
expect(shortenRevision("b05b699647daae446ce6c30e8c1a5449851c5d2a")).toBe("b05b699647da");
});
it("leaves short and non-hash values untouched", () => {
expect(shortenRevision("b05b699")).toBe("b05b699");
expect(shortenRevision("local")).toBe("local");
expect(shortenRevision("main")).toBe("main");
expect(shortenRevision("hivegrid-web:b05b699647daae446ce6c30e8c1a5449851c5d2a")).toBe("hivegrid-web:b05b699647daae446ce6c30e8c1a5449851c5d2a");
expect(shortenRevision("2026-07-09T00:00:00.000Z")).toBe("2026-07-09T00:00:00.000Z");
});
});
@@ -0,0 +1,216 @@
import { buildDeployAdminVM, type DeployAdminData, type DeploySignal, type MigrationState } from "@hivegrid/view-models";
import { FeatherRocket, FeatherTableProperties } from "@subframe/core";
import { LoaderFunctionArgs, MetaFunction, useLoaderData } from "react-router";
import { useTranslation } from "react-i18next";
import { AdminPageHeader } from "~/components/screens/admin/AdminPageHeader";
import { getTranslations } from "~/locale/i18next.server";
import { getDeployAdminSnapshot } from "~/services/admin/deploy-admin.server";
import { ADMIN_AREA_ACCESS } from "~/services/admin/admin-access-contract";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { BadgeFeedback } from "~/ui/components/BadgeFeedback";
import { Card } from "~/ui/components/Card";
import { EmptyState } from "~/ui/components/EmptyState";
import { StatsCard } from "~/ui/components/StatsCard";
import { Table } from "~/ui/components/Table";
type LoaderData = {
title: string;
vm: ReturnType<typeof buildDeployAdminVM>;
};
export const meta: MetaFunction<typeof loader> = ({ data }) => [{ title: data?.title }];
export const loader = async ({ request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, ADMIN_AREA_ACCESS.deploys);
const { t } = await getTranslations(request);
const snapshot = await getDeployAdminSnapshot();
return {
title: `${t("admin.deploys.title")} | ${process.env.APP_NAME}`,
vm: buildDeployAdminVM(snapshot),
} satisfies LoaderData;
};
export default function AdminDeploysRoute() {
const { t } = useTranslation();
const data = useLoaderData<LoaderData>();
return (
<div className="flex w-full flex-col">
<AdminPageHeader title={t("admin.deploys.title")} description={t("admin.deploys.description")} />
<div className="mobile:px-4 flex w-full flex-col items-start gap-4 px-6 py-6">
{data.vm.status === "ready" ? <DeploysPage data={data.vm.data} /> : <DeploysEmpty />}
</div>
</div>
);
}
function DeploysPage({ data }: { data: DeployAdminData }) {
const { t } = useTranslation();
return (
<>
<Card variant="neutral">
<div className="flex w-full flex-wrap items-center justify-between gap-3">
<span className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-secondary">
{t("admin.deploys.deployLine", {
environment: data.metadata.environment,
release: data.metadata.release,
branch: data.metadata.branch,
})}
</span>
<BadgeFeedback farbe={statusTone(data.overallStatus)}>{t(data.overallLabelKey)}</BadgeFeedback>
</div>
</Card>
<div className="mobile:grid-cols-1 grid w-full gap-4 lg:grid-cols-3">
{data.signals.map((signal) => (
<SignalCard key={signal.id} signal={signal} />
))}
</div>
<div className="mobile:grid-cols-1 grid w-full gap-4 xl:grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)]">
<VersionCard data={data} />
<MigrationCard data={data} />
</div>
</>
);
}
function SignalCard({ signal }: { signal: DeploySignal }) {
const { t } = useTranslation();
return (
<StatsCard
label={t(signal.labelKey)}
value={signal.value}
trend={signal.status === "ok" ? "positive" : signal.status === "unknown" ? "neutral" : "negative"}
percentage=""
comparisonText={t(signal.detailKey)}
icon={<FeatherRocket />}
/>
);
}
function VersionCard({ data }: { data: DeployAdminData }) {
const { t } = useTranslation();
const rows = [
["admin.deploys.fields.environment", data.metadata.environment],
["admin.deploys.fields.nodeEnv", data.metadata.nodeEnv],
["admin.deploys.fields.release", data.metadata.release],
["admin.deploys.fields.revision", data.metadata.revision],
["admin.deploys.fields.branch", data.metadata.branch],
["admin.deploys.fields.image", data.metadata.image],
["admin.deploys.fields.buildTime", data.metadata.buildTime],
] as const;
return (
<Card>
<div className="flex w-full items-start gap-3">
<span className="text-heading- font-heading- text-icon-neutral-tertiary">
<FeatherRocket />
</span>
<div className="flex min-w-0 flex-col items-start">
<span className="text-body-large-0 font-body-large-0 text-text-neutral-primary">{t("admin.deploys.version.title")}</span>
<span className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-tertiary">{t("admin.deploys.version.description")}</span>
</div>
</div>
{/*
`min-w-0` keeps the grid from growing past the card: without it a 40-char
commit hash pushed the value column wider than its container and ran over
the neighbouring cards (admin audit 2026-07-26, P0-07). Long hashes are
additionally shortened for reading, with the full value on hover.
*/}
<dl className="grid w-full min-w-0 grid-cols-[9rem_minmax(0,1fr)] gap-x-3 gap-y-2">
{rows.map(([labelKey, value]) => (
<div key={labelKey} className="contents">
<dt className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-tertiary">{t(labelKey)}</dt>
<dd className="text-text-neutral-primary min-w-0 truncate font-mono text-xs" title={value}>
{shortenRevision(value)}
</dd>
</div>
))}
</dl>
</Card>
);
}
function MigrationCard({ data }: { data: DeployAdminData }) {
const { t } = useTranslation();
return (
<Card>
<div className="flex w-full items-start justify-between gap-4">
<div className="flex min-w-0 items-start gap-3">
<span className="text-heading- font-heading- text-icon-neutral-tertiary">
<FeatherTableProperties />
</span>
<div className="flex min-w-0 flex-col items-start">
<span className="text-body-large-0 font-body-large-0 text-text-neutral-primary">{t("admin.deploys.migrations.title")}</span>
<span className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-tertiary">
{t("admin.deploys.migrations.description")}
</span>
</div>
</div>
<BadgeFeedback farbe={data.migrationSummary.pending > 0 || data.migrationSummary.failed > 0 ? "subtle-warning" : "subtle-positive"} size="small">
{t("admin.deploys.migrations.summary", data.migrationSummary)}
</BadgeFeedback>
</div>
<Table
header={
<Table.HeaderRow>
<Table.HeaderCell>{t("admin.deploys.migrations.name")}</Table.HeaderCell>
<Table.HeaderCell>{t("admin.deploys.migrations.state")}</Table.HeaderCell>
<Table.HeaderCell>{t("admin.deploys.migrations.appliedAt")}</Table.HeaderCell>
</Table.HeaderRow>
}
>
{data.migrations.map((migration) => (
<Table.Row key={migration.name}>
<Table.Cell>
<span className="text-text-neutral-primary max-w-80 truncate font-mono text-xs">{migration.name}</span>
</Table.Cell>
<Table.Cell>
<BadgeFeedback farbe={migrationTone(migration.state)} size="small">
{t(`admin.deploys.migrationState.${migration.state}`)}
</BadgeFeedback>
</Table.Cell>
<Table.Cell>
<span className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-tertiary">
{migration.appliedAt ?? t("shared.notSet")}
</span>
</Table.Cell>
</Table.Row>
))}
</Table>
</Card>
);
}
function DeploysEmpty() {
const { t } = useTranslation();
return <EmptyState outlined title={t("admin.deploys.empty.headline")} body={t("admin.deploys.empty.body")} />;
}
const FULL_COMMIT_HASH = /^[0-9a-f]{13,}$/iu;
const SHORT_HASH_LENGTH = 12;
/**
* Shortens a full commit hash to its readable prefix. Anything that is not a
* long hex string (image tags, branch names, `local`) is left untouched, and the
* complete value stays available through the cell's `title`.
*/
export function shortenRevision(value: string): string {
return FULL_COMMIT_HASH.test(value) ? value.slice(0, SHORT_HASH_LENGTH) : value;
}
function statusTone(status: DeploySignal["status"]): "subtle-positive" | "subtle-warning" | "subtle-negative" | "subtle-neutral" {
if (status === "ok") return "subtle-positive";
if (status === "warning") return "subtle-warning";
if (status === "critical") return "subtle-negative";
return "subtle-neutral";
}
function migrationTone(state: MigrationState): "subtle-positive" | "subtle-warning" | "subtle-negative" | "subtle-neutral" {
if (state === "applied") return "subtle-positive";
if (state === "pending") return "subtle-warning";
if (state === "failed" || state === "rolledBack") return "subtle-negative";
return "subtle-neutral";
}
@@ -0,0 +1,44 @@
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import { getSystemHealthSnapshot } from "~/services/admin/system-health.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { loader } from "./health";
vi.mock("react-i18next", () => ({ useTranslation: () => ({ t: (key: string) => key }) }));
vi.mock("~/components/ui/layouts/EditPageLayout", () => ({ default: () => null }));
vi.mock("~/locale/i18next.server", () => ({ getTranslations: vi.fn() }));
vi.mock("~/services/admin/system-health.server", () => ({ getSystemHealthSnapshot: vi.fn() }));
vi.mock("~/utils/helpers/.server/PermissionsService", () => ({ verifyUserHasPermission: vi.fn() }));
function callLoader(url = "https://admin.example.test/system/health") {
return loader({ request: new Request(url), params: {}, context: {} } as LoaderFunctionArgs);
}
describe("admin system route", () => {
beforeEach(() => {
vi.clearAllMocks();
process.env.APP_NAME = "HiveGrid";
vi.mocked(verifyUserHasPermission).mockResolvedValue(undefined as never);
vi.mocked(getTranslations).mockResolvedValue({ t: (key: string) => key } as never);
vi.mocked(getSystemHealthSnapshot).mockResolvedValue({
deploy: { environment: "staging", release: "abc123", nodeEnv: "production" },
services: [
{ id: "web", labelKey: "admin.system.services.web.label", category: "runtime", configured: true, reachable: true },
{ id: "postgres", labelKey: "admin.system.services.postgres.label", category: "database", configured: true, reachable: true },
],
} as never);
});
it("requires metrics permission and returns a system health VM", async () => {
const data = await callLoader();
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.metrics.view");
expect(getSystemHealthSnapshot).toHaveBeenCalledOnce();
expect(data.vm.status).toBe("ready");
if (data.vm.status !== "ready") return;
expect(data.vm.data.summary.ok).toBe(2);
expect(data.title).toBe("admin.system.title | HiveGrid");
});
});
@@ -0,0 +1,182 @@
import { buildSystemHealthVM, type SystemHealthData, type SystemHealthService } from "@hivegrid/view-models";
import {
FeatherAlertTriangle,
FeatherCheckCircle,
FeatherDatabase,
FeatherExternalLink,
FeatherHardDrive,
FeatherHelpCircle,
FeatherRadioTower,
FeatherServer,
FeatherShieldCheck,
} from "@subframe/core";
import { Link, LoaderFunctionArgs, MetaFunction, useLoaderData } from "react-router";
import { useTranslation } from "react-i18next";
import { AdminPageHeader } from "~/components/screens/admin/AdminPageHeader";
import { getTranslations } from "~/locale/i18next.server";
import { getSystemHealthSnapshot } from "~/services/admin/system-health.server";
import { ADMIN_AREA_ACCESS } from "~/services/admin/admin-access-contract";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { BadgeFeedback } from "~/ui/components/BadgeFeedback";
import { BannerAlert } from "~/ui/components/BannerAlert";
import { Button } from "~/ui/components/Button";
import { Card } from "~/ui/components/Card";
import { EmptyState } from "~/ui/components/EmptyState";
import { StatsCard } from "~/ui/components/StatsCard";
type LoaderData = {
title: string;
vm: ReturnType<typeof buildSystemHealthVM>;
};
export const meta: MetaFunction<typeof loader> = ({ data }) => [{ title: data?.title }];
export const loader = async ({ request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, ADMIN_AREA_ACCESS.system);
const { t } = await getTranslations(request);
const snapshot = await getSystemHealthSnapshot();
return {
title: `${t("admin.system.title")} | ${process.env.APP_NAME}`,
vm: buildSystemHealthVM(snapshot),
} satisfies LoaderData;
};
export default function AdminSystemRoute() {
const { t } = useTranslation();
const data = useLoaderData<LoaderData>();
return (
<div className="flex w-full flex-col">
<AdminPageHeader title={t("admin.system.title")} description={t("admin.system.description")} />
<div className="mobile:px-4 flex w-full flex-col items-start gap-4 px-6 py-6">
{data.vm.status === "ready" ? <SystemHealthPage data={data.vm.data} /> : <SystemHealthEmpty />}
</div>
</div>
);
}
function SystemHealthPage({ data }: { data: SystemHealthData }) {
const { t } = useTranslation();
return (
<>
<Card variant="neutral">
<div className="flex w-full flex-wrap items-center justify-between gap-3">
<span className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-secondary">
{t("admin.system.deployLine", {
environment: data.deploy.environment,
release: data.deploy.release,
nodeEnv: data.deploy.nodeEnv,
})}
</span>
<BadgeFeedback farbe={statusTone(data.overallStatus)}>{t(data.overallLabelKey)}</BadgeFeedback>
</div>
</Card>
<div className="mobile:grid-cols-1 grid w-full grid-cols-5 gap-4 md:grid-cols-2 xl:grid-cols-5">
<StatsCard
label={t("admin.system.summary.ok")}
value={data.summary.ok}
trend="positive"
percentage=""
comparisonText=""
icon={<FeatherCheckCircle />}
/>
<StatsCard
label={t("admin.system.summary.warning")}
value={data.summary.warning}
trend={data.summary.warning ? "negative" : "positive"}
percentage=""
comparisonText=""
icon={<FeatherAlertTriangle />}
/>
<StatsCard
label={t("admin.system.summary.critical")}
value={data.summary.critical}
trend={data.summary.critical ? "negative" : "positive"}
percentage=""
comparisonText=""
icon={<FeatherAlertTriangle />}
/>
<StatsCard
label={t("admin.system.summary.unknown")}
value={data.summary.unknown}
trend="neutral"
percentage=""
comparisonText=""
icon={<FeatherHelpCircle />}
/>
<StatsCard
label={t("admin.system.summary.total")}
value={data.summary.total}
trend="neutral"
percentage=""
comparisonText=""
icon={<FeatherServer />}
/>
</div>
{data.summary.critical > 0 ? (
<BannerAlert type="error" fillContainer>
{t("admin.system.incident.title")} — {t("admin.system.incident.body")}
</BannerAlert>
) : null}
<div className="mobile:grid-cols-1 grid w-full gap-4 lg:grid-cols-2 xl:grid-cols-3">
{data.services.map((service) => (
<ServiceCard key={service.id} service={service} />
))}
</div>
</>
);
}
function ServiceCard({ service }: { service: SystemHealthService }) {
const { t } = useTranslation();
const detail = service.detailKey ? t(service.detailKey, { value: service.detailValue }) : service.detailValue;
return (
<Card>
<div className="flex w-full items-start justify-between gap-4">
<div className="flex min-w-0 items-start gap-3">
<span className="text-heading- font-heading- text-icon-neutral-tertiary">{categoryIcon(service.category)}</span>
<div className="flex min-w-0 flex-col items-start">
<span className="text-body-large-0 font-body-large-0 text-text-neutral-primary truncate">{t(service.labelKey)}</span>
<span className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-tertiary">{t(service.categoryLabelKey)}</span>
</div>
</div>
<BadgeFeedback farbe={statusTone(service.status)} size="small">
{t(service.statusLabelKey)}
</BadgeFeedback>
</div>
<span className="text-body-small-regular-150 font-body-small-regular-150 text-text-neutral-secondary min-h-10 w-full">{detail}</span>
{service.href ? (
<Link to={service.href}>
<Button variant="tertiary" size="small" iconRight={<FeatherExternalLink />}>
{t("admin.system.actions.openDetail")}
</Button>
</Link>
) : null}
</Card>
);
}
function SystemHealthEmpty() {
const { t } = useTranslation();
return <EmptyState outlined title={t("admin.system.empty.headline")} body={t("admin.system.empty.body")} />;
}
function categoryIcon(category: SystemHealthService["category"]) {
if (category === "database") return <FeatherDatabase />;
if (category === "queue") return <FeatherRadioTower />;
if (category === "storage") return <FeatherHardDrive />;
if (category === "observability") return <FeatherShieldCheck />;
return <FeatherServer />;
}
function statusTone(status: SystemHealthService["status"]): "subtle-positive" | "subtle-warning" | "subtle-negative" | "subtle-neutral" {
if (status === "ok") return "subtle-positive";
if (status === "warning") return "subtle-warning";
if (status === "critical") return "subtle-negative";
return "subtle-neutral";
}
@@ -0,0 +1,64 @@
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import { getOperatorHealthSnapshot } from "~/services/admin/operator-health.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { loader } from "./index";
vi.mock("react-i18next", () => ({ useTranslation: () => ({ t: (key: string) => key }) }));
vi.mock("~/components/ui/layouts/EditPageLayout", () => ({ default: () => null }));
vi.mock("~/components/ui/errors/ServerError", () => ({ default: () => null }));
vi.mock("~/locale/format", () => ({ useLocaleFormatters: () => ({ dateTime: (value: Date) => value.toISOString() }) }));
vi.mock("~/locale/i18next.server", () => ({ getTranslations: vi.fn() }));
vi.mock("~/services/admin/operator-health.server", () => ({ getOperatorHealthSnapshot: vi.fn() }));
vi.mock("~/utils/helpers/.server/PermissionsService", () => ({ verifyUserHasPermission: vi.fn() }));
function callLoader(url = "https://admin.example.test/system") {
return loader({ request: new Request(url), params: {}, context: {} } as LoaderFunctionArgs);
}
describe("admin health route", () => {
beforeEach(() => {
vi.clearAllMocks();
process.env.APP_NAME = "HiveGrid";
vi.mocked(verifyUserHasPermission).mockResolvedValue(undefined as never);
vi.mocked(getTranslations).mockResolvedValue({ t: (key: string) => key } as never);
vi.mocked(getOperatorHealthSnapshot).mockResolvedValue({
subsystems: [
{ id: "system", status: "ok", href: "/admin/system" },
{ id: "deploy", status: "ok", href: "/system/deploys" },
{ id: "queues", status: "warning", href: "/system/jobs" },
{ id: "webhooks", status: "ok", href: "/system/webhooks" },
{ id: "billing", status: "warning", href: "/system/billing" },
],
deploy: { environment: "production", release: "abc123", revision: "abc123", branch: "main" },
signals: { failedJobsTotal: 2, pausedQueues: 0, webhookFailures: 0, billingErrors: 1 },
links: { jobs: "/system/jobs", webhooks: "/system/webhooks", billing: "/system/billing" },
billingErrors: [{ id: "log_1", eventType: "invoice.payment_failed", error: "boom", createdAt: "2026-07-09T00:00:00.000Z", relatedTenantId: "tenant_1" }],
} as never);
});
it("requires metrics permission and aggregates the operator health VM", async () => {
const data = await callLoader();
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.metrics.view");
expect(getOperatorHealthSnapshot).toHaveBeenCalledOnce();
expect(data.vm.status).toBe("ready");
if (data.vm.status !== "ready") return;
expect(data.vm.data.overallStatus).toBe("warning");
expect(data.vm.data.attention.map((row) => row.id)).toEqual(["failedJobs", "billingErrors"]);
expect(data.vm.data.billingErrors).toHaveLength(1);
expect(data.title).toBe("admin.health.title | HiveGrid");
});
it("returns a renderable error state when aggregation fails", async () => {
vi.mocked(getOperatorHealthSnapshot).mockRejectedValueOnce(new Error("snapshot failed"));
const data = await callLoader();
expect(data.vm.status).toBe("error");
if (data.vm.status !== "error") return;
expect(data.vm.error.messageKey).toBe("admin.health.error.body");
});
});
@@ -0,0 +1,42 @@
import { buildOperatorHealthVM } from "@hivegrid/view-models";
import { LoaderFunctionArgs, MetaFunction, useLoaderData } from "react-router";
import { AdminHealthPage } from "~/components/screens/admin/AdminHealthPage";
import ServerError from "~/components/ui/errors/ServerError";
import { getTranslations } from "~/locale/i18next.server";
import { getOperatorHealthSnapshot } from "~/services/admin/operator-health.server";
import { ADMIN_AREA_ACCESS } from "~/services/admin/admin-access-contract";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
type LoaderData = {
title: string;
vm: ReturnType<typeof buildOperatorHealthVM>;
};
export const meta: MetaFunction<typeof loader> = ({ data }) => [{ title: data?.title }];
export const loader = async ({ request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, ADMIN_AREA_ACCESS.health);
const { t } = await getTranslations(request);
try {
const snapshot = await getOperatorHealthSnapshot();
return {
title: `${t("admin.health.title")} | ${process.env.APP_NAME}`,
vm: buildOperatorHealthVM(snapshot),
} satisfies LoaderData;
} catch {
return {
title: `${t("admin.health.title")} | ${process.env.APP_NAME}`,
vm: { status: "error", error: { messageKey: "admin.health.error.body", code: "HEALTH_UNAVAILABLE" } },
} satisfies LoaderData;
}
};
export default function AdminHealthRoute() {
const data = useLoaderData<LoaderData>();
return <AdminHealthPage vm={data.vm} />;
}
export function ErrorBoundary() {
return <ServerError />;
}
@@ -0,0 +1,171 @@
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { ActionFunctionArgs, LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { getUserInfo, validateCSRFToken } from "~/utils/session.server";
import { getUser } from "~/utils/db/users.db.server";
import { userHasPermission } from "~/utils/db/permissions/userRoles.db.server";
import {
getQueueFailedJobsSnapshot,
getQueueMonitorSnapshot,
pauseQueue,
QueueMonitorControlError,
resumeQueue,
retryQueueJob,
} from "~/services/admin/queue-monitor.server";
import { setOperatorPortalDomainKillSwitch } from "~/services/admin/portal-domain-operator.server";
import { action, loader } from "./jobs";
vi.mock("react-i18next", () => ({
useTranslation: () => ({ t: (key: string, params?: Record<string, string | number>) => (params ? `${key}:${Object.values(params).join(":")}` : key) }),
}));
vi.mock("~/components/ui/layouts/EditPageLayout", () => ({ default: () => null }));
vi.mock("~/components/ui/errors/ServerError", () => ({ default: () => null }));
vi.mock("~/components/ui/buttons/ButtonPrimary", () => ({ default: () => null }));
vi.mock("~/components/ui/buttons/ButtonSecondary", () => ({ default: () => null }));
vi.mock("~/utils/data/useRootData", () => ({ useRootData: () => ({ csrf: "csrf" }) }));
vi.mock("~/locale/format", () => ({
useLocaleFormatters: () => ({
dateTime: (value: Date) => value.toISOString(),
}),
}));
vi.mock("~/locale/i18next.server", () => ({ getTranslations: vi.fn() }));
vi.mock("~/utils/helpers/.server/PermissionsService", () => ({ verifyUserHasPermission: vi.fn() }));
vi.mock("~/utils/session.server", () => ({ getUserInfo: vi.fn(), validateCSRFToken: vi.fn() }));
vi.mock("~/utils/db/users.db.server", () => ({ getUser: vi.fn() }));
vi.mock("~/utils/db/permissions/userRoles.db.server", () => ({ userHasPermission: vi.fn() }));
vi.mock("~/services/admin/queue-monitor.server", () => ({
getQueueMonitorSnapshot: vi.fn(),
getQueueFailedJobsSnapshot: vi.fn(),
pauseQueue: vi.fn(),
resumeQueue: vi.fn(),
retryQueueJob: vi.fn(),
QueueMonitorControlError: class QueueMonitorControlError extends Error {
constructor(readonly code: string, message: string) {
super(message);
}
},
}));
vi.mock("~/services/admin/admin-action-audit.server", () => ({
AdminActionInputError: class AdminActionInputError extends Error {
readonly i18nKey = "admin.audit.errors.reasonRequired";
},
}));
vi.mock("~/services/admin/portal-domain-operator.server", () => ({
PORTAL_DOMAIN_KILL_SWITCH_PERMISSION: "admin.settings.danger.reset",
PortalDomainOperatorError: class PortalDomainOperatorError extends Error {},
setOperatorPortalDomainKillSwitch: vi.fn(),
}));
vi.mock("~/services/customer-portal/portal-domain.server", () => ({
PortalDomainError: class PortalDomainError extends Error {},
}));
function callLoader(url = "https://admin.example.test/system/jobs") {
return loader({ request: new Request(url), params: {}, context: {} } as LoaderFunctionArgs);
}
function callAction(form: Record<string, string>) {
return action({
request: new Request("https://admin.example.test/system/jobs", {
method: "POST",
body: new URLSearchParams(form),
}),
params: {},
context: {},
} as ActionFunctionArgs);
}
describe("admin jobs route", () => {
beforeEach(() => {
vi.clearAllMocks();
process.env.APP_NAME = "HiveGrid";
vi.mocked(verifyUserHasPermission).mockResolvedValue(undefined as never);
vi.mocked(getTranslations).mockResolvedValue({ t: (key: string) => key } as never);
vi.mocked(validateCSRFToken).mockResolvedValue(undefined as never);
vi.mocked(getUserInfo).mockResolvedValue({ userId: "admin_1" } as never);
vi.mocked(getUser).mockResolvedValue({ id: "admin_1", email: "admin@hivegrid.de" } as never);
vi.mocked(userHasPermission).mockResolvedValue(true);
vi.mocked(getQueueMonitorSnapshot).mockResolvedValue([
{ queueName: "hivegrid.email", group: "mail", active: 1, waiting: 2, delayed: 0, failed: 3, completed: 10, paused: false },
] as never);
vi.mocked(getQueueFailedJobsSnapshot).mockResolvedValue([
{
queueName: "hivegrid.email",
jobs: [{ id: "job_1", name: "deliver-webhook", failedReason: "Timeout", attemptsMade: 2, timestamp: 1783549200000 }],
},
] as never);
});
it("checks metrics permission and builds queue monitor data", async () => {
const data = await callLoader();
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.metrics.view");
expect(getQueueMonitorSnapshot).toHaveBeenCalledOnce();
expect(getQueueFailedJobsSnapshot).toHaveBeenCalledWith(5);
expect(data.vm.status).toBe("ready");
if (data.vm.status !== "ready") return;
expect(data.vm.data.failedTotal).toBe(3);
expect(data.failedJobs[0].jobs[0].name).toBe("deliver-webhook");
expect(data.canManagePortalDomainKillSwitch).toBe(true);
});
it("returns a renderable error state when Redis/BullMQ is unavailable", async () => {
vi.mocked(getQueueMonitorSnapshot).mockRejectedValueOnce(new Error("redis missing"));
const data = await callLoader();
expect(data.vm.status).toBe("error");
expect(data.failedJobs).toEqual([]);
});
it("routes pause, resume, and retry actions to the audited queue service", async () => {
await callAction({ csrf: "csrf", action: "pause", queueName: "hivegrid.email" });
await callAction({ csrf: "csrf", action: "resume", queueName: "hivegrid.email" });
await callAction({ csrf: "csrf", action: "retry-job", queueName: "hivegrid.email", jobId: "job_1" });
expect(validateCSRFToken).toHaveBeenCalledTimes(3);
expect(pauseQueue).toHaveBeenCalledWith(expect.objectContaining({ queueName: "hivegrid.email", actorUserId: "admin_1" }));
expect(resumeQueue).toHaveBeenCalledWith(expect.objectContaining({ queueName: "hivegrid.email", actorEmail: "admin@hivegrid.de" }));
expect(retryQueueJob).toHaveBeenCalledWith(expect.objectContaining({ queueName: "hivegrid.email", jobId: "job_1" }));
});
it("preserves generation-aware recovery guidance for the financial provider queue", async () => {
vi.mocked(retryQueueJob).mockRejectedValueOnce(
new QueueMonitorControlError("DIRECT_OUTBOX_RETRY_FORBIDDEN", "use outbox replay"),
);
const response = await callAction({
csrf: "csrf",
action: "retry-job",
queueName: "outbox.billing-product-provider",
jobId: "job_1",
});
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: "admin.jobs.errors.directOutboxRetryForbidden" });
});
it("requires the destructive operator permission and delegates the portal-domain kill switch", async () => {
const response = await callAction({
csrf: "csrf",
action: "portal-domain-kill-enable",
tenantId: "tenant_1",
reason: "Compromised routing",
});
expect(response.status).toBe(200);
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.metrics.view");
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.settings.danger.reset");
expect(setOperatorPortalDomainKillSwitch).toHaveBeenCalledWith(
expect.objectContaining({
tenantId: "tenant_1",
actorUserId: "admin_1",
enabled: true,
reason: "Compromised routing",
request: expect.any(Request),
}),
);
await expect(response.json()).resolves.toEqual({ success: "admin.jobs.portalDomainKillSwitch.enabled" });
});
});
@@ -0,0 +1,172 @@
import { buildQueueMonitorVM } from "@hivegrid/view-models";
import { LoaderFunctionArgs, MetaFunction, useActionData, useLoaderData, useNavigation, type ActionFunctionArgs } from "react-router";
import ServerError from "~/components/ui/errors/ServerError";
import { AdminJobsPage } from "~/components/screens/admin/AdminJobsPage";
import { getTranslations } from "~/locale/i18next.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { getUserInfo, validateCSRFToken } from "~/utils/session.server";
import { getUser } from "~/utils/db/users.db.server";
import { userHasPermission } from "~/utils/db/permissions/userRoles.db.server";
import { useRootData } from "~/utils/data/useRootData";
import {
getQueueFailedJobsSnapshot,
getQueueJobDetail,
getQueueMonitorSnapshot,
pauseQueue,
QueueMonitorControlError,
resumeQueue,
retryQueueJob,
type QueueFailedJobsSnapshot,
type QueueJobDetail,
} from "~/services/admin/queue-monitor.server";
import { AdminActionInputError } from "~/services/admin/admin-action-audit.server";
import { ADMIN_AREA_ACCESS } from "~/services/admin/admin-access-contract";
import {
PORTAL_DOMAIN_KILL_SWITCH_PERMISSION,
PortalDomainOperatorError,
setOperatorPortalDomainKillSwitch,
} from "~/services/admin/portal-domain-operator.server";
import { PortalDomainError } from "~/services/customer-portal/portal-domain.server";
type LoaderData = {
title: string;
vm: ReturnType<typeof buildQueueMonitorVM>;
failedJobs: QueueFailedJobsSnapshot[];
canManagePortalDomainKillSwitch: boolean;
jobDetail: { queueName: string; job: QueueJobDetail } | null;
};
type ActionData = {
success?: string;
error?: string;
};
export const meta: MetaFunction<typeof loader> = ({ data }) => [{ title: data?.title }];
export const loader = async ({ request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, ADMIN_AREA_ACCESS.jobs);
const { t } = await getTranslations(request);
const userInfo = await getUserInfo(request);
const canManagePortalDomainKillSwitch = await userHasPermission(
userInfo.userId,
null,
PORTAL_DOMAIN_KILL_SWITCH_PERMISSION,
);
const url = new URL(request.url);
const detailQueue = url.searchParams.get("detailQueue");
const detailJob = url.searchParams.get("detailJob");
try {
const [queues, failedJobs] = await Promise.all([getQueueMonitorSnapshot(), getQueueFailedJobsSnapshot(5)]);
let jobDetail: LoaderData["jobDetail"] = null;
if (detailQueue && detailJob) {
try {
const job = await getQueueJobDetail(detailQueue, detailJob);
jobDetail = job ? { queueName: detailQueue, job } : null;
} catch {
jobDetail = null;
}
}
return {
title: `${t("admin.jobs.title")} | ${process.env.APP_NAME}`,
vm: buildQueueMonitorVM({ queues }),
failedJobs,
canManagePortalDomainKillSwitch,
jobDetail,
} satisfies LoaderData;
} catch {
return {
title: `${t("admin.jobs.title")} | ${process.env.APP_NAME}`,
vm: { status: "error", error: { messageKey: "admin.jobs.errors.queueUnavailable", code: "QUEUE_UNAVAILABLE" } },
failedJobs: [],
canManagePortalDomainKillSwitch,
jobDetail: null,
} satisfies LoaderData;
}
};
function badRequest(data: ActionData) {
return Response.json(data, { status: 400 });
}
export const action = async ({ request }: ActionFunctionArgs) => {
await verifyUserHasPermission(request, ADMIN_AREA_ACCESS.jobs);
const { t } = await getTranslations(request);
await validateCSRFToken(request);
const form = await request.formData();
const action = form.get("action")?.toString() ?? "";
const queueName = form.get("queueName")?.toString() ?? "";
if (action === "portal-domain-kill-enable" || action === "portal-domain-kill-disable") {
await verifyUserHasPermission(request, PORTAL_DOMAIN_KILL_SWITCH_PERMISSION);
}
const userInfo = await getUserInfo(request);
const actor = await getUser(userInfo.userId);
const baseInput = { queueName, actorUserId: userInfo.userId, actorEmail: actor?.email ?? null, request };
try {
if (action === "pause") {
await pauseQueue(baseInput);
return Response.json({ success: t("admin.jobs.actions.paused") } satisfies ActionData);
}
if (action === "resume") {
await resumeQueue(baseInput);
return Response.json({ success: t("admin.jobs.actions.resumed") } satisfies ActionData);
}
if (action === "retry-job") {
await retryQueueJob({ ...baseInput, jobId: form.get("jobId")?.toString() ?? "" });
return Response.json({ success: t("admin.jobs.actions.retried") } satisfies ActionData);
}
if (action === "portal-domain-kill-enable" || action === "portal-domain-kill-disable") {
const enabled = action === "portal-domain-kill-enable";
await setOperatorPortalDomainKillSwitch({
tenantId: form.get("tenantId")?.toString() ?? "",
actorUserId: userInfo.userId,
enabled,
reason: form.get("reason")?.toString() ?? "",
request,
});
return Response.json({
success: t(enabled ? "admin.jobs.portalDomainKillSwitch.enabled" : "admin.jobs.portalDomainKillSwitch.disabled"),
} satisfies ActionData);
}
return badRequest({ error: t("shared.invalidForm") });
} catch (error) {
if (error instanceof AdminActionInputError) {
return badRequest({ error: t(error.i18nKey) });
}
if (error instanceof PortalDomainOperatorError) {
return badRequest({ error: t("admin.jobs.errors.portalDomainKillSwitchNotAllowed") });
}
if (error instanceof PortalDomainError) {
return badRequest({ error: t("admin.jobs.errors.portalDomainKillSwitchFailed") });
}
if (error instanceof QueueMonitorControlError && error.code === "DIRECT_OUTBOX_RETRY_FORBIDDEN") {
return badRequest({ error: t("admin.jobs.errors.directOutboxRetryForbidden") });
}
return badRequest({ error: t("admin.jobs.errors.actionFailed") });
}
};
export default function AdminJobsRoute() {
const data = useLoaderData<LoaderData>();
const actionData = useActionData<ActionData>();
const navigation = useNavigation();
const rootData = useRootData();
return (
<AdminJobsPage
vm={data.vm}
failedJobs={data.failedJobs}
csrf={rootData.csrf ?? ""}
submitting={navigation.state === "submitting"}
feedback={actionData}
canManagePortalDomainKillSwitch={data.canManagePortalDomainKillSwitch}
jobDetail={data.jobDetail}
/>
);
}
export function ErrorBoundary() {
return <ServerError />;
}
@@ -0,0 +1,174 @@
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { ActionFunctionArgs, LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { db } from "~/utils/db.server";
import { getUserInfo, validateCSRFToken } from "~/utils/session.server";
import { getUser } from "~/utils/db/users.db.server";
import { requestWebhookReplay } from "~/services/admin/webhook-inbox.server";
import { action, loader } from "./webhooks";
vi.mock("react-i18next", () => ({
useTranslation: () => ({ t: (key: string, params?: Record<string, string | number>) => (params?.duration ? `${key}:${params.duration}` : key) }),
}));
vi.mock("~/components/ui/layouts/EditPageLayout", () => ({ default: () => null }));
vi.mock("~/components/ui/errors/ServerError", () => ({ default: () => null }));
vi.mock("~/components/ui/buttons/ButtonPrimary", () => ({ default: () => null }));
vi.mock("~/utils/data/useRootData", () => ({ useRootData: () => ({ csrf: "csrf" }) }));
vi.mock("~/locale/format", () => ({
useLocaleFormatters: () => ({
dateTime: (value: Date) => value.toISOString(),
}),
}));
vi.mock("~/locale/i18next.server", () => ({ getTranslations: vi.fn() }));
vi.mock("~/utils/helpers/.server/PermissionsService", () => ({ verifyUserHasPermission: vi.fn() }));
vi.mock("~/utils/session.server", () => ({ getUserInfo: vi.fn(), validateCSRFToken: vi.fn() }));
vi.mock("~/utils/db/users.db.server", () => ({ getUser: vi.fn() }));
vi.mock("~/services/admin/webhook-inbox.server", async () => {
const actual = await vi.importActual<typeof import("~/services/admin/webhook-inbox.server")>("~/services/admin/webhook-inbox.server");
return {
...actual,
requestWebhookReplay: vi.fn(),
};
});
vi.mock("~/utils/db.server", () => ({
db: {
eventWebhookAttempt: {
findMany: vi.fn(),
},
},
}));
function callLoader(url = "https://admin.example.test/system/webhooks") {
return loader({ request: new Request(url), params: {}, context: {} } as LoaderFunctionArgs);
}
function callAction(form: Record<string, string>) {
return action({
request: new Request("https://admin.example.test/system/webhooks", {
method: "POST",
body: new URLSearchParams(form),
}),
params: {},
context: {},
} as ActionFunctionArgs);
}
describe("admin webhooks route", () => {
beforeEach(() => {
vi.clearAllMocks();
process.env.APP_NAME = "HiveGrid";
vi.mocked(verifyUserHasPermission).mockResolvedValue(undefined as never);
vi.mocked(getTranslations).mockResolvedValue({
t: (key: string, params?: Record<string, string>) => (params?.attemptId ? `${key}:${params.attemptId}` : key),
} as never);
vi.mocked(validateCSRFToken).mockResolvedValue(undefined as never);
vi.mocked(getUserInfo).mockResolvedValue({ userId: "admin_1" } as never);
vi.mocked(getUser).mockResolvedValue({ id: "admin_1", email: "admin@hivegrid.de" } as never);
vi.mocked(requestWebhookReplay).mockResolvedValue({ replayAttemptId: "attempt_replay" } as never);
vi.mocked(db.eventWebhookAttempt.findMany).mockResolvedValue([
{
id: "attempt_failed",
eventId: "event_failed",
endpoint: "https://api.hivegrid.de/webhooks/mollie",
success: false,
status: 500,
message: "Provider timeout",
body: JSON.stringify({ token: "secret", kept: "value" }),
createdAt: new Date("2026-07-09T10:00:00.000Z"),
startedAt: new Date("2026-07-09T10:00:00.000Z"),
finishedAt: new Date("2026-07-09T10:00:01.000Z"),
event: {
id: "event_failed",
name: "billing.mollie.webhook",
resource: "billing",
tenantId: "tenant_1",
userId: null,
},
},
{
id: "attempt_delivered",
eventId: "event_delivered",
endpoint: "https://api.hivegrid.de/webhooks/lago",
success: true,
status: 204,
message: "Admin replay requested.",
body: "{}",
createdAt: new Date("2026-07-09T10:01:00.000Z"),
startedAt: new Date("2026-07-09T10:01:00.000Z"),
finishedAt: new Date("2026-07-09T10:01:00.500Z"),
event: {
id: "event_delivered",
name: "billing.lago.invoice",
resource: "billing",
tenantId: "tenant_1",
userId: null,
},
},
{
id: "attempt_queue_unavailable",
eventId: "event_queue_unavailable",
endpoint: "https://api.hivegrid.de/webhooks/lago",
success: false,
status: 503,
message: "admin.webhooks.messages.queueUnavailable",
body: "{}",
createdAt: new Date("2026-07-09T10:02:00.000Z"),
startedAt: new Date("2026-07-09T10:02:00.000Z"),
finishedAt: new Date("2026-07-09T10:02:00.500Z"),
event: {
id: "event_queue_unavailable",
name: "billing.lago.invoice",
resource: "billing",
tenantId: "tenant_1",
userId: null,
},
},
] as never);
});
it("checks event permission and builds the webhook inbox", async () => {
const data = await callLoader();
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.events.view");
expect(db.eventWebhookAttempt.findMany).toHaveBeenCalledWith(expect.objectContaining({ take: 100 }));
expect(data.vm.status).toBe("ready");
if (data.vm.status !== "ready") return;
expect(data.vm.data.summary).toMatchObject({ totalCount: 3, failedCount: 2, deliveredCount: 1 });
expect(data.vm.data.rows.find((row) => row.id === "attempt_failed")?.payloadPreview).toContain("[REDACTED]");
expect(data.vm.data.rows.find((row) => row.id === "attempt_delivered")?.message).toBe("admin.webhooks.messages.replayRequested");
expect(data.vm.data.rows.find((row) => row.id === "attempt_queue_unavailable")?.message).toBe("admin.webhooks.messages.queueUnavailable");
});
it("filters rows by delivery status", async () => {
const data = await callLoader("https://admin.example.test/system/webhooks?status=delivered");
expect(data.filter).toBe("delivered");
expect(data.vm.status).toBe("ready");
if (data.vm.status !== "ready") return;
expect(data.vm.data.rows).toHaveLength(1);
expect(data.vm.data.rows[0].id).toBe("attempt_delivered");
});
it("routes replay form submissions to the audited admin service", async () => {
const response = (await callAction({
csrf: "csrf",
action: "request-replay",
attemptId: "attempt_failed",
reason: "Provider Timeout erneut ausliefern",
})) as Response;
await expect(response.json()).resolves.toEqual({ success: "admin.webhooks.actions.replayRequested:attempt_replay" });
expect(verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "admin.events.view");
expect(validateCSRFToken).toHaveBeenCalledWith(expect.any(Request));
expect(requestWebhookReplay).toHaveBeenCalledWith(
expect.objectContaining({
attemptId: "attempt_failed",
reason: "Provider Timeout erneut ausliefern",
actorUserId: "admin_1",
actorEmail: "admin@hivegrid.de",
})
);
});
});
@@ -0,0 +1,350 @@
import {
buildWebhookInboxVM,
type WebhookInboxData,
type WebhookInboxInputRow,
type WebhookInboxRow,
type WebhookInboxStatus,
type WebhookInboxVM,
} from "@hivegrid/view-models";
import { Activity, AlertTriangle, CheckCircle2, Clock3, ExternalLink, RadioTower, ShieldQuestion } from "lucide-react";
import type React from "react";
import { Form, Link, LoaderFunctionArgs, MetaFunction, useActionData, useLoaderData, useNavigation, type ActionFunctionArgs } from "react-router";
import { useTranslation } from "react-i18next";
import EditPageLayout from "~/components/ui/layouts/EditPageLayout";
import ServerError from "~/components/ui/errors/ServerError";
import { Badge, type BadgeColor } from "~/components/ui/badge";
import { Card, CardContent, CardHeader, CardTitle } from "~/components/ui/card";
import ButtonPrimary from "~/components/ui/buttons/ButtonPrimary";
import { getTranslations } from "~/locale/i18next.server";
import { useLocaleFormatters } from "~/locale/format";
import { db } from "~/utils/db.server";
import { adminPath } from "~/utils/app/CanonicalUrlUtils";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import { redactDiagnosticJsonString } from "~/utils/redaction";
import { useRootData } from "~/utils/data/useRootData";
import { getUserInfo, validateCSRFToken } from "~/utils/session.server";
import { getUser } from "~/utils/db/users.db.server";
import { AdminActionInputError } from "~/services/admin/admin-action-audit.server";
import { AdminWebhookInboxError, requestWebhookReplay } from "~/services/admin/webhook-inbox.server";
const WEBHOOK_FILTERS = ["all", "failed", "pending", "delivered", "unknown"] as const;
type WebhookFilter = (typeof WEBHOOK_FILTERS)[number];
type LoaderData = {
title: string;
vm: WebhookInboxVM;
filter: WebhookFilter;
};
type ActionData = {
success?: string;
error?: string;
};
export const meta: MetaFunction<typeof loader> = ({ data }) => [{ title: data?.title }];
export const loader = async ({ request }: LoaderFunctionArgs) => {
await verifyUserHasPermission(request, "admin.events.view");
const { t } = await getTranslations(request);
const filter = parseWebhookFilter(new URL(request.url).searchParams.get("status"));
const attempts = await db.eventWebhookAttempt.findMany({
take: 100,
include: {
event: {
select: {
id: true,
name: true,
resource: true,
tenantId: true,
userId: true,
},
},
},
orderBy: { createdAt: "desc" },
});
const inputRows: WebhookInboxInputRow[] = attempts.map((attempt) => ({
id: attempt.id,
eventId: attempt.eventId,
eventName: attempt.event.name,
eventResource: attempt.event.resource,
tenantId: attempt.event.tenantId,
userId: attempt.event.userId,
endpoint: attempt.endpoint,
success: attempt.success,
status: attempt.status,
message: localizeKnownWebhookMessage(attempt.message, t),
body: redactDiagnosticJsonString(attempt.body),
createdAt: attempt.createdAt.toISOString(),
startedAt: attempt.startedAt?.toISOString() ?? null,
finishedAt: attempt.finishedAt?.toISOString() ?? null,
}));
const vm = filterWebhookInboxVM(buildWebhookInboxVM({ rows: inputRows }), filter);
return {
title: `${t("admin.webhooks.title")} | ${process.env.APP_NAME}`,
vm,
filter,
} satisfies LoaderData;
};
function localizeKnownWebhookMessage(message: string | null, t: (key: string) => string): string | null {
if (message === "admin.webhooks.messages.replayRequested" || message === "Admin replay requested.") {
return t("admin.webhooks.messages.replayRequested");
}
if (message === "admin.webhooks.messages.queueUnavailable" || message === "Webhook delivery queue is unavailable.") {
return t("admin.webhooks.messages.queueUnavailable");
}
return message;
}
function badRequest(data: ActionData) {
return Response.json(data, { status: 400 });
}
function webhookActionErrorKey(error: unknown): string {
if (error instanceof AdminWebhookInboxError || error instanceof AdminActionInputError) return error.i18nKey;
return "admin.webhooks.errors.UNKNOWN";
}
export const action = async ({ request }: ActionFunctionArgs) => {
await verifyUserHasPermission(request, "admin.events.view");
const { t } = await getTranslations(request);
await validateCSRFToken(request);
const form = await request.formData();
const action = form.get("action")?.toString() ?? "";
if (action !== "request-replay") {
return badRequest({ error: t("shared.invalidForm") });
}
const userInfo = await getUserInfo(request);
const actor = await getUser(userInfo.userId);
try {
const result = await requestWebhookReplay({
attemptId: form.get("attemptId")?.toString() ?? "",
reason: form.get("reason")?.toString() ?? "",
actorUserId: userInfo.userId,
actorEmail: actor?.email ?? null,
request,
});
return Response.json({ success: t("admin.webhooks.actions.replayRequested", { attemptId: result.replayAttemptId }) } satisfies ActionData);
} catch (error) {
return badRequest({ error: t(webhookActionErrorKey(error)) });
}
};
export default function AdminWebhooksRoute() {
const { t } = useTranslation();
const data = useLoaderData<LoaderData>();
const actionData = useActionData<ActionData>();
const navigation = useNavigation();
const rootData = useRootData();
const rows = data.vm.status === "ready" ? data.vm.data.rows : [];
const summary = data.vm.status === "ready" ? data.vm.data.summary : null;
const loading = navigation.state === "submitting";
return (
<EditPageLayout
title={t("admin.webhooks.title")}
buttons={
<Link to={adminPath("events", { mode: "host-aware" })} className="text-primary inline-flex items-center gap-1 text-sm font-medium hover:underline">
{t("admin.webhooks.links.events")}
<ExternalLink className="size-4" aria-hidden="true" />
</Link>
}
fullWidth
>
<div className="space-y-4">
<div className="border-border bg-surface-neutral-primary rounded-md border p-4">
<div className="text-muted-foreground text-sm">{t("admin.webhooks.description")}</div>
{actionData?.success && <div className="mt-3 rounded-md bg-green-50 px-3 py-2 text-sm text-green-800">{actionData.success}</div>}
{actionData?.error && <div className="mt-3 rounded-md bg-red-50 px-3 py-2 text-sm text-red-800">{actionData.error}</div>}
</div>
{summary ? <WebhookSummaryGrid summary={summary} /> : null}
<WebhookFilters active={data.filter} />
{data.vm.status === "empty" ? (
<div className="border-border bg-background rounded-md border p-6">
<div className="font-medium">{t("admin.webhooks.empty.headline")}</div>
<div className="text-muted-foreground mt-1 text-sm">{t("admin.webhooks.empty.body")}</div>
</div>
) : (
<div className="space-y-3">
{rows.map((row) => (
<WebhookAttemptCard key={row.id} row={row} csrf={rootData.csrf} loading={loading} />
))}
</div>
)}
</div>
</EditPageLayout>
);
}
function filterWebhookInboxVM(vm: WebhookInboxVM, filter: WebhookFilter): WebhookInboxVM {
if (filter === "all" || vm.status !== "ready") return vm;
const rows = vm.data.rows.filter((row) => row.deliveryStatus === filter);
if (rows.length === 0) return { status: "empty" };
return buildWebhookInboxVM({ rows });
}
function parseWebhookFilter(value: string | null): WebhookFilter {
return WEBHOOK_FILTERS.includes(value as WebhookFilter) ? (value as WebhookFilter) : "all";
}
function WebhookFilters({ active }: { active: WebhookFilter }) {
const { t } = useTranslation();
return (
<div className="flex flex-wrap gap-2">
{WEBHOOK_FILTERS.map((filter) => (
<Link
key={filter}
to={adminPath(filter === "all" ? "webhooks" : `webhooks?status=${filter}`, { mode: "host-aware" })}
className={`rounded-md border px-3 py-2 text-sm font-medium ${
active === filter ? "border-foreground bg-foreground text-background" : "border-border bg-background text-foreground hover:bg-muted"
}`}
>
{t(`admin.webhooks.filters.${filter}`)}
</Link>
))}
</div>
);
}
function WebhookSummaryGrid({ summary }: { summary: WebhookInboxData["summary"] }) {
const { t } = useTranslation();
return (
<div className="grid gap-3 md:grid-cols-2 xl:grid-cols-5">
<WebhookSummaryCard title={t("admin.webhooks.summary.total")} value={summary.totalCount} icon={<RadioTower className="size-5" aria-hidden="true" />} tone="neutral" />
<WebhookSummaryCard title={t("admin.webhooks.summary.failed")} value={summary.failedCount} icon={<AlertTriangle className="size-5" aria-hidden="true" />} tone={summary.failedCount > 0 ? "danger" : "success"} />
<WebhookSummaryCard title={t("admin.webhooks.summary.pending")} value={summary.pendingCount} icon={<Clock3 className="size-5" aria-hidden="true" />} tone={summary.pendingCount > 0 ? "warning" : "success"} />
<WebhookSummaryCard title={t("admin.webhooks.summary.delivered")} value={summary.deliveredCount} icon={<CheckCircle2 className="size-5" aria-hidden="true" />} tone="success" />
<WebhookSummaryCard title={t("admin.webhooks.summary.unknown")} value={summary.unknownCount} icon={<ShieldQuestion className="size-5" aria-hidden="true" />} tone={summary.unknownCount > 0 ? "warning" : "success"} />
</div>
);
}
function WebhookSummaryCard({
title,
value,
icon,
tone,
}: {
title: string;
value: number;
icon: React.ReactNode;
tone: "success" | "warning" | "danger" | "neutral";
}) {
return (
<Card className="gap-4 rounded-lg py-5">
<CardHeader>
<div className="flex items-center justify-between gap-3">
<CardTitle className="text-sm leading-5">{title}</CardTitle>
<div className={`flex size-10 shrink-0 items-center justify-center rounded-md border ${toneIconClasses(tone)}`}>{icon}</div>
</div>
</CardHeader>
<CardContent>
<div className="text-2xl font-semibold leading-7">{value}</div>
</CardContent>
</Card>
);
}
function WebhookAttemptCard({ row, csrf, loading }: { row: WebhookInboxRow; csrf?: string; loading: boolean }) {
const { t } = useTranslation();
const formatters = useLocaleFormatters();
return (
<div className="border-border bg-background rounded-md border p-4">
<div className="flex flex-wrap items-start justify-between gap-3">
<div className="min-w-0">
<div className="flex flex-wrap items-center gap-2">
<Badge color={statusColor(row.deliveryStatus)} withColorDot>
{t(row.statusLabelKey)}
</Badge>
<Badge color="gray">{t(row.providerLabelKey)}</Badge>
{row.status ? <Badge color="gray">HTTP {row.status}</Badge> : null}
</div>
<div className="text-foreground mt-2 font-semibold break-all">{row.eventName}</div>
<div className="text-muted-foreground mt-1 text-sm break-all">{row.endpoint}</div>
</div>
<div className="text-muted-foreground text-right text-xs">
<div>{formatters.dateTime(new Date(row.createdAt))}</div>
{row.durationMs !== null ? <div>{t("admin.webhooks.fields.durationMs", { duration: row.durationMs })}</div> : null}
</div>
</div>
<div className="mt-4 grid gap-4 md:grid-cols-[1fr_1fr_2fr]">
<WebhookField label={t("admin.webhooks.fields.tenant")} value={row.tenantId} />
<WebhookField label={t("admin.webhooks.fields.resource")} value={row.eventResource} />
<WebhookField label={t("admin.webhooks.fields.message")} value={row.message} />
</div>
<div className="border-border bg-muted/40 mt-4 rounded-md border p-3">
<div className="text-muted-foreground mb-2 flex items-center gap-2 text-xs font-medium uppercase">
<Activity className="size-4" aria-hidden="true" />
{t("admin.webhooks.fields.payloadPreview")}
</div>
<pre className="text-foreground max-h-36 overflow-auto whitespace-pre-wrap break-words text-xs leading-5">{row.payloadPreview || t("shared.notSet")}</pre>
</div>
{row.deliveryStatus === "failed" ? <WebhookReplayForm row={row} csrf={csrf} loading={loading} /> : null}
</div>
);
}
function WebhookReplayForm({ row, csrf, loading }: { row: WebhookInboxRow; csrf?: string; loading: boolean }) {
const { t } = useTranslation();
return (
<Form method="post" className="border-border mt-4 grid gap-3 border-t pt-4 md:grid-cols-[minmax(180px,1fr)_auto]">
<input type="hidden" name="csrf" value={csrf ?? ""} />
<input type="hidden" name="action" value="request-replay" />
<input type="hidden" name="attemptId" value={row.id} />
<label className="text-muted-foreground space-y-1 text-xs font-medium">
{t("admin.webhooks.fields.replayReason")}
<input
className="border-border bg-background text-foreground h-9 w-full rounded-md border px-3 text-sm"
name="reason"
placeholder={t("admin.webhooks.placeholders.replayReason")}
required
/>
</label>
<div className="flex items-end">
<ButtonPrimary type="submit" disabled={loading} className="h-9 px-3 text-xs">
{t("admin.webhooks.actions.requestReplay")}
</ButtonPrimary>
</div>
</Form>
);
}
function WebhookField({ label, value }: { label: string; value: string | null }) {
return (
<div className="space-y-1">
<div className="text-muted-foreground text-xs font-medium uppercase">{label}</div>
<div className="text-foreground text-sm break-all">{value || "-"}</div>
</div>
);
}
function statusColor(status: WebhookInboxStatus): BadgeColor {
if (status === "delivered") return "green";
if (status === "failed") return "red";
if (status === "pending") return "yellow";
return "gray";
}
function toneIconClasses(tone: "success" | "warning" | "danger" | "neutral") {
if (tone === "success") return "border-green-500 bg-green-500/5 text-green-700";
if (tone === "warning") return "border-yellow-500 bg-yellow-500/5 text-yellow-700";
if (tone === "danger") return "border-red-500 bg-red-500/5 text-red-700";
return "border-gray-500 bg-gray-500/5 text-gray-700";
}
export function ErrorBoundary() {
return <ServerError />;
}