@camunda/e2e-test-suite 0.0.1242 → 0.0.1243

package/dist/utils/api/http.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * HTTP client for the Orchestration Cluster REST v2 API.
+ *
+ * Wraps Playwright's `APIRequestContext` with the three things a Helm-deployed
+ * cluster needs and a localhost one does not: pluggable auth (see `auth.ts`),
+ * tenant propagation (see `tenancy.ts`), and tolerance of the ingress dropping
+ * requests while orchestration pods roll during an upgrade.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiClient = void 0;
+const config_1 = require("./config");
+const auth_1 = require("./auth");
+const tenancy_1 = require("./tenancy");
+/**
+ * Two different layers answer 5xx while a pod rolls during an upgrade-minor
+ * run, and both are transient rather than a real answer to any assertion here.
+ *
+ * The ingress emits an nginx error page when it cannot reach an orchestration
+ * pod: 502/504 when an upstream is reachable but not answering, 503 when no
+ * endpoint is ready at all.
+ *
+ * The orchestration REST API itself emits 503 UNAVAILABLE ("The search client
+ * could not connect to the search server") while its search client briefly
+ * cannot reach Elasticsearch/OpenSearch — the same restart window, one layer
+ * down. That one carries a real JSON problem body, so a content-type check
+ * alone reads it as a final answer and skips the retry entirely. This is the
+ * bug 2f00674 fixed in the shell suite, reintroduced here by porting the
+ * nginx-only check without its follow-up.
+ *
+ * Anything else — including a JSON 5xx that is not the search-backend message
+ * — is returned as-is, and a sustained outage still surfaces once the retry
+ * budget is spent.
+ */
+const GATEWAY_STATUSES = new Set([502, 503, 504]);
+const GATEWAY_MAX_ATTEMPTS = 12;
+const GATEWAY_MAX_BACKOFF_MS = 10000;
+const SEARCH_BACKEND_UNAVAILABLE = 'could not connect to the search server';
+/**
+ * The same pod roll also drops connections outright, which never reaches the
+ * status check above: `fetch` rejects instead of resolving, so the retry loop
+ * was skipped entirely and the test failed with a bare "socket hang up".
+ *
+ * These are transport-level failures with no HTTP answer behind them, so they
+ * carry no information about the assertion under test and are retried on the
+ * same budget as a gateway 5xx. A name not in this list propagates unchanged —
+ * a genuine client bug must not be retried into a timeout.
+ */
+const TRANSIENT_CONNECTION_ERRORS = [
+    'socket hang up',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'EPIPE',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+    'other side closed',
+    'network socket disconnected',
+];
+/**
+ * The XML endpoints declare `produces = {text/xml, application/problem+json}`
+ * (see `ProcessDefinitionController` / `DecisionDefinitionController` in
+ * camunda/camunda), so a blanket `Accept: application/json` makes Spring answer
+ * 406 before the handler runs — which reads as a failed assertion on a
+ * perfectly healthy cluster, and also masks the 404 an absent key should give.
+ *
+ * Deriving this from the path rather than the call site keeps a new `/xml`
+ * endpoint correct by default.
+ */
+function acceptFor(path) {
+    return path?.endsWith('/xml')
+        ? 'text/xml, application/problem+json'
+        : 'application/json';
+}
+function isTransientConnectionError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return TRANSIENT_CONNECTION_ERRORS.some((needle) => message.toLowerCase().includes(needle.toLowerCase()));
+}
+function backoffMs(attempt) {
+    return Math.min(attempt * 2000, GATEWAY_MAX_BACKOFF_MS);
+}
+async function isGatewayError(response) {
+    if (!GATEWAY_STATUSES.has(response.status()))
+        return false;
+    const body = await response.text().catch(() => '');
+    return (body.includes('nginx') ||
+        body.trim() === '' ||
+        body.includes(SEARCH_BACKEND_UNAVAILABLE));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Announces a replayed request that could have had an effect already.
+ *
+ * A retry can duplicate a side effect: the connection can drop *after* the
+ * engine accepted the command, so a replayed `POST /process-instances` is two
+ * instances and a replayed deployment is a second version.
+ *
+ * Not retrying commands is not the safer default here. The retry exists
+ * because an upgrade-minor run rolls the orchestration pods under a live
+ * suite, and its absence produced 12 `socket hang up` failures in a single
+ * run. Neither Playwright nor Node tells us whether the request reached a
+ * server — the case where a replay is provably safe — or whether only the
+ * response was lost, so restricting retries by method would trade a frequent
+ * observed failure for a rare silent one.
+ *
+ * What is not acceptable is the duplicate being invisible, so every replay of
+ * a mutating request says so. A duplicated definition or instance is then one
+ * grep away instead of an unexplained extra row. Whether to narrow the retry
+ * further is a call for the suite's owners; `tests/api/README.md` records the
+ * trade-off.
+ *
+ * Two things are excluded to keep the warning worth reading. `/search` POSTs
+ * are queries, so a replay has no effect to duplicate. And a bare 503 is the
+ * ingress saying no endpoint was ready, which means the request never reached
+ * the application — unlike 502/504, where an upstream was reached and only the
+ * answer went missing, and unlike a dropped socket.
+ */
+function warnIfMutationReplayed(method, path, attempt, reason) {
+    const mutates = (method === 'post' || method === 'patch') && !path.endsWith('/search');
+    if (!mutates || reason === 'HTTP 503')
+        return;
+    console.warn(`Replaying ${method.toUpperCase()} ${path} after ${reason} (attempt ` +
+        `${attempt + 2}). If the first attempt was already accepted, its ` +
+        `effect now exists twice.`);
+}
+class ApiClient {
+    request;
+    config;
+    constructor(request, config = config_1.apiConfig) {
+        this.request = request;
+        this.config = config;
+    }
+    /**
+     * Expands a path template against the shared `/v2` prefix.
+     *
+     * Throws on a missing placeholder rather than emitting a literal `{key}` in
+     * the URL: the gateway answers such a path with a plausible 404, so a test
+     * asserting 404 would pass without exercising anything.
+     */
+    buildUrl(path, params, query) {
+        const expanded = path.replace(/\{(\w+)\}/g, (_match, key) => {
+            const value = params?.[key];
+            if (value === undefined || value === null || value === '') {
+                throw new Error(`buildUrl: missing path parameter "${key}" for "${path}". ` +
+                    `Received: ${JSON.stringify(params ?? {})}`);
+            }
+            return encodeURIComponent(String(value));
+        });
+        let url = `${this.config.baseUrl}/v2${expanded}`;
+        const pairs = Object.entries(query ?? {})
+            .filter(([, value]) => value !== undefined)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        if (pairs.length > 0) {
+            url += (url.includes('?') ? '&' : '?') + pairs.join('&');
+        }
+        return url;
+    }
+    async headersFor(options, contentType, path) {
+        const headers = {
+            Accept: acceptFor(path),
+            ...options.headers,
+        };
+        if (contentType)
+            headers['Content-Type'] = contentType;
+        if (options.authorization === null) {
+            return headers;
+        }
+        headers.Authorization =
+            options.authorization ?? (await (0, auth_1.authHeader)(this.request, this.config));
+        return headers;
+    }
+    async send(method, path, options = {}) {
+        const tenantMode = options.tenant ?? 'auto';
+        const hasBody = options.body !== undefined;
+        const isMultipart = options.multipart !== undefined;
+        const body = hasBody
+            ? (0, tenancy_1.applyTenantToBody)(options.body, tenantMode, this.config)
+            : undefined;
+        // Tenant-aware endpoints that carry no body take the tenant on the query
+        // string instead.
+        const query = {
+            ...(hasBody || isMultipart
+                ? {}
+                : (0, tenancy_1.tenantQueryParam)(tenantMode, this.config)),
+            ...options.query,
+        };
+        const url = this.buildUrl(path, options.params, query);
+        const headers = await this.headersFor(options, hasBody ? 'application/json' : undefined, path);
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await this.request.fetch(url, {
+                    method: method.toUpperCase(),
+                    headers,
+                    ...(hasBody ? { data: body } : {}),
+                    ...(isMultipart
+                        ? {
+                            multipart: options.multipart,
+                        }
+                        : {}),
+                    // Assertions own the status; never let Playwright throw on 4xx/5xx.
+                    failOnStatusCode: false,
+                    timeout: 30000,
+                });
+            }
+            catch (error) {
+                if (attempt >= GATEWAY_MAX_ATTEMPTS ||
+                    !isTransientConnectionError(error)) {
+                    throw error;
+                }
+                warnIfMutationReplayed(method, path, attempt, error instanceof Error ? error.message : String(error));
+                await sleep(backoffMs(attempt + 1));
+                continue;
+            }
+            if (attempt >= GATEWAY_MAX_ATTEMPTS ||
+                !(await isGatewayError(response))) {
+                return response;
+            }
+            warnIfMutationReplayed(method, path, attempt, `HTTP ${response.status()}`);
+            await sleep(backoffMs(attempt + 1));
+        }
+    }
+    get(path, options = {}) {
+        return this.send('get', path, options);
+    }
+    post(path, options = {}) {
+        return this.send('post', path, options);
+    }
+    put(path, options = {}) {
+        return this.send('put', path, options);
+    }
+    patch(path, options = {}) {
+        return this.send('patch', path, options);
+    }
+    delete(path, options = {}) {
+        return this.send('delete', path, options);
+    }
+    /** Raw request for the handful of cases needing a non-JSON content type. */
+    raw(method, path, options = {}) {
+        return this.send(method, path, options);
+    }
+}
+exports.ApiClient = ApiClient;

