@camunda8/orchestration-cluster-api 8.9.0-alpha.1 → 8.9.0-alpha.11

package/CHANGELOG.md

@@ -1,3 +1,55 @@
+# [8.9.0-alpha.11](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.10...v8.9.0-alpha.11) (2026-03-06)
+
+
+### Features
+
+* add per-operation retry config. New tuning for backpressure ([9dd921a](https://github.com/camunda/orchestration-cluster-api-js/commit/9dd921a0eae67d56d0e8a7d6423ac7d8a3edd3b4))
+
+# [8.9.0-alpha.10](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.9...v8.9.0-alpha.10) (2026-03-05)
+
+### Features
+
+- tune backpressure ([b64c6f1](https://github.com/camunda/orchestration-cluster-api-js/commit/b64c6f14a5b4755881cb1c79c804a5cd8403145f))
+
+# [8.9.0-alpha.9](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.8...v8.9.0-alpha.9) (2026-03-05)
+
+### Features
+
+- add startup jitter for workers ([95b431d](https://github.com/camunda/orchestration-cluster-api-js/commit/95b431d97fc42aaddfde0b744a8ad94bf82ce401))
+- regenerate from stable/8.9 ([390a04e](https://github.com/camunda/orchestration-cluster-api-js/commit/390a04e6ea06b462ffd6d77d4ed10a3bf31dffda))
+
+# [8.9.0-alpha.8](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.7...v8.9.0-alpha.8) (2026-03-02)
+
+### Features
+
+- support deprecated enums ([a1a2290](https://github.com/camunda/orchestration-cluster-api-js/commit/a1a22908fef6ca75ce353b851d4b6aabd7aa4522))
+
+# [8.9.0-alpha.7](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.6...v8.9.0-alpha.7) (2026-03-02)
+
+### Bug Fixes
+
+- rebuild from upstream spec ([efd13cb](https://github.com/camunda/orchestration-cluster-api-js/commit/efd13cbaec2e3fa2c0a8c0578f5d5b0fa0101715))
+
+# [8.9.0-alpha.6](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.5...v8.9.0-alpha.6) (2026-02-17)
+
+### Features
+
+- regenerate from latest schema ([c2d9dff](https://github.com/camunda/orchestration-cluster-api-js/commit/c2d9dffe96f645d2043f62335ef97bdc381b37b1))
+
+## [1.2.4-alpha.1](https://github.com/camunda/orchestration-cluster-api-js/compare/v1.2.3...v1.2.4-alpha.1) (2026-01-22)
+
+### Bug Fixes
+
+- correctly type optional parameters ([8fef8c8](https://github.com/camunda/orchestration-cluster-api-js/commit/8fef8c8a4bc69a3dd86b76ac1e01431d97607050))
+- enhance response validation error message ([d138134](https://github.com/camunda/orchestration-cluster-api-js/commit/d1381348f46c187e8321fdec088b7654b70c4fa8))
+- handle multi-part spec ([86ac930](https://github.com/camunda/orchestration-cluster-api-js/commit/86ac930e3b599126cf5446bcaa323089049bb4ef))
+- **spec:** prevent path-local $like refs breaking dts build ([3b75200](https://github.com/camunda/orchestration-cluster-api-js/commit/3b75200caeffb198f072668567cff7e34f5700f0))
+
+### Features
+
+- build 8.9 from monorepo spec ([a80303d](https://github.com/camunda/orchestration-cluster-api-js/commit/a80303d3a54f2d6db77c428f46848f131bd8bf42))
+- build from 8.9 spec ([e4ab53c](https://github.com/camunda/orchestration-cluster-api-js/commit/e4ab53cd253ca5d1fcf2d0bf0626c8d26c7da49c))
+
 ## [1.2.3](https://github.com/camunda/orchestration-cluster-api-js/compare/v1.2.2...v1.2.3) (2025-12-05)
 
 ### Bug Fixes

package/README.md

@@ -14,6 +14,7 @@ Type‑safe, promise‑based client for the Camunda 8 Orchestration Cluster REST
 - Immutable, deep‑frozen configuration accessible through a factory‑created client instance
 - Automatic body-level tenantId defaulting: if a request body supports an optional tenantId and you omit it, the SDK fills it from CAMUNDA_DEFAULT_TENANT_ID (path params are never auto-filled)
 - Automatic transient HTTP retry (429, 503, network) with exponential backoff + full jitter (configurable via CAMUNDA_SDK_HTTP_RETRY\*). Non-retryable 500s fail fast. Pluggable strategy surface (default uses p-retry when available, internal fallback otherwise).
+- Per-method retry override: disable or customize retry policy on any individual API call without changing global settings
 
 ## Install
 
@@ -28,6 +29,23 @@ Runtime support:
 
 For older Node versions supply a fetch ponyfill AND a `File` shim (or upgrade). For legacy browsers, add a fetch polyfill (e.g. `whatwg-fetch`).
 
+## Versioning
+
+This SDK does **not** follow traditional semver. The **major.minor** version tracks the Camunda server version, so you can easily match the SDK to your deployment target (e.g. SDK `8.9.x` targets Camunda `8.9`).
+
+**Patch releases** contain fixes, features, and occasionally **breaking type changes**. A breaking type change typically means an upstream API definition fix that corrects the shape of a request or response model — your code may stop type-checking even though it worked before.
+
+When this happens, we signal it in the [CHANGELOG](https://github.com/camunda/orchestration-cluster-api-js/releases).
+
+**Recommended approach:**
+
+- **Ride the latest** — accept that types may shift and update your code when it happens. This keeps you on the most accurate API surface.
+- **Pin and review** — pin to a specific patch version in `package.json` and review the [CHANGELOG](https://github.com/camunda/orchestration-cluster-api-js/releases) before upgrading:
+
+  ```json
+  "@camunda8/orchestration-cluster-api": "8.9.3"
+  ```
+
 ## Quick Start (Zero‑Config – Recommended)
 
 Keep configuration out of application code. Let the factory read `CAMUNDA_*` variables from the environment (12‑factor style). This makes rotation, secret management, and environment promotion safer & simpler.
@@ -132,15 +150,61 @@ Behavior:
 - `strict` - fail on type mismatch or missing required fields
 - `fanatical` - fail on type mismatch, missing required fields, or unknown additional fields
 
+## Per-Method Retry Override
+
+Every API method accepts an optional trailing `options` parameter that lets you override or disable the global retry policy for that single call.
+
+### Disable Retry for a Single Call
+
+```ts
+// This call will not retry on transient errors
+await camunda.completeJob({ jobKey }, { retry: false });
+```
+
+### Override Specific Retry Settings
+
+Pass a partial `HttpRetryPolicy` to override individual fields. Unspecified fields inherit from the global configuration.
+
+```ts
+import type { OperationOptions } from '@camunda8/orchestration-cluster-api';
+
+// More aggressive retry for this operation only
+await camunda.createProcessInstance(
+  { processDefinitionId: 'payment-process' },
+  { retry: { maxAttempts: 8, maxDelayMs: 5000 } }
+);
+
+// Minimal retry: single retry with short backoff
+await camunda.getTopology({ retry: { maxAttempts: 2, baseDelayMs: 50 } });
+```
+
+### How It Works
+
+| `options.retry` value | Behavior                                                             |
+| --------------------- | -------------------------------------------------------------------- |
+| omitted / `undefined` | Uses global policy (`CAMUNDA_SDK_HTTP_RETRY_*` env vars)             |
+| `false`               | Disables retry entirely (single attempt, no backoff)                 |
+| `{ maxAttempts: 5 }`  | Merges with global policy — only the specified fields are overridden |
+
+The `HttpRetryPolicy` fields available for override:
+
+| Field         | Type     | Description                             |
+| ------------- | -------- | --------------------------------------- |
+| `maxAttempts` | `number` | Total attempts (initial + retries)      |
+| `baseDelayMs` | `number` | Base delay for exponential backoff (ms) |
+| `maxDelayMs`  | `number` | Maximum delay cap (ms)                  |
+
 ## Advanced HTTP Retry: Cockatiel Adapter (Optional)
 
-The SDK includes built‑in transient HTTP retry (429, 503, network errors) using a p‑retry based engine plus a fallback implementation. For advanced resilience patterns (circuit breakers, timeouts, custom classification, combining policies) you can integrate [cockatiel](https://github.com/connor4312/cockatiel).
+For advanced resilience patterns beyond per-method overrides — circuit breakers, timeouts, custom classification, combining policies — you can integrate [cockatiel](https://github.com/connor4312/cockatiel).
+
+> **Tip:** For most use cases, per-method retry override (above) is sufficient. Reach for Cockatiel when you need circuit breaking, hedging, or bulkhead controls.
 
 ### When To Use Cockatiel
 
-- You need different retry policies per operation (e.g. idempotent GET vs mutating POST)
 - You want circuit breaking, hedging, timeout, or bulkhead controls
 - You want to add custom classification (e.g. retry certain 5xx only on safe verbs)
+- You need to compose multiple resilience policies together
 
 ### Disable Built‑In HTTP Retries
 
@@ -275,7 +339,7 @@ const policy = retry(classify, {
 - Keep SDK retries disabled to prevent duplicate layers.
 - SDK synthesizes `Error` objects with a `status` for retry-significant HTTP responses (429, 503, 500), enabling classification.
 - You can tag errors (e.g. assign `err.__opVerb`) in a wrapper if verb-level logic is needed.
-- Future improvement: an official `retryStrategy` injection hook—current approach is non-invasive.
+- For per-operation retry customization without external dependencies, use the built-in [per-method retry override](#per-method-retry-override) instead.
 
 > Combine cockatiel retry with a circuit breaker, timeout, or bulkhead policy for more robust behavior in partial outages.
 
@@ -377,6 +441,21 @@ Factors use integer percentages to avoid floating point drift in env parsing; th
 
 If you have concrete tuning needs, open an issue describing workload patterns (operation mix, baseline concurrency, observed broker limits) to help prioritize which knobs to surface.
 
+### What Should I Set?
+
+If you're unsure about your workload shape, **don't set anything**. The default BALANCED profile activates automatically and outperforms no-gating (LEGACY) in most scenarios — on raw throughput alone, not just error reduction.
+
+Benchmark results against a single-node local cluster with multiple independent clients (no shared state between them):
+
+| Scenario                      | BALANCED        | LEGACY (no gating) |
+| ----------------------------- | --------------- | ------------------ |
+| Single-client (1K processes)  | **80.1 ops/s**  | 67.8 ops/s         |
+| Single-client sustained (10K) | **119.6 ops/s** | 87.8 ops/s         |
+| Multi-client 3+2 spike        | **86.3 ops/s**  | 48.0 ops/s         |
+| Stress 8 clients ×1000        | 76.3 ops/s      | **106.4 ops/s**    |
+
+BALANCED wins 3 of 4 on pure throughput. The only scenario where LEGACY is faster is extreme overload (800 concurrent requests against a single broker) — and in that case LEGACY accumulates 44,505 errors vs BALANCED's 15,527. The default just works.
+
 ## Job Workers (Polling API)
 
 The SDK provides a lightweight polling job worker for service task job types using `createJobWorker`. It activates jobs in batches (respecting a concurrency limit), validates variables (optional), and offers action helpers on each job.
@@ -404,6 +483,7 @@ const worker = client.createJobWorker({
   outputSchema: Output, // validates variables passed to complete(...)
   validateSchemas: true, // set false for max throughput (skip Zod)
   autoStart: true, // default true; start polling immediately
+  startupJitterMaxSeconds: 5, // random delay up to 5s before first poll (default 0)
   jobHandler: (job) => {
     // Access typed variables
     const vars = job.variables; // inferred from Input schema
@@ -526,6 +606,22 @@ Activation cancellations during stop are logged at debug (`activation.cancelled`
 
 You can register multiple workers on a single client instance—one per job type is typical. The client exposes `client.getWorkers()` for inspection and `client.stopAllWorkers()` for coordinated shutdown.
 
+### Startup Jitter
+
+When deploying multiple application instances simultaneously (e.g. a rolling restart or scale-up), all workers start polling at the same time and can saturate the server with activation requests. Set `startupJitterMaxSeconds` to spread out the initial poll across a random window:
+
+```ts
+client.createJobWorker({
+  jobType: 'process-order',
+  maxParallelJobs: 10,
+  jobTimeoutMs: 30_000,
+  startupJitterMaxSeconds: 5, // each instance delays 0–5s before first poll
+  jobHandler: async (job) => job.complete(),
+});
+```
+
+A value of `0` (the default) means no delay.
+
 ### Receipt Type (Unique Symbol)
 
 Action methods return a unique symbol (not a string) to avoid accidental misuse and allow internal metrics. If you store the receipt, annotate its type as `JobActionReceipt` to preserve uniqueness: