98 lines
4.0 KiB
Markdown
98 lines
4.0 KiB
Markdown
# Tasks: enterprise-network-assignment
|
|
|
|
**Change ID**: enterprise-network-assignment
|
|
**Package**: `@suaveplan/network-assignment`
|
|
**Target path**: `universal/network/network-assignment`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`
|
|
|
|
---
|
|
|
|
## 1. Scaffold
|
|
|
|
- [x] Create `universal/network/network-assignment/` with `src/`, `tests/`, `src/__benchmarks__/`, and feature subdirectories.
|
|
- [x] Write `package.json` at version `0.1.0`: `"sideEffects": false`, exports map, deps per `proposal.md`.
|
|
- [x] Write `tsconfig.json`, `vitest.config.ts`, scripts (including `bench`).
|
|
|
|
---
|
|
|
|
## 2. Types and error codes
|
|
|
|
- [x] Define all public types in `src/types/common.ts`: `Peer`, `AssignerOptions`, `AssignerSnapshot`, `RebalanceResult`, `AssignmentAlgorithm`.
|
|
- [x] Write `src/types/common.md` (≥200 words, simple + advanced examples).
|
|
- [x] Define error codes in `src/error-codes.ts`.
|
|
- [x] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
|
|
|
|
---
|
|
|
|
## 3. Algorithm implementations (`src/algorithms/`)
|
|
|
|
### 3a. Consistent hash
|
|
|
|
- [x] Implement `consistentHash(key, peers, virtualNodes?)`:
|
|
- Build virtual node ring: for each peer, hash `${peer.id}#${i}` for `i` in `0..virtualNodes`.
|
|
- For assignment, hash `key` and find the next clockwise virtual node.
|
|
- Return the peer owning that virtual node.
|
|
- [x] Write `consistent-hash.test.ts` (≤500 lines): determinism, adding peer minimally disrupts existing assignments (monotonicity), empty peers returns null.
|
|
- [x] Write `consistent-hash.md` (≥200 words).
|
|
|
|
### 3b. Rendezvous hash
|
|
|
|
- [x] Implement `rendezvousHash(key, peers)`:
|
|
- For each peer, compute `hash(key + peer.id)`.
|
|
- Return peer with highest hash value (HRW algorithm).
|
|
- [x] Write `rendezvous-hash.test.ts` + `rendezvous-hash.md`.
|
|
|
|
### 3c. Weighted random
|
|
|
|
- [x] Implement `weightedRandom(peers, rng)`:
|
|
- Normalise weights; use CDF + `rng.next()` to select.
|
|
- [x] Write `weighted-random.test.ts` + `weighted-random.md`.
|
|
|
|
### 3d. Latency-aware
|
|
|
|
- [x] Implement `latencyAware(peers, maxPeers?)`:
|
|
- Sort peers by `latencyMs` ascending; return first (lowest-latency).
|
|
- Fall back to first peer if no latency data.
|
|
- [x] Write `latency-aware.test.ts` + `latency-aware.md`.
|
|
|
|
---
|
|
|
|
## 4. Assigner (`src/core/assigner/`)
|
|
|
|
- [x] Implement `createAssigner(options?)`:
|
|
- Stores peers in `Map<string, Peer>`.
|
|
- Selects algorithm implementation based on `options.algorithm`.
|
|
- [x] Implement `assigner.addPeer(peer)`, `removePeer(id)`.
|
|
- [x] Implement `assigner.assign(key)` — calls algorithm; OTel counter `assignment.assign_total`.
|
|
- [x] Implement `assigner.assignN(key, n)` — returns top-N distinct peers (rendezvous iterates CDF; consistent-hash walks ring).
|
|
- [x] Implement `assigner.rebalance()` — snapshot before/after peer list; compute diff; OTel histogram `assignment.rebalance_duration_ms`.
|
|
- [x] Implement `assigner.snapshot()`.
|
|
- [x] Write `assigner.test.ts` (≤500 lines): all four algorithms, assignN, rebalance, no peers.
|
|
- [x] Write `assigner.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 5. Benchmarks (`src/__benchmarks__/assignment.bench.ts`)
|
|
|
|
- [x] `consistent_hash_1k`: 1k `assign` calls with 20-peer ring.
|
|
- [x] `rendezvous_1k`: 1k `assign` calls with 20 peers.
|
|
- [x] `rebalance_100_keys`: rebalance after adding 1 peer with 100 pre-assigned keys.
|
|
|
|
---
|
|
|
|
## 6. Property-based tests (`tests/property.test.ts`)
|
|
|
|
- [x] Consistent hash monotonicity: adding 1 peer reassigns ≤ `(N_keys / N_peers)` keys on average.
|
|
- [x] Determinism: same key + same peers always yields same assignment across all algorithms.
|
|
- [x] AssignN uniqueness: all N returned peers are distinct.
|
|
|
|
---
|
|
|
|
## 7. Docs and verify
|
|
|
|
- [x] All per-file `.md` files per layout in `proposal.md`.
|
|
- [x] `universal/network/network-assignment/README.md`.
|
|
- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-assignment` — all green, 100% coverage.
|
|
- [x] `bun scripts/publish.ts --package @suaveplan/network-assignment`.
|
|
- [x] Update `CLAUDE.md`. Archive change folder.
|