Files
unshackle/unshackle/core/api/session_store.py
T
imSp4rky 5086dafff3 feat(api)!: add a server drain and never answer with a 5xx
POST/DELETE /api/dashboard/drain refuses new sessions and jobs (SERVER_DRAINING, 409) and warns open sessions. A CDN can replace a 5xx body, so server errors are now 422, retryable ones and the tunnel check 424, and a new middleware turns any 5xx into 422.

BREAKING CHANGE: INTERNAL_ERROR, DOWNLOAD_ERROR, WORKER_ERROR and the fallback return 422 instead of 500; NETWORK_ERROR and SERVICE_UNAVAILABLE return 424 instead of 503; /api/tunnel/check failures return 424 instead of 502.
2026-10-21 17:15:33 -06:00

374 lines
15 KiB
Python

"""Server-side remote session store for the remote-dl client-server architecture.
Maintains authenticated service instances between API calls so that
a client can authenticate once and then make several requests (get the tracks,
get the segment URLs, get the licence in proxy mode) with the same
remote session.
"""
from __future__ import annotations
import asyncio
import logging
import uuid
from collections import deque
from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any, Deque, Dict, List, Optional
from unshackle.core.api.events import bus
from unshackle.core.api.input_bridge import AUTH_INPUT_TIMEOUT, AuthStatus, InputBridge
from unshackle.core.api.sanitize import sanitize_log
from unshackle.core.config import config
from unshackle.core.tracks import Track
log = logging.getLogger("api.session")
DRAIN_WARNING = (
"This server restarts for an update when the open downloads finish. "
"This download continues. Start new downloads after the restart."
)
@dataclass
class SessionEntry:
"""A single authenticated remote session with a service."""
session_id: str
service_tag: str
service_instance: Any
titles: Any = None # Titles_T from get_titles()
title_map: Dict[str, Any] = field(default_factory=dict)
current_title_id: Optional[str] = None # title the client last asked tracks for
tracks: Dict[str, Track] = field(default_factory=dict)
served_keys: Dict[str, tuple[str, str]] = field(
default_factory=dict
) # KID -> (KEY, serving vault name or "cdm") from server_cdm
tracks_by_title: Dict[str, Dict[str, Track]] = field(default_factory=dict)
chapters_by_title: Dict[str, List[Any]] = field(default_factory=dict)
lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False, compare=False)
creator_ip: Optional[str] = None
owner_key: Optional[str] = None # X-Secret-Key that owns this session
cache_tag: Optional[str] = None
server_account: Optional[str] = None # profile name when the server lent its own account
server_cdm: Optional[bool] = None # False: the client's own device licenses this session
server_cdm_max_height: Optional[int] = None
server_vault: bool = False # a session the client's device licenses may still take keys from the server vault
server_device: bool = False # its service runs on the server's lent device, so keys come only from a vault
client_auth: bool = False # the login is the client's: it succeeded without a server account
input_bridge: Optional[InputBridge] = None
log_buffer: Optional[Any] = None # SessionLogBuffer mirroring the service's self.log
auth_status: AuthStatus = AuthStatus.AUTHENTICATED
auth_error: Optional[str] = None
client: Dict[str, Any] = field(default_factory=dict) # version/argv/platform the client reported
actions: Deque[Dict[str, Any]] = field(default_factory=lambda: deque(maxlen=500))
created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
last_accessed: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
def touch(self) -> None:
"""Update last_accessed timestamp."""
self.last_accessed = datetime.now(timezone.utc)
@property
def in_use(self) -> bool:
"""True while a request holds the lock for service work; the store does not expire such a remote session.
A request can run for longer than the TTL, and expiry would remove the cache directory
that the worker thread still writes to.
"""
return self.lock.locked()
def summary(self) -> Dict[str, Any]:
"""Dashboard view of the session: no service instance, no raw owner key."""
from unshackle.core.api.stats import mask_key
now = datetime.now(timezone.utc)
title_id = (
self.current_title_id if self.current_title_id in self.title_map else next(iter(self.title_map), None)
)
title = self.title_map.get(title_id) if title_id else None
return {
"id": self.session_id,
"owner": mask_key(self.owner_key),
"creator_ip": self.creator_ip,
"service": self.service_tag,
"title_id": title_id,
"title": str(title) if title else None,
"titles": len(self.title_map),
"tracks": len(self.tracks),
"auth_status": self.auth_status.value,
"auth_error": self.auth_error,
"server_account": self.server_account,
"server_cdm": self.server_cdm,
"server_cdm_max_height": self.server_cdm_max_height,
"log_seq": self.log_buffer.last_seq if self.log_buffer else 0,
"client": self.client,
"actions": list(self.actions),
"created_at": self.created_at.isoformat(),
"last_accessed": self.last_accessed.isoformat(),
"created_ts": self.created_at.timestamp(),
"last_accessed_ts": self.last_accessed.timestamp(),
"age_seconds": int((now - self.created_at).total_seconds()),
"idle_seconds": int((now - self.last_accessed).total_seconds()),
}
def _schedule_pending_reload(service_tag: str) -> None:
"""Apply staged service reloads now that a remote session ended; the task runs after the store lock releases."""
from unshackle.core.api.download_manager import schedule_pending_reload
schedule_pending_reload(service_tag)
def _publish(action: str, entry: SessionEntry, reason: Optional[str] = None) -> None:
data = {"action": action, **entry.summary()}
if reason:
data["reason"] = reason
bus.publish("session", data)
class SessionStore:
"""Thread-safe remote session store with TTL-based expiration."""
def __init__(self) -> None:
self._sessions: Dict[str, SessionEntry] = {}
self._lock = asyncio.Lock()
self._cleanup_task: Optional[asyncio.Task] = None
self.draining = False
@property
def ttl(self) -> int:
"""Remote session TTL in seconds from config."""
return config.serve.get("session_ttl", 300)
@property
def max_sessions(self) -> Optional[int]:
"""Max concurrent sessions from config; None when the operator set no limit.
``max_sessions: null`` or ``0`` means unlimited, so a dashboard can tell "no cap" from
a cap that happens to sit at the default.
"""
limit = config.serve.get("max_sessions", 100)
return limit if isinstance(limit, int) and limit > 0 else None
async def create(
self,
service_tag: str,
service_instance: Any,
session_id: Optional[str] = None,
owner_key: Optional[str] = None,
creator_ip: Optional[str] = None,
server_account: Optional[str] = None,
) -> SessionEntry:
"""Make a new remote session with an authenticated service instance."""
async with self._lock:
max_sessions = self.max_sessions
if max_sessions is not None and len(self._sessions) >= max_sessions:
sessions = self._sessions
oldest_id = min(sessions, key=lambda k: (sessions[k].in_use, sessions[k].last_accessed))
log.warning(f"Max sessions reached ({max_sessions}), evicting oldest: {oldest_id}")
evicted = self._sessions.pop(oldest_id)
if evicted.input_bridge:
evicted.input_bridge.cancel()
self.cleanup_cache_dir(evicted.cache_tag)
_publish("delete", evicted, "evicted")
_schedule_pending_reload(evicted.service_tag)
session_id = session_id or str(uuid.uuid4())
entry = SessionEntry(
session_id=session_id,
service_tag=service_tag,
service_instance=service_instance,
owner_key=owner_key,
creator_ip=creator_ip,
server_account=server_account,
)
self._sessions[session_id] = entry
_publish("create", entry)
log.info(f"Created session {sanitize_log(session_id)} for service {sanitize_log(service_tag)}")
return entry
async def get(self, session_id: str) -> Optional[SessionEntry]:
"""Get a remote session by ID, returns None if not found or expired."""
async with self._lock:
entry = self._sessions.get(session_id)
if entry is None:
return None
if not entry.in_use and entry.auth_status not in (AuthStatus.AUTHENTICATING, AuthStatus.PENDING_INPUT):
elapsed = (datetime.now(timezone.utc) - entry.last_accessed).total_seconds()
if elapsed > self.ttl:
log.info(f"Session {sanitize_log(session_id)} expired (elapsed={elapsed:.0f}s, ttl={self.ttl}s)")
self.cleanup_cache_dir(entry.cache_tag)
_publish("delete", self._sessions.pop(session_id), "expired")
_schedule_pending_reload(entry.service_tag)
return None
entry.touch()
return entry
def peek(self, session_id: str) -> Optional[SessionEntry]:
"""A remote session entry without touching it, for read-only observers.
``get`` refreshes ``last_accessed`` and expires stale entries, so an observer polling
through it would keep an idle remote session alive and always report it as active.
"""
return self._sessions.get(session_id)
async def delete(self, session_id: str) -> bool:
"""Delete a remote session. Returns True if it existed."""
async with self._lock:
entry = self._sessions.pop(session_id, None)
if entry:
if entry.input_bridge:
entry.input_bridge.cancel()
self.cleanup_cache_dir(entry.cache_tag)
_publish("delete", entry, "closed")
log.info(f"Deleted session {sanitize_log(session_id)}")
_schedule_pending_reload(entry.service_tag)
return True
return False
async def cleanup_expired(self) -> int:
"""Remove all expired sessions. Returns count of removed sessions."""
async with self._lock:
now = datetime.now(timezone.utc)
expired = []
for sid, entry in self._sessions.items():
if entry.in_use:
continue
elapsed = (now - entry.last_accessed).total_seconds()
if entry.auth_status in (AuthStatus.AUTHENTICATING, AuthStatus.PENDING_INPUT):
if elapsed > AUTH_INPUT_TIMEOUT:
expired.append(sid)
elif elapsed > self.ttl:
expired.append(sid)
ended_tags: set[str] = set()
for sid in expired:
entry = self._sessions.pop(sid)
if entry.input_bridge:
entry.input_bridge.cancel()
self.cleanup_cache_dir(entry.cache_tag)
_publish("delete", entry, "expired")
ended_tags.add(entry.service_tag)
for tag in ended_tags:
_schedule_pending_reload(tag)
if expired:
log.info(f"Cleaned up {len(expired)} expired sessions")
return len(expired)
async def start_cleanup_loop(self) -> None:
"""Start periodic cleanup of expired sessions."""
if self._cleanup_task is not None:
return
async def loop() -> None:
while True:
await asyncio.sleep(60)
try:
await self.cleanup_expired()
except Exception:
log.exception("Error during session cleanup")
self._cleanup_task = asyncio.create_task(loop())
log.info("Session cleanup loop started")
async def stop_cleanup_loop(self) -> None:
"""Stop the periodic cleanup task."""
if self._cleanup_task is not None:
self._cleanup_task.cancel()
self._cleanup_task = None
async def cancel_all_bridges(self) -> None:
"""Cancel all active input bridges (called on server shutdown)."""
async with self._lock:
for entry in self._sessions.values():
if entry.input_bridge:
entry.input_bridge.cancel()
count = len(self._sessions)
if count:
log.info(f"Cancelled bridges for {count} active session(s)")
@staticmethod
def cleanup_cache_dir(cache_tag: Optional[str]) -> None:
"""Remove the remote session cache directory and empty parents."""
if not cache_tag:
return
import shutil
cache_dir = config.directories.cache / cache_tag
if cache_dir.is_dir():
try:
shutil.rmtree(cache_dir)
except Exception as e:
log.warning(f"Failed to remove session cache {cache_dir}: {e}")
for parent in cache_dir.parents:
if parent == config.directories.cache:
break
try:
if parent.is_dir() and not any(parent.iterdir()):
parent.rmdir()
except OSError:
break
@staticmethod
def publish_update(entry: SessionEntry) -> None:
"""Tell dashboard listeners that a session's summary changed (titles or tracks loaded, auth settled)."""
_publish("update", entry)
def record_action(self, session_id: str, action: Dict[str, Any]) -> None:
"""Append one request to the session's action log and tell dashboard listeners."""
entry = self._sessions.get(session_id)
if entry is None:
return
entry.actions.append(action)
_publish("update", entry)
def list(self) -> List[SessionEntry]:
"""Snapshot of every live session."""
return list(self._sessions.values())
def start_drain(self) -> None:
"""Refuse new sessions and jobs until the restart, and warn each open session through its service log."""
if self.draining:
return
self.draining = True
log.warning(f"Draining: new sessions and jobs are refused, {len(self._sessions)} session(s) open")
for entry in self._sessions.values():
if entry.log_buffer is not None:
entry.log_buffer.append(logging.WARNING, DRAIN_WARNING)
def stop_drain(self) -> None:
if self.draining:
self.draining = False
log.warning("Drain cancelled: new sessions and jobs are accepted again")
@property
def session_count(self) -> int:
"""Number of active sessions."""
return len(self._sessions)
session_store: Optional[SessionStore] = None
def refuse_while_draining() -> None:
"""Raise SERVER_DRAINING for a new session or job once the operator has started a drain."""
from unshackle.core.api.errors import APIError, APIErrorCode
if get_session_store().draining:
raise APIError(
APIErrorCode.SERVER_DRAINING,
"This server restarts for an update and does not start new sessions or downloads now. "
"Try again in a few minutes.",
retryable=True,
)
def get_session_store() -> SessionStore:
"""Get or make the global remote session store singleton."""
global session_store
if session_store is None:
session_store = SessionStore()
return session_store