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

package/dist/esm/core/config.js

@@ -1,16 +1,33 @@
 import { WotchiConfigurationError } from "./errors.js";
+import { MAX_ALERT_THRESHOLD, MAX_CAPTURE_RATE, MAX_CIRCUIT_BREAKER_COOLDOWN_MS, MAX_CIRCUIT_BREAKER_FAILURES, MAX_COOLDOWN_MS, MAX_EVENTS_PER_WINDOW, MAX_GROUPS, MAX_NORMALIZATION_DEPTH, MAX_NORMALIZATION_KEYS, MAX_NORMALIZATION_STACK_LENGTH, MAX_NORMALIZATION_STRING_LENGTH, MAX_PENDING_ALERTS, MAX_NOTIFIER_TIMEOUT_MS, MAX_WINDOW_MS, } from "./limits.js";
 export { WotchiConfigurationError };
 const MAX_REDACT_KEYS = 100;
+const MAX_RULES = 50;
+const MAX_RULE_STRING_LENGTH = 200;
+const MAX_LINK_TEMPLATE_LENGTH = 1_000;
+const ALLOWED_LINK_PLACEHOLDERS = new Set([
+    "service",
+    "environment",
+    "release",
+    "instance",
+    "fingerprint",
+    "requestId",
+    "correlationId",
+    "traceId",
+    "spanId",
+    "route",
+    "statusCode",
+]);
 const isRecord = (value) => typeof value === "object" && value !== null;
 const fail = (field) => {
     throw new WotchiConfigurationError(`${field} is invalid`);
 };
-const readPositiveInteger = (parent, field, defaultValue) => {
+const readPositiveInteger = (parent, field, defaultValue, maximum) => {
     const value = parent?.[field];
     if (value === undefined) {
         return defaultValue;
     }
-    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > maximum) {
         return fail(field);
     }
     return value;
@@ -24,6 +41,120 @@ const readOptionalRecord = (value, field) => {
     }
     return value;
 };
