@futurewindai/wotchi 0.1.0-beta.2 → 0.1.0-beta.6

package/dist/esm/notifiers/webhook-http.js

@@ -0,0 +1,387 @@
+import dns from "node:dns";
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import { toBoundedAlertPayload, toBoundedPayload } from "./alert-payload.js";
+const DEFAULT_TIMEOUT_MS = 3_000;
+const MAX_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_BYTES = 8_192;
+const MAX_PAYLOAD_BYTES = 32_768;
+const MAX_URL_LENGTH = 2_048;
+const MAX_HEADER_COUNT = 20;
+const MAX_HEADER_VALUE_LENGTH = 2_000;
+const wait = (delayMs) => new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+});
+const normalizeHost = (value) => value
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "")
+    .replace(/\.$/g, "");
+const parseIPv4 = (value) => {
+    const parts = value.split(".");
+    if (parts.length !== 4 || parts.some((part) => !/^\d+$/.test(part))) {
+        return undefined;
+    }
+    const numbers = parts.map(Number);
+    return numbers.every((part) => part >= 0 && part <= 255) ? numbers : undefined;
+};
+const isPrivateIPv4 = (value) => {
+    const parts = parseIPv4(value);
+    if (parts === undefined) {
+        return false;
+    }
+    const first = parts[0] ?? -1;
+    const second = parts[1] ?? -1;
+    return (first === 0 ||
+        first === 10 ||
+        first === 127 ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        (first === 198 && (second === 18 || second === 19)));
+};
+const parseIPv6 = (value) => {
+    const host = normalizeHost(value);
+    const halves = host.split("::");
+    if (halves.length > 2) {
+        return undefined;
+    }
+    const parseHalf = (half) => {
+        if (half === "") {
+            return [];
+        }
+        const groups = half.split(":");
+        const values = [];
+        for (const group of groups) {
+            if (group.includes(".")) {
+                const ipv4 = parseIPv4(group);
+                if (ipv4 === undefined) {
+                    return undefined;
+                }
+                values.push((ipv4[0] ?? 0) * 256 + (ipv4[1] ?? 0));
+                values.push((ipv4[2] ?? 0) * 256 + (ipv4[3] ?? 0));
+                continue;
+            }
+            if (!/^[0-9a-f]{1,4}$/i.test(group)) {
+                return undefined;
+            }
+            values.push(Number.parseInt(group, 16));
+        }
+        return values;
+    };
+    const left = parseHalf(halves[0] ?? "");
+    const right = parseHalf(halves[1] ?? "");
+    if (left === undefined || right === undefined) {
+        return undefined;
+    }
+    const missing = halves.length === 2 ? 8 - left.length - right.length : 0;
+    if (missing < 1 || left.length + right.length + missing !== 8) {
+        return undefined;
+    }
+    const groups = [...left, ...Array.from({ length: missing }, () => 0), ...right];
+    return groups.flatMap((group) => [(group >> 8) & 0xff, group & 0xff]);
+};
+const isPrivateIPv6 = (value) => {
+    const bytes = parseIPv6(value);
+    if (bytes === undefined) {
+        return false;
+    }
+    const allZero = bytes.every((byte) => byte === 0);
+    const loopback = allZero || (bytes.slice(0, 15).every((byte) => byte === 0) && bytes[15] === 1);
+    const first = bytes[0] ?? 0;
+    const second = bytes[1] ?? 0;
+    if (loopback ||
+        first === 0xfc ||
+        first === 0xfd ||
+        (first === 0xfe && (second & 0xc0) === 0x80)) {
+        return true;
+    }
+    const mapped = bytes.slice(0, 10).every((byte) => byte === 0) && bytes[10] === 0xff && bytes[11] === 0xff;
+    const compatible = bytes.slice(0, 12).every((byte) => byte === 0);
+    if (!mapped && !compatible) {
+        return false;
+    }
+    return isPrivateIPv4(bytes.slice(12).join("."));
+};
+const isPrivateDestination = (value) => {
+    const host = normalizeHost(value);
+    if (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host.endsWith(".local") ||
+        host === "metadata.google.internal" ||
+        host.endsWith(".internal")) {
+        return true;
+    }
+    const family = net.isIP(host);
+    return family === 4 ? isPrivateIPv4(host) : family === 6 && isPrivateIPv6(host);
+};
+const privateDestinationError = () => new TypeError("webhook private or internal destinations require allowPrivateDestinations");
+const normalizeUrl = (value, allowHttpLoopback = false, allowPrivateDestinations = false) => {
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > MAX_URL_LENGTH) {
+        throw new TypeError("webhook url is invalid");
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError("webhook url is invalid");
+    }
+    if (url.username !== "" || url.password !== "" || url.hash !== "") {
+        throw new TypeError("webhook url must not contain credentials or a fragment");
+    }
+    if (url.protocol === "https:" &&
+        !allowPrivateDestinations &&
+        isPrivateDestination(url.hostname)) {
+        throw privateDestinationError();
+    }
+    if (url.protocol === "https:") {
+        return url;
+    }
+    const loopback = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+    if (url.protocol !== "http:" || !allowHttpLoopback || !loopback.has(url.hostname)) {
+        throw new TypeError("webhook url must be HTTPS or explicitly enabled loopback HTTP");
+    }
+    return url;
+};
+const normalizeHeaders = (headers) => {
+    if (headers === undefined) {
+        return undefined;
+    }
+    const entries = Object.entries(headers);
+    if (entries.length > MAX_HEADER_COUNT) {
+        throw new TypeError("webhook headers exceed the maximum count");
+    }
+    const normalized = {};
+    for (const [name, value] of entries) {
+        if (!/^[A-Za-z0-9-]+$/.test(name) || name.length > 100) {
+            throw new TypeError("webhook header name is invalid");
+        }
+        if (typeof value !== "string" ||
+            value.length > MAX_HEADER_VALUE_LENGTH ||
+            /[\r\n]/.test(value)) {
+            throw new TypeError("webhook header value is invalid");
+        }
+        const normalizedName = name.toLowerCase();
+        if (normalizedName === "content-length" || normalizedName === "host") {
+            throw new TypeError(`webhook header ${normalizedName} is reserved`);
+        }
+        normalized[normalizedName] = value;
+    }
+    return normalized;
+};
+export function normalizeWebhookOptions(options) {
+    if (options.allowHttpLoopback !== undefined && typeof options.allowHttpLoopback !== "boolean") {
+        throw new TypeError("webhook allowHttpLoopback is invalid");
+    }
+    const allowHttpLoopback = options.allowHttpLoopback === true;
+    const allowPrivateDestinations = options.allowPrivateDestinations === true;
+    const url = normalizeUrl(options.url, allowHttpLoopback, allowPrivateDestinations);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMEOUT_MS) {
+        throw new TypeError("webhook timeoutMs is invalid");
+    }
+    const maxRetries = options.maxRetries ?? 1;
+    if (!Number.isSafeInteger(maxRetries) || maxRetries < 0 || maxRetries > 1) {
+        throw new TypeError("webhook maxRetries must be 0 or 1");
+    }
+    if (options.payloadBuilder !== undefined && typeof options.payloadBuilder !== "function") {
+        throw new TypeError("webhook payloadBuilder is invalid");
+    }
+    const headers = normalizeHeaders(options.headers);
+    return {
+        url,
+        ...(headers === undefined ? {} : { headers }),
+        timeoutMs,
+        maxRetries,
+        allowHttpLoopback,
+        allowPrivateDestinations: allowPrivateDestinations || (url.protocol === "http:" && allowHttpLoopback),
+        ...(options.payloadBuilder === undefined ? {} : { payloadBuilder: options.payloadBuilder }),
+    };
+}
+const resolveWebhookAddress = async (hostname, timeoutMs, signal) => {
+    let timer;
+    let removeAbortListener = () => undefined;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("webhook destination lookup timed out")), timeoutMs);
+        });
+        const races = [dns.promises.lookup(hostname), timeout];
+        if (signal !== undefined) {
+            const aborted = new Promise((_, reject) => {
+                const onAbort = () => reject(new Error("webhook request timed out"));
+                if (signal.aborted) {
+                    onAbort();
+                    return;
+                }
+                signal.addEventListener("abort", onAbort, { once: true });
+                removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+            });
+            races.push(aborted);
+        }
+        return await Promise.race(races);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        removeAbortListener();
+    }
+};
+const defaultRequest = async (options, body, timeoutMs) => {
+    const resolvedAddress = await resolveWebhookAddress(options.hostname, timeoutMs, options.signal);
+    if (!options.allowPrivateDestinations && isPrivateDestination(resolvedAddress.address)) {
+        throw privateDestinationError();
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let removeAbortListener = () => undefined;
+        const finish = (callback) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            removeAbortListener();
+            callback();
+        };
+        const { allowPrivateDestinations: _allowPrivateDestinations, ...nodeOptions } = options;
+        const request = (options.protocol === "http:" ? http : https).request({
+            ...nodeOptions,
+            lookup: (_hostname, _lookupOptions, callback) => callback(null, resolvedAddress.address, resolvedAddress.family),
+        }, (response) => {
+            const chunks = [];
+            let size = 0;
+            response.on("data", (chunk) => {
+                size += Buffer.byteLength(chunk);
+                if (size > MAX_RESPONSE_BYTES) {
+                    request.destroy();
+                    finish(() => reject(new Error("webhook response body exceeded limit")));
+                    return;
+                }
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            response.once("error", (error) => finish(() => reject(error)));
+            response.once("end", () => finish(() => resolve({
+                statusCode: response.statusCode ?? 0,
+                headers: response.headers,
+                body: Buffer.concat(chunks).toString("utf8"),
+            })));
+        });
+        const onAbort = () => {
+            request.destroy();
+        };
+        if (options.signal !== undefined) {
+            options.signal.addEventListener("abort", onAbort, { once: true });
+            removeAbortListener = () => options.signal?.removeEventListener("abort", onAbort);
+            if (options.signal.aborted) {
+                onAbort();
+            }
+        }
+        request.once("error", (error) => finish(() => reject(error)));
+        request.setTimeout(timeoutMs, () => {
+            request.destroy();
+            finish(() => reject(new Error("webhook request timed out")));
+        });
+        request.end(body);
+    });
+};
+const requestWithTimeout = async (request, options, body, timeoutMs) => {
+    let timer;
+    const controller = new AbortController();
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new Error("webhook request timed out"));
+            }, timeoutMs);
+        });
+        return await Promise.race([
+            request({ ...options, signal: controller.signal }, body, timeoutMs),
+            timeout,
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+};
+const deepFreeze = (value) => {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value)) {
+        deepFreeze(child);
+    }
+    return value;
+};
+const serializeAlert = (alert, payloadBuilder) => {
+    const sanitizedAlert = deepFreeze(toBoundedAlertPayload(alert));
+    let payload;
+    try {
+        const custom = payloadBuilder === undefined ? sanitizedAlert : payloadBuilder(sanitizedAlert);
+        payload = toBoundedPayload(custom);
+    }
+    catch {
+        throw new Error("webhook payload builder failed");
+    }
+    const envelope = {
+        version: 1,
+        type: "incident.alert",
+        sentAt: new Date().toISOString(),
+        alert: payload,
+    };
+    const serialized = JSON.stringify(envelope);
+    if (Buffer.byteLength(serialized, "utf8") <= MAX_PAYLOAD_BYTES) {
+        return serialized;
+    }
+    const fallback = JSON.stringify({
+        version: 1,
+        type: "incident.alert",
+        sentAt: new Date().toISOString(),
+        alert: {
+            title: alert.title.slice(0, 300),
+            fingerprint: alert.fingerprint.slice(0, 200),
+            severity: alert.severity,
+            summary: alert.summary.slice(0, 2_000),
+            service: alert.service.slice(0, 200),
+            environment: alert.environment.slice(0, 200),
+            occurrences: alert.occurrences,
+            truncated: true,
+        },
+    });
+    return fallback;
+};
+export async function sendWebhookAlert(options, request = defaultRequest) {
+    const normalized = normalizeWebhookOptions(options);
+    const body = serializeAlert(options.alert, normalized.payloadBuilder);
+    const requestOptions = {
+        protocol: normalized.url.protocol,
+        hostname: normalized.url.hostname.replace(/^\[|\]$/g, ""),
+        ...(normalized.url.port === "" ? {} : { port: normalized.url.port }),
+        method: "POST",
+        path: `${normalized.url.pathname || "/"}${normalized.url.search}`,
+        headers: {
+            ...(normalized.headers ?? {}),
+            "content-type": "application/json",
+            "content-length": Buffer.byteLength(body, "utf8"),
+        },
+        allowPrivateDestinations: normalized.allowPrivateDestinations,
+    };
+    let attempt = 0;
+    while (true) {
+        const response = await requestWithTimeout(request, requestOptions, body, normalized.timeoutMs);
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+            return;
+        }
+        if (attempt < normalized.maxRetries &&
+            (response.statusCode === 429 || response.statusCode >= 500)) {
+            attempt += 1;
+            await wait(50);
+            continue;
+        }
+        throw new Error(`Webhook request failed with status ${response.statusCode}`);
+    }
+}

