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

package/dist/esm/core/client.js

@@ -1,4 +1,5 @@
 import { validateConfig } from "./config.js";
+import { createCaptureAdmission } from "./admission.js";
 import { createDiagnosticsState, snapshotDiagnostics } from "./diagnostics.js";
 import { fingerprintSafeErrorEvent } from "./fingerprint.js";
 import { createGroupStore } from "./group-store.js";
@@ -10,6 +11,34 @@ import { redactError, redactValue } from "./redact.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const asString = (value) => typeof value === "string" ? value : undefined;
 const asStatusCode = (value) => typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
+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 safeTrace = (value, privacy) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const redacted = redactValue(value, privacy);
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const traceId = asString(redacted.traceId);
+    const spanId = asString(redacted.spanId);
+    if (traceId === undefined && spanId === undefined) {
+        return undefined;
+    }
+    return {
+        ...(traceId === undefined ? {} : { traceId: traceId.slice(0, 128) }),
+        ...(spanId === undefined ? {} : { spanId: spanId.slice(0, 128) }),
+    };
+};
 const safeRecord = (value, privacy) => {
     if (value === undefined) {
         return undefined;
@@ -39,20 +68,48 @@ const safeRequest = (request, privacy) => {
     const method = asString(redacted.method);
     const route = asString(redacted.route);
     const requestId = asString(redacted.requestId);
+    const correlationId = asString(redacted.correlationId);
     const statusCode = asStatusCode(redacted.statusCode);
+    const trace = safeTrace(redacted.trace, privacy);
     if (method === undefined &&
         route === undefined &&
         requestId === undefined &&
-        statusCode === undefined) {
+        correlationId === undefined &&
+        statusCode === undefined &&
+        trace === undefined) {
         return undefined;
     }
     return {
         ...(method === undefined ? {} : { method }),
         ...(route === undefined ? {} : { route }),
         ...(requestId === undefined ? {} : { requestId }),
+        ...(correlationId === undefined ? {} : { correlationId }),
         ...(statusCode === undefined ? {} : { statusCode }),
+        ...(trace === undefined ? {} : { trace }),
     };
 };
+const safeTags = (value, privacy) => {
+    const redacted = redactValue(value, { ...privacy, maxKeys: Math.min(privacy.maxKeys, 50) });
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const tags = {};
+    for (const [key, tagValue] of Object.entries(redacted)) {
+        if (key.length > 64 || typeof tagValue !== "string") {
+            continue;
+        }
+        tags[key] = tagValue.slice(0, 200);
+    }
+    return Object.keys(tags).length === 0 ? undefined : tags;
+};
+const safeShortString = (value, privacy, maxLength) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const redacted = redactValue(value, { ...privacy, maxStringLength: maxLength });
+    const text = asString(redacted);
+    return text === undefined ? undefined : text.slice(0, maxLength);
+};
 const safeMessage = (value, privacy) => {
     const normalized = normalizeUnknown(value, privacy);
     return typeof normalized === "string" ? normalized : "[unreadable value]";
@@ -66,6 +123,150 @@ const normalizeEventAlertThreshold = (value) => {
     }
     return value;
 };
+const safeErrorFromValue = (value, privacy) => {
+    const redacted = redactValue(value, privacy);
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const name = asString(redacted.name);
+    const message = asString(redacted.message);
+    if (name === undefined || message === undefined) {
+        return undefined;
+    }
+    const stack = asString(redacted.stack);
+    const code = asString(redacted.code);
+    const applicationFrame = asString(redacted.applicationFrame);
+    return {
+        name,
+        message,
+        ...(stack === undefined ? {} : { stack }),
+        ...(code === undefined ? {} : { code }),
+        ...(applicationFrame === undefined
+            ? {}
+            : { applicationFrame: applicationFrame.slice(0, 1_000) }),
+    };
+};
+const safeAlertFromValue = (value, fallback, privacy) => {
+    const redacted = redactValue(value, privacy);
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const title = asString(redacted.title);
+    const fingerprint = asString(redacted.fingerprint);
+    const summary = asString(redacted.summary);
+    const severity = asString(redacted.severity);
+    const firstSeenAt = asString(redacted.firstSeenAt);
+    const lastSeenAt = asString(redacted.lastSeenAt);
+    const service = asString(redacted.service);
+    const environment = asString(redacted.environment);
+    const occurrences = asStatusCode(redacted.occurrences);
+    if (title === undefined ||
+        fingerprint === undefined ||
+        summary === undefined ||
+        firstSeenAt === undefined ||
+        lastSeenAt === undefined ||
+        service === undefined ||
+        environment === undefined ||
+        occurrences === undefined ||
+        (severity !== "low" && severity !== "medium" && severity !== "high" && severity !== "critical")) {
+        return undefined;
+    }
+    const rawActions = redacted.suggestedActions;
+    if (!Array.isArray(rawActions)) {
+        return undefined;
+    }
+    const suggestedActions = rawActions
+        .filter((action) => typeof action === "string")
+        .slice(0, 5)
+        .map((action) => action.slice(0, 600));
+    const error = safeErrorFromValue(redacted.error, privacy);
+    const request = safeRequest(redacted.request, privacy);
+    const trace = safeTrace(redacted.trace, privacy);
+    const context = safeRecord(redacted.context, privacy);
+    const tags = safeTags(redacted.tags, privacy);
+    const linksValue = safeRecord(redacted.links, privacy);
+    const logLink = linksValue === undefined ? undefined : asString(linksValue.log);
+    const traceLink = linksValue === undefined ? undefined : asString(linksValue.trace);
+    const links = linksValue
+        ? {
+            ...(logLink === undefined ? {} : { log: logLink.slice(0, 2_048) }),
+            ...(traceLink === undefined ? {} : { trace: traceLink.slice(0, 2_048) }),
+        }
+        : undefined;
+    const instance = asString(redacted.instance);
+    const release = asString(redacted.release);
+    const correlationId = asString(redacted.correlationId);
+    const operation = asString(redacted.operation);
+    const job = asString(redacted.job);
+    return deepFreeze({
+        id: asString(redacted.id) ?? fallback.id,
+        fingerprint: fingerprint.slice(0, 200),
+        title: title.slice(0, 300),
+        severity,
+        summary: summary.slice(0, 2_000),
+        suggestedActions,
+        firstSeenAt: firstSeenAt.slice(0, 100),
+        lastSeenAt: lastSeenAt.slice(0, 100),
+        occurrences: Math.max(0, Math.min(occurrences, Number.MAX_SAFE_INTEGER)),
+        service: service.slice(0, 300),
+        environment: environment.slice(0, 300),
+        ...(instance === undefined ? {} : { instance: instance.slice(0, 200) }),
+        ...(release === undefined ? {} : { release: release.slice(0, 200) }),
+        ...(correlationId === undefined ? {} : { correlationId: correlationId.slice(0, 200) }),
+        ...(operation === undefined ? {} : { operation: operation.slice(0, 200) }),
+        ...(job === undefined ? {} : { job: job.slice(0, 200) }),
+        ...(tags === undefined ? {} : { tags }),
+        ...(error === undefined ? {} : { error }),
+        ...(request === undefined ? {} : { request }),
+        ...(trace === undefined ? {} : { trace }),
+        ...(context === undefined ? {} : { context }),
+        ...(links === undefined || Object.keys(links).length === 0 ? {} : { links }),
+    });
+};
+const normalizeFingerprintOverride = (override, event) => {
+    if (override === undefined) {
+        return undefined;
+    }
+    const value = typeof override === "function" ? override(event) : override;
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > 200) {
+        throw new TypeError("fingerprint must be a non-empty string no longer than 200 characters");
+    }
+    return value.trim();
+};
+const renderLinks = (templates, event, fingerprint) => {
+    if (templates === undefined) {
+        return undefined;
+    }
+    const values = {
+        service: event.service,
+        environment: event.environment,
+        release: event.release ?? "",
+        instance: event.instance ?? "",
+        fingerprint,
+        requestId: event.request?.requestId ?? "",
+        correlationId: event.correlationId ?? event.request?.correlationId ?? "",
+        traceId: event.trace?.traceId ?? event.request?.trace?.traceId ?? "",
+        spanId: event.trace?.spanId ?? event.request?.trace?.spanId ?? "",
+        route: event.request?.route ?? "",
+        statusCode: event.request?.statusCode === undefined ? "" : String(event.request.statusCode),
+    };
+    const render = (template) => {
+        const expanded = template.replace(/\{\{([^{}]+)\}\}/g, (_match, key) => encodeURIComponent(values[key] ?? ""));
+        const redacted = redactValue(expanded, { maxStringLength: 2_048 });
+        return typeof redacted === "string" ? redacted.slice(0, 2_048) : "";
+    };
+    const result = {};
+    if (templates.log !== undefined) {
+        result.log = render(templates.log);
+    }
+    if (templates.trace !== undefined && (values.traceId !== "" || values.spanId !== "")) {
+        result.trace = render(templates.trace);
+    }
+    return Object.keys(result).length === 0 ? undefined : result;
+};
 export function createWotchi(config) {
     const normalized = validateConfig(config);
     const now = Date.now;
@@ -79,48 +280,162 @@ export function createWotchi(config) {
     const queue = createNotificationQueue({
         maxPendingAlerts: normalized.queue.maxPendingAlerts,
         concurrency: normalized.queue.concurrency,
+        notifierTimeoutMs: normalized.queue.notifierTimeoutMs,
+        notifierCircuitBreaker: normalized.queue.notifierCircuitBreaker,
     });
+    const admission = normalized.overload === undefined
+        ? undefined
+        : createCaptureAdmission({
+            maxEventsPerSecond: normalized.overload.maxEventsPerSecond,
+            burst: normalized.overload.burst,
+            now,
+        });
     const privacy = normalized.privacy;
     let eventSequence = 0;
-    const captureSafeEvent = (error, metadata, context, request, eventKind = "error", alertThreshold = normalized.grouping.alertThreshold) => {
+    let overloadLastAlertAt = 0;
+    const matchingRule = (event) => normalized.rules.find((rule) => (rule.environment === undefined || rule.environment === event.environment) &&
+        (rule.route === undefined || rule.route === event.request?.route));
+    const captureSafeEvent = (error, metadata, context, request, eventKind = "error", alertThreshold = normalized.grouping.alertThreshold, fingerprintOverride, severityOverride, trace, correlationId, operation, job, tags) => {
         const timestamp = now();
         const safeError = redactError(normalizeError(error, privacy), privacy);
         const requestContext = safeRequest(request, privacy);
         const eventContext = mergeContext(metadata, context, privacy);
+        const requestTrace = safeTrace(trace ?? requestContext?.trace, privacy);
+        const eventCorrelationId = safeShortString(correlationId ?? requestContext?.correlationId, privacy, 200);
+        const operationValue = safeShortString(operation ?? eventContext?.operation, privacy, 200);
+        const jobValue = safeShortString(job ?? eventContext?.job ?? eventContext?.queue, privacy, 200);
+        const eventTags = safeTags(tags, privacy);
         const safeEvent = {
             id: `event-${eventSequence + 1}`,
             timestamp: new Date(timestamp).toISOString(),
             service: normalized.service,
             environment: normalized.environment,
+            ...(normalized.instance === undefined ? {} : { instance: normalized.instance }),
             ...(normalized.release === undefined ? {} : { release: normalized.release }),
+            ...(eventCorrelationId === undefined ? {} : { correlationId: eventCorrelationId }),
+            ...(operationValue === undefined ? {} : { operation: operationValue.slice(0, 200) }),
+            ...(jobValue === undefined ? {} : { job: jobValue.slice(0, 200) }),
+            ...(eventTags === undefined ? {} : { tags: eventTags }),
             error: safeError,
             ...(requestContext === undefined ? {} : { request: requestContext }),
+            ...(requestTrace === undefined ? {} : { trace: requestTrace }),
             ...(eventContext === undefined ? {} : { context: eventContext }),
         };
         eventSequence += 1;
-        const fingerprint = fingerprintSafeErrorEvent(safeEvent);
-        const group = groupStore.record(fingerprint, safeEvent);
-        const decision = evaluateIncidentPolicy({
+        const filteredEvent = deepFreeze(safeEvent);
+        if (normalized.filter !== undefined) {
+            try {
+                const accepted = normalized.filter(filteredEvent);
+                if (typeof accepted !== "boolean") {
+                    diagnostics.filterFailures += 1;
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+                if (!accepted) {
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+            }
+            catch {
+                diagnostics.filterFailures += 1;
+                diagnostics.eventsSuppressed += 1;
+                return;
+            }
+        }
+        const rule = matchingRule(filteredEvent);
+        if (rule?.ignore === true) {
+            diagnostics.eventsSuppressed += 1;
+            return;
+        }
+        let fingerprint;
+        try {
+            fingerprint = normalizeFingerprintOverride(fingerprintOverride, filteredEvent);
+        }
+        catch {
+            diagnostics.fingerprintCallbackFailures += 1;
+        }
+        if (fingerprint === undefined && normalized.fingerprint !== undefined) {
+            try {
+                fingerprint = normalizeFingerprintOverride(normalized.fingerprint, filteredEvent);
+            }
+            catch {
+                diagnostics.fingerprintCallbackFailures += 1;
+            }
+        }
+        fingerprint ??= fingerprintSafeErrorEvent(filteredEvent);
+        const group = groupStore.record(fingerprint, filteredEvent, rule?.severity ?? severityOverride ?? "medium");
+        const policyInput = {
             group,
             now: timestamp,
-            alertThreshold,
+            alertThreshold: rule?.alertThreshold ?? alertThreshold,
             cooldownMs: normalized.grouping.cooldownMs,
             eventKind,
-        });
+        };
+        const manualSeverity = rule?.severity ?? severityOverride;
+        const decision = manualSeverity === undefined
+            ? evaluateIncidentPolicy(policyInput)
+            : evaluateIncidentPolicy({ ...policyInput, manualSeverity });
         if (decision.shouldAlert) {
-            const alert = buildIncidentAlert(group, decision);
-            if (queue.enqueue(alert, normalized.notifiers)) {
+            const builtAlert = buildIncidentAlert(group, decision);
+            const links = renderLinks(normalized.links, filteredEvent, fingerprint);
+            const alert = deepFreeze({
+                ...builtAlert,
+                ...(links === undefined ? {} : { links }),
+            });
+            let finalAlert = alert;
+            if (normalized.beforeSend !== undefined) {
+                let transformed;
+                try {
+                    transformed = normalized.beforeSend(alert);
+                }
+                catch {
+                    diagnostics.beforeSendFailures += 1;
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+                if (transformed === null) {
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+                if (transformed !== undefined) {
+                    const sanitized = safeAlertFromValue(transformed, alert, privacy);
+                    if (sanitized === undefined) {
+                        diagnostics.beforeSendFailures += 1;
+                        diagnostics.eventsSuppressed += 1;
+                        return;
+                    }
+                    finalAlert = sanitized;
+                }
+            }
+            if (queue.enqueue(finalAlert, normalized.notifiers)) {
                 groupStore.markAlerted(fingerprint, timestamp);
             }
         }
         diagnostics.capturedEvents += 1;
     };
-    const captureException = (error, context) => {
+    const emitOverloadSignal = (timestamp) => {
+        const cooldownMs = normalized.overload?.alertCooldownMs ?? 0;
+        if (cooldownMs > 0 && timestamp - overloadLastAlertAt < cooldownMs) {
+            return;
+        }
+        overloadLastAlertAt = timestamp;
+        captureSafeEvent(new Error("Wotchi capture overload: admission limit reached"), undefined, { droppedEvents: diagnostics.eventsDroppedOverload }, undefined, "runtime-monitor", 1, "wotchi.capture.overload", "high", undefined, undefined, "wotchi.overload", undefined, undefined);
+    };
+    const captureException = (error, context, options) => {
         if (!normalized.enabled) {
             return;
         }
+        if (queue.isClosed()) {
+            diagnostics.capturesAfterShutdown += 1;
+            return;
+        }
         try {
-            captureSafeEvent(error, undefined, context, undefined);
+            if (admission !== undefined && !admission.tryAcquire()) {
+                diagnostics.eventsDroppedOverload += 1;
+                emitOverloadSignal(now());
+                return;
+            }
+            captureSafeEvent(error, undefined, context, options?.request, "error", normalizeEventAlertThreshold(options?.alertThreshold) ?? normalized.grouping.alertThreshold, options?.fingerprint, options?.severity, options?.trace, options?.correlationId, options?.operation, options?.job, options?.tags);
         }
         catch {
             diagnostics.captureFailures += 1;
@@ -130,6 +445,10 @@ export function createWotchi(config) {
         if (!normalized.enabled) {
             return;
         }
+        if (queue.isClosed()) {
+            diagnostics.capturesAfterShutdown += 1;
+            return;
+        }
         try {
             if (event === null || typeof event !== "object" || event.level !== "error") {
                 throw new TypeError("event.level must be error");
@@ -138,24 +457,100 @@ export function createWotchi(config) {
                 throw new TypeError("event.message must be a string");
             }
             const alertThreshold = normalizeEventAlertThreshold(event.alertThreshold);
-            captureSafeEvent(event.error ?? safeMessage(event.message, privacy), event.metadata, event.context, event.request, event.kind ?? "error", alertThreshold ?? normalized.grouping.alertThreshold);
+            if (admission !== undefined &&
+                event.kind !== "process-monitor" &&
+                event.kind !== "runtime-monitor" &&
+                !admission.tryAcquire()) {
+                diagnostics.eventsDroppedOverload += 1;
+                emitOverloadSignal(now());
+                return;
+            }
+            captureSafeEvent(event.error ?? safeMessage(event.message, privacy), event.metadata, event.context, event.request, event.kind ?? "error", alertThreshold ?? normalized.grouping.alertThreshold, event.fingerprint, event.severity, event.trace, event.correlationId, event.operation, event.job, event.tags);
         }
         catch {
             diagnostics.captureFailures += 1;
         }
     };
+    const readDiagnostics = () => snapshotDiagnostics(diagnostics, {
+        groupsEvicted: groupStore.groupsEvicted(),
+        alertsQueued: queue.alertsQueued(),
+        alertsDropped: queue.alertsDropped(),
+        alertsSent: queue.alertsSent(),
+        notifierFailures: queue.notifierFailures(),
+        notifierTimeouts: queue.notifierTimeouts(),
+        notifierCircuitOpenSkips: queue.notifierCircuitOpenSkips(),
+        activeGroups: groupStore.size(),
+        pendingAlerts: queue.pending(),
+    });
+    const testAlert = async () => {
+        const timestamp = new Date(now()).toISOString();
+        const alert = {
+            id: `wotchi-test-${timestamp}`,
+            fingerprint: "wotchi-test-alert",
+            title: "Wotchi — Test alert",
+            severity: "low",
+            summary: "This is a notifier configuration test alert.",
+            suggestedActions: ["Confirm this destination received the test alert."],
+            firstSeenAt: timestamp,
+            lastSeenAt: timestamp,
+            occurrences: 1,
+            service: normalized.service,
+            environment: normalized.environment,
+            ...(normalized.instance === undefined ? {} : { instance: normalized.instance }),
+            ...(normalized.release === undefined ? {} : { release: normalized.release }),
+        };
+        let jobResult;
+        if (!queue.enqueue(alert, normalized.notifiers, (result) => {
+            jobResult = result;
+        })) {
+            return {
+                status: "queue-full",
+                configurationAccepted: true,
+                queued: false,
+                flushed: false,
+                delivered: false,
+                notifierFailures: 0,
+                diagnostics: readDiagnostics(),
+                error: "Notification queue is full; test alert was not queued.",
+            };
+        }
+        try {
+            await queue.flush();
+        }
+        catch {
+            return {
+                status: "timeout",
+                configurationAccepted: true,
+                queued: true,
+                flushed: false,
+                delivered: false,
+                notifierFailures: jobResult?.notifierFailures ?? 0,
+                diagnostics: readDiagnostics(),
+                error: "Notification queue flush timed out.",
+            };
+        }
+        const notifierFailures = jobResult?.notifierFailures ?? 0;
+        const status = notifierFailures > 0 ? "notifier-failed" : "sent";
+        return {
+            status,
+            configurationAccepted: true,
+            queued: true,
+            flushed: true,
+            delivered: status === "sent",
+            notifierFailures,
+            diagnostics: readDiagnostics(),
+            ...(status === "notifier-failed" ? { error: "One or more notifiers failed." } : {}),
+        };
+    };
+    const shutdown = async (timeoutMs) => {
+        await queue.close(timeoutMs);
+    };
     return {
         captureException,
         captureEvent,
+        testAlert,
         flush: (timeoutMs) => queue.flush(timeoutMs),
-        getDiagnostics: () => snapshotDiagnostics(diagnostics, {
-            groupsEvicted: groupStore.groupsEvicted(),
-            alertsQueued: queue.alertsQueued(),
-            alertsDropped: queue.alertsDropped(),
-            alertsSent: queue.alertsSent(),
-            notifierFailures: queue.notifierFailures(),
-            activeGroups: groupStore.size(),
-            pendingAlerts: queue.pending(),
-        }),
+        shutdown,
+        getDiagnostics: readDiagnostics,
     };
 }