Add runbooks, backup coverage, inventory, roles from groups, Prometheus metrics and event webhooks
- Runbooks: notes per server/integration, shown next to matching alerts - Backup coverage page across Proxmox and PBS, with a digest section - Hardware inventory with warranty, power and running cost - Authentik group to role mapping with preview and safeguards - /metrics (bearer token) and signed outgoing event webhooks - Docs: README, DATABASE, NOTIFICATIONS, ROLES and new API.md Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
c36e2092c5
commit
c17e9aa140
55 files changed
+7177
-27
No files matched your search
@@ -0,0 +1,105 @@
|
||||
/**
|
||||
* Event webhooks: tell another system when something happens. Each webhook is a URL with the events it wants; when one happens it is
|
||||
* sent a JSON message, signed with the webhook's secret so the receiver can tell it came from here. This is separate from the chat-style
|
||||
* webhook under Settings → Notifications, which carries the same sentence a person would read.
|
||||
*
|
||||
* alert.opened / alert.resolved a problem began or ended — on the same terms as a notification (a problem under maintenance,
|
||||
* or folded under another, isn't announced until it stands alone)
|
||||
* maintenance.started / .ended a maintenance window began or finished, however it was made
|
||||
*
|
||||
* Delivery is best-effort and never holds anything up: one try, one more if that fails, then the result is noted on the webhook (shown in
|
||||
* Settings) and forgotten.
|
||||
*/
|
||||
import { createHmac, randomUUID } from "node:crypto";
|
||||
import { eq } from "drizzle-orm";
|
||||
import { db } from "../db/client.js";
|
||||
import { eventWebhooks, webhookEvents, type WebhookEvent } from "../db/schema.js";
|
||||
import { decryptSecret, encryptSecret } from "../crypto.js";
|
||||
import { env } from "../env.js";
|
||||
|
||||
export type EventWebhookRow = typeof eventWebhooks.$inferSelect;
|
||||
|
||||
const ENCRYPTED_PREFIX = "enc:v1:";
|
||||
const TIMEOUT_MS = 5000;
|
||||
const RETRY_AFTER_MS = 2000;
|
||||
|
||||
/** The stored form of a secret: encrypted when an encryption key is set, as the notification channels' secrets are. */
|
||||
export function sealSecret(plain: string): string {
|
||||
return env.credentialsEncryptionEnabled ? ENCRYPTED_PREFIX + encryptSecret(plain) : plain;
|
||||
}
|
||||
|
||||
function openSecret(stored: string | null): string | null {
|
||||
if (!stored) return null;
|
||||
if (!stored.startsWith(ENCRYPTED_PREFIX)) return stored;
|
||||
try {
|
||||
return decryptSecret(stored.slice(ENCRYPTED_PREFIX.length));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function parseEvents(stored: string): WebhookEvent[] {
|
||||
try {
|
||||
const v = JSON.parse(stored);
|
||||
return Array.isArray(v) ? v.filter((e): e is WebhookEvent => (webhookEvents as readonly string[]).includes(e)) : [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/** The signature a receiver should compute over the exact body it got: HMAC-SHA256 with the secret, as hex, prefixed "sha256=". */
|
||||
export function signBody(secret: string, body: string): string {
|
||||
return `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
|
||||
}
|
||||
|
||||
export interface Delivery {
|
||||
ok: boolean;
|
||||
/** "200", or what went wrong. */
|
||||
result: string;
|
||||
}
|
||||
|
||||
async function post(row: EventWebhookRow, event: string, body: string, deliveryId: string): Promise<Delivery> {
|
||||
const secret = openSecret(row.secret);
|
||||
const headers: Record<string, string> = {
|
||||
"Content-Type": "application/json",
|
||||
"User-Agent": "HomelabManager-Webhook",
|
||||
"X-HLM-Event": event,
|
||||
"X-HLM-Delivery": deliveryId,
|
||||
};
|
||||
if (secret) headers["X-HLM-Signature"] = signBody(secret, body);
|
||||
try {
|
||||
const res = await fetch(row.url, { method: "POST", headers, body, signal: AbortSignal.timeout(TIMEOUT_MS), redirect: "manual" });
|
||||
return { ok: res.status >= 200 && res.status < 300, result: String(res.status) };
|
||||
} catch (err) {
|
||||
const name = err instanceof Error ? err.name : "";
|
||||
return { ok: false, result: name === "TimeoutError" ? "timed out" : err instanceof Error ? err.message.slice(0, 120) : "failed" };
|
||||
}
|
||||
}
|
||||
|
||||
/** One message to one webhook, retried once if it didn't go through. The outcome is written on the webhook. */
|
||||
export async function deliver(row: EventWebhookRow, event: string, data: unknown, options: { retryAfterMs?: number } = {}): Promise<Delivery> {
|
||||
const deliveryId = randomUUID();
|
||||
const body = JSON.stringify({ event, id: deliveryId, createdAt: new Date().toISOString(), source: "homelab-manager", data });
|
||||
let outcome = await post(row, event, body, deliveryId);
|
||||
if (!outcome.ok) {
|
||||
await new Promise((r) => setTimeout(r, options.retryAfterMs ?? RETRY_AFTER_MS));
|
||||
outcome = await post(row, event, body, deliveryId);
|
||||
}
|
||||
try {
|
||||
await db.update(eventWebhooks).set({ lastAttemptAt: new Date().toISOString(), lastResult: outcome.result }).where(eq(eventWebhooks.id, row.id));
|
||||
} catch (err) {
|
||||
console.error("[webhooks] couldn't note the result:", err);
|
||||
}
|
||||
return outcome;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sends an event to every enabled webhook that wants it. Returns at once — delivery carries on in the background and can never delay or
|
||||
* fail what caused the event.
|
||||
*/
|
||||
export function emitEvent(event: WebhookEvent, data: unknown): void {
|
||||
void (async () => {
|
||||
const rows = await db.select().from(eventWebhooks).where(eq(eventWebhooks.enabled, true));
|
||||
await Promise.all(rows.filter((r) => parseEvents(r.events).includes(event)).map((r) => deliver(r, event, data)));
|
||||
})().catch((err) => console.error("[webhooks] couldn't send an event:", err));
|
||||
}
|
||||
Reference in new issue
Block a user