@cqrs-ddd/pipeline-resilience 0.5.0

package/dist/resilience.behavior.js

@@ -0,0 +1,159 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { PIPELINE_BEHAVIOR_CONTRACT, } from '@cqrs-ddd/pipeline';
+import { ResilienceConfigurationError } from './errors/resilience-configuration.error.js';
+import { buildResiliencePolicy, } from './helpers/policy-factory.js';
+import { runWithResilienceAbortSignal, runWithResilienceRequest, } from './helpers/resilience-context.js';
+function getResilienceSafetyIssues(options, requestKind) {
+    if (!options || options.policy)
+        return [];
+    const issues = [];
+    const dependencyLayers = options;
+    if (dependencyLayers.circuitBreaker !== undefined ||
+        dependencyLayers.fallback !== undefined) {
+        issues.push({
+            message: 'circuitBreaker and fallback are not applied around a whole handler; they belong to a named policy of an outbound dependency',
+            fix: 'Declare them as a named policy, new ResiliencePolicies({ <name>: { ... } }), and run the outbound call through it.',
+        });
+    }
+    const classifiesErrors = typeof options.handle === 'function' || options.handleAllErrors === true;
+    if (options.retry && !classifiesErrors) {
+        issues.push({
+            message: 'retry requires handle(error) or explicit handleAllErrors: true',
+            fix: 'Specify handle: (err) => boolean or handleAllErrors: true in ResilienceBehavior options.',
+        });
+    }
+    if (options.retry &&
+        requestKind !== 'query' &&
+        options.retry.replaySafe !== true) {
+        issues.push({
+            message: `retry on non-query handler (${requestKind}) replays downstream work; commands/events must set retry.replaySafe: true`,
+            fix: 'Set retry: { ...retry, replaySafe: true } after verifying handler side effects are idempotent or transactional.',
+        });
+    }
+    if (options.timeout &&
+        requestKind !== 'query' &&
+        options.timeout.strategy !== 'cooperative' &&
+        options.timeout.replaySafe !== true) {
+        issues.push({
+            message: `aggressive timeout on non-query handler (${requestKind}) answers the caller while the handler keeps running, so a retry can overlap its side effects`,
+            fix: "Use timeout: { ...timeout, strategy: 'cooperative' } and pass getResilienceAbortSignal() to cancellable work, or set timeout.replaySafe: true after verifying overlapping executions are safe.",
+        });
+    }
+    return issues;
+}
+/**
+ * Pipeline behavior that wraps each command / query / event handler in a
+ * cockatiel resilience policy — the layers that make sense around a whole
+ * handler: retry, timeout and bulkhead.
+ *
+ * A circuit breaker and a fallback belong to an outbound dependency, not to a
+ * handler: declare them on a named policy (`new ResiliencePolicies({ ... })`)
+ * and use it in the adapter through {@link ResiliencePolicies}. The behavior
+ * contract rejects them here.
+ *
+ * Resolution of the effective options for a handler where this behavior is
+ * attached:
+ * 1. Application-wide defaults, the first constructor argument.
+ * 2. Per-handler options from `pipeline.wrap(options, [ResilienceBehavior, { ... }])`,
+ *    shallow-merged on top of the defaults (handler keys win).
+ *
+ * Policies are built **lazily on first invocation and cached per handler**, so
+ * a stateful layer (bulkhead) correctly shares state across
+ * every request to that handler. When no options resolve, the behavior caches
+ * that result and passes subsequent invocations directly to `next()` without
+ * constructing or executing a cockatiel policy.
+ *
+ * ### Replay / error-classification safety
+ *
+ * A handler-level retry calls `next()` again, which means the complete
+ * downstream pipeline and handler are replayed. To avoid accidental duplicate
+ * side effects, command/event retries must explicitly set
+ * `retry.replaySafe: true`. A retry must also define which errors are transient via `handle(error)`, unless the caller
+ * intentionally opts into `handleAllErrors: true`. An `aggressive` timeout
+ * (the default strategy) on a command/event answers the caller while the
+ * handler keeps running, so it requires `strategy: 'cooperative'` or
+ * `timeout.replaySafe: true`.
+ *
+ * Timeout and bulkhead-only policies do not require an error classifier because
+ * they do not decide which application errors are retryable.
+ * A custom pre-built Cockatiel `policy` also bypasses the declarative safety
+ * checks because the caller owns its semantics directly.
+ */
+export class ResilienceBehavior {
+    defaultOptions;
+    static [PIPELINE_BEHAVIOR_CONTRACT] = {
+        validate: (context) => {
+            const options = context.effectiveOptions;
+            const issues = getResilienceSafetyIssues(options, context.requestKind);
+            if (issues.length === 0)
+                return undefined;
+            return issues.map((issue) => ({
+                handlerName: context.handlerName,
+                behaviorName: ResilienceBehavior.name,
+                message: issue.message,
+                fix: issue.fix,
+            }));
+        },
+    };
+    logger;
+    /**
+     * Per-handler policy cache. `null` means "resolved, but nothing configured"
+     * (pass-through), distinct from `undefined` ("not yet resolved").
+     */
+    policyCache = new Map();
+    constructor(defaultOptions, logger) {
+        this.defaultOptions = defaultOptions;
+        this.logger = logger ?? console;
+    }
+    async handle(context, next) {
+        const policy = this.resolvePolicy(context);
+        if (!policy)
+            return next();
+        // The policy is shared across every request that reaches this handler, so
+        // the request's own labels travel with the execution rather than being
+        // captured when the policy was built.
+        return runWithResilienceRequest({ requestName: context.requestName, handlerName: context.handlerName }, () => policy.execute((policyContext) => {
+            // Cockatiel supplies the effective AbortSignal (including timeout
+            // cancellation) to each execute callback. Bind it to this attempt's
+            // async execution so an aggressive timeout followed by a retry cannot
+            // replace the signal still observed by work from the timed-out attempt.
+            return runWithResilienceAbortSignal(policyContext.signal, next);
+        }));
+    }
+    /** Resolves, validates, and caches the composed policy for the handler in `context`. */
+    resolvePolicy(context) {
+        const cached = this.policyCache.get(context.handlerType);
+        if (cached !== undefined)
+            return cached;
+        const handlerOptions = context.getBehaviorOptions(ResilienceBehavior);
+        const effective = this.resolveEffectiveOptions(handlerOptions);
+        this.assertSafeConfiguration(context, effective);
+        const policy = effective
+            ? buildResiliencePolicy(effective, {
+                logger: this.logger,
+                requestName: context.requestName,
+                handlerName: context.handlerName,
+            })
+            : null;
+        this.policyCache.set(context.handlerType, policy);
+        return policy;
+    }
+    /**
+     * Rejects ambiguous whole-handler resilience configurations before Cockatiel
+     * policy creation. This turns replay/error-classification assumptions into an
+     * explicit application decision instead of a hidden default.
+     */
+    assertSafeConfiguration(context, options) {
+        const issues = getResilienceSafetyIssues(options, context.requestKind);
+        if (issues.length > 0) {
+            throw new ResilienceConfigurationError(context.requestName, context.requestKind, issues[0].message);
+        }
+    }
+    /** Shallow-merges pipeline-level options over the constructor defaults. */
+    resolveEffectiveOptions(options) {
+        if (!this.defaultOptions && !options)
+            return undefined;
+        return { ...this.defaultOptions, ...options };
+    }
+}
+//# sourceMappingURL=resilience.behavior.js.map

