@gkoos/caracal 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { admissionSignal, emitRuntimeEvent, nextAttempt, withAdmissionSignal, withSignal } from './chunk-5CXDW7W6.js';
-export { operation } from './chunk-5CXDW7W6.js';
+export { operation } from './chunk-JV2OLYOF.js';
+import { MAX_TIMER_MS, admissionSignal, emitRuntimeEvent, nextAttempt, withAdmissionSignal, withSignal } from './chunk-FD7IZJKY.js';
 import { randomUUID } from 'crypto';
 
 var BulkheadRejectedError = class extends Error {
@@ -34,7 +34,7 @@ function local(options) {
   const { name, limit } = options;
   const queue = options.queue && { ...options.queue };
   validate(name, limit);
-  if (queue && (!Number.isSafeInteger(queue.limit) || queue.limit < 1 || !Number.isSafeInteger(queue.timeoutMs) || queue.timeoutMs < 1 || queue.timeoutMs > 2147483647))
+  if (queue && (!Number.isSafeInteger(queue.limit) || queue.limit < 1 || !Number.isSafeInteger(queue.timeoutMs) || queue.timeoutMs < 1 || queue.timeoutMs > MAX_TIMER_MS))
     throw new RangeError("Invalid bounded queue");
   let occupancy = 0;
   const waiting = [];
@@ -97,8 +97,8 @@ function local(options) {
         return await next(context);
       } finally {
         occupancy--;
-        waiting[0]?.();
         event(context, "local", name, "process", "released", occupancy);
+        waiting[0]?.();
       }
     }
   });