package/dist/esm/notifiers/webhook.js

@@ -0,0 +1,24 @@
+import { normalizeWebhookOptions, sendWebhookAlert, } from "./webhook-http.js";
+export function createWebhookNotifier(options, request) {
+    const normalized = normalizeWebhookOptions(options);
+    const sendOptions = {
+        url: normalized.url.toString(),
+        ...(normalized.headers === undefined ? {} : { headers: normalized.headers }),
+        timeoutMs: normalized.timeoutMs,
+        maxRetries: normalized.maxRetries,
+        allowHttpLoopback: normalized.allowHttpLoopback,
+        allowPrivateDestinations: normalized.allowPrivateDestinations,
+        ...(normalized.payloadBuilder === undefined
+            ? {}
+            : { payloadBuilder: normalized.payloadBuilder }),
+    };
+    return {
+        name: "webhook",
+        async send(alert) {
+            await sendWebhookAlert({ ...sendOptions, alert }, request);
+        },
+    };
+}
+export function webhookNotifier(options) {
+    return createWebhookNotifier(options);
+}

package/dist/types/core/admission.d.ts

@@ -0,0 +1,10 @@
+export interface CaptureAdmissionOptions {
+    maxEventsPerSecond: number;
+    burst: number;
+    now?: () => number;
+}
+export interface CaptureAdmission {
+    tryAcquire(): boolean;
+}
+/** A small token bucket used before normalization to bound overload work. */
+export declare function createCaptureAdmission(options: CaptureAdmissionOptions): CaptureAdmission;

package/dist/types/core/config.d.ts

@@ -1,11 +1,17 @@
-import type { WotchiConfig, WotchiNotifier } from "./types.js";
+import type { WotchiConfig, WotchiIncidentRule, WotchiLinkTemplates, WotchiNotifier } from "./types.js";
 import { WotchiConfigurationError } from "./errors.js";
 export { WotchiConfigurationError };
 export interface NormalizedWotchiConfig {
     readonly service: string;
     readonly environment: string;
+    readonly instance?: string;
     readonly release?: string;
     readonly enabled: boolean;
+    readonly filter?: WotchiConfig["filter"];
+    readonly fingerprint?: WotchiConfig["fingerprint"];
+    readonly beforeSend?: WotchiConfig["beforeSend"];
+    readonly links?: Readonly<WotchiLinkTemplates>;
+    readonly rules: readonly WotchiIncidentRule[];
     readonly grouping: {
         readonly windowMs: number;
         readonly alertThreshold: number;
@@ -16,6 +22,16 @@ export interface NormalizedWotchiConfig {
     readonly queue: {
         readonly maxPendingAlerts: number;
         readonly concurrency: 1;
+        readonly notifierTimeoutMs: number;
+        readonly notifierCircuitBreaker: {
+            readonly failureThreshold: number;
+            readonly cooldownMs: number;
+        };
+    };
+    readonly overload?: {
+        readonly maxEventsPerSecond: number;
+        readonly burst: number;
+        readonly alertCooldownMs: number;
     };
     readonly privacy: {
         readonly redactKeys: readonly string[];

package/dist/types/core/diagnostics.d.ts

@@ -2,6 +2,12 @@ import type { WotchiDiagnostics } from "./types.js";
 export interface DiagnosticsState {
     capturedEvents: number;
     captureFailures: number;
+    fingerprintCallbackFailures: number;
+    filterFailures: number;
+    beforeSendFailures: number;
+    eventsSuppressed: number;
+    eventsDroppedOverload: number;
+    capturesAfterShutdown: number;
 }
 export declare function createDiagnosticsState(): DiagnosticsState;
-export declare function snapshotDiagnostics(state: DiagnosticsState, values: Omit<WotchiDiagnostics, "capturedEvents" | "captureFailures">): Readonly<WotchiDiagnostics>;
+export declare function snapshotDiagnostics(state: DiagnosticsState, values: Omit<WotchiDiagnostics, "capturedEvents" | "captureFailures" | "fingerprintCallbackFailures" | "filterFailures" | "beforeSendFailures" | "eventsSuppressed" | "eventsDroppedOverload" | "capturesAfterShutdown">): Readonly<WotchiDiagnostics>;

package/dist/types/core/incident-policy.d.ts

@@ -1,5 +1,5 @@
 import type { IncidentGroup, IncidentSeverity } from "./types.js";
-export type IncidentEventKind = "error" | "manual" | "process-monitor";
+export type IncidentEventKind = "error" | "manual" | "process-monitor" | "runtime-monitor";
 export interface IncidentPolicyInput {
     group: IncidentGroup;
     now: number;

package/dist/types/core/limits.d.ts

@@ -0,0 +1,14 @@
+export declare const MAX_GROUPS = 10000;
+export declare const MAX_EVENTS_PER_WINDOW = 10000;
+export declare const MAX_PENDING_ALERTS = 10000;
+export declare const MAX_WINDOW_MS: number;
+export declare const MAX_ALERT_THRESHOLD = 1000000;
+export declare const MAX_COOLDOWN_MS: number;
+export declare const MAX_CAPTURE_RATE = 1000000;
+export declare const MAX_NOTIFIER_TIMEOUT_MS = 60000;
+export declare const MAX_CIRCUIT_BREAKER_COOLDOWN_MS: number;
+export declare const MAX_CIRCUIT_BREAKER_FAILURES = 100;
+export declare const MAX_NORMALIZATION_DEPTH = 20;
+export declare const MAX_NORMALIZATION_KEYS = 10000;
+export declare const MAX_NORMALIZATION_STRING_LENGTH = 32768;
+export declare const MAX_NORMALIZATION_STACK_LENGTH = 32768;

package/dist/types/core/notification-queue.d.ts

@@ -2,15 +2,28 @@ import type { IncidentAlert, WotchiNotifier } from "./types.js";
 export interface NotificationQueueOptions {
     maxPendingAlerts: number;
     concurrency: 1;
+    notifierTimeoutMs?: number;
+    notifierCircuitBreaker?: {
+        failureThreshold: number;
+        cooldownMs: number;
+    };
     onNotifierError?: (error: unknown, notifier: WotchiNotifier) => void;
 }
+export interface NotificationJobResult {
+    notifierFailures: number;
+    sent: number;
+}
 export interface NotificationQueue {
-    enqueue(alert: IncidentAlert, notifiers: readonly WotchiNotifier[]): boolean;
+    enqueue(alert: IncidentAlert, notifiers: readonly WotchiNotifier[], onComplete?: (result: NotificationJobResult) => void): boolean;
     flush(timeoutMs?: number): Promise<void>;
+    close(timeoutMs?: number): Promise<void>;
+    isClosed(): boolean;
     pending(): number;
     alertsQueued(): number;
     alertsDropped(): number;
     alertsSent(): number;
     notifierFailures(): number;
+    notifierTimeouts(): number;
+    notifierCircuitOpenSkips(): number;
 }
 export declare function createNotificationQueue(options: NotificationQueueOptions): NotificationQueue;

package/dist/types/core/prometheus.d.ts

@@ -0,0 +1,7 @@
+import type { WotchiClient } from "./types.js";
+export declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+export interface WotchiPrometheusExporter {
+    readonly contentType: typeof PROMETHEUS_CONTENT_TYPE;
+    render(): string;
+}
+export declare function createWotchiPrometheusExporter(client: Pick<WotchiClient, "getDiagnostics">): WotchiPrometheusExporter;

package/dist/types/core/runtime-monitor.d.ts

@@ -0,0 +1,15 @@
+import type { WotchiClient } from "./types.js";
+export interface WotchiRuntimeWatcherOptions {
+    intervalMs?: number;
+    cpuPercent?: number;
+    rssBytes?: number;
+    heapUsedBytes?: number;
+    eventLoopDelayMs?: number;
+    pendingAlerts?: number;
+    notifierFailures?: number;
+    alertThreshold?: number;
+}
+export interface WotchiRuntimeWatcherHandle {
+    unregister(): void;
+}
+export declare function registerWotchiRuntimeWatcher(client: Pick<WotchiClient, "captureEvent" | "getDiagnostics">, options?: WotchiRuntimeWatcherOptions): WotchiRuntimeWatcherHandle;