package/dist/resilience.behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.behavior.js","sourceRoot":"","sources":["../src/resilience.behavior.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAML,0BAA0B,GAG3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,4CAA4C,CAAC;AAC1F,OAAO,EAEL,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,iCAAiC,CAAC;AAQzC,SAAS,yBAAyB,CAChC,OAA8C,EAC9C,WAAsD;IAEtD,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,gBAAgB,GAAG,OAGxB,CAAC;IACF,IACE,gBAAgB,CAAC,cAAc,KAAK,SAAS;QAC7C,gBAAgB,CAAC,QAAQ,KAAK,SAAS,EACvC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EACL,6HAA6H;YAC/H,GAAG,EAAE,oHAAoH;SAC1H,CAAC,CAAC;IACL,CAAC;IAED,MAAM,gBAAgB,GACpB,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,eAAe,KAAK,IAAI,CAAC;IAC3E,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,gEAAgE;YACzE,GAAG,EAAE,0FAA0F;SAChG,CAAC,CAAC;IACL,CAAC;IAED,IACE,OAAO,CAAC,KAAK;QACb,WAAW,KAAK,OAAO;QACvB,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,IAAI,EACjC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,+BAA+B,WAAW,4EAA4E;YAC/H,GAAG,EAAE,iHAAiH;SACvH,CAAC,CAAC;IACL,CAAC;IAED,IACE,OAAO,CAAC,OAAO;QACf,WAAW,KAAK,OAAO;QACvB,OAAO,CAAC,OAAO,CAAC,QAAQ,KAAK,aAAa;QAC1C,OAAO,CAAC,OAAO,CAAC,UAAU,KAAK,IAAI,EACnC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,4CAA4C,WAAW,+FAA+F;YAC/J,GAAG,EAAE,gMAAgM;SACtM,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,OAAO,kBAAkB;IAgCV,cAAc;IA3BjC,MAAM,CAAU,CAAC,0BAA0B,CAAC,GAA8B;QACxE,QAAQ,EAAE,CACR,OAA0C,EACA,EAAE;YAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,gBAEX,CAAC;YACd,MAAM,MAAM,GAAG,yBAAyB,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;YACvE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC;YAE1C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,YAAY,EAAE,kBAAkB,CAAC,IAAI;gBACrC,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,EAAE,KAAK,CAAC,GAAG;aACf,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC;IAEe,MAAM,CAAiB;IACxC;;;OAGG;IACc,WAAW,GAAG,IAAI,GAAG,EAAiC,CAAC;IAExE,YACmB,cAA0C,EAC3D,MAAuB;8BADN,cAAc;QAG/B,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,OAAO,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,MAAM,CACV,OAAyB,EACzB,IAAkB;QAElB,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,EAAE,CAAC;QAE3B,0EAA0E;QAC1E,uEAAuE;QACvE,sCAAsC;QACtC,OAAO,wBAAwB,CAC7B,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,EACtE,GAAG,EAAE,CACH,MAAM,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,EAAE;YAC/B,kEAAkE;YAClE,oEAAoE;YACpE,sEAAsE;YACtE,wEAAwE;YACxE,OAAO,4BAA4B,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAClE,CAAC,CAAC,CACL,CAAC;IACJ,CAAC;IAED,wFAAwF;IAChF,aAAa,CAAC,OAAyB;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACzD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QAExC,MAAM,cAAc,GAClB,OAAO,CAAC,kBAAkB,CAA4B,kBAAkB,CAAC,CAAC;QAC5E,MAAM,SAAS,GAAG,IAAI,CAAC,uBAAuB,CAAC,cAAc,CAAC,CAAC;QAE/D,IAAI,CAAC,uBAAuB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAEjD,MAAM,MAAM,GAAG,SAAS;YACtB,CAAC,CAAC,qBAAqB,CAAC,SAAS,EAAE;gBAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,WAAW,EAAE,OAAO,CAAC,WAAW;aACjC,CAAC;YACJ,CAAC,CAAC,IAAI,CAAC;QAET,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACK,uBAAuB,CAC7B,OAAyB,EACzB,OAA8C;QAE9C,MAAM,MAAM,GAAG,yBAAyB,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QACvE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,4BAA4B,CACpC,OAAO,CAAC,WAAW,EACnB,OAAO,CAAC,WAAW,EACnB,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAClB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,uBAAuB,CACrB,OAAmC;QAEnC,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QACvD,OAAO,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,GAAG,OAAO,EAAE,CAAC;IAChD,CAAC;CACF"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@cqrs-ddd/pipeline-resilience",
+  "version": "0.5.0",
+  "description": "Retry, timeout, circuit breaker, bulkhead and fallback policies (cockatiel) for @cqrs-ddd/pipeline",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "cqrs",
+    "pipeline",
+    "resilience",
+    "fault-tolerance",
+    "retry",
+    "circuit-breaker",
+    "timeout",
+    "bulkhead",
+    "fallback",
+    "cockatiel"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/ddd-cqrs.git",
+    "directory": "packages/pipeline-resilience"
+  },
+  "homepage": "https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-resilience/",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "cockatiel": "^4.0.0",
+    "@cqrs-ddd/pipeline": "^0.5.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.3",
+    "cockatiel": "^4.0.0",
+    "vitest": "^5.0.3",
+    "@cqrs-ddd/pipeline": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}