93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# ADR: Session lifecycle — TTL and replay protection
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Date
|
|
|
|
2026-04-28
|
|
|
|
## Context
|
|
|
|
`InMemoryGameSessionStore` had no TTL and no cleanup mechanism. Every session created stayed in memory until the process restarted. Additionally, `evaluateAnswer` never removed a question from the answer key after evaluating it, meaning the same question could be submitted multiple times and receive a valid result each time — a potential exploit in multiplayer and a correctness bug in singleplayer.
|
|
|
|
## Decision
|
|
|
|
Add a `ttlMs` parameter to `GameSessionStore.create()` so both the in-memory and future Valkey implementations handle expiry consistently. Delete questions from the answer key after evaluation. Delete the session when the last question is answered.
|
|
|
|
## Options considered
|
|
|
|
### Option A — Delete on last answer only
|
|
|
|
Simple. Covers replay protection and normal session completion. Abandoned sessions (player starts game, never finishes) still leak memory.
|
|
|
|
### Option B — Delete on last answer + TTL on the interface ✅
|
|
|
|
Delete on answer covers normal flow. TTL covers abandoned sessions. TTL on the interface means `ValKeyGameSessionStore` can use Redis-native `EXPIRE` without any interface changes during migration.
|
|
|
|
Chosen because it closes the memory leak entirely and makes the Valkey migration a zero-interface-change operation.
|
|
|
|
### Option C — TTL hardcoded inside InMemoryGameSessionStore only
|
|
|
|
Simpler short-term. But the interface wouldn't carry the TTL parameter, so `ValKeyGameSessionStore` would need a different mechanism — inconsistency between implementations.
|
|
|
|
## Consequences
|
|
|
|
- Sessions expire after 30 minutes of inactivity regardless of completion state
|
|
- Submitting the same question twice throws `NotFoundError` on the second attempt
|
|
- Sessions are deleted automatically when the last question is answered
|
|
- `GameSessionStore.create()` now requires a `ttlMs` argument — any future implementation must honour it
|
|
- `ValKeyGameSessionStore` can implement TTL via Redis `EXPIRE` with no interface changes
|
|
- `InMemoryGameSessionStore` stores `{ data, expiresAt }` entries instead of raw `GameSessionData` — expiry is checked lazily on `get()`
|
|
|
|
## Affected files
|
|
|
|
- `apps/api/src/gameSessionStore/GameSessionStore.ts` — `ttlMs` added to `create`
|
|
- `apps/api/src/gameSessionStore/InMemoryGameSessionStore.ts` — TTL implementation
|
|
- `apps/api/src/gameSessionStore/InMemoryGameSessionStore.test.ts` — new test file
|
|
- `apps/api/src/services/gameService.ts` — passes TTL to `store.create`, deletes question after evaluation, deletes session when empty
|
|
- `apps/api/src/services/gameService.test.ts` — replay protection and session cleanup tests added
|
|
|
|
## References
|
|
|
|
- [Redis EXPIRE command](https://redis.io/commands/expire/)
|
|
|
|
---
|
|
|
|
## Setup guide / implementation notes
|
|
|
|
1. `GameSessionStore.ts` — add `ttlMs` to `create`:
|
|
|
|
```ts
|
|
create(sessionId: string, data: GameSessionData, ttlMs: number): Promise<void>;
|
|
```
|
|
|
|
2. `InMemoryGameSessionStore.ts` — wrap stored data with expiry:
|
|
|
|
```ts
|
|
type SessionEntry = { data: GameSessionData; expiresAt: number };
|
|
```
|
|
|
|
Check expiry on `get()`, delete expired entries lazily.
|
|
|
|
3. `gameService.ts` — pass TTL when creating session:
|
|
|
|
```ts
|
|
await store.create(sessionId, { answers: answerKey }, 30 * 60 * 1000);
|
|
```
|
|
|
|
After evaluating an answer:
|
|
|
|
```ts
|
|
session.answers.delete(submission.questionId);
|
|
if (session.answers.size === 0) {
|
|
await store.delete(submission.sessionId);
|
|
}
|
|
```
|
|
|
|
4. When implementing `ValKeyGameSessionStore`, pass `ttlMs` to Redis `EXPIRE`:
|
|
|
|
```ts
|
|
await valkey.set(sessionId, serialize(data), "EX", Math.ceil(ttlMs / 1000));
|
|
```
|