package/dist/utils/api/identity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Identity helpers for the specs that need a username to hang something off.
+ *
+ * Membership and authorization take a username in the path or the body, and
+ * the endpoint that *creates* a username is the only part an OIDC cluster
+ * withholds. Going through `provisionUsername` rather than posting to
+ * `/v2/users` directly keeps those specs running in both modes instead of
+ * skipping them wherever the Users API is closed — which is every SM Helm
+ * run, and role, group and tenant membership is exactly the surface an
+ * upgrade is most likely to break.
+ */
+import type { ApiClient } from './http';
+import type { ResourceTracker } from './cleanup';
+/**
+ * A username the membership and authorization endpoints will accept.
+ *
+ * Where the cluster keeps its own user store the user is really created and
+ * tracked for cleanup, so the assertions run against a principal that exists.
+ *
+ * Under OIDC there is nothing to create: users belong to the identity
+ * provider. The engine guards membership with
+ * `!localUserEnabled || userState.getUser(entityId).isPresent()`, so with
+ * local users off the existence check short-circuits and a bare username is
+ * accepted — which is also why assigning an *unknown* user is a 204 there and
+ * a 404 with a local store (see `absentUserMembership` in `capabilities.ts`).
+ * Returning a synthetic name is therefore not a stub: it is the same thing an
+ * identity-provider user looks like to these endpoints before first sign-in.
+ */
+export declare function provisionUsername(api: ApiClient, resources: ResourceTracker): Promise<string>;

