# Route Spec

## Route ID
`notifications-stream`

## Endpoint
`GET /api/v1/notifications/stream`

## Human Description
Server-Sent Events stream for real-time notification events. Hub discussion/chat messages, saved discussions, reports, and blocks are excluded because they do not create user-facing notification events. Muted hub content activity is also excluded for the muted user.

## Authentication
- Required: `yes`

## Request
### Headers
- `Authorization: Bearer <token>`
- `Accept: text/event-stream`

## Responses
### Success: `200 OK`
Content-Type: `text/event-stream`

Event format:
```text
event: notification
data: {"id":"ntf_3","type":"post_commented","postId":"pst_1","commentId":"cmt_1"}
```

### Error: `401 Unauthorized`
When returned:
- Missing or invalid access token.

Body:
```json
{"success": false, "error": {"code": "UNAUTHORIZED", "message": "Authentication required.", "details": {}}}
```

### Error: `426 Upgrade Required`
When returned:
- Client transport does not support required streaming behavior.

Body:
```json
{"success": false, "error": {"code": "SSE_NOT_SUPPORTED", "message": "Server-sent events are not supported by this client.", "details": {}}}
```

## Idempotency and Retries
- Idempotent: `no` (Stream)
- Retry guidance: **CRITICAL**. Cloud Run enforces an absolute maximum connection timeout of 1 hour (3600 seconds). The frontend client MUST be designed to gracefully catch this inevitable disconnection and immediately reconnect to the stream without user disruption.

## Data & Caching Dependencies
- **Spanner Tables:** `notifications (Read/Write)`
- **Redis Cache:** `None`
- **GCS Storage:** `None`
- **Edge Cache (CDN):** `No`

## Side Effects
- None (read-only endpoint).