# 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.