feat: Node.js CircuitBreaker with exponential OPEN cooldown — GH#4775

[balhar-jakub]

Closes #4775

Adds a CircuitBreaker state machine to the Node.js onboarding enabler EurekaClient with exponential OPEN cooldown.

Changes

• CircuitBreaker.js — new state machine (CLOSED→OPEN→HALF_OPEN→CLOSED) with exponential backoff: cooldownTime × 2^(N-1) capped at backoffMax
• EurekaClient.js — heartbeat and registry fetch scheduling rewritten to use setTimeout-based scheduling with circuit breaker gating; falls back to legacy setInterval when circuitBreaker.enabled=false
• defaultConfig.js — circuitBreaker config block (enabled, maxFailures=5, cooldownTime=60000, backoffMax=300000)
• 49 CircuitBreaker unit tests + 11 EurekaClient integration tests (AC1-AC9 + disabled fallback + registry fetch gate)
• EPL-2.0 license only on all modified files (stripped Apache/MIT from prior art)

[balhar-jakub]

QA + Security Review — PR #4793 (Closes #4775)

Verdict: ✅ APPROVED (pending CI)

Architecture Validation

Implementation matches the architect's solution design exactly:

• ✅ Standalone CircuitBreaker.js extending EventEmitter
• ✅ States: CLOSED → OPEN → HALF_OPEN → CLOSED
• ✅ Exponential OPEN cooldown: cooldownTime × 2^(openCycleCount-1) capped at backoffMax
• ✅ baseCooldown removed — cooldownTime serves as sole base
• ✅ Single shared circuit breaker for both heartbeat and registry fetch
• ✅ setTimeout-based scheduling with circuitBreaker.enabled=false fallback to legacy setInterval
• ✅ renew(callback = noop) backward-compatible signature
• ✅ stop() clears both _heartbeatTimeout and _registryFetchTimeout
• ✅ Config under eureka.circuitBreaker with all 4 keys (enabled, maxFailures, cooldownTime, backoffMax)
• ✅ 49 CircuitBreaker unit tests + 11 EurekaClient integration tests
• ✅ EPL-2.0 license only on all modified files

Pavel's Lens — All 8 Rules

Rule	Status	Notes
1. Config consistency	✅ PASS	defaultConfig.js has circuitBreaker block with all 4 keys and defaults. No start.sh or Docker config needed for Node.js client library.
2. Deduplication	✅ PASS	No duplicated logic. _computeOpenCooldown() used by both CLOSED backoff and OPEN cooldown — clean reuse within the class.
3. Null safety	✅ PASS	this._openedAt === null guarded in _cooldownExpired(). `cbConfig
4. Test parametrization	✅ PASS	49 unit tests + 11 integration tests. Tests use sinon.useFakeTimers() for deterministic timing. Edge cases include overflow resilience (50 rapid OPEN cycles).
5. Security boundaries	✅ PASS	No new endpoints, no TLS changes, no auth/authz modifications. Circuit breaker is internal retry logic only. No secrets exposed.
6. z/OS awareness	✅ PASS	Configurable timeouts (cooldownTime, backoffMax) allow tuning for slow mainframe environments. No hardcoded timing assumptions.
7. Log quality	✅ PASS	WARN for circuit open (actionable), INFO for half-open/close (diagnostic). Transition messages include state names: "CLOSED → OPEN". Appropriate levels.
8. TODO tracking	✅ PASS	No TODO/FIXME/HACK comments in modified files.

Codebase Grep Results

• No TODOs/FIXMEs in onboarding-enabler-nodejs/src/
• No hardcoded secrets/tokens in new code
• No duplicate patterns across modules
• Null checks are proper (_openedAt === null guard, || {} fallbacks)
• No schema files to update (Node.js client library, not Java/Spring)
• No OpenAPI definitions affected (client library, not server-side API)
• No docs-site changes needed (internal retry implementation detail)

Build & Tests

• DCO: ✅ PASS (all 6 commits signed off by Jakub Balhar)
• WIP: ✅ PASS
• Local build: BUILD SUCCESSFUL (./gradlew :onboarding-enabler-nodejs:build)
• Local tests: 137 passing, 1 pre-existing failure (yml config test unrelated to this PR)
• CI: Pending (5 checks running — BuildAndTest, Identify security, InfinispanJGroup, PublishJib, Register)

Minor Observations (non-blocking)

1. Shared circuit breaker across heartbeat + registry fetch: Both operations share one breaker. A successful registry fetch resets the failure counter even if heartbeats are failing. This is architect-designed and correct — both target the same Discovery Service.

2. eslint-disable for no-underscore-dangle: Applied to both CircuitBreaker.js and EurekaClient.js. Required because internal state fields use underscore prefix (_state, _openedAt, _openCycleCount). This is a reasonable pattern for distinguishing internal from public API.

[balhar-jakub]

CI Status Update — PR #4793

BuildAndTest FAILURE: Pre-existing CI infrastructure issue (NOT caused by this PR)

The BuildAndTest CI check fails at :onboarding-enabler-nodejs:npmInstall with:

npm warn EBADENGINE Unsupported engine {
  package: '@zowe/apiml-onboarding-enabler-nodejs@3.2.6',
  required: { npm: '>=10.9.8', node: '>=24.16.0' },
  current: { node: 'v24.10.0', npm: '10.9.0' }
}

Root cause: The CI runner's Node.js version (v24.10.0) is older than the engine requirement in onboarding-enabler-nodejs/package.json (node: '>=24.16.0'). This requirement exists on v3.x.x itself — confirmed by git show origin/v3.x.x:onboarding-enabler-nodejs/package.json.

Impact: ANY PR against v3.x.x will fail CI with the same npm install error. This is unrelated to the circuit breaker changes.

No changes to package.json or package-lock.json were made in this PR (verified: git diff origin/v3.x.x..HEAD -- onboarding-enabler-nodejs/package.json returns empty).

InfinispanJGroupStabilityTest: Cancelled (transient GitHub Actions issue)

This job was cancelled before running any steps. Unrelated to Node.js changes.

All other checks: ✅ PASS

• DCO: pass
• WIP: pass
• PR Instructions: pass
• Register: pass
• Identify security related PR: pass
• PublishJibContainers: pass
• SonarCloud: pass
• SonarCloud Code Analysis: pass
• All CI test sub-jobs (CITests, CITestsRegistration, etc.): pass (run within PublishJibContainers)

[tapheret2]

Review pass

Static review of the open diff:

• Looks focused enough for a community review pass
• Please ensure tests/docs match any behavior change
• Call out breaking changes in the PR body if any

Thanks — re-submitted after rate-limit cooldown.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud