Muted text
// CORRECT - theme tokensMuted text
``` ### Resource Management - **Add `.catch()` to fire-and-forget promises** — prevents unhandled rejections - **Add `.unref()` to cleanup intervals** — allows graceful Node.js shutdown - **Handle `res.on('close')`** — destroy streams on client disconnect - **Close resources in catch blocks** — ZIP handles, file descriptors, DB connections - **Track `closed` state for SSE** — check before every `res.write()` and after awaits - **Cancel pending timers on cleanup** — track timer IDs, clear in `finally`/cleanup - **Use `shuttingDown` flag** — prevent new resource acquisition during shutdown - **Await mount operations** — never fire-and-forget ZIP mounts ```typescript // WRONG - unhandled rejection downloadInBackground(gameId); // CORRECT downloadInBackground(gameId).catch((err) => logger.error('Download failed:', err) ); // WRONG - interval keeps process alive this.cleanupInterval = setInterval(() => this.cleanup(), 60000); // CORRECT this.cleanupInterval = setInterval(() => this.cleanup(), 60000); this.cleanupInterval.unref(); // WRONG - write after client disconnect res.write(`data: ${JSON.stringify(update)}\n\n`); // CORRECT let closed = false; req.on('close', () => { closed = true; }); if (!closed) { res.write(`data: ${JSON.stringify(update)}\n\n`); } ``` ### Security - **Allowlists over denylists** — for domains, CGI env vars, file extensions - **Validate resolved paths** — `path.resolve()` + `startsWith(baseDir)` prevents traversal - **Resolve symlinks first** — `fs.realpath()` before path validation - **Use `URL` constructor** — not string concatenation for URL building - **`encodeURIComponent()`** for URL params — handles special characters - **Pre-check DNS resolution** — prevents SSRF via DNS rebinding - **Verify checksums** — for downloaded files, throw on verification failure - **Re-validate after async operations** — file paths after download, tokens after refresh - **Guest users (id=0) have restricted permissions** — `games.read`, `playlists.read`, and `games.play` only; no writes ```typescript // WRONG - path traversal vulnerability const filePath = path.join(baseDir, req.params.filename); return fs.readFile(filePath); // CORRECT const filePath = path.resolve(baseDir, req.params.filename); const realPath = await fs.realpath(filePath); if (!realPath.startsWith(baseDir)) { throw new AppError(403, 'Access denied'); } return fs.readFile(realPath); // WRONG - string concatenation for URLs const url = baseUrl + '/' + filename; // CORRECT const url = new URL(filename, baseUrl).href; ``` ### Error Handling - **Only cache ENOENT** — never cache transient errors (negative cache poisoning) - **Prevent double Promise settlement** — use `settled` flag in event handlers - **Differentiate error types** — JSON parse errors vs ENOENT in config loading - **Log errors with context** — include IDs, paths, operation names - **Use `AppError` with appropriate status codes** — 400 for validation, 404 for not found, 500 for internal ```typescript // WRONG - caches all errors try { return await fs.readFile(path); } catch { this.notFoundCache.set(path, true); // Caches permission errors too! } // CORRECT - only cache definitive "not found" try { return await fs.readFile(path); } catch (error: unknown) { if (error instanceof Error && 'code' in error && error.code === 'ENOENT') { this.notFoundCache.set(path, true); } throw error; } // WRONG - double settlement possible return new Promise((resolve, reject) => { req.on('end', () => resolve(body)); req.on('error', reject); }); // CORRECT return new Promise((resolve, reject) => { let settled = false; req.on('end', () => { if (!settled) { settled = true; resolve(body); } }); req.on('error', (err) => { if (!settled) { settled = true; reject(err); } }); }); ``` ### Code Quality - **Don't export internal constants** — reduces public API surface - **Don't duplicate utilities** — consolidate to single source of truth - **`[...arr].sort()`** — not `arr.sort()`, avoid mutation - **Use `switch` for mutually exclusive conditions** — not overlapping `if` blocks - **Remove unused imports/variables** — keep code clean - **Consistent naming** — camelCase for variables, PascalCase for components/types - **Add `displayName` to HOC-wrapped components** — improves debugging - **Prefer early returns** — reduces nesting, improves readability ```typescript // WRONG - overlapping if blocks if (!cacheType || cacheType === 'games') clearGamesCache(); if (!cacheType || cacheType === 'users') clearUsersCache(); // CORRECT - mutually exclusive switch (cacheType) { case 'games': clearGamesCache(); break; case 'users': clearUsersCache(); break; default: clearGamesCache(); clearUsersCache(); } // WRONG - mutates original array const sorted = tags.sort(); // CORRECT - creates new array const sorted = [...tags].sort(); ``` ### Zod Validation - **Align frontend/backend schemas** — same limits, same required fields - **Use `.min()` and `.max()`** — validate string lengths, number ranges - **Use `.url()` for URLs** — validates format - **Use enums for known values** — `z.enum(['option1', 'option2'])` - **Validate optional fields properly** — `z.string().optional()` not `z.string()` ```typescript // Backend schema const createPlaylistSchema = z.object({ title: z.string().min(1).max(100), description: z.string().max(500).optional(), gameIds: z.array(z.string().uuid()).max(100), }); // Frontend schema should match const playlistSchema = z.object({ title: z.string().min(1, 'Title required').max(100, 'Title too long'), description: z.string().max(500).optional(), gameIds: z.array(z.string()).max(100), }); ``` --- ## Project-Specific Patterns ### API Layer Pattern All frontend API calls must go through `frontend/src/lib/api.ts`: ```typescript // In api.ts - add new endpoint export const playlistsApi = { getAll: async (params?: PaginationParams) => { const { data } = await api.get{example.description}