+const normalizeRuleString = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return fail(field);
+    }
+    return value.trim().slice(0, MAX_RULE_STRING_LENGTH);
+};
+const normalizeSeverity = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value !== "low" && value !== "medium" && value !== "high" && value !== "critical") {
+        return fail(field);
+    }
+    return value;
+};
+const freezeHook = (hook) => {
+    try {
+        return Object.freeze(hook);
+    }
+    catch {
+        return hook;
+    }
+};
+const normalizeLinks = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return fail("links");
+    }
+    const normalized = {};
+    for (const key of ["log", "trace"]) {
+        const raw = value[key];
+        if (raw === undefined) {
+            continue;
+        }
+        if (typeof raw !== "string" || raw.length === 0 || raw.length > MAX_LINK_TEMPLATE_LENGTH) {
+            return fail(`links.${key}`);
+        }
+        let parsed;
+        try {
+            parsed = new URL(raw.replace(/\{\{[^{}]+\}\}/g, "placeholder"));
+        }
+        catch {
+            return fail(`links.${key}`);
+        }
+        if (parsed.protocol !== "https:" ||
+            parsed.username !== "" ||
+            parsed.password !== "" ||
+            parsed.hash !== "") {
+            return fail(`links.${key}`);
+        }
+        const placeholders = raw.match(/\{\{([^{}]+)\}\}/g) ?? [];
+        if (/[{}]/.test(raw.replace(/\{\{[^{}]+\}\}/g, ""))) {
+            return fail(`links.${key}`);
+        }
+        for (const placeholder of placeholders) {
+            const name = placeholder.slice(2, -2);
+            if (!ALLOWED_LINK_PLACEHOLDERS.has(name)) {
+                return fail(`links.${key}`);
+            }
+        }
+        normalized[key] = raw;
+    }
+    return Object.freeze(normalized);
+};
+const normalizeRules = (value) => {
+    if (value === undefined) {
+        return Object.freeze([]);
+    }
+    if (!Array.isArray(value) || value.length > MAX_RULES) {
+        return fail("rules");
+    }
+    const rules = value.map((rawRule, index) => {
+        if (!isRecord(rawRule)) {
+            return fail(`rules[${index}]`);
+        }
+        const alertThreshold = rawRule.alertThreshold;
+        if (alertThreshold !== undefined &&
+            (typeof alertThreshold !== "number" ||
+                !Number.isSafeInteger(alertThreshold) ||
+                alertThreshold <= 0 ||
+                alertThreshold > 1_000_000)) {
+            return fail(`rules[${index}].alertThreshold`);
+        }
+        if (rawRule.ignore !== undefined && typeof rawRule.ignore !== "boolean") {
+            return fail(`rules[${index}].ignore`);
+        }
+        const environment = normalizeRuleString(rawRule.environment, `rules[${index}].environment`);
+        const route = normalizeRuleString(rawRule.route, `rules[${index}].route`);
+        const severity = normalizeSeverity(rawRule.severity, `rules[${index}].severity`);
+        const rule = {};
+        if (environment !== undefined) {
+            rule.environment = environment;
+        }
+        if (route !== undefined) {
+            rule.route = route;
+        }
+        if (rawRule.ignore !== undefined) {
+            rule.ignore = rawRule.ignore;
+        }
+        if (alertThreshold !== undefined) {
+            rule.alertThreshold = alertThreshold;
+        }
+        if (severity !== undefined) {
+            rule.severity = severity;
+        }
+        return Object.freeze(rule);
+    });
+    return Object.freeze(rules);
+};
 const normalizeRedactKeys = (privacy) => {
     const value = privacy?.redactKeys;
     if (value === undefined) {
@@ -46,11 +177,19 @@ const normalizeNotifiers = (value) => {
     }
     for (let index = 0; index < value.length; index += 1) {
         const notifier = value[index];
-        if (!isRecord(notifier) ||
-            typeof notifier.name !== "string" ||
-            notifier.name.trim().length === 0 ||
-            typeof notifier.send !== "function") {
-            return fail(`notifiers[${index}]`);
+        const valid = (() => {
+            try {
+                return (isRecord(notifier) &&
+                    typeof notifier.name === "string" &&
+                    notifier.name.trim().length > 0 &&
+                    typeof notifier.send === "function");
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (!valid) {
+            return fail("notifiers[" + index + "]");
         }
     }
     return Object.freeze([...value]);
@@ -71,12 +210,28 @@ export function validateConfig(config) {
         (typeof config.release !== "string" || config.release.trim().length === 0)) {
         return fail("release");
     }
+    if (config.instance !== undefined &&
+        (typeof config.instance !== "string" || config.instance.trim().length === 0)) {
+        return fail("instance");
+    }
     if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
         return fail("enabled");
     }
+    if (config.filter !== undefined && typeof config.filter !== "function") {
+        return fail("filter");
+    }
+    if (config.fingerprint !== undefined && typeof config.fingerprint !== "function") {
+        return fail("fingerprint");
+    }
+    if (config.beforeSend !== undefined && typeof config.beforeSend !== "function") {
+        return fail("beforeSend");
+    }
     const grouping = readOptionalRecord(config.grouping, "grouping");
     const queue = readOptionalRecord(config.queue, "queue");
+    const notifierCircuitBreaker = readOptionalRecord(queue?.notifierCircuitBreaker, "queue.notifierCircuitBreaker");
     const privacy = readOptionalRecord(config.privacy, "privacy");
+    const overload = readOptionalRecord(config.overload, "overload");
+    const links = normalizeLinks(config.links);
     const concurrency = queue?.concurrency;
     if (concurrency !== undefined && concurrency !== 1) {
         return fail("queue.concurrency");
@@ -84,25 +239,45 @@ export function validateConfig(config) {
     const normalized = {
         service: service.trim(),
         environment: environment.trim(),
-        ...(config.release === undefined ? {} : { release: config.release.trim() }),
+        ...(config.instance === undefined ? {} : { instance: config.instance.trim().slice(0, 200) }),
+        ...(config.release === undefined ? {} : { release: config.release.trim().slice(0, 200) }),
         enabled: config.enabled ?? true,
+        ...(config.filter === undefined ? {} : { filter: freezeHook(config.filter) }),
+        ...(config.fingerprint === undefined ? {} : { fingerprint: freezeHook(config.fingerprint) }),
+        ...(config.beforeSend === undefined ? {} : { beforeSend: freezeHook(config.beforeSend) }),
+        ...(links === undefined ? {} : { links }),
+        rules: normalizeRules(config.rules),
         grouping: Object.freeze({
-            windowMs: readPositiveInteger(grouping, "windowMs", 60_000),
-            alertThreshold: readPositiveInteger(grouping, "alertThreshold", 3),
-            cooldownMs: readPositiveInteger(grouping, "cooldownMs", 900_000),
-            maxGroups: readPositiveInteger(grouping, "maxGroups", 200),
-            maxEventsPerWindow: readPositiveInteger(grouping, "maxEventsPerWindow", 100),
+            windowMs: readPositiveInteger(grouping, "windowMs", 60_000, MAX_WINDOW_MS),
+            alertThreshold: readPositiveInteger(grouping, "alertThreshold", 3, MAX_ALERT_THRESHOLD),
+            cooldownMs: readPositiveInteger(grouping, "cooldownMs", 900_000, MAX_COOLDOWN_MS),
+            maxGroups: readPositiveInteger(grouping, "maxGroups", 200, MAX_GROUPS),
+            maxEventsPerWindow: readPositiveInteger(grouping, "maxEventsPerWindow", 100, MAX_EVENTS_PER_WINDOW),
         }),
         queue: Object.freeze({
-            maxPendingAlerts: readPositiveInteger(queue, "maxPendingAlerts", 100),
+            maxPendingAlerts: readPositiveInteger(queue, "maxPendingAlerts", 100, MAX_PENDING_ALERTS),
             concurrency: 1,
+            notifierTimeoutMs: readPositiveInteger(queue, "notifierTimeoutMs", 5_000, MAX_NOTIFIER_TIMEOUT_MS),
+            notifierCircuitBreaker: Object.freeze({
+                failureThreshold: readPositiveInteger(notifierCircuitBreaker, "failureThreshold", 3, MAX_CIRCUIT_BREAKER_FAILURES),
+                cooldownMs: readPositiveInteger(notifierCircuitBreaker, "cooldownMs", 30_000, MAX_CIRCUIT_BREAKER_COOLDOWN_MS),
+            }),
         }),
+        ...(overload === undefined
+            ? {}
+            : {
+                overload: Object.freeze({
+                    maxEventsPerSecond: readPositiveInteger(overload, "maxEventsPerSecond", 1_000, MAX_CAPTURE_RATE),
+                    burst: readPositiveInteger(overload, "burst", readPositiveInteger(overload, "maxEventsPerSecond", 1_000, MAX_CAPTURE_RATE), MAX_CAPTURE_RATE),
+                    alertCooldownMs: readPositiveInteger(overload, "alertCooldownMs", 60_000, MAX_COOLDOWN_MS),
+                }),
+            }),
         privacy: Object.freeze({
             redactKeys: normalizeRedactKeys(privacy),
-            maxDepth: readPositiveInteger(privacy, "maxDepth", 5),
-            maxKeys: readPositiveInteger(privacy, "maxKeys", 100),
-            maxStringLength: readPositiveInteger(privacy, "maxStringLength", 500),
-            maxStackLength: readPositiveInteger(privacy, "maxStackLength", 4_000),
+            maxDepth: readPositiveInteger(privacy, "maxDepth", 5, MAX_NORMALIZATION_DEPTH),
+            maxKeys: readPositiveInteger(privacy, "maxKeys", 100, MAX_NORMALIZATION_KEYS),
+            maxStringLength: readPositiveInteger(privacy, "maxStringLength", 500, MAX_NORMALIZATION_STRING_LENGTH),
+            maxStackLength: readPositiveInteger(privacy, "maxStackLength", 4_000, MAX_NORMALIZATION_STACK_LENGTH),
         }),
         notifiers: normalizeNotifiers(config.notifiers),
     };

package/dist/esm/core/diagnostics.js

@@ -1,10 +1,25 @@
 export function createDiagnosticsState() {
-    return { capturedEvents: 0, captureFailures: 0 };
+    return {
+        capturedEvents: 0,
+        captureFailures: 0,
+        fingerprintCallbackFailures: 0,
+        filterFailures: 0,
+        beforeSendFailures: 0,
+        eventsSuppressed: 0,
+        eventsDroppedOverload: 0,
+        capturesAfterShutdown: 0,
+    };
 }
 export function snapshotDiagnostics(state, values) {
     return Object.freeze({
         capturedEvents: state.capturedEvents,
         captureFailures: state.captureFailures,
+        fingerprintCallbackFailures: state.fingerprintCallbackFailures,
+        filterFailures: state.filterFailures,
+        beforeSendFailures: state.beforeSendFailures,
+        eventsSuppressed: state.eventsSuppressed,
+        eventsDroppedOverload: state.eventsDroppedOverload,
+        capturesAfterShutdown: state.capturesAfterShutdown,
         ...values,
     });
 }

package/dist/esm/core/group-store.js

@@ -1,4 +1,5 @@
 import { normalizeUnknown } from "./normalize.js";
+import { MAX_EVENTS_PER_WINDOW, MAX_GROUPS } from "./limits.js";
 import { createRollingWindow } from "./rolling-window.js";
 const cloneSafeEvent = (event) => {
     const context = event.context === undefined ? undefined : normalizeUnknown(event.context);
@@ -7,16 +8,29 @@ const cloneSafeEvent = (event) => {
         timestamp: event.timestamp,
         service: event.service,
         environment: event.environment,
+        ...(event.instance === undefined ? {} : { instance: event.instance }),
         ...(event.release === undefined ? {} : { release: event.release }),
+        ...(event.correlationId === undefined ? {} : { correlationId: event.correlationId }),
+        ...(event.operation === undefined ? {} : { operation: event.operation }),
+        ...(event.job === undefined ? {} : { job: event.job }),
+        ...(event.tags === undefined ? {} : { tags: { ...event.tags } }),
         error: { ...event.error },
         ...(event.request === undefined ? {} : { request: { ...event.request } }),
+        ...(event.trace === undefined ? {} : { trace: { ...event.trace } }),
         ...(context === undefined ? {} : { context: context }),
     };
 };
 export function createGroupStore(options) {
-    if (!Number.isSafeInteger(options.maxGroups) || options.maxGroups <= 0) {
+    if (!Number.isSafeInteger(options.maxGroups) ||
+        options.maxGroups <= 0 ||
+        options.maxGroups > MAX_GROUPS) {
         throw new RangeError("maxGroups must be a positive integer");
     }
+    if (!Number.isSafeInteger(options.maxEventsPerWindow) ||
+        options.maxEventsPerWindow <= 0 ||
+        options.maxEventsPerWindow > MAX_EVENTS_PER_WINDOW) {
+        throw new RangeError("maxEventsPerWindow must be a positive integer");
+    }
     const now = options.now ?? Date.now;
     const groups = new Map();
     let evicted = 0;
@@ -33,14 +47,9 @@ export function createGroupStore(options) {
         severity: group.severity,
     });
     const evictLeastRecent = () => {
-        let candidate;
-        for (const group of groups.values()) {
-            if (candidate === undefined || group.lastSeenMs < candidate.lastSeenMs) {
-                candidate = group;
-            }
-        }
-        if (candidate !== undefined) {
-            groups.delete(candidate.fingerprint);
+        const oldestFingerprint = groups.keys().next().value;
+        if (typeof oldestFingerprint === "string") {
+            groups.delete(oldestFingerprint);
             evicted += 1;
         }
     };
@@ -66,6 +75,10 @@ export function createGroupStore(options) {
             };
             groups.set(fingerprint, group);
         }
+        else {
+            groups.delete(fingerprint);
+            groups.set(fingerprint, group);
+        }
         group.lastSeenMs = timestamp;
         group.totalCount += 1;
         group.severity = severity;

package/dist/esm/core/incident-builder.js

@@ -1,3 +1,4 @@
+import { selectApplicationFrame } from "./stack-frame.js";
 const titleCase = (value) => `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
 const suggestedActions = (group) => {
     const text = `${group.sample.error.name} ${group.sample.error.message}`.toLowerCase();
@@ -27,6 +28,11 @@ const suggestedActions = (group) => {
 export function buildIncidentAlert(group, decision) {
     const message = group.sample.error.message;
     const errorName = group.sample.error.name;
+    const applicationFrame = selectApplicationFrame(group.sample.error.stack);
+    const error = {
+        ...group.sample.error,
+        ...(applicationFrame === undefined ? {} : { applicationFrame }),
+    };
     return {
         id: `wotchi-${group.fingerprint}-${group.lastSeenAt}`,
         fingerprint: group.fingerprint,
@@ -39,5 +45,17 @@ export function buildIncidentAlert(group, decision) {
         occurrences: group.windowCount,
         service: group.sample.service,
         environment: group.sample.environment,
+        ...(group.sample.instance === undefined ? {} : { instance: group.sample.instance }),
+        ...(group.sample.release === undefined ? {} : { release: group.sample.release }),
+        ...(group.sample.correlationId === undefined
+            ? {}
+            : { correlationId: group.sample.correlationId }),
+        ...(group.sample.operation === undefined ? {} : { operation: group.sample.operation }),
+        ...(group.sample.job === undefined ? {} : { job: group.sample.job }),
+        ...(group.sample.tags === undefined ? {} : { tags: group.sample.tags }),
+        error,
+        ...(group.sample.request === undefined ? {} : { request: group.sample.request }),
+        ...(group.sample.trace === undefined ? {} : { trace: group.sample.trace }),
+        ...(group.sample.context === undefined ? {} : { context: group.sample.context }),
     };
 }

package/dist/esm/core/incident-policy.js

@@ -10,13 +10,8 @@ export function evaluateIncidentPolicy(input) {
     const eventKind = input.eventKind ?? "error";
     const isCritical = eventKind === "process-monitor";
     const isHigh = input.group.windowCount >= 20 || hasUnavailableResponse(input.group);
-    const severity = isCritical
-        ? "critical"
-        : isHigh
-            ? "high"
-            : eventKind === "manual"
-                ? (input.manualSeverity ?? "low")
-                : "medium";
+    const severity = input.manualSeverity ??
+        (isCritical ? "critical" : isHigh ? "high" : eventKind === "manual" ? "low" : "medium");
     const eligible = isCritical ||
         isHigh ||
         eventKind === "manual" ||

package/dist/esm/core/limits.js

@@ -0,0 +1,14 @@
+export const MAX_GROUPS = 10_000;
+export const MAX_EVENTS_PER_WINDOW = 10_000;
+export const MAX_PENDING_ALERTS = 10_000;
+export const MAX_WINDOW_MS = 7 * 24 * 60 * 60 * 1_000;
+export const MAX_ALERT_THRESHOLD = 1_000_000;
+export const MAX_COOLDOWN_MS = 30 * 24 * 60 * 60 * 1_000;
+export const MAX_CAPTURE_RATE = 1_000_000;
+export const MAX_NOTIFIER_TIMEOUT_MS = 60_000;
+export const MAX_CIRCUIT_BREAKER_COOLDOWN_MS = 24 * 60 * 60 * 1_000;
+export const MAX_CIRCUIT_BREAKER_FAILURES = 100;
+export const MAX_NORMALIZATION_DEPTH = 20;
+export const MAX_NORMALIZATION_KEYS = 10_000;
+export const MAX_NORMALIZATION_STRING_LENGTH = 32_768;
+export const MAX_NORMALIZATION_STACK_LENGTH = 32_768;

package/dist/esm/core/normalize.js

@@ -2,18 +2,19 @@ const UNREADABLE_VALUE = "[unreadable value]";
 const MAX_DEPTH_VALUE = "[MaxDepth]";
 const CIRCULAR_VALUE = "[Circular]";
 const MAX_KEYS_VALUE = "[MaxKeys]";
+const UNSAFE_OBJECT_KEYS = new Set(["__proto__", "prototype", "constructor"]);
 const defaultLimits = {
     maxDepth: 5,
     maxKeys: 100,
     maxStringLength: 500,
     maxStackLength: 4_000,
 };
-const boundedLimit = (value, fallback) => Number.isSafeInteger(value) && value > 0 ? value : fallback;
+const boundedLimit = (value, fallback, maximum) => Number.isSafeInteger(value) && value > 0 && value <= maximum ? value : fallback;
 const normalizeLimits = (limits) => ({
-    maxDepth: boundedLimit(limits?.maxDepth ?? defaultLimits.maxDepth, defaultLimits.maxDepth),
-    maxKeys: boundedLimit(limits?.maxKeys ?? defaultLimits.maxKeys, defaultLimits.maxKeys),
-    maxStringLength: boundedLimit(limits?.maxStringLength ?? defaultLimits.maxStringLength, defaultLimits.maxStringLength),
-    maxStackLength: boundedLimit(limits?.maxStackLength ?? defaultLimits.maxStackLength, defaultLimits.maxStackLength),
+    maxDepth: boundedLimit(limits?.maxDepth ?? defaultLimits.maxDepth, defaultLimits.maxDepth, MAX_NORMALIZATION_DEPTH),
+    maxKeys: boundedLimit(limits?.maxKeys ?? defaultLimits.maxKeys, defaultLimits.maxKeys, MAX_NORMALIZATION_KEYS),
+    maxStringLength: boundedLimit(limits?.maxStringLength ?? defaultLimits.maxStringLength, defaultLimits.maxStringLength, MAX_NORMALIZATION_STRING_LENGTH),
+    maxStackLength: boundedLimit(limits?.maxStackLength ?? defaultLimits.maxStackLength, defaultLimits.maxStackLength, MAX_NORMALIZATION_STACK_LENGTH),
 });
 const truncate = (value, limit) => value.slice(0, limit);
 const readProperty = (value, key) => {
@@ -85,12 +86,20 @@ const normalizeValue = (value, depth, state, limits) => {
     }
     const result = {};
     for (const key of keys) {
+        if (UNSAFE_OBJECT_KEYS.has(key)) {
+            continue;
+        }
         if (state.keysVisited >= limits.maxKeys - 1) {
             result["[truncated]"] = MAX_KEYS_VALUE;
             break;
         }
         state.keysVisited += 1;
-        result[truncate(key, limits.maxStringLength)] = normalizeValue(readProperty(value, key), depth + 1, state, limits);
+        const child = readProperty(value, key);
+        const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+        result[truncate(key, limits.maxStringLength)] =
+            normalizedKey === "stack" && typeof child === "string"
+                ? truncate(child, limits.maxStackLength)
+                : normalizeValue(child, depth + 1, state, limits);
     }
     return result;
 };
@@ -132,3 +141,4 @@ export function normalizeError(error, limits) {
     const message = typeof normalized === "string" ? normalized : UNREADABLE_VALUE;
     return { name: "UnknownError", message };
 }
+import { MAX_NORMALIZATION_DEPTH, MAX_NORMALIZATION_KEYS, MAX_NORMALIZATION_STACK_LENGTH, MAX_NORMALIZATION_STRING_LENGTH, } from "./limits.js";

package/dist/esm/core/notification-queue.js

@@ -1,11 +1,34 @@
+import { MAX_CIRCUIT_BREAKER_COOLDOWN_MS, MAX_CIRCUIT_BREAKER_FAILURES, MAX_NOTIFIER_TIMEOUT_MS, MAX_PENDING_ALERTS, } from "./limits.js";
 const DEFAULT_FLUSH_TIMEOUT_MS = 5_000;
+const DEFAULT_NOTIFIER_TIMEOUT_MS = 5_000;
+const DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 3;
+const DEFAULT_CIRCUIT_COOLDOWN_MS = 30_000;
 export function createNotificationQueue(options) {
-    if (!Number.isSafeInteger(options.maxPendingAlerts) || options.maxPendingAlerts <= 0) {
+    if (!Number.isSafeInteger(options.maxPendingAlerts) ||
+        options.maxPendingAlerts <= 0 ||
+        options.maxPendingAlerts > MAX_PENDING_ALERTS) {
         throw new RangeError("maxPendingAlerts must be a positive integer");
     }
     if (options.concurrency !== 1) {
         throw new RangeError("concurrency must be 1");
     }
+    if (options.notifierTimeoutMs !== undefined &&
+        (!Number.isSafeInteger(options.notifierTimeoutMs) ||
+            options.notifierTimeoutMs <= 0 ||
+            options.notifierTimeoutMs > MAX_NOTIFIER_TIMEOUT_MS)) {
+        throw new RangeError("notifierTimeoutMs must be a positive integer");
+    }
+    if (options.notifierCircuitBreaker !== undefined) {
+        const { failureThreshold, cooldownMs } = options.notifierCircuitBreaker;
+        if (!Number.isSafeInteger(failureThreshold) ||
+            failureThreshold <= 0 ||
+            failureThreshold > MAX_CIRCUIT_BREAKER_FAILURES ||
+            !Number.isSafeInteger(cooldownMs) ||
+            cooldownMs <= 0 ||
+            cooldownMs > MAX_CIRCUIT_BREAKER_COOLDOWN_MS) {
+            throw new RangeError("notifierCircuitBreaker limits are invalid");
+        }
+    }
     const pendingJobs = [];
     let drainPromise;
     let resolveDrain;
@@ -14,6 +37,15 @@ export function createNotificationQueue(options) {
     let dropped = 0;
     let sent = 0;
     let failures = 0;
+    let timeouts = 0;
+    let circuitOpenSkips = 0;
+    let closed = false;
+    const notifierStates = new Map();
+    const notifierTimeoutMs = options.notifierTimeoutMs ?? DEFAULT_NOTIFIER_TIMEOUT_MS;
+    const circuit = options.notifierCircuitBreaker ?? {
+        failureThreshold: DEFAULT_CIRCUIT_FAILURE_THRESHOLD,
+        cooldownMs: DEFAULT_CIRCUIT_COOLDOWN_MS,
+    };
     const notifyFailure = (error, notifier) => {
         failures += 1;
         try {
@@ -32,14 +64,56 @@ export function createNotificationQueue(options) {
         resolveDrain = undefined;
     };
     const processJob = async (job) => {
-        for (const notifier of job.notifiers) {
+        const results = await Promise.all(job.notifiers.map(async (notifier) => {
+            const state = notifierStates.get(notifier) ?? { failures: 0, openUntil: 0 };
+            const timestamp = Date.now();
+            if (state.openUntil > timestamp) {
+                circuitOpenSkips += 1;
+                notifyFailure(new Error(`Notifier circuit is open: ${notifier.name}`), notifier);
+                return { sent: 0, failed: 1 };
+            }
+            if (state.openUntil !== 0) {
+                state.openUntil = 0;
+                state.failures = 0;
+            }
+            let timer;
             try {
-                await notifier.send(job.alert);
+                const timeout = new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        timeouts += 1;
+                        reject(new Error(`Notifier timed out after ${notifierTimeoutMs}ms: ${notifier.name}`));
+                    }, notifierTimeoutMs);
+                    timer.unref?.();
+                });
+                await Promise.race([notifier.send(job.alert), timeout]);
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                state.failures = 0;
+                notifierStates.set(notifier, state);
                 sent += 1;
+                return { sent: 1, failed: 0 };
             }
             catch (error) {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                state.failures += 1;
+                if (state.failures >= circuit.failureThreshold) {
+                    state.openUntil = Date.now() + circuit.cooldownMs;
+                }
+                notifierStates.set(notifier, state);
                 notifyFailure(error, notifier);
+                return { sent: 0, failed: 1 };
             }
+        }));
+        const jobSent = results.reduce((total, result) => total + result.sent, 0);
+        const jobFailures = results.reduce((total, result) => total + result.failed, 0);
+        try {
+            job.onComplete?.({ notifierFailures: jobFailures, sent: jobSent });
+        }
+        catch {
+            // Job observers cannot be allowed to affect notification processing.
         }
     };
     const pump = () => {
@@ -56,16 +130,24 @@ export function createNotificationQueue(options) {
             });
         }
     };
-    const enqueue = (alert, notifiers) => {
-        if (pendingJobs.length >= options.maxPendingAlerts) {
+    const enqueue = (alert, notifiers, onComplete) => {
+        if (closed || pendingJobs.length >= options.maxPendingAlerts) {
             dropped += 1;
             return false;
         }
-        pendingJobs.push({ alert, notifiers: [...notifiers] });
+        pendingJobs.push({
+            alert,
+            notifiers: [...notifiers],
+            ...(onComplete === undefined ? {} : { onComplete }),
+        });
         queued += 1;
         pump();
         return true;
     };
+    const close = (timeoutMs = DEFAULT_FLUSH_TIMEOUT_MS) => {
+        closed = true;
+        return flush(timeoutMs);
+    };
     const flush = (timeoutMs = DEFAULT_FLUSH_TIMEOUT_MS) => {
         if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
             return Promise.reject(new RangeError("timeoutMs must be a positive integer"));
@@ -91,10 +173,14 @@ export function createNotificationQueue(options) {
     return {
         enqueue,
         flush,
+        close,
+        isClosed: () => closed,
         pending: () => pendingJobs.length,
         alertsQueued: () => queued,
         alertsDropped: () => dropped,
         alertsSent: () => sent,
         notifierFailures: () => failures,
+        notifierTimeouts: () => timeouts,
+        notifierCircuitOpenSkips: () => circuitOpenSkips,
     };
 }