@@ -212,13 +212,23 @@ function distributed(options) {
         }
       };
       try {
-        if (performance.now() >= deadline)
+        if (performance.now() >= deadline) {
+          event(
+            context,
+            "distributed",
+            name,
+            scope,
+            "rejected",
+            admitted.occupancy,
+            "admission-expired"
+          );
           throw new BulkheadRejectedError(
             "distributed",
             name,
             scope,
             "admission-expired"
           );
+        }
         admissionSignal(context)?.throwIfAborted();
         event(
           context,
@@ -320,6 +330,14 @@ var DEFAULT_OPEN_MS = 1e4;
 var DEFAULT_HALF_OPEN_SUCCESSES = 1;
 var DEFAULT_HALF_OPEN_PROBES = 1;
 var DEFAULT_WINDOW_SIZE = 100;
+var FAILURE_THRESHOLD_SCALE = 1e3;
+function assertResolvableThreshold(failureThreshold) {
+  const numerator = Math.round(failureThreshold * FAILURE_THRESHOLD_SCALE);
+  if (numerator < 1 || numerator >= FAILURE_THRESHOLD_SCALE)
+    throw new RangeError(
+      `failureThreshold must be at least 0.0005 and below 0.9995 (thresholds are resolved to thousandths); got ${failureThreshold}`
+    );
+}
 function validate2(opts) {
   if (!opts.name.trim())
     throw new RangeError("Circuit breaker name must not be empty");
@@ -329,6 +347,7 @@ function validate2(opts) {
   const { failureThreshold = DEFAULT_FAILURE_THRESHOLD } = opts;
   if (!Number.isFinite(failureThreshold) || failureThreshold <= 0 || failureThreshold >= 1)
     throw new RangeError("failureThreshold must be a number in (0, 1)");
+  assertResolvableThreshold(failureThreshold);
   const { openMs = DEFAULT_OPEN_MS } = opts;
   if (!Number.isInteger(openMs) || openMs < 1)
     throw new RangeError("openMs must be a positive integer");
@@ -571,6 +590,7 @@ function validateDistributed(opts) {
   const { failureThreshold = DEFAULT_DIST_FAILURE_THRESHOLD } = opts;
   if (!Number.isFinite(failureThreshold) || failureThreshold <= 0 || failureThreshold >= 1)
     throw new RangeError("failureThreshold must be a number in (0, 1)");
+  assertResolvableThreshold(failureThreshold);
   const { openMs = DEFAULT_DIST_OPEN_MS } = opts;
   if (!Number.isInteger(openMs) || openMs < 1)
     throw new RangeError("openMs must be a positive integer");
@@ -603,7 +623,9 @@ function distributed2(options) {
   const resolveScope = options.scope;
   const minimumThroughput = options.minimumThroughput ?? DEFAULT_DIST_MINIMUM_THROUGHPUT;
   const failureThreshold = options.failureThreshold ?? DEFAULT_DIST_FAILURE_THRESHOLD;
-  const failureThresholdNumerator = Math.round(failureThreshold * 1e3);
+  const failureThresholdNumerator = Math.round(
+    failureThreshold * FAILURE_THRESHOLD_SCALE
+  );
   const windowSize = options.windowSize ?? DEFAULT_DIST_WINDOW_SIZE;
   const openMs = options.openMs ?? DEFAULT_DIST_OPEN_MS;
   const windowTtlMs = options.windowTtlMs ?? Math.max(openMs * 3, 6e4);
@@ -767,8 +789,9 @@ function distributed2(options) {
           classifier,
           isSuccess ? { status: "success", value } : { status: "failure", error: thrownError }
         );
-        if (breakerOutcome !== "ignored") {
+        if (breakerOutcome !== "ignored" || admission.kind === "probe") {
           const outcomeStr = breakerOutcome === "success" ? "success" : "failure";
+          const settleOutcome = breakerOutcome === "ignored" ? "ignored" : outcomeStr;
           if (admission.kind === "closed") {
             try {
               const result = await coordinator.observe(identity, {
@@ -826,49 +849,51 @@ function distributed2(options) {
             try {
               const result = await coordinator.settleProbe(identity, {
                 probeToken: admission.probeToken,
-                outcome: outcomeStr,
+                outcome: settleOutcome,
                 generation: admission.generation,
                 halfOpenSuccesses,
                 openMs,
                 windowTtlMs
               });
-              if (result.type === "stale") {
-                emitRuntimeEvent(context, {
-                  type: "breaker.observation-stale",
-                  coordination: "distributed",
-                  policyName: name,
-                  scope,
-                  attemptGeneration: admission.generation,
-                  currentGeneration: result.generation
-                });
-              } else {
-                emitRuntimeEvent(context, {
-                  type: "breaker.observation",
-                  coordination: "distributed",
-                  policyName: name,
-                  scope,
-                  outcome: outcomeStr,
-                  generation: admission.generation
-                });
-                if (result.type === "transitioned") {
-                  if (result.newState === "closed") {
-                    lastKnownState.forget(identity.operation, scope);
-                  } else {
-                    lastKnownState.remember(
-                      identity.operation,
-                      scope,
-                      result.newState
-                    );
-                  }
+              if (breakerOutcome !== "ignored") {
+                if (result.type === "stale") {
                   emitRuntimeEvent(context, {
-                    type: "breaker.state-changed",
+                    type: "breaker.observation-stale",
                     coordination: "distributed",
                     policyName: name,
                     scope,
-                    state: result.newState,
-                    previousState: "half-open",
-                    generation: result.newGeneration
+                    attemptGeneration: admission.generation,
+                    currentGeneration: result.generation
+                  });
+                } else {
+                  emitRuntimeEvent(context, {
+                    type: "breaker.observation",
+                    coordination: "distributed",
+                    policyName: name,
+                    scope,
+                    outcome: outcomeStr,
+                    generation: admission.generation
                   });
+                  if (result.type === "transitioned") {
+                    if (result.newState === "closed") {
+                      lastKnownState.forget(identity.operation, scope);
+                    } else {
+                      lastKnownState.remember(
+                        identity.operation,
+                        scope,
+                        result.newState
+                      );
+                    }
+                    emitRuntimeEvent(context, {
+                      type: "breaker.state-changed",
+                      coordination: "distributed",
+                      policyName: name,
+                      scope,
+                      state: result.newState,
+                      previousState: "half-open",
+                      generation: result.newGeneration
+                    });
+                  }
                 }
               }
             } catch (settleError) {
@@ -911,6 +936,11 @@ function delayFor(options, context, attempt, outcome) {
   if (!Number.isFinite(delay) || delay < 0) {
     throw new RangeError("retry delay must be a finite non-negative number");
   }
+  if (delay > MAX_TIMER_MS) {
+    throw new RangeError(
+      `retry delay must not exceed ${MAX_TIMER_MS} ms, the largest delay setTimeout honours`
+    );
+  }
   return delay;
 }
 function wait(delayMs, signal) {
@@ -947,6 +977,11 @@ function retry(options) {
   if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1) {
     throw new RangeError("maxAttempts must be a positive integer");
   }
+  if (typeof options.delay === "number" && (!Number.isFinite(options.delay) || options.delay < 0 || options.delay > MAX_TIMER_MS)) {
+    throw new RangeError(
+      `retry delay must be a finite number within 0..${MAX_TIMER_MS} ms`
+    );
+  }
   return Object.freeze({
     name: "retry",
     async execute(initialContext, next) {
@@ -958,6 +993,12 @@ function retry(options) {
           const outcome = { status: "success", value };
           const outcomeClassification = classification(context, outcome);
           if (outcomeClassification !== "retryable" || context.capabilities.replay !== "safe") {
+            emitRuntimeEvent(context, {
+              type: "retry.declined",
+              outcome: summarized(outcome),
+              classification: outcomeClassification,
+              reason: context.capabilities.replay !== "safe" ? "replay-unsafe" : "not-retryable"
+            });
             return value;
           }
           if (context.attempt >= options.maxAttempts) {
@@ -981,7 +1022,16 @@ function retry(options) {
         } catch (error) {
           const outcome = { status: "failure", error };
           const outcomeClassification = classification(context, outcome);
-          if (admissionSignal(context)?.aborted || context.capabilities.replay !== "safe" || outcomeClassification !== "retryable") {
+          if (admissionSignal(context)?.aborted) {
+            throw error;
+          }
+          if (context.capabilities.replay !== "safe" || outcomeClassification !== "retryable") {
+            emitRuntimeEvent(context, {
+              type: "retry.declined",
+              outcome: summarized(outcome),
+              classification: outcomeClassification,
+              reason: context.capabilities.replay !== "safe" ? "replay-unsafe" : "not-retryable"
+            });
             throw error;
           }
           if (context.attempt >= options.maxAttempts) {
@@ -1027,6 +1077,11 @@ function timeout(options) {
   if (!Number.isFinite(options.ms) || options.ms <= 0) {
     throw new RangeError("timeout ms must be a finite positive number");
   }
+  if (options.ms > MAX_TIMER_MS) {
+    throw new RangeError(
+      `timeout ms must not exceed ${MAX_TIMER_MS} ms, the largest delay setTimeout honours`
+    );
+  }
   return Object.freeze({
     name: "timeout",
     async execute(context, next) {