lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
myxce/.kiro/specs/controller-peers-env-fallback/requirements.md
Rongsong Shen 668e3f6893
chore: persist OpenWolf state, controller-peers-env-fallback spec, and scheduler backlog notes 
- .wolf/anatomy-index.json, anatomy.md, memory.md: OpenWolf hook-maintained
  project index and session log, refreshed by this session's activity.
- .kiro/specs/controller-peers-env-fallback/: spec scaffold (brief,
  requirements, design, research) from prior spec-init work.
- issues/new_requirements.md: scheduler simulator enhancement backlog
  (info-command improvements, pend-reason detail, decision tracing).

Excluded as non-persistent: issues/Issues.md (empty placeholder),
src/lib/testsuite/test_xcectx_reconnect_race.c (self-documented as an
ASAN stress reproduction only, not a committed regression test, and not
wired into meson.build), scheduler-replay-20260922-095207.replay
(4MB binary debug capture, no .replay files are tracked in this repo).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-23 03:19:52 +00:00

7.8 KiB
Raw Blame History

Requirements Document

Introduction

Operators and deploy/test scripts must retype the full --peers candidate list on every invocation of controller, scheduler, worker, and harness/xce_test, and the --controller target on every invocation of xceadmin — there is no way to set a default once per session or environment for the four --peers-based components today. --peers is optional for all four, and omitting it intentionally selects each component's existing standalone/single-controller behavior (confirmed: each component's own startup log already names this an intentional path, not an error) — that behavior must keep working unchanged. xceadmin already solved the equivalent problem for its own --controller option via the XCEADMIN_CONTROLLER environment variable (bug-1566), and, separately, xceadmin's --controller option can already accept a comma-separated list of candidates and will try each in order until one is reachable (bug-1821), rather than only a single target.

This feature introduces one new environment variable, XCE_CONTROLLER_PEERS, read as a fallback default by all five components (controller, scheduler, worker, harness/xce_test, and xceadmin) whenever their respective connection-target option (--peers or --controller) is not explicitly given on the command line — and only then; an explicit option value is always used exactly as it is today, with the environment variable never consulted. xceadmin's existing XCEADMIN_CONTROLLER variable keeps working exactly as it does today, as a lower-priority fallback beneath the new variable.

Boundary Context

  • In scope: A single new environment variable, XCE_CONTROLLER_PEERS, providing the default connection target for controller, scheduler, worker, harness/xce_test (via their existing --peers option) and xceadmin (via its existing --controller option), consulted only when the corresponding command-line option is omitted.
  • Out of scope: The apiserver (its controller connection comes from a configuration file, not a command-line option, and is unaffected) and xcecli's --url option (a different target — the apiserver, not a controller — and unaffected). Any change to src/tools/deploy-ha.sh's generated scripts, which continue to pass --peers/--controller explicitly exactly as they do today. Any change to what each component does today when its connection-target option is omitted and no environment variable applies either (today's standalone/single-controller behavior is preserved exactly).
  • Adjacent expectations: xceadmin's existing multi-candidate, try-until-reachable behavior for --controller (bug-1821) and its existing XCEADMIN_CONTROLLER fallback (bug-1566) are both reused unmodified — this feature only changes what value feeds into that already-existing behavior, never how that behavior itself works.

Requirements

Requirement 1: Default peers candidate list for --peers-based components

Objective: As an operator running controller, scheduler, worker, or harness/xce_test, I want a default --peers candidate list available via an environment variable, so that I don't have to retype it on every invocation while still being able to run any single invocation without it.

Acceptance Criteria

  1. The peers-based component (controller, scheduler, worker, or harness/xce_test) shall recognize XCE_CONTROLLER_PEERS as the environment variable providing its default --peers candidate list.
  2. When the peers-based component starts with an explicit --peers argument, the peers-based component shall use that argument's value and shall not consult XCE_CONTROLLER_PEERS.
  3. When the peers-based component starts without an explicit --peers argument and XCE_CONTROLLER_PEERS is set to a non-empty value, the peers-based component shall use that value as its --peers candidate list, exactly as if it had been supplied via --peers.
  4. When the peers-based component starts without an explicit --peers argument and XCE_CONTROLLER_PEERS is unset or empty, the peers-based component shall behave exactly as it does today when started with no --peers argument (today's standalone/single-controller behavior, unchanged).
  5. If the candidate-list value in use — from either --peers or XCE_CONTROLLER_PEERS — fails to parse as a valid candidate list, the peers-based component shall report a parse-error message, and that message shall identify whether the invalid value came from the --peers argument or from the XCE_CONTROLLER_PEERS environment variable.
  6. The peers-based component's --peers help/usage text shall document XCE_CONTROLLER_PEERS as an environment-variable fallback for that option.

Requirement 2: Default controller candidate list for xceadmin

Objective: As an xceadmin operator, I want --controller to fall back to the same environment variable the other XCE components use, so that one variable configures every tool's default connection target.

Acceptance Criteria

  1. When an xceadmin subcommand that accepts --controller runs without an explicit --controller option and XCE_CONTROLLER_PEERS is set to a non-empty value, xceadmin shall derive its controller candidate list from XCE_CONTROLLER_PEERS.
  2. Where a candidate entry in XCE_CONTROLLER_PEERS carries a name= prefix, xceadmin shall remove the prefix before treating that entry as a controller candidate.
  3. When xceadmin derives its controller candidate list from XCE_CONTROLLER_PEERS, xceadmin shall attempt each resulting candidate in the same order the variable lists them, moving to the next candidate only when the current one is unreachable — the same behavior xceadmin already provides for an explicit multi-candidate --controller value.
  4. When an xceadmin subcommand that accepts --controller runs with an explicit --controller option, xceadmin shall use that option's value and shall not consult XCE_CONTROLLER_PEERS or XCEADMIN_CONTROLLER.
  5. When an xceadmin subcommand that accepts --controller runs without an explicit --controller option, and XCE_CONTROLLER_PEERS is unset or empty, and XCEADMIN_CONTROLLER is set to a non-empty value, xceadmin shall use XCEADMIN_CONTROLLER exactly as it does today.
  6. When an xceadmin subcommand that accepts --controller runs without an explicit --controller option, and both XCE_CONTROLLER_PEERS and XCEADMIN_CONTROLLER are unset or empty, xceadmin shall fall back to its existing hardcoded default controller target, unchanged.
  7. The --controller option's help text shall document XCE_CONTROLLER_PEERS as its preferred environment-variable fallback, alongside the existing XCEADMIN_CONTROLLER mention.

Requirement 3: Documentation of the new environment variable

Objective: As an operator or future contributor, I want the project's build/deployment documentation to describe XCE_CONTROLLER_PEERS, so that I can discover and use it without reading source code.

Acceptance Criteria

  1. The project's build/deployment steering documentation shall describe XCE_CONTROLLER_PEERS: which components read it, its value format, and its precedence relative to each component's connection-target option (--peers or --controller).
  2. The HA cluster deployment guidance shall note that XCE_CONTROLLER_PEERS is available as an alternative to passing --peers/--controller explicitly on every generated script invocation, without stating or implying any change to what those generated scripts themselves pass.
  3. The multi-host verification guidance shall note the same availability wherever it currently documents driving deployment via --peers, without stating or implying any change to that verification's own generated invocations.