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