AI Implementation feature(863): Challenges Page and Challenge Solve Modal (#45)

2026-07-23 00:13:59 +00:00
parent dcda3dfd4d
commit 0bd1d9472a
40 changed files with 4710 additions and 130 deletions
@@ -0,0 +1,85 @@
+---
+type: guide
+title: Notifications
+description: SPA-wide notification store + the global HTTP error interceptor that translates backend error codes and statuses into friendly user-facing messages.
+tags: [guide, notifications, error, interceptor, toast, ux]
+timestamp: 2026-07-23T00:10:00Z
+---
+
+# Components
+
+| Symbol                              | Path                                                                                 | Responsibility                                                                                |
+|-------------------------------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
+| `NotificationService`               | `frontend/src/app/core/services/notification.service.ts`                            | Root-provided signal-backed store of `{ id, kind, message, ts }` records; `error()` / `info()` push, `dismiss(id)` / `clear()` remove. |
+| `errorNotificationInterceptor`      | `frontend/src/app/core/interceptors/error-notification.interceptor.ts`               | Functional HTTP interceptor that catches `HttpErrorResponse`, looks up the error code, and pushes a friendly message into `NotificationService`. |
+| `NotificationService.messages`      | signal (consumed by future toast UI)                                                 | Currently the messages signal is appended in-memory only; the list itself doubles as the integration point for a future toast/banner component. Each push also mirrors the message to the browser console (`console.error` for `error`, `console.info` for `info`). |
+
+# Wiring
+
+`frontend/src/main.ts` registers the interceptor **after** `authInterceptor` so
+the auth header is already attached when the error interceptor sees
+the request:
+
+```ts
+provideHttpClient(
+  withInterceptors([csrfInterceptor, authInterceptor, errorNotificationInterceptor]),
+)
+```
+
+The interceptor:
+
+1. Catches every `HttpErrorResponse` thrown from any HTTP call.
+2. Maps the response to a friendly message using `friendlyMessage(status, err.error)`.
+3. Suppresses notifications for endpoints that have their own
+   user-facing error presentation (see *Suppression rules* below).
+4. Pushes the message via `NotificationService.error(...)`.
+5. Re-throws the original error so the caller still receives the
+   `ApiErrorEnvelope` (e.g. `ChallengesApiService.submit` reads
+   `envelope.code` to render the modal's inline error).
+
+# Friendly message mapping
+
+`friendlyMessage(status, body)` resolves in this order:
+
+| Source                                              | Message                                                                      |
+|-----------------------------------------------------|------------------------------------------------------------------------------|
+| `status === 0` (network / CORS / aborted)           | `Network error. Please try again.`                                          |
+| `body.code` matches `FRIENDLY_MESSAGES`             | The mapped friendly text (see table below).                                  |
+| `status === 401` or `403`                           | `Your session is no longer valid.` (unless suppressed).                      |
+| `status === 404`                                    | `Not found.`                                                                  |
+| `status >= 500`                                     | `Server error. Please try again later.`                                      |
+| `body.message` (non-empty)                          | Falls back to that message.                                                  |
+| otherwise                                           | `Request failed (<status>).`                                                 |
+
+`FRIENDLY_MESSAGES` lookup table:
+
+| Error code            | Friendly text                                              |
+|-----------------------|------------------------------------------------------------|
+| `EVENT_NOT_RUNNING`   | `Submissions are only accepted while the event is running.` |
+| `FLAG_INCORRECT`      | `Incorrect flag.`                                          |
+| `UNAUTHORIZED`        | `Your session is no longer valid.`                         |
+| `FORBIDDEN`           | `You are not allowed to perform this action.`              |
+| `NOT_FOUND`           | `Not found.`                                                |
+| `VALIDATION_FAILED`   | `Invalid input.`                                            |
+
+# Suppression rules
+
+Some errors are expected and have their own UI. To avoid double-toasting:
+
+| URL pattern                           | Status | Why                                                                                              |
+|---------------------------------------|--------|---------------------------------------------------------------------------------------------------|
+| `/api/v1/auth/login` `/csrf` `/register` | `401`  | A failed login or first-fetch of the CSRF cookie produces a `401`; the form already renders the inline error. |
+| `/api/v1/challenges/status`           | `401`  | The challenges page uses the snapshot as a bootstrap hint only — the SSE stream (`/api/v1/events`) is the source of truth and will deliver the next frame. |
+
+In both cases the interceptor still re-throws the error so callers can
+react locally; only the notification push is skipped.
+
+# See also
+
+- [Challenges Board](/guides/challenges-board.md) (uses
+  `errorNotificationInterceptor` for non-flag submission failures)
+- [Authenticated Shell](/guides/authenticated-shell.md) (cross-tab
+  invalidation propagates from a 401 SSE response via
+  `NotificationService` is **not** triggered — the shell uses its own
+  peer-invalidation channel)
+- [REST API Overview](/api/rest-overview.md) (error envelope)