backend.mdc

---
globs: backend/**/*.ts
---

# Backend-Regeln

## Module System
- Backend verwendet **ES Modules** (`"type": "module"` in package.json)
- Alle Imports müssen `.js`-Extension haben: `import { foo } from './bar.js'`
- Jest-Tests laufen im CJS-Modus via `tsconfig.jest.json` und `moduleNameMapper`

## Paket-Scope
- Paketname: `@webmud3/backend`
- Shared-Typen importieren via: `import { ... } from '@webmud3/shared'`

## Architektur
- **Environment**: Singleton via `Environment.getInstance()` – nie direkt `process.env` lesen
- **MudConfigService**: Singleton via `MudConfigService.getInstance(configPath)` – Multi-MUD-Konfiguration
  - Lädt `mud_config.json` wenn `MUD_CONFIG_PATH` Env-Var gesetzt und Datei existiert
  - Fallback: Kein Config → `TELNET_HOST`/`TELNET_PORT` Env-Vars werden direkt genutzt
  - Lookup: `getMudById()`, `resolveConnection()`, `getGmcpSupport()`, `getMudList()`
- **Middleware**: Jede Middleware als eigene `use*`-Funktion in `core/middleware/`
- **Telnet-Handler**: Neue Telnet-Options als Factory-Funktion in `features/telnet/utils/handle-*.ts` anlegen
- **Logging**: Immer `logger` aus `shared/utils/logger.ts` verwenden (Winston), nie `console.log`

## Telnet-Option hinzufügen
1. Option in `features/telnet/models/telnet-options.ts` definieren
2. Handler-Funktion in `features/telnet/utils/handle-<option>.ts` erstellen
3. Handler in `TelnetClient.optionsHandler`-Map registrieren
4. Optional: State-Tracking via `getState()` / `onStateChange()`

## Socket.IO Events
- Neue Client→Server Events: Interface `ClientToServerEvents` in `shared/` erweitern
- Neue Server→Client Events: Interface `ServerToClientEvents` in `shared/` erweitern
- Handler im `SocketManager.handleClientConnection()` registrieren
- GMCP-Events: `mudGmcpIncoming`/`mudGmcpStart` (Server→Client), `mudGmcpOutgoing` (Client→Server)
- GMCP-Weiterleitung: TelnetClient Events ↔ Socket.IO Events im SocketManager
- **Core.BrowserInfo Enrichment**: Bei `mudGmcpOutgoing` mit `Core.BrowserInfo` wird serverseitig `real_ip` injiziert
  - `SocketManager.extractRealIp()` → `x-forwarded-for` (erster Eintrag) oder `socket.handshake.address`
  - Auch `client` (clientName) wird hinzugefügt — Frontend-Daten werden gemergt

## TypeScript
- `strict: true`
- Target: ES2020
- Module: nodenext / moduleResolution: nodenext

## Testing
- Jest mit `ts-jest`
- Test-Dateien: `*.spec.ts` neben den Source-Dateien
- Config: `jest.config.cjs`