kcApi-Response-Wrapper: Zentrale Erfolgs-/Fehlerbehandlung fuer Keycloak-Admin-API-Aufrufe #201

New issue

Open

opened 2026-07-03 17:34:51 +02:00 by niboer · 0 comments

niboer commented

2026-07-03 17:34:51 +02:00

Owner

Beschreibung

Aktuell ruft jede Stelle im Backend kcApi() roh auf und prueft den HTTP-Status selbst. Dabei wird oft vergessen, dass Keycloak-API-Endpunkte unterschiedliche Erfolgs-Statuscodes (200, 201, 204, …) verwenden.

Beispiel: Bug #200

In backend/src/routes/persons.ts:554 wurde if (emailStatus !== 200) geschrieben, aber Keycloaks execute-actions-email liefert bei Erfolg HTTP 204. Der Fehler blieb unentdeckt, weil vier andere Stellen in keycloak-provision.ts und keycloak-sync.ts korrekt auf 204 checken – aber keine gemeinsame Abstraktion dafuer sorgt.

Gewuenschte Loesung

Ein zentraler kcApi-Wrapper (oder eine Konfiguration in backend/src/lib/keycloak-api.ts), der:

Akzeptierte Erfolgs-Statuscodes als Parameter oder Defaults definiert
Standardmaessig 200, 201, 202, 204 als Erfolg wertet
Ein typisiertes Erfolgs-/Fehler-Objekt zurueckgibt (anstatt rohe { status, data }-Paare)
Die Log-Ausgabe von Keycloak-Fehlern einheitlich gestaltet

Vorteile

DRY: Statuscode-Vergleich nicht an jeder Aufrufstelle wiederholen
Robustheit: Gegen 200/204-Verwechslungen wie #200 immun
Konsistenz: Einheitliche Fehlerbehandlung und Logging
Testbarkeit: Wrapper kann zentral gemockt werden

Nachteile

Einarbeitung: Bestehende Caller (6-8 Stellen) muessen umgestellt werden
Indirektion: Bei speziellen Anforderungen (z. B. 201 als Erfolg + Body auswerten) muss der Wrapper flexibel bleiben
Tests: Tests muessen auf den neuen Rueckgabetyp angepasst werden, falls sich die Signatur aendert

Aufwandsschaetzung

Wrapper bauen (backend/src/lib/keycloak-api.ts): ~1-2h
Alle Caller umstellen: ~2h
Tests anpassen: ~1h
PR-Review + ggf. Nachbesserung: ~1h
Gesamt: ca. 5-7h (ein Arbeitstag)

Betroffene Dateien (ca. 8 Vorkommen)

backend/src/routes/persons.ts – invite-Endpunkt (2x kcApi)
backend/src/lib/keycloak-provision.ts – Realm-Bootstrap (3x kcApi)
backend/src/lib/keycloak-sync.ts – User-Sync (1x kcApi)
backend/src/lib/keycloak-provision.ts – seedDevUsers (1x kcApi)
Tests: backend/src/__tests__/persons.test.ts (kcApi-Mocks)

Labels

component/backend, type/feature, MS-REST

## Beschreibung Aktuell ruft jede Stelle im Backend `kcApi()` roh auf und prueft den HTTP-Status selbst. Dabei wird oft vergessen, dass Keycloak-API-Endpunkte unterschiedliche Erfolgs-Statuscodes (200, 201, 204, …) verwenden. ### Beispiel: Bug #200 In `backend/src/routes/persons.ts:554` wurde `if (emailStatus !== 200)` geschrieben, aber Keycloaks `execute-actions-email` liefert bei Erfolg **HTTP 204**. Der Fehler blieb unentdeckt, weil vier andere Stellen in `keycloak-provision.ts` und `keycloak-sync.ts` korrekt auf `204` checken – aber keine gemeinsame Abstraktion dafuer sorgt. ## Gewuenschte Loesung Ein zentraler `kcApi`-Wrapper (oder eine Konfiguration in `backend/src/lib/keycloak-api.ts`), der: - Akzeptierte Erfolgs-Statuscodes als Parameter oder Defaults definiert - Standardmaessig 200, 201, 202, 204 als Erfolg wertet - Ein typisiertes Erfolgs-/Fehler-Objekt zurueckgibt (anstatt rohe `{ status, data }`-Paare) - Die Log-Ausgabe von Keycloak-Fehlern einheitlich gestaltet ### Vorteile - **DRY**: Statuscode-Vergleich nicht an jeder Aufrufstelle wiederholen - **Robustheit**: Gegen 200/204-Verwechslungen wie #200 immun - **Konsistenz**: Einheitliche Fehlerbehandlung und Logging - **Testbarkeit**: Wrapper kann zentral gemockt werden ### Nachteile - **Einarbeitung**: Bestehende Caller (6-8 Stellen) muessen umgestellt werden - **Indirektion**: Bei speziellen Anforderungen (z. B. 201 als Erfolg + Body auswerten) muss der Wrapper flexibel bleiben - **Tests**: Tests muessen auf den neuen Rueckgabetyp angepasst werden, falls sich die Signatur aendert ### Aufwandsschaetzung - **Wrapper bauen** (`backend/src/lib/keycloak-api.ts`): ~1-2h - **Alle Caller umstellen**: ~2h - **Tests anpassen**: ~1h - **PR-Review + ggf. Nachbesserung**: ~1h - **Gesamt**: ca. **5-7h** (ein Arbeitstag) ### Betroffene Dateien (ca. 8 Vorkommen) - `backend/src/routes/persons.ts` – invite-Endpunkt (2x kcApi) - `backend/src/lib/keycloak-provision.ts` – Realm-Bootstrap (3x kcApi) - `backend/src/lib/keycloak-sync.ts` – User-Sync (1x kcApi) - `backend/src/lib/keycloak-provision.ts` – seedDevUsers (1x kcApi) - Tests: `backend/src/__tests__/persons.test.ts` (kcApi-Mocks) ## Labels component/backend, type/feature, MS-REST

niboer added this to the MS-REST: Restliche Aufgaben milestone

2026-07-03 17:34:51 +02:00

niboer added the

type/feature

component/backend

labels

2026-07-03 17:34:51 +02:00

niboer referenced this issue from a commit

2026-07-03 18:13:35 +02:00

docs(backend): Keycloak-Admin-REST-API-Doku-Link + Statuscode-Hinweis in AGENTS