lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
myxce/.kiro/specs/controller-status/requirements.md
Rongsong Shen 5b14bcf832 spec(controller-status): requirements (rename from controller-lsid) 
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.
2026-06-20 03:34:14 +00:00

2.8 KiB
Raw Blame History

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