# Partition Manager And Map Table
Once storage is range-partitioned, the system needs a control plane that answers:
```text
which partition server owns this key range right now?
```
## Components
```mermaid
flowchart TB
API[API servers] --> PMT[(partition map table)]
API --> PS1[partition server 1]
API --> PS2[partition server 2]
PM[partition manager] --> PMT
PM --> PS1
PM --> PS2
LS[lock service<br/>ZooKeeper/etcd/Paxos-style] <--> PM
```
| Component | Responsibility |
|---|---|
| Partition map table | durable mapping from range to partition server |
| Partition manager | split ranges, assign ranges, react to load/failure |
| Partition server | serve assigned ranges |
| Lock service | leader election and ownership coordination |
## Hot Path vs Control Path
The partition manager should not be in every request path if avoidable.
Better shape:
1. API server reads/caches the partition map.
2. API server talks directly to the partition server.
3. Partition manager updates the map only when ownership changes.
This keeps the control plane off the hot path.
## Map Cache Contract
API servers usually cache the partition map to avoid a metadata lookup on every request. That cache needs a correctness protocol.
| Case | Required Behavior |
|---|---|
| API routes to old owner | old owner rejects with stale-owner or epoch error |
| API has missing range | refresh map before failing the request |
| partition move in progress | writes use fencing token/epoch to prevent split brain |
| map table unavailable | cached reads may continue only within the allowed staleness contract |
The map should include an epoch or generation number. Partition servers compare request epochs against their current lease before accepting writes.
## Invariants
- A range has exactly one active owner for writes.
- A partition server can own multiple ranges.
- Partition changes are visible through the partition map.
- Old ownership must be invalidated before new writes are accepted.
- Failover must not create split-brain writes for the same range.
## Failover
When a partition server fails:
```mermaid
flowchart LR
H[health check fails] --> PM[partition manager]
PM --> R[find ranges owned by failed server]
R --> A[assign ranges to healthy servers]
A --> M[update partition map table]
```
This is safe only if durable bytes live outside the failed partition server or are replicated elsewhere.
## Split Flow
```text
1. choose split point from load and key distribution
2. create child ranges in preparing state
3. fence old owner for the moving subrange
4. assign child range to new owner
5. publish new map epoch
6. let clients refresh on stale-map errors
```
Planned movement should look like failover: ownership changes through the same lease and map machinery, not through an ad hoc admin path.
## Senior-Level Check
Ask:
- How stale can an API server's cached partition map be?
- What error tells an API server to refresh ownership?
- Can two partition managers run at once?
- Is the map update atomic with ownership handoff?
- What happens during planned rolling upgrades?