myxce/src/docs/FUTURE_WORK.md

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.