package/dist/utils/api/identity.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Identity helpers for the specs that need a username to hang something off.
+ *
+ * Membership and authorization take a username in the path or the body, and
+ * the endpoint that *creates* a username is the only part an OIDC cluster
+ * withholds. Going through `provisionUsername` rather than posting to
+ * `/v2/users` directly keeps those specs running in both modes instead of
+ * skipping them wherever the Users API is closed — which is every SM Helm
+ * run, and role, group and tenant membership is exactly the surface an
+ * upgrade is most likely to break.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provisionUsername = void 0;
+const config_1 = require("./config");
+const beans_1 = require("./beans");
+const assertions_1 = require("./assertions");
+const bpmn_1 = require("./bpmn");
+/**
+ * A username the membership and authorization endpoints will accept.
+ *
+ * Where the cluster keeps its own user store the user is really created and
+ * tracked for cleanup, so the assertions run against a principal that exists.
+ *
+ * Under OIDC there is nothing to create: users belong to the identity
+ * provider. The engine guards membership with
+ * `!localUserEnabled || userState.getUser(entityId).isPresent()`, so with
+ * local users off the existence check short-circuits and a bare username is
+ * accepted — which is also why assigning an *unknown* user is a 204 there and
+ * a 404 with a local store (see `absentUserMembership` in `capabilities.ts`).
+ * Returning a synthetic name is therefore not a stub: it is the same thing an
+ * identity-provider user looks like to these endpoints before first sign-in.
+ */
+async function provisionUsername(api, resources) {
+    if (!config_1.apiConfig.usersApiEnabled) {
+        return (0, bpmn_1.uniqueId)('oidc-user');
+    }
+    const user = (0, beans_1.newUser)();
+    await (0, assertions_1.assertCreated)(await api.post('/users', { body: user, tenant: 'none' }));
+    resources.track('user', user.username);
+    return user.username;
+}
+exports.provisionUsername = provisionUsername;

