chore: baseline snapshot — prior-session work + ha-consistency-invariants spec family
Pre-existing uncommitted work: ha-repl-hardening payload data plane (7.x), heartbeat liveness fix (Req 1.3), connection-reuse ASAN fixes, doc cleanup. New: ha-consistency-invariants umbrella (requirements/design/research) and its four implementation sub-specs (specs generated via batch, cross-spec review applied), steering roadmap + product.md Raft+CP decision.
This commit is contained in:
parent
084244941b
commit
06135954ff
88 changed files with 25611 additions and 5285 deletions
|
|
@ -1,108 +1,7 @@
|
|||
# XCE Controller: Future Work Items
|
||||
|
||||
> **Status**: Tracked from config-replication-design.md review
|
||||
> **Last Updated**: 2026-05-12
|
||||
|
||||
---
|
||||
|
||||
## 1. Admin Config Tool (prerequisite for Phase 2)
|
||||
|
||||
`OP_upgradeConfig` requires an admin tool to drive it. The tool must:
|
||||
|
||||
- Encode a `ClusterConfig` YAML/JSON file to Cap'n Proto binary
|
||||
- Compute SHA-256 over the binary bytes
|
||||
- Connect to the primary controller's endpoint (SSL, same CA as controllers)
|
||||
- Send `OP_upgradeConfig` with the binary blob and SHA-256
|
||||
- Display the reply: new version tag, acked count, and any error message
|
||||
- Poll `OP_probe` after restart to confirm the primary is back online with the new config
|
||||
|
||||
Suggested interface: `xce-config push --controller <host:port> --config cluster.yaml`
|
||||
|
||||
---
|
||||
|
||||
## 2. Quorum-ACK Gate Before Restart (§14.4 extension)
|
||||
|
||||
Current `OP_upgradeConfig` restarts the primary after best-effort push to standbys.
|
||||
A quorum-ACK gate would refuse to restart unless a minimum number of standbys
|
||||
acknowledge the push, preventing silent rollback when all standbys are offline.
|
||||
|
||||
Requires: `OP_upgradeConfig` reply to include `--require-standby-ack=N` flag.
|
||||
|
||||
---
|
||||
|
||||
## 3. OP_heartbeat Peers Cross-Validation (§11.2)
|
||||
|
||||
Include a hash of the local `--peers` string in the heartbeat request. If two
|
||||
candidates disagree on the peers list, log ERROR. Detects misconfigured nodes
|
||||
at election time rather than silently producing dual-primary split-brain.
|
||||
|
||||
---
|
||||
|
||||
## 4. Lost and Found Drain Command (§6.5 extension)
|
||||
|
||||
`xcecli lost-and-found drain` — reassign or cancel sidelined jobs, reset
|
||||
`lost_and_found_job_count` to 0. Automates operator cleanup after config upgrade.
|
||||
|
||||
---
|
||||
|
||||
## 5. OP_upgradeConfig Standby Redirect (§10.12 verification)
|
||||
|
||||
Test that a standby correctly returns an error reply with the primary's address
|
||||
when an admin tool sends `OP_upgradeConfig` to a standby, and the admin tool
|
||||
retries against the primary.
|
||||
|
||||
---
|
||||
|
||||
## 6. validate_host() Implementation Plan
|
||||
|
||||
`validate_host()` is currently a stub that returns success for all peers. Before
|
||||
`CONF_ENABLE_UPGRADE_CONFIG` can be set to 1, it MUST be enhanced with a real
|
||||
authorisation check. Minimum viable implementation:
|
||||
|
||||
- Verify the peer's X.509 certificate Common Name (CN) against a configured
|
||||
allowlist of authorised admin hosts.
|
||||
- Add `--admin-cn` CLI flag or `admin_cn_list` config field to specify allowed CNs.
|
||||
- Reject `OP_upgradeConfig` requests from peers whose CN is not in the allowlist
|
||||
with a clear error message.
|
||||
- Log all rejected attempts at WARN level with peer CN and IP.
|
||||
|
||||
Future extensions (not required for gate removal): IP allowlist, role-based
|
||||
access, mutual-TLS with admin-specific CA.
|
||||
|
||||
---
|
||||
|
||||
## 7. OP_replConfig Access Control Hardening
|
||||
|
||||
`OP_replConfig` currently serves the full cluster config blob to any peer that
|
||||
completes an SSL handshake with a CA-signed cert (trusted-LAN model, §5.3).
|
||||
Enhancements to consider:
|
||||
|
||||
- Verify the requesting peer is a known controller (listed in `--peers`) before
|
||||
serving the config blob.
|
||||
- Rate-limit `OP_replConfig` requests per peer to prevent repeated disk I/O on
|
||||
the primary.
|
||||
- Add a `minimum_role` check (e.g., only serve to `HostRole_controller` peers,
|
||||
not arbitrary SSL clients).
|
||||
|
||||
---
|
||||
|
||||
## 8. Lost-and-Found Internal Keyword Validation
|
||||
|
||||
The name `"lost_and_found"` is an internal controller keyword for synthetic
|
||||
queue and host entries created during WAL recovery (§6.5). The controller
|
||||
rejects this name at both `load_primary_config()` and `OP_upgradeConfig` entry
|
||||
points.
|
||||
|
||||
**Config tool responsibility**: The admin config tool (Future Work §1) MUST
|
||||
validate that user-authored config files do not use the reserved names
|
||||
`"lost_and_found"` for any queue or host. The tool should emit a clear error
|
||||
and refuse to encode the config blob. This provides defence-in-depth: the
|
||||
controller enforces at runtime, and the tool prevents at authoring time.
|
||||
|
||||
**Migration path for pre-existing clusters**: If a cluster already has a
|
||||
user-defined queue or host named `"lost_and_found"` before upgrading to this
|
||||
controller version, the operator must rename it in the cluster config YAML
|
||||
before the upgrade. The admin config tool will validate this; if bypassing
|
||||
the tool and hand-crafting a Cap'n Proto blob, the controller's
|
||||
`load_primary_config()` will FATAL with a message identifying the reserved
|
||||
name. See `config-replication-design.md` §6.5 and §7.1.
|
||||
> **Moved (2026-06-10)**: All items merged into the single consolidated future-work document at
|
||||
> [`.kiro/steering/roadmap.md`](../../.kiro/steering/roadmap.md).
|
||||
>
|
||||
> Section mapping: §1+§8 → admin-config-tool (backlog); §2 → superseded by ha-consistency-invariants Req 5;
|
||||
> §3, §4, §5, §6, §7 → Hardening / Direct-Implementation Items.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue