Shard Controller
The Go controller is the optional control plane for distributing global shard ownership across multiple physical PXE nodes.
It does not replace the bare-metal data plane. Each PXE node still owns its own transport/TLS/Gateway execution; the controller decides who owns which shards and for how long.
Authenticated request signing/TLS and durable per-device identity are still required before this controller should be exposed outside a trusted development environment.
Run it
cd controller
$env:TOTAL_SHARDS = "128"
go run .
Default listener:
127.0.0.1:8080
Environment variables
| Variable | Meaning | Default |
|---|---|---|
TOTAL_SHARDS | Global Discord shard count | 1 |
LEASE_SECONDS | Node ownership timeout | 30 |
LISTEN | HTTP listen address | 127.0.0.1:8080 |
Endpoints
POST /v1/checkin
GET /v1/nodes
GET /v1/plan
POST /v1/identify/claim
GET /v1/route?guild_id=...
GET /healthz
Node check-in
A node declares its ID and local capacity.
Example:
Invoke-RestMethod http://127.0.0.1:8080/v1/checkin `
-Method Post `
-ContentType application/json `
-Body '{"node_id":"compaq-01","capacity":16}'
The controller then produces deterministic contiguous shard ranges while respecting declared node capacity.
Lease model
Ownership is time-bounded:
node checks in
↓
controller assigns contiguous shard range
↓
lease generation + expiry returned
↓
node owns that range while lease is valid
↓
lease expires
↓
node must stop shard-owned traffic
This prevents duplicate live owners after control-plane/network failure.
Deterministic contiguous ranges
The controller sorts participating nodes deterministically and allocates ranges based on declared capacity.
Why contiguous ownership matters:
- easier local slot mapping
- easier operator inspection
- simpler guild-to-node routing
- less fragmented rebalance state
Cross-node Identify gating
Discord's Identify concurrency is global to the bot, not per machine.
Before a node Identifies a shard, the control-plane design uses:
POST /v1/identify/claim
{
"node_id": "compaq-01",
"shard_id": 17
}
The controller verifies ownership and coordinates the appropriate concurrency bucket across nodes.
Two PXE machines can each be internally correct and still violate Discord's global Identify limits if they independently consume the same concurrency bucket.
Guild routing
GET /v1/route?guild_id=123456789012345678
The controller applies Discord's shard-routing formula, determines the global shard ID, then reports which node currently leases that shard.
Conceptually:
guild ID
-> global shard ID
-> active node lease
-> owning PXE machine
Controller vs runtime responsibilities
| Controller | PXE runtime |
|---|---|
| node registration | boot/hardware ownership |
| capacity planning | TCP/TLS/WebSocket |
| contiguous shard leases | Gateway sessions |
| lease expiry | local reconnect/backoff |
| Identify claim coordination | actual Identify transmission |
| guild-to-node routing | local shard slot execution |
Failure cases
Node stops checking in
Its lease eventually expires and ownership can be reassigned.
Node reconnects after expiry
The runtime must not blindly resume old shard ownership. It needs a fresh controller lease.
Capacity changes
A new deterministic plan may move the node's contiguous range. Existing live sessions must be retired/rebuilt according to the new ownership generation.
Controller disappears
Nodes must not retain shard ownership indefinitely. Lease expiry is the safety boundary.
Current limitation
The controller exists and the runtime contains local lease-expiry behavior, but complete live controller-to-PXE integration is still ongoing.
See Controller Protocol for endpoint/state details.