package/dist/utils/api/keys.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Keys that no record holds, for the "absent resource" assertions.
+ *
+ * Zeebe encodes the partition in the high bits of a key —
+ * `(partitionId << 51) + counter`, see `Protocol.java` in camunda/camunda —
+ * so which absent key to use depends on how the endpoint is served:
+ *
+ *  - A **query** (`GET /v2/...`, a `/search`) reads secondary storage and
+ *    looks the key up as a value. Any number that is not present answers 404,
+ *    partition or no partition.
+ *  - A **command** (`PUT .../variables`, a cancellation, a completion) may be
+ *    routed to the partition its key names before anything looks the record
+ *    up. A key below `1 << 51` decodes to partition 0, which no cluster has,
+ *    so the gateway cannot deliver it and answers `503 UNAVAILABLE` —
+ *    "Expected to handle request, but request could not be delivered" —
+ *    rather than the 404 the test means to assert.
+ *
+ * How much of that is observable varies by endpoint, so treat it as a rule to
+ * follow rather than a claim about every path. `PUT
+ * /element-instances/{key}/variables` is where the 503 was actually seen, and
+ * it is what this constant was added for. Other commands currently answer 404
+ * for a partition-0 key, presumably because the REST layer resolves the record
+ * before dispatching — but that is an implementation detail no test should
+ * depend on. Every command assertion therefore uses the routable key, so none
+ * of them can start testing the router if that resolution order changes.
+ *
+ * Import these rather than redeclaring the literal. Eight specs used to carry
+ * their own `const ABSENT_KEY`, which shadowed this module and is why the
+ * command sites drifted onto the query-side key in the first place.
+ */
+/** Partition 0 — fine for queries, unroutable for commands. */
+export declare const ABSENT_KEY = "999999999999";
+/**
+ * Partition 1, counter far beyond anything a test cluster allocates: routable,
+ * so a command reaches a partition and is rejected as not found.
+ */
+export declare const ABSENT_ROUTABLE_KEY: string;

package/dist/utils/api/keys.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Keys that no record holds, for the "absent resource" assertions.
+ *
+ * Zeebe encodes the partition in the high bits of a key —
+ * `(partitionId << 51) + counter`, see `Protocol.java` in camunda/camunda —
+ * so which absent key to use depends on how the endpoint is served:
+ *
+ *  - A **query** (`GET /v2/...`, a `/search`) reads secondary storage and
+ *    looks the key up as a value. Any number that is not present answers 404,
+ *    partition or no partition.
+ *  - A **command** (`PUT .../variables`, a cancellation, a completion) may be
+ *    routed to the partition its key names before anything looks the record
+ *    up. A key below `1 << 51` decodes to partition 0, which no cluster has,
+ *    so the gateway cannot deliver it and answers `503 UNAVAILABLE` —
+ *    "Expected to handle request, but request could not be delivered" —
+ *    rather than the 404 the test means to assert.
+ *
+ * How much of that is observable varies by endpoint, so treat it as a rule to
+ * follow rather than a claim about every path. `PUT
+ * /element-instances/{key}/variables` is where the 503 was actually seen, and
+ * it is what this constant was added for. Other commands currently answer 404
+ * for a partition-0 key, presumably because the REST layer resolves the record
+ * before dispatching — but that is an implementation detail no test should
+ * depend on. Every command assertion therefore uses the routable key, so none
+ * of them can start testing the router if that resolution order changes.
+ *
+ * Import these rather than redeclaring the literal. Eight specs used to carry
+ * their own `const ABSENT_KEY`, which shadowed this module and is why the
+ * command sites drifted onto the query-side key in the first place.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ABSENT_ROUTABLE_KEY = exports.ABSENT_KEY = void 0;
+/** Partition 0 — fine for queries, unroutable for commands. */
+exports.ABSENT_KEY = '999999999999';
+/**
+ * Partition 1, counter far beyond anything a test cluster allocates: routable,
+ * so a command reaches a partition and is rejected as not found.
+ */
+exports.ABSENT_ROUTABLE_KEY = String(2251799813685248n + 999999999n);

package/dist/utils/api/paths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Every Orchestration Cluster REST v2 path this suite exercises.
+ *
+ * `buildUrl` accepts only these literals, so an endpoint that is renamed or
+ * mistyped fails to compile. The legacy shell suite concatenated path strings,
+ * where a typo produced a plausible 404 that an assertion expecting 404 then
+ * reported as a pass.
+ *
+ * The union is only as good as the literals in it: the first cluster run
+ * rejected paths that had been written from assumption rather than read off
+ * the controllers, and the compiler had happily accepted all of them. Every
+ * entry here is checked against the v2 OpenAPI spec on stable/8.8, stable/8.9
+ * and stable/8.10 in camunda/camunda
+ * (`zeebe/gateway-protocol/src/main/proto/v2/`), and a new one should be added
+ * the same way — the type gives no protection against a path that never
+ * existed.
+ *
+ * Eleven entries failed that check. Four announced themselves as failures;
+ * the rest did not, because the test using each one expected a status list
+ * that the 404 from an unrouted path already satisfied. Checking the whole
+ * union against the spec, rather than only the paths that went red, is what
+ * found them.
+ */
+export declare const API_PATHS: readonly ["/authentication/me", "/authentication/me/authorizations/search", "/topology", "/license", "/status", "/system/usage-metrics", "/clock", "/clock/reset", "/setup/user", "/process-definitions/search", "/process-definitions/{processDefinitionKey}", "/process-definitions/{processDefinitionKey}/xml", "/process-definitions/{processDefinitionKey}/form", "/process-definitions/{processDefinitionKey}/statistics/element-instances", "/process-instances", "/process-instances/search", "/process-instances/cancellation", "/process-instances/migration", "/process-instances/modification", "/process-instances/incident-resolution", "/process-instances/{processInstanceKey}", "/process-instances/{processInstanceKey}/cancellation", "/process-instances/{processInstanceKey}/migration", "/process-instances/{processInstanceKey}/modification", "/process-instances/{processInstanceKey}/sequence-flows", "/process-instances/{processInstanceKey}/call-hierarchy", "/process-instances/{processInstanceKey}/incidents/search", "/process-instances/{processInstanceKey}/statistics/element-instances", "/deployments", "/resources/{resourceKey}", "/resources/{resourceKey}/deletion", "/decision-definitions/search", "/decision-definitions/{decisionDefinitionKey}", "/decision-definitions/{decisionDefinitionKey}/xml", "/decision-definitions/evaluation", "/decision-instances/search", "/decision-instances/{decisionEvaluationInstanceKey}", "/decision-requirements/search", "/decision-requirements/{decisionRequirementsKey}", "/decision-requirements/{decisionRequirementsKey}/xml", "/user-tasks/search", "/user-tasks/{userTaskKey}", "/user-tasks/{userTaskKey}/form", "/user-tasks/{userTaskKey}/assignment", "/user-tasks/{userTaskKey}/assignee", "/user-tasks/{userTaskKey}/completion", "/user-tasks/{userTaskKey}/variables/search", "/jobs/search", "/jobs/activation", "/jobs/{jobKey}", "/jobs/{jobKey}/completion", "/jobs/{jobKey}/failure", "/jobs/{jobKey}/error", "/messages/publication", "/messages/correlation", "/message-subscriptions/search", "/correlated-message-subscriptions/search", "/signals/broadcast", "/element-instances/search", "/element-instances/{elementInstanceKey}", "/element-instances/{elementInstanceKey}/variables", "/element-instances/ad-hoc-activities/{adHocSubProcessInstanceKey}/activation", "/variables/search", "/variables/{variableKey}", "/incidents/search", "/incidents/{incidentKey}", "/incidents/{incidentKey}/resolution", "/forms/{formKey}", "/documents", "/documents/{documentId}", "/batch-operations/search", "/batch-operations/{batchOperationKey}", "/batch-operations/{batchOperationKey}/suspension", "/batch-operations/{batchOperationKey}/resumption", "/batch-operations/{batchOperationKey}/cancellation", "/batch-operation-items/search", "/authorizations", "/authorizations/search", "/authorizations/{authorizationKey}", "/roles", "/roles/search", "/roles/{roleId}", "/roles/{roleId}/users/search", "/roles/{roleId}/users/{username}", "/roles/{roleId}/groups/search", "/roles/{roleId}/groups/{groupId}", "/roles/{roleId}/clients/search", "/roles/{roleId}/clients/{clientId}", "/roles/{roleId}/mapping-rules/search", "/roles/{roleId}/mapping-rules/{mappingRuleId}", "/groups", "/groups/search", "/groups/{groupId}", "/groups/{groupId}/users/search", "/groups/{groupId}/users/{username}", "/groups/{groupId}/roles/search", "/groups/{groupId}/clients/search", "/groups/{groupId}/clients/{clientId}", "/groups/{groupId}/mapping-rules/search", "/groups/{groupId}/mapping-rules/{mappingRuleId}", "/users", "/users/search", "/users/{username}", "/mapping-rules", "/mapping-rules/search", "/mapping-rules/{mappingRuleId}", "/tenants", "/tenants/search", "/tenants/{tenantId}", "/tenants/{tenantId}/users/search", "/tenants/{tenantId}/users/{username}", "/tenants/{tenantId}/groups/search", "/tenants/{tenantId}/groups/{groupId}", "/tenants/{tenantId}/roles/search", "/tenants/{tenantId}/roles/{roleId}", "/tenants/{tenantId}/clients/search", "/tenants/{tenantId}/clients/{clientId}", "/tenants/{tenantId}/mapping-rules/search", "/tenants/{tenantId}/mapping-rules/{mappingRuleId}"];
+export type ApiPath = (typeof API_PATHS)[number];

