Files
2026-04-16 15:52:46 +09:00

654 lines
23 KiB
Python

"""
room.py — Multi-device karaoke room API
Endpoints:
POST /api/room/{room_id}/join — device auth, role assignment, session token
GET /api/room/{room_id}/snapshot — full room state for initial load / reconnect
GET /api/room/{room_id}/events — SSE broadcast stream
POST /api/room/{room_id}/queue/mutate — queue operations (versioned, idempotent)
POST /api/room/{room_id}/playback/mutate — playback transport operations
POST /api/room/{room_id}/transfer_host — explicit host hand-off
ADR references: ADR-002 (transport), ADR-003 (mutation contract), ADR-004 (security)
Checklist: Milestone C (C1, C2, C3)
"""
from __future__ import annotations
import asyncio
import base64
import dataclasses
import hashlib
import hmac
import json
import logging
import os
import time
import uuid
from collections import deque
from typing import Any, AsyncIterator
from fastapi import APIRouter, HTTPException, Query
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
_log = logging.getLogger(__name__)
router = APIRouter(prefix="/api/room", tags=["room"])
# ── Kill-switch ───────────────────────────────────────────────────────────────
def _check_enabled() -> None:
if os.environ.get("KK_ROOM_DISABLED", "").strip() == "1":
raise HTTPException(status_code=503, detail="Room service unavailable")
# ── HMAC session token ────────────────────────────────────────────────────────
TOKEN_LIFETIME_S = 4 * 3600 # 4 hours
_STARTUP_SECRET: bytes = os.urandom(32) # fallback when KK_SECRET_KEY unset
def _get_secret() -> bytes:
env = os.environ.get("KK_SECRET_KEY", "").strip()
return env.encode() if env else _STARTUP_SECRET
def _sign_token(payload: dict[str, Any]) -> str:
body = json.dumps(payload, separators=(",", ":"), sort_keys=True)
b64 = base64.urlsafe_b64encode(body.encode()).rstrip(b"=").decode()
sig = hmac.new(_get_secret(), b64.encode(), hashlib.sha256).hexdigest()
return f"kk1.{b64}.{sig}"
def _verify_token(token: str) -> dict[str, Any] | None:
if not token.startswith("kk1."):
return None
parts = token.split(".")
if len(parts) != 3:
return None
_, b64, sig = parts
expected = hmac.new(_get_secret(), b64.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, sig):
return None
try:
padding = (-len(b64)) % 4
payload = json.loads(base64.urlsafe_b64decode(b64 + "=" * padding))
except Exception:
return None
if payload.get("expires_at", 0) < time.time():
return None
return payload
def _require_session(room_id: str, token: str) -> dict[str, Any]:
payload = _verify_token(token)
if not payload:
raise HTTPException(status_code=401, detail="Invalid or expired session token")
if payload.get("room_id") != room_id:
raise HTTPException(status_code=401, detail="Token not valid for this room")
if room_id not in _rooms:
raise HTTPException(status_code=404, detail="Room not found")
room = _rooms[room_id]
device_id = payload["device_id"]
if device_id not in room.members:
raise HTTPException(status_code=401, detail="Device not in room")
return payload
# ── In-memory room state ──────────────────────────────────────────────────────
HOST_FAILOVER_GRACE_S = 15
SSE_BUFFER_MAX = 200
ROOM_TTL_S = 600 # 10 min after last activity with no subscribers
@dataclasses.dataclass
class RoomQueueItem:
id: str
song_id: str
source_kind: str # 'project' | 'sek'
source_ref: str # projectId or sekPackageId[:sekFolder]
title: str
artist: str | None
album_art: str | None
singer_label: str | None
requested_by: str # device_id
@dataclasses.dataclass
class PlaybackState:
current_index: int = -1
is_playing: bool = False
position_ms: int = 0
key_semitones: int = 0
tempo_delta: int = 0
@dataclasses.dataclass
class RoomState:
room_id: str
queue: list[RoomQueueItem] = dataclasses.field(default_factory=list)
queue_version: int = 0
playback: PlaybackState = dataclasses.field(default_factory=PlaybackState)
members: dict[str, str] = dataclasses.field(default_factory=dict) # device_id → role
host_device_id: str | None = None
created_at: float = dataclasses.field(default_factory=time.time)
last_activity: float = dataclasses.field(default_factory=time.time)
# SSE
event_counter: int = 0
event_log: deque = dataclasses.field(default_factory=lambda: deque(maxlen=SSE_BUFFER_MAX))
subscribers: dict[str, asyncio.Queue] = dataclasses.field(default_factory=dict)
# Idempotency: action_id → (response_dict, expires_at)
idempotency: dict[str, tuple[dict, float]] = dataclasses.field(default_factory=dict)
# Rate limits: device_id → (tokens, last_refill_ts)
rate_buckets: dict[str, tuple[float, float]] = dataclasses.field(default_factory=dict)
# Host failover async task
failover_task: asyncio.Task | None = None
_rooms: dict[str, RoomState] = {}
def _get_or_create_room(room_id: str) -> RoomState:
if room_id not in _rooms:
_rooms[room_id] = RoomState(room_id=room_id)
return _rooms[room_id]
def _snapshot_dict(room: RoomState) -> dict:
return {
"room_id": room.room_id,
"queue_version": room.queue_version,
"queue": [dataclasses.asdict(item) for item in room.queue],
"playback_state": dataclasses.asdict(room.playback),
"members": dict(room.members),
"host_device_id": room.host_device_id,
"server_ts": int(time.time() * 1000),
}
def _broadcast(room: RoomState, event_type: str, data: dict) -> None:
room.event_counter += 1
event = {
"id": str(room.event_counter),
"type": event_type,
"data": data,
"ts": time.time(),
}
room.event_log.append(event)
for q in list(room.subscribers.values()):
try:
q.put_nowait(event)
except asyncio.QueueFull:
pass
# ── Rate limiting (token bucket) ──────────────────────────────────────────────
def _check_rate(room: RoomState, device_id: str,
burst: float = 10.0, rate: float = 10.0) -> None:
now = time.time()
tokens, last = room.rate_buckets.get(device_id, (burst, now))
tokens = min(burst, tokens + (now - last) * rate)
if tokens < 1.0:
raise HTTPException(
status_code=429,
detail="Too many requests",
headers={"Retry-After": "1"},
)
room.rate_buckets[device_id] = (tokens - 1.0, now)
# ── Idempotency ───────────────────────────────────────────────────────────────
def _get_cached(room: RoomState, action_id: str) -> dict | None:
now = time.time()
# Purge expired
expired = [k for k, (_, exp) in room.idempotency.items() if exp < now]
for k in expired:
del room.idempotency[k]
if action_id in room.idempotency:
return room.idempotency[action_id][0]
return None
def _cache(room: RoomState, action_id: str, response: dict) -> None:
room.idempotency[action_id] = (response, time.time() + 60.0)
# ── Role authorization ────────────────────────────────────────────────────────
def _authz(role: str, allowed: set[str], detail: str = "insufficient_role") -> None:
if role not in allowed:
raise HTTPException(status_code=403, detail=detail)
_HOST_CURATOR = {"host", "curator"}
_HOST_CURATOR_GUEST = {"host", "curator", "guest"}
_HOST_ONLY = {"host"}
# ── Host failover ─────────────────────────────────────────────────────────────
def _schedule_failover(room: RoomState, disconnected_id: str) -> None:
async def _do_failover() -> None:
await asyncio.sleep(HOST_FAILOVER_GRACE_S)
# If disconnected device reconnected as a subscriber, abort
if disconnected_id in room.subscribers:
return
connected = [d for d in room.subscribers if d != disconnected_id]
if not connected:
return
new_host = connected[0]
room.members[new_host] = "host"
room.host_device_id = new_host
_log.info("Room %s: host failover → %s", room.room_id, new_host)
_broadcast(room, "member_updated", {
"members": dict(room.members),
"host_device_id": room.host_device_id,
})
if room.failover_task and not room.failover_task.done():
room.failover_task.cancel()
room.failover_task = asyncio.create_task(_do_failover())
# ── SSE generator ─────────────────────────────────────────────────────────────
async def _sse_stream(room: RoomState, device_id: str,
last_event_id: str | None) -> AsyncIterator[str]:
queue: asyncio.Queue = asyncio.Queue(maxsize=50)
room.subscribers[device_id] = queue
try:
# Replay missed events if Last-Event-ID provided
if last_event_id is not None:
try:
last_seq = int(last_event_id)
missed = [e for e in room.event_log if int(e["id"]) > last_seq]
if not missed and room.event_counter > last_seq:
# Gap too large — tell client to re-fetch snapshot
yield (
f"event: room_reset\n"
f"data: {json.dumps({'reason': 'gap_too_large'})}\n"
f"id: {room.event_counter}\n\n"
)
else:
for evt in missed:
yield (
f"event: {evt['type']}\n"
f"data: {json.dumps(evt['data'])}\n"
f"id: {evt['id']}\n\n"
)
except (ValueError, TypeError):
pass
while True:
try:
evt = await asyncio.wait_for(queue.get(), timeout=25.0)
yield (
f"event: {evt['type']}\n"
f"data: {json.dumps(evt['data'])}\n"
f"id: {evt['id']}\n\n"
)
except asyncio.TimeoutError:
# Keepalive ping — not buffered in event_log
yield f"event: ping\ndata: {json.dumps({'ts': int(time.time() * 1000)})}\n\n"
finally:
room.subscribers.pop(device_id, None)
if room.members.get(device_id) == "host":
_schedule_failover(room, device_id)
# ═════════════════════════════════════════════════════════════════════════════
# Endpoints
# ═════════════════════════════════════════════════════════════════════════════
# ── Join ──────────────────────────────────────────────────────────────────────
class JoinRequest(BaseModel):
room_id: str
device_id: str
display_name: str | None = None
is_tv: bool = False
@router.post("/{room_id}/join")
async def join_room(room_id: str, body: JoinRequest):
_check_enabled()
room = _get_or_create_room(room_id)
device_id = body.device_id[:64]
# Role assignment
existing_tv = [d for d, r in room.members.items() if r == "tv"]
if body.is_tv and not existing_tv:
role = "tv"
elif not room.members:
role = "host"
room.host_device_id = device_id
elif device_id in room.members:
# Rejoin: keep existing role (re-issue token)
role = room.members[device_id]
else:
role = "guest"
room.members[device_id] = role
room.last_activity = time.time()
now = time.time()
payload = {
"device_id": device_id,
"room_id": room_id,
"role": role,
"issued_at": int(now),
"expires_at": int(now + TOKEN_LIFETIME_S),
}
token = _sign_token(payload)
_broadcast(room, "member_updated", {
"members": dict(room.members),
"host_device_id": room.host_device_id,
})
_log.info("Room %s: %s joined as %s", room_id, device_id, role)
return {
"session_token": token,
"role": role,
"expires_at": payload["expires_at"],
"room_id": room_id,
}
# ── Snapshot ──────────────────────────────────────────────────────────────────
@router.get("/{room_id}/snapshot")
async def get_snapshot(room_id: str, token: str = Query(...)):
_check_enabled()
_require_session(room_id, token)
return _snapshot_dict(_rooms[room_id])
# ── SSE stream ────────────────────────────────────────────────────────────────
@router.get("/{room_id}/events")
async def room_events(
room_id: str,
token: str = Query(...),
lastEventId: str | None = Query(None),
):
_check_enabled()
payload = _require_session(room_id, token)
room = _rooms[room_id]
device_id = payload["device_id"]
return StreamingResponse(
_sse_stream(room, device_id, lastEventId),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache",
"X-Accel-Buffering": "no",
"Connection": "keep-alive",
},
)
# ── Queue mutations ───────────────────────────────────────────────────────────
class QueueItemPayload(BaseModel):
song_id: str
source_kind: str
source_ref: str
title: str
artist: str | None = None
album_art: str | None = None
singer_label: str | None = None
requested_by: str
class QueueOperation(BaseModel):
type: str
item: QueueItemPayload | None = None
item_id: str | None = None
before_item_id: str | None = None # reorder: insert before this id (None = tail)
class QueueMutateRequest(BaseModel):
client_action_id: str
base_queue_version: int
operation: QueueOperation
device_id: str
session_token: str
@router.post("/{room_id}/queue/mutate")
async def mutate_queue(room_id: str, body: QueueMutateRequest):
_check_enabled()
payload = _require_session(room_id, body.session_token)
room = _rooms[room_id]
device_id = payload["device_id"]
role = room.members.get(device_id, "guest")
_check_rate(room, device_id)
# Idempotency
cached = _get_cached(room, body.client_action_id)
if cached:
return cached
# Version conflict
if body.base_queue_version != room.queue_version:
return {
"accepted": False,
"conflict": True,
"server_queue_version": room.queue_version,
"queue": [dataclasses.asdict(i) for i in room.queue],
"client_action_id": body.client_action_id,
"reason": "base_queue_version_mismatch",
}
op = body.operation
if op.type == "enqueue":
_authz(role, _HOST_CURATOR_GUEST)
if op.item is None:
raise HTTPException(status_code=422, detail="item required for enqueue")
if role == "guest":
limit = int(os.environ.get("KK_GUEST_QUEUE_LIMIT", "5"))
own = [i for i in room.queue if i.requested_by == device_id]
if len(own) >= limit:
raise HTTPException(status_code=422, detail="guest_queue_limit_reached")
sl = (op.item.singer_label or "")[:64] or None
new_item = RoomQueueItem(
id=str(uuid.uuid4()),
song_id=op.item.song_id[:256],
source_kind=op.item.source_kind,
source_ref=op.item.source_ref[:512],
title=op.item.title[:256],
artist=(op.item.artist or "")[:256] or None,
album_art=op.item.album_art,
singer_label=sl,
requested_by=device_id,
)
room.queue.append(new_item)
if room.playback.current_index < 0 and room.queue:
room.playback.current_index = 0
elif op.type == "remove":
if op.item_id is None:
raise HTTPException(status_code=422, detail="item_id required for remove")
item = next((i for i in room.queue if i.id == op.item_id), None)
if item is not None:
if item.requested_by != device_id:
_authz(role, _HOST_CURATOR)
else:
_authz(role, _HOST_CURATOR_GUEST)
idx = room.queue.index(item)
room.queue.remove(item)
if not room.queue:
room.playback.current_index = -1
elif idx < room.playback.current_index:
room.playback.current_index -= 1
elif idx == room.playback.current_index:
room.playback.current_index = min(
room.playback.current_index, len(room.queue) - 1
)
elif op.type == "reorder":
_authz(role, _HOST_CURATOR)
if op.item_id is None:
raise HTTPException(status_code=422, detail="item_id required for reorder")
from_idx = next(
(i for i, it in enumerate(room.queue) if it.id == op.item_id), None
)
if from_idx is not None:
item = room.queue.pop(from_idx)
if op.before_item_id is None:
room.queue.append(item)
to_idx = len(room.queue) - 1
else:
to_idx = next(
(i for i, it in enumerate(room.queue) if it.id == op.before_item_id),
len(room.queue),
)
room.queue.insert(to_idx, item)
# Fix current_index tracking
ci = room.playback.current_index
if ci == from_idx:
room.playback.current_index = to_idx
elif from_idx < ci <= to_idx:
room.playback.current_index = ci - 1
elif to_idx <= ci < from_idx:
room.playback.current_index = ci + 1
elif op.type == "sing_now":
_authz(role, _HOST_ONLY)
if op.item_id is None:
raise HTTPException(status_code=422, detail="item_id required for sing_now")
idx = next(
(i for i, it in enumerate(room.queue) if it.id == op.item_id), None
)
if idx is not None:
room.playback.current_index = idx
elif op.type == "clear_all":
_authz(role, _HOST_ONLY)
room.queue.clear()
room.playback.current_index = -1
elif op.type == "advance":
if role not in _HOST_ONLY and role != "tv":
raise HTTPException(status_code=403, detail="insufficient_role")
ci = room.playback.current_index
if ci >= 0 and room.queue:
room.queue.pop(ci)
room.playback.current_index = (
-1 if not room.queue else min(ci, len(room.queue) - 1)
)
else:
raise HTTPException(status_code=422, detail=f"Unknown operation: {op.type!r}")
room.queue_version += 1
room.last_activity = time.time()
queue_list = [dataclasses.asdict(i) for i in room.queue]
response: dict = {
"accepted": True,
"queue_version": room.queue_version,
"queue": queue_list,
"client_action_id": body.client_action_id,
}
_cache(room, body.client_action_id, response)
_broadcast(room, "queue_updated", {
"queue_version": room.queue_version,
"queue": queue_list,
})
return response
# ── Playback mutations ────────────────────────────────────────────────────────
class PlaybackOperation(BaseModel):
type: str
position_ms: int | None = None
semitones: int | None = None
bpm_delta: int | None = None
class PlaybackMutateRequest(BaseModel):
client_action_id: str
device_id: str
session_token: str
operation: PlaybackOperation
@router.post("/{room_id}/playback/mutate")
async def mutate_playback(room_id: str, body: PlaybackMutateRequest):
_check_enabled()
payload = _require_session(room_id, body.session_token)
room = _rooms[room_id]
device_id = payload["device_id"]
role = room.members.get(device_id, "guest")
_check_rate(room, device_id, burst=5.0, rate=5.0)
_authz(role, _HOST_ONLY)
op = body.operation
if op.type == "play":
room.playback.is_playing = True
elif op.type == "pause":
room.playback.is_playing = False
elif op.type == "seek":
if op.position_ms is not None:
room.playback.position_ms = max(0, op.position_ms)
elif op.type == "set_key":
if op.semitones is not None:
room.playback.key_semitones = max(-6, min(6, op.semitones))
elif op.type == "set_tempo":
if op.bpm_delta is not None:
room.playback.tempo_delta = max(-20, min(20, op.bpm_delta))
else:
raise HTTPException(status_code=422, detail=f"Unknown operation: {op.type!r}")
room.last_activity = time.time()
playback_dict = dataclasses.asdict(room.playback)
_broadcast(room, "playback_updated", {
"queue_version": room.queue_version,
"playback_state": playback_dict,
})
return {
"accepted": True,
"client_action_id": body.client_action_id,
"playback_state": playback_dict,
}
# ── Host transfer ─────────────────────────────────────────────────────────────
class TransferHostRequest(BaseModel):
new_host_device_id: str
session_token: str
@router.post("/{room_id}/transfer_host")
async def transfer_host(room_id: str, body: TransferHostRequest):
_check_enabled()
payload = _require_session(room_id, body.session_token)
room = _rooms[room_id]
device_id = payload["device_id"]
role = room.members.get(device_id, "guest")
_authz(role, _HOST_ONLY)
new_host = body.new_host_device_id
if new_host not in room.members:
raise HTTPException(status_code=404, detail="new_host_device_id not in room")
room.members[device_id] = "guest"
room.members[new_host] = "host"
room.host_device_id = new_host
_broadcast(room, "member_updated", {
"members": dict(room.members),
"host_device_id": room.host_device_id,
})
return {"ok": True, "host_device_id": new_host}