Rongsong Shen
5b14bcf832
EARS requirements for a controller status query (XCE lsid analog): primary identity (unknown when unelected), answered-by node+role (distinct from cluster view), configured peers+count, committed config version + content checksum (catch same-version divergence), term/commit-apply/fenced/cluster-name, failover-aware delivery, test-client command, and wait-primary switching its probe to it. C tier only.
31 lines
2.8 KiB
Markdown
31 lines
2.8 KiB
Markdown
# Requirements Document
|
|
|
|
## Project Description (Input)
|
|
|
|
Add an LSF-`lsid`-style controller status opcode (C tier only) so a client can query basic cluster/controller identity and health in one cheap call.
|
|
|
|
**Returns:**
|
|
- Which node is the current PRIMARY (name; empty/none if mid-election)
|
|
- The responding node's role (PRIMARY/STANDBY/ELECTING/INIT)
|
|
- The configured controllers/peers (name + host:port list and count)
|
|
- The configuration version (the HA committed `config_tag`)
|
|
- Additional status: current term (election epoch), `committed_lsn`/`applied_lsn` (catch-up/health), cluster name, serving/fenced state
|
|
|
|
Answerable by ANY node (a standby reports who the primary is from its ctrlhello/heartbeat state), so `lsid` works even when the query doesn't land on the primary; it is a failover-aware READ like the existing `clusterconf` op. All the underlying data already exists in `src/controller/ha.h` (`ha->role`, `ha->term`, `committed_config_tag`, `committed_lsn`, peer/candidate list).
|
|
|
|
**Components (C tier):**
|
|
1. `src/schema/controller.capnp` — new `CtrlInfo`/`CtrlStatus` struct + request opcode + reply-union member, modeled on the existing `clusterconf` opcode (`controller.capnp:489`).
|
|
2. Controller `handle_ctrlinfo` handler mirroring `handle_clusterconf`.
|
|
3. libxce `xce_ctrlinfo_req` / `xce_ctrlinfo` / `xcecli_ctrlinfo` (+ free helper) as a failover-aware read.
|
|
4. `src/controller/testsuite/test.c` — a `ctrlinfo`/`lsid` client command that prints the status, AND switch `cmd_wait_primary`'s probe from `joblist_query` to this lighter, more-direct status op. (`wait-primary` currently piggybacks on `joblist` purely to avoid a new opcode; with this op it becomes a cheap "is a serving primary present + who" probe that can also report the elected primary and term — better diagnostics, directly useful for the `ha-commit-durability` Phase 6 liveness / >60s-election investigation.)
|
|
|
|
**KEY DESIGN DECISION the spec must resolve:** whether to EXTEND the existing `clusterconf` opcode (which already returns much richer cluster detail — name/resources/queues/workers) with these HA-status fields, OR add a separate lean status op. `lsid` wants a fast focused identity/health view, not the full resource/queue/worker dump, so the leaning is a dedicated lean op, but the spec should weigh reuse vs separation explicitly.
|
|
|
|
**IN SCOPE:** C tier only (controller opcode + libxce + `xce_test` command + `wait-primary` integration).
|
|
|
|
**OUT OF SCOPE:** the Go CLI/REST `xce lsid` surface (a later pass); changing HA/election/replication behavior (this only READS existing HA state); structured/JSON output beyond the capnp reply.
|
|
|
|
This is the "controller status/probe opcode" that the `xce-test-e2e-primitives` spec explicitly deferred as out-of-scope.
|
|
|
|
## Requirements
|
|
<!-- Will be generated in /kiro-spec-requirements phase -->
|