package/dist/utils/api/paths.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_PATHS = void 0;
+/**
+ * Every Orchestration Cluster REST v2 path this suite exercises.
+ *
+ * `buildUrl` accepts only these literals, so an endpoint that is renamed or
+ * mistyped fails to compile. The legacy shell suite concatenated path strings,
+ * where a typo produced a plausible 404 that an assertion expecting 404 then
+ * reported as a pass.
+ *
+ * The union is only as good as the literals in it: the first cluster run
+ * rejected paths that had been written from assumption rather than read off
+ * the controllers, and the compiler had happily accepted all of them. Every
+ * entry here is checked against the v2 OpenAPI spec on stable/8.8, stable/8.9
+ * and stable/8.10 in camunda/camunda
+ * (`zeebe/gateway-protocol/src/main/proto/v2/`), and a new one should be added
+ * the same way — the type gives no protection against a path that never
+ * existed.
+ *
+ * Eleven entries failed that check. Four announced themselves as failures;
+ * the rest did not, because the test using each one expected a status list
+ * that the 404 from an unrouted path already satisfied. Checking the whole
+ * union against the spec, rather than only the paths that went red, is what
+ * found them.
+ */
+exports.API_PATHS = [
+    // Authentication, cluster and system
+    '/authentication/me',
+    '/authentication/me/authorizations/search',
+    '/topology',
+    '/license',
+    '/status',
+    '/system/usage-metrics',
+    '/clock',
+    '/clock/reset',
+    '/setup/user',
+    // Process definitions
+    '/process-definitions/search',
+    '/process-definitions/{processDefinitionKey}',
+    '/process-definitions/{processDefinitionKey}/xml',
+    '/process-definitions/{processDefinitionKey}/form',
+    '/process-definitions/{processDefinitionKey}/statistics/element-instances',
+    // Process instances
+    '/process-instances',
+    '/process-instances/search',
+    '/process-instances/cancellation',
+    '/process-instances/migration',
+    '/process-instances/modification',
+    '/process-instances/incident-resolution',
+    '/process-instances/{processInstanceKey}',
+    '/process-instances/{processInstanceKey}/cancellation',
+    '/process-instances/{processInstanceKey}/migration',
+    '/process-instances/{processInstanceKey}/modification',
+    '/process-instances/{processInstanceKey}/sequence-flows',
+    '/process-instances/{processInstanceKey}/call-hierarchy',
+    '/process-instances/{processInstanceKey}/incidents/search',
+    '/process-instances/{processInstanceKey}/statistics/element-instances',
+    // Deployments and resources
+    '/deployments',
+    '/resources/{resourceKey}',
+    '/resources/{resourceKey}/deletion',
+    // Decisions
+    '/decision-definitions/search',
+    '/decision-definitions/{decisionDefinitionKey}',
+    '/decision-definitions/{decisionDefinitionKey}/xml',
+    // Evaluation is a collection-level POST carrying the decision id or key in
+    // the body — there is no per-key `/evaluate` sub-resource.
+    '/decision-definitions/evaluation',
+    '/decision-instances/search',
+    // Addressed by the compound `<decisionEvaluationKey>-<index>`.
+    '/decision-instances/{decisionEvaluationInstanceKey}',
+    '/decision-requirements/search',
+    '/decision-requirements/{decisionRequirementsKey}',
+    '/decision-requirements/{decisionRequirementsKey}/xml',
+    // User tasks
+    '/user-tasks/search',
+    '/user-tasks/{userTaskKey}',
+    '/user-tasks/{userTaskKey}/form',
+    '/user-tasks/{userTaskKey}/assignment',
+    '/user-tasks/{userTaskKey}/assignee',
+    '/user-tasks/{userTaskKey}/completion',
+    '/user-tasks/{userTaskKey}/variables/search',
+    // Jobs
+    '/jobs/search',
+    '/jobs/activation',
+    '/jobs/{jobKey}',
+    '/jobs/{jobKey}/completion',
+    '/jobs/{jobKey}/failure',
+    '/jobs/{jobKey}/error',
+    // Messages and subscriptions
+    '/messages/publication',
+    '/messages/correlation',
+    '/message-subscriptions/search',
+    '/correlated-message-subscriptions/search',
+    '/signals/broadcast',
+    // Element instances
+    '/element-instances/search',
+    '/element-instances/{elementInstanceKey}',
+    '/element-instances/{elementInstanceKey}/variables',
+    '/element-instances/ad-hoc-activities/{adHocSubProcessInstanceKey}/activation',
+    // Variables, incidents, forms, documents
+    '/variables/search',
+    '/variables/{variableKey}',
+    '/incidents/search',
+    '/incidents/{incidentKey}',
+    '/incidents/{incidentKey}/resolution',
+    '/forms/{formKey}',
+    '/documents',
+    '/documents/{documentId}',
+    // Batch operations
+    '/batch-operations/search',
+    '/batch-operations/{batchOperationKey}',
+    '/batch-operations/{batchOperationKey}/suspension',
+    '/batch-operations/{batchOperationKey}/resumption',
+    '/batch-operations/{batchOperationKey}/cancellation',
+    '/batch-operation-items/search',
+    // Authorizations
+    '/authorizations',
+    '/authorizations/search',
+    '/authorizations/{authorizationKey}',
+    // Roles
+    '/roles',
+    '/roles/search',
+    '/roles/{roleId}',
+    '/roles/{roleId}/users/search',
+    '/roles/{roleId}/users/{username}',
+    '/roles/{roleId}/groups/search',
+    '/roles/{roleId}/groups/{groupId}',
+    '/roles/{roleId}/clients/search',
+    '/roles/{roleId}/clients/{clientId}',
+    '/roles/{roleId}/mapping-rules/search',
+    '/roles/{roleId}/mapping-rules/{mappingRuleId}',
+    // Groups
+    '/groups',
+    '/groups/search',
+    '/groups/{groupId}',
+    '/groups/{groupId}/users/search',
+    '/groups/{groupId}/users/{username}',
+    '/groups/{groupId}/roles/search',
+    '/groups/{groupId}/clients/search',
+    '/groups/{groupId}/clients/{clientId}',
+    '/groups/{groupId}/mapping-rules/search',
+    '/groups/{groupId}/mapping-rules/{mappingRuleId}',
+    // Users and clients
+    '/users',
+    '/users/search',
+    '/users/{username}',
+    // Mapping rules
+    '/mapping-rules',
+    '/mapping-rules/search',
+    '/mapping-rules/{mappingRuleId}',
+    // Tenants
+    '/tenants',
+    '/tenants/search',
+    '/tenants/{tenantId}',
+    '/tenants/{tenantId}/users/search',
+    '/tenants/{tenantId}/users/{username}',
+    '/tenants/{tenantId}/groups/search',
+    '/tenants/{tenantId}/groups/{groupId}',
+    '/tenants/{tenantId}/roles/search',
+    '/tenants/{tenantId}/roles/{roleId}',
+    '/tenants/{tenantId}/clients/search',
+    '/tenants/{tenantId}/clients/{clientId}',
+    '/tenants/{tenantId}/mapping-rules/search',
+    '/tenants/{tenantId}/mapping-rules/{mappingRuleId}',
+];

package/dist/utils/api/tenancy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Multi-tenancy handling for REST v2 requests.
+ *
+ * On a multi-tenant cluster every tenant-aware endpoint needs the tenant
+ * supplied, but the endpoints disagree on where: search endpoints take it
+ * inside `filter`, mutations take it at the body root, job activation takes an
+ * array under `tenantIds`, and GETs take it as a query parameter. When
+ * multi-tenancy is off the cluster rejects the field entirely, so nothing is
+ * injected.
+ */
+import { type ApiConfig } from './config';
+export type TenantMode = 
+/** Pick `filter` or root by body shape — the default for most endpoints. */
+'auto'
+/** Always inside `filter` (search endpoints). */
+ | 'filter'
+/** Always at the body root (creation and mutation endpoints). */
+ | 'root'
+/** `tenantIds: [tenant]` — job activation only. */
+ | 'tenantIds'
+/** Endpoint is not tenant-aware (clock, identity, setup). */
+ | 'none';
+/**
+ * Applies the tenant to a request body. `auto` mirrors what the endpoints
+ * expect: a body that already filters gets the tenant added to that filter, a
+ * body that paginates or sorts without filtering gains one, and anything else
+ * is treated as a mutation and takes the tenant at the root.
+ */
+export declare function applyTenantToBody(body: unknown, mode: TenantMode, config?: ApiConfig): unknown;
+/** The `tenantId` query parameter for tenant-aware GET and DELETE requests. */
+export declare function tenantQueryParam(mode: TenantMode, config?: ApiConfig): Record<string, string>;