Node.js EurekaClient: interval configuration never read from process.env

[balhar-jakub]

Description

The Node.js onboarding enabler EurekaClient merges configuration from four sources:

// EurekaClient.js:116
this.config = merge({}, defaultConfig, defaultYml, envYml, config);

Layer	Source
1	defaultConfig.js (hardcoded defaults)
2	eureka-client.yml
3	eureka-client-{env}.yml
4	Constructor config parameter

There is no layer that reads individual properties from process.env. The only process.env access in the entire module is at line 107, used exclusively to select the YAML file suffix:

const env = process.env.EUREKA_ENV || process.env.NODE_ENV || "development";

Impact

Properties like EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS and EUREKA_CLIENT_INSTANCEINFOREPLICATIONINTERVALSECONDS are never consumed. This means the Node.js enabler cannot be configured via the standard Zowe pattern of zowe.yaml → environment variable translation. Configuration can only be supplied through YAML files or the programmatic constructor parameter.

Expected behavior

After the YAML layers and before the constructor parameter, a step should read relevant Eureka configuration properties from process.env to allow runtime overrides via environment variables.

Files

• onboarding-enabler-nodejs/src/EurekaClient.js:116
• onboarding-enabler-nodejs/src/defaultConfig.js

[balhar-jakub]

Problem Analysis — Node.js EurekaClient: interval configuration never read from process.env (#4774)

Refined Problem Statement

The Node.js onboarding enabler's EurekaClient exposes no way to configure Eureka heartbeat and registry-fetch intervals via environment variables. This breaks the standard Zowe configuration pattern where zowe.yaml properties are translated into environment variables that the enabler consumes at startup.

Real-world scenario: A system programmer deploys a Node.js microservice using the Zowe onboarding enabler. They set components.<service>.eureka.client.registryFetchIntervalSeconds: 60 in zowe.yaml. Zowe's configuration translation layer converts this to EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS=60 in the process environment. But the Node.js enabler never reads process.env.EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS — it only reads this.config.eureka.registryFetchInterval, which was set from defaultConfig.js (30s hardcoded) and YAML files. The sysprog's configuration is silently ignored.

Persona: System programmer responsible for tuning Zowe services in production. They expect environment-variable-based overrides to work consistently across all enablers (Java and Node.js).

Current Architecture Touchpoints

Layer	Source	Line
1	defaultConfig.js — hardcoded defaults	N/A
2	eureka-client.yml — file in CWD	EurekaClient.js:74
3	eureka-client-{env}.yml — env-specific file	EurekaClient.js:75
4	Constructor config parameter	EurekaClient.js:78

The merge chain is merge({}, defaultConfig, defaultYml, envYml, config) at EurekaClient.js:78. After the merge, properties are read throughout the class as this.config.eureka.heartbeatInterval, this.config.eureka.registryFetchInterval, etc.

The only process.env access in the entire module is on line 69, used exclusively to select the YAML file suffix: const env = process.env.EUREKA_ENV || process.env.NODE_ENV || 'development';.

The circuit breaker configuration (circuitBreaker.enabled, maxFailures, cooldownTime, backoffMax) has the same gap — none of these are readable from environment variables either.

Scope

In scope:

• Add a configuration layer that reads Eureka interval properties from process.env between the YAML layers (layer 3) and the constructor parameter (layer 4)
• At minimum: heartbeatInterval, registryFetchInterval (the two properties that control scheduling intervals)
• Use environment variable naming consistent with the Java Eureka client conventions used elsewhere in Zowe (EUREKA_CLIENT_*)

Out of scope:

• Changing the existing YAML or constructor-config behavior — those layers continue to work as before
• Adding env-var support for every single config property in defaultConfig.js (though the architect should evaluate which ones are most valuable)
• Java-side EurekaClient changes

Acceptance Criteria

1. When EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS is set in the environment, this.config.eureka.registryFetchInterval reflects its value (in milliseconds), overriding the YAML/default value
2. When EUREKA_CLIENT_INSTANCEINFOREPLICATIONINTERVALSECONDS is set in the environment, this.config.eureka.heartbeatInterval reflects its value (in milliseconds), overriding the YAML/default value
3. When neither env var is set, existing behavior is unchanged — YAML and default values apply as before
4. The constructor config parameter continues to have highest precedence (overrides env vars)
5. Environment variable values that cannot be parsed as positive integers are either rejected with a clear error or logged as a warning with a fallback to the YAML/default value
6. Existing unit tests pass, and new tests cover the env-var-override behavior
7. The circuit breaker configuration properties (maxFailures, cooldownTime, backoffMax) are also made readable from process.env using the same pattern

Design Questions for the Architect

1. Naming convention: The Java Eureka client uses seconds-based env vars (e.g., EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS), but the Node.js enabler internally uses milliseconds. Should the env vars be seconds (with conversion to ms) for consistency with the Java side, or milliseconds for consistency with the internal API?
2. Which properties? The issue specifically mentions registryFetchInterval and heartbeatInterval. Should the circuit breaker properties (maxFailures, cooldownTime, backoffMax) also be exposed via env vars? What about clusterRefreshInterval, maxRetries, requestRetryDelay?
3. Error handling: If an env var is set to a non-numeric value, should the enabler fail-fast at startup or log a warning and use the YAML/default fallback?
4. Merge location: Should the env-var layer be inserted between YAML layers and constructor config (preserving constructor override), or should it be the lowest-precedence layer (after defaults, before YAML files)?
5. Circuit breaker env vars: If circuit breaker properties are also exposed, what naming convention? EUREKA_CLIENT_CIRCUITBREAKER_MAXFAILURES? Or flat like EUREKA_CLIENT_CB_MAXFAILURES?

Constraints

• Must not change the public constructor API of Eureka — existing callers pass config objects and must continue to work
• Must preserve the existing precedence order: constructor > env > YAML files > defaults
• Changes limited to onboarding-enabler-nodejs/src/ — no Java-side modifications
• Must follow existing code style: ES modules, lodash.merge for config assembly, JSDoc comments
• No new npm dependencies without strong justification

[balhar-jakub]

Solution Design — Node.js EurekaClient: env-var config for intervals (#4774)

High-Level Architecture

Approach: Insert a new process.env configuration layer into the existing merge chain with a lightweight, data-driven envConfig module. No new npm dependencies, no constructor API changes.

merge({}, defaultConfig, defaultYml, envYml, envConfig(), config)
                       ^defaults  ^file     ^env-file  ^env-vars  ^constructor (highest)

New file: onboarding-enabler-nodejs/src/envConfig.js
Modified file: onboarding-enabler-nodejs/src/EurekaClient.js (line 116 — one line change + import)

Design Decisions

Q1: Naming convention — seconds or milliseconds?

Decision: Seconds in env vars, milliseconds internally. The env var names match the Java Eureka client convention (EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS), which is what Zowe's zowe.yaml → env translation layer already produces. The module converts seconds → milliseconds (× 1000) before merging, so the internal API (this.config.eureka.registryFetchInterval) remains in ms. This preserves consistency with the Java side while keeping the internal API unchanged.

Q2: Which properties?

Decision: registryFetchInterval and heartbeatInterval only. These are the two properties that control scheduling intervals and are the ones specifically cited in the issue. The circuit breaker properties (maxFailures, cooldownTime, backoffMax) do NOT exist in the current codebase — they are being implemented separately in #4775. The envConfig module is designed with a data-driven ENV_MAP array so that #4775 (or any future property) can add entries without structural changes.

Properties in defaultConfig.js and their env-var status:

Property	Env Var	Included?	Rationale
registryFetchInterval	EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS	✅ Yes	Issue target
heartbeatInterval	EUREKA_CLIENT_INSTANCEINFOREPLICATIONINTERVALSECONDS	✅ Yes	Issue target
maxRetries	—	❌ Deferred	Not time-sensitive; can be added later
requestRetryDelay	—	❌ Deferred	Not time-sensitive; can be added later
clusterRefreshInterval	—	❌ Deferred	Not time-sensitive; can be added later
maxFailures	—	❌ N/A	Does not exist yet (#4775)
cooldownTime	—	❌ N/A	Does not exist yet (#4775)
backoffMax	—	❌ N/A	Does not exist yet (#4775)

Q3: Error handling

Decision: Log a warning and fall back to YAML/default. Fail-fast would crash the entire service for a misconfigured env var — too aggressive for a config tuning parameter. The module logs via the existing Logger class at warn level. Invalid values (non-numeric, zero, negative) produce:

[warn] Invalid value for EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS: "sixty". Expected a positive integer. Using default.

The property is simply omitted from the returned config object, so the merge chain falls through to the next layer (YAML files → defaults).

Q4: Merge location

Decision: Between envYml and config (constructor parameter). This preserves the stated precedence: constructor > env > YAML files > defaults. The constructor config parameter remains the highest-precedence override. If a user passes { eureka: { registryFetchInterval: 5000 } } to the constructor, it defeats both env vars and YAML.

Q5: Circuit breaker env var naming

Deferred to #4775. When circuit breaker properties are implemented, they should follow the same flat naming convention as the interval properties: EUREKA_CLIENT_MAXFAILURES, EUREKA_CLIENT_COOLDOWNTIME, EUREKA_CLIENT_BACKOFFMAX (all seconds-based). The envConfig.js module's ENV_MAP array makes adding these a one-line-per-property change.

Implementation Plan

Step 1: Create onboarding-enabler-nodejs/src/envConfig.js

A data-driven module with an ENV_MAP array that:

• Maps env var names → eureka config keys → time unit (seconds or milliseconds)
• Parses each env var as a positive integer
• Converts seconds-based values to milliseconds
• Logs warnings on invalid values, returns undefined for that property (skip in merge)
• Returns a partial config object { eureka: { registryFetchInterval: 60000, ... } }

// envConfig.js — maps EUREKA_CLIENT_* env vars to eureka config properties
import Logger from './Logger.js';

const logger = new Logger();

const ENV_MAP = [
  { env: 'EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS',          key: 'registryFetchInterval',  unit: 'seconds' },
  { env: 'EUREKA_CLIENT_INSTANCEINFOREPLICATIONINTERVALSECONDS', key: 'heartbeatInterval',      unit: 'seconds' },
  // Future: add entries here for #4775 circuit breaker properties
  // { env: 'EUREKA_CLIENT_MAXFAILURES',   key: 'maxFailures',   unit: 'milliseconds' },
  // { env: 'EUREKA_CLIENT_COOLDOWNTIME',  key: 'cooldownTime',  unit: 'seconds' },
  // { env: 'EUREKA_CLIENT_BACKOFFMAX',    key: 'backoffMax',    unit: 'seconds' },
];

function parsePositiveInt(envName) {
  const raw = process.env[envName];
  if (raw === undefined || raw === '') return undefined;
  const parsed = parseInt(raw, 10);
  if (isNaN(parsed) || parsed <= 0) {
    logger.warn(`Invalid value for ${envName}: "${raw}". Expected a positive integer. Using default.`);
    return undefined;
  }
  return parsed;
}

export default function envConfig() {
  const result = { eureka: {} };
  for (const { env, key, unit } of ENV_MAP) {
    const value = parsePositiveInt(env);
    if (value !== undefined) {
      result.eureka[key] = unit === 'seconds' ? value * 1000 : value;
    }
  }
  return result;
}

~30 lines. No npm dependencies. ES module export.

Step 2: Modify EurekaClient.js (line 116)

Two changes:

1. Add import: import envConfig from './envConfig.js'; (next to the defaultConfig import)
2. Change line 116 from:

   this.config = merge({}, defaultConfig, defaultYml, envYml, config);

   to:

   this.config = merge({}, defaultConfig, defaultYml, envYml, envConfig(), config);

Step 3: Add tests in onboarding-enabler-nodejs/test/EurekaClient.test.js

New describe('env var configuration', ...) block with:

1. env var overrides YAML default — set process.env.EUREKA_CLIENT_REGISTRYFETCHINTERVALSECONDS = '60' before constructing, verify client.config.eureka.registryFetchInterval === 60000
2. env var overrides YAML default (heartbeat) — same pattern for EUREKA_CLIENT_INSTANCEINFOREPLICATIONINTERVALSECONDS
3. constructor overrides env var — set both env var and constructor config.eureka.registryFetchInterval, verify constructor wins
4. missing env var — no change — don't set env var, verify values come from defaults (30000)
5. invalid env var — fallback — set env var to "abc", verify it falls back to default + logs warning
6. zero env var — fallback — set env var to "0", verify it falls back to default

Step 4: Verify

cd /home/balda/zowe/api-layer
export JAVA_HOME=/home/balda/.sdkman/candidates/java/17.0.18.1-sem
export PATH=$JAVA_HOME/bin:$PATH
./gradlew :onboarding-enabler-nodejs:build

Precedence Chain (After Change)

Layer	Source	Precedence
1	defaultConfig.js	Lowest
2	eureka-client.yml	↑
3	eureka-client-{env}.yml	↑
4	process.env (via envConfig.js)	↑
5	Constructor config parameter	Highest

Edge Cases & Risks

Case	Behavior
Env var = "-1"	Warning logged, falls back to YAML/default
Env var = "0"	Warning logged, falls back to YAML/default (zero would break setInterval)
Env var = ""	Treated as unset, falls through silently
Env var = not-a-number	Warning logged, falls back to YAML/default
Env var = "3.5"	parseInt truncates to 3 → 3000ms. Documented edge case — use integer values
Constructor passes same key	Constructor wins (lodash.merge, last-write-wins)
Both env vars unset	No eureka key in returned object → merge skips it, existing behavior preserved
process.env is empty (test env)	envConfig() returns { eureka: {} }, merge is a no-op

Files Created/Modified

File	Action	Lines
onboarding-enabler-nodejs/src/envConfig.js	New	~30
onboarding-enabler-nodejs/src/EurekaClient.js	Modify	+2 (import + 1 line change)
onboarding-enabler-nodejs/test/EurekaClient.test.js	Append tests	~80