55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
# Wave B-5b: `@suaveplan/game-server` performance slice
|
|
|
|
**Package**: `@suaveplan/game-server`
|
|
**Status**: PROPOSED
|
|
**Type**: feature-add (additive to existing 0.1.0 package)
|
|
|
|
## Why
|
|
|
|
Wave A landed the `@suaveplan/game-server` core foundation. Five
|
|
parallel waves now extend the package along orthogonal axes; B-5 owns
|
|
the **matchmaking + performance** axis. This change covers the
|
|
performance half; a sibling change (`game-server-matchmaking`) covers
|
|
queue / matcher / spectator / engine.
|
|
|
|
The upstream reference
|
|
(`/mnt/s/web/suaveplan/packages/universal/game-server/src/performance/`)
|
|
ships three modules — `ObjectPool`, `SessionPool`, `NetworkTierAdapter`
|
|
— but couples them to upstream-only types (`Logger`,
|
|
`GameEventEmitter`, `SessionNodeImpl`) and lacks typed-error /
|
|
Zod-validated boundaries. This slice ports the algorithms, replaces the
|
|
upstream couplings with `@suaveplan/types` (`Clock`) plus typed
|
|
observer callbacks, and adds OTel-native instrumentation across all
|
|
three modules.
|
|
|
|
## What changes
|
|
|
|
- ADDED: `src/performance/object-pool/` — generic typed object pool
|
|
with factory + reset + optional dispose; configurable
|
|
`initialSize`/`maxSize`/`preAllocate`; `acquire` / `release` /
|
|
`withObject` / `clear` / `dispose` / `getStats`; two OTel counters;
|
|
typed-error boundary (`POOL_EXHAUSTED`, `POOL_DISPOSED`,
|
|
`RELEASE_FOREIGN_OBJECT`, `INVALID_POOL_CONFIG`).
|
|
- ADDED: `src/performance/session-pool/` — session-specific wrapper
|
|
over `ObjectPool` that pools plain-data `PooledSession` records
|
|
(`id`, `type`, `metadata`, `children[]`); injectable `Clock`;
|
|
`acquireSession`/`releaseSession`/`withSession`/`getStats`.
|
|
- ADDED: `src/performance/network-tier-adapter/` — bridge between the
|
|
game-server's matchmaking layer and the `@suaveplan/network` tier
|
|
model; `registerNodeCapabilities` / `getOptimalTier` /
|
|
`getLoadBalancingRecommendations` / `validateTierCapacity` /
|
|
`getStats`; one OTel counter; typed-error boundary
|
|
(`INVALID_TIER_CONFIG`, `UNKNOWN_TIER`); optional
|
|
`onCapabilityUpdated` listener.
|
|
|
|
## Impact
|
|
|
|
- Affected specs: `openspec/specs/game-server/spec.md` (game-server
|
|
capability).
|
|
- New error codes: `POOL_EXHAUSTED`, `POOL_DISPOSED`,
|
|
`RELEASE_FOREIGN_OBJECT`, `INVALID_POOL_CONFIG`,
|
|
`INVALID_TIER_CONFIG`, `UNKNOWN_TIER`.
|
|
- New subpath exports: `./performance/{object-pool, session-pool,
|
|
network-tier-adapter}`.
|
|
- No `core/` / `state/` / `engine/` / `network/` modifications.
|