Loading...
We use a RESTful approach for state changes and WebSockets for real-time telemetry/social features.
* **Authentication & Identity**
* `POST /api/v1/auth/login`
* **Body:** credentials or OAuth tokens.
* **Response:** `{ "access_token": "<JWT>", "refresh_token": "<JWT>", "expires_in": 3600 }`
* **Content Library Management**
* `GET /api/v1/content`
* **Query Params:** `?category=gaming&sort=popular&limit=50&offset=0`
* **Response:** Paginated list of VR video metadata.
* `POST /api/v1/content/upload`
* **Headers:** `Authorization: Bearer <JWT>`, `Idempotency-Key: <UUID>`
* **Body:** Metadata payload.
* **Response:** Pre-signed S3 URL for direct-to-cloud raw file upload.
* `PUT /api/v1/content/{video_id}` / `DELETE /api/v1/content/{video_id}`
* **Headers:** `Authorization: Bearer <JWT>`
* **Action:** Update metadata or soft-delete content (creator/admin only).
* **Streaming Session Management**
* `POST /api/v1/sessions/start`
* **Headers:** `Authorization: Bearer <JWT>`
* **Body:** `{ "video_id": "<ID>", "device_type": "oculus_quest_3" }`
* **Response:** `{ "session_id": "<UUID>", "manifest_url": "<CDN_SIGNED_URL>", "drm_license_url": "<URL>" }`
* `POST /api/v1/sessions/{session_id}/heartbeat`
* **Action:** Sends client-side telemetry (buffering, bitrate, FOV metrics) every 10 seconds.
* **Social Interactions**
* `POST /api/v1/social/rooms`
* **Response:** Creates a shared viewing room.
* `POST /api/v1/social/rooms/{room_id}/join`
* **Response:** Returns WebSocket endpoint `wss://social.vr-stream.com/ws/{room_id}?token=<JWT>` for real-time positional audio and avatar syncing.
Client Devices: VR headsets running client applications handling viewport-adaptive rendering and DRM decryption.
* **Security & Data Protection:**
* **Encryption at Rest & In Transit:** All internal and external network traffic is enforced over TLS 1.3. All persistent data in Object Storage and databases is encrypted at rest using AES-256 via a managed Key Management Service (KMS).
* **Access Control:** Beyond standard JWTs, the system employs strict Role-Based Access Control (RBAC). Only the user or an admin can modify their profile data. Internal microservices use mutual TLS (mTLS) to authenticate with each other, preventing lateral movement if a service is compromised.
* **Content Protection:** To prevent unauthorized downloading or piracy of VR streams, we integrate Digital Rights Management (DRM) (e.g., Widevine, FairPlay). The Session Service issues short-lived DRM license tokens. Furthermore, direct access to the CDN is protected via short-lived Signed URLs tied to the user's session IP.
* **High Availability & Minimal Downtime:**
* **Multi-Region Active-Active:** The architecture is deployed across at least two geographically isolated regions. We use a globally distributed, multi-master database (like DynamoDB Global Tables or Google Cloud Spanner) to ensure data is synchronized synchronously or near-synchronously.
* **Automated Failover:** Traffic is managed via Geo-DNS routing (e.g., Route 53). If a region experiences degradation, health checks automatically fail the DNS records, seamlessly rerouting global traffic to the healthy region.
* **Zero-Downtime Deployments:** Services run in Kubernetes clusters utilizing Horizontal Pod Autoscalers (HPA). All updates follow a Canary or Blue-Green deployment strategy. The database schemas are designed for backward compatibility, ensuring that application updates do not require database locking or downtime.
* **Scalability & Performance:**
* **Viewport-Adaptive Streaming:** We serve tiled video. The client only downloads high-resolution tiles for the user's exact field of view (FOV), drastically reducing bandwidth overhead.
* **Handling Edge Cases:**
* **Thundering Herd Scenario:** A massive viral VR event causes millions of simultaneous manifest requests.
* *Resolution:* Request Coalescing (Single-Flight Pattern) at the API Gateway holds concurrent duplicate requests, queries the backend exactly once, caches the result in Redis, and resolves all waiting requests simultaneously. We utilize cache jitter (adding random variance to TTLs) to prevent cache stampedes.
* **Idempotent Case:** A creator uploads a massive 50GB file, but the network drops during the final metadata confirmation, prompting a retry.
* *Resolution:* The `POST /api/v1/content/upload` endpoint requires an `Idempotency-Key` header. The gateway caches the result of the first successful transaction against this UUID in Redis. Retries immediately return the cached success response without duplicating the database write or S3 upload processing.
* **Rate Limit Case:** A malicious bot attempts to scrape the content library or DDoS the auth service.
* *Resolution:* The API Gateway implements a distributed Token Bucket algorithm backed by Redis. Limits are stratified (e.g., 5 login attempts/min, 100 library reads/min). Violations trigger an immediate `429 Too Many Requests` or temporary IP ban via a Web Application Firewall (WAF).