"""
Redis utilities for cross-worker coordination and caching.

Provides:
- Distributed locking (stream gating, generic locks)
- Shared caching (HEAD responses, extractors, MPD, segments, init segments)
- In-flight request deduplication
- Cooldown/throttle tracking

All caches are shared across all uvicorn workers via Redis.

IMPORTANT: Redis is OPTIONAL. If settings.redis_url is None, all functions
gracefully degrade:
- Locks always succeed immediately (no cross-worker coordination)
- Cache operations return None/False (no shared caching)
- Cooldowns always allow (no rate limiting)

This allows single-worker deployments to work without Redis.
"""

import asyncio
import hashlib
import json
import logging
import time
from typing import Optional

from mediaflow_proxy.configs import settings

logger = logging.getLogger(__name__)

# =============================================================================
# Redis Clients (Lazy Singletons)
# =============================================================================
# Two clients: one for text/JSON (decode_responses=True), one for binary data

_redis_client = None
_redis_binary_client = None
_redis_available: Optional[bool] = None  # None = not checked yet


def is_redis_configured() -> bool:
    """Check if Redis URL is configured in settings."""
    return settings.redis_url is not None and settings.redis_url.strip() != ""


async def is_redis_available() -> bool:
    """
    Check if Redis is configured and reachable.

    Caches the result after first successful/failed connection attempt.
    """
    global _redis_available

    if not is_redis_configured():
        return False

    if _redis_available is not None:
        return _redis_available

    # Try to connect
    try:
        import redis.asyncio as redis

        client = redis.from_url(
            settings.redis_url,
            decode_responses=True,
            socket_connect_timeout=2,
            socket_timeout=2,
        )
        await client.ping()
        await client.aclose()
        _redis_available = True
        logger.info(f"Redis is available: {settings.redis_url}")
    except Exception as e:
        _redis_available = False
        logger.warning(f"Redis not available (features will be disabled): {e}")

    return _redis_available


async def get_redis():
    """
    Get or create the Redis connection pool for text/JSON data (lazy singleton).

    The connection pool is shared across all async tasks in a single worker.
    Each worker process has its own pool, but Redis itself coordinates across workers.

    Returns None if Redis is not configured or not available.
    """
    global _redis_client

    if not is_redis_configured():
        return None

    if _redis_client is None:
        import redis.asyncio as redis

        _redis_client = redis.from_url(
            settings.redis_url,
            decode_responses=True,
            socket_connect_timeout=5,
            socket_timeout=5,
        )
        # Test connection
        try:
            await _redis_client.ping()
            logger.info(f"Redis connected (text): {settings.redis_url}")
        except Exception as e:
            logger.error(f"Redis connection failed: {e}")
            _redis_client = None
            return None
    return _redis_client


async def get_redis_binary():
    """
    Get or create the Redis connection pool for binary data (lazy singleton).

    Used for caching segments and init segments without base64 encoding overhead.

    Returns None if Redis is not configured or not available.
    """
    global _redis_binary_client

    if not is_redis_configured():
        return None

    if _redis_binary_client is None:
        import redis.asyncio as redis

        _redis_binary_client = redis.from_url(
            settings.redis_url,
            decode_responses=False,  # Keep bytes as-is
            socket_connect_timeout=5,
            socket_timeout=5,
        )
        # Test connection
        try:
            await _redis_binary_client.ping()
            logger.info(f"Redis connected (binary): {settings.redis_url}")
        except Exception as e:
            logger.error(f"Redis binary connection failed: {e}")
            _redis_binary_client = None
            return None
    return _redis_binary_client


async def close_redis():
    """Close all Redis connection pools (call on shutdown)."""
    global _redis_client, _redis_binary_client, _redis_available
    if _redis_client is not None:
        await _redis_client.aclose()
        _redis_client = None
    if _redis_binary_client is not None:
        await _redis_binary_client.aclose()
        _redis_binary_client = None
    _redis_available = None
    logger.info("Redis connections closed")


# =============================================================================
# Instance Namespace Helper
# =============================================================================
# Some cached data is bound to the outgoing IP of the pod that produced it
# (e.g. extractor results resolved via the pod's egress IP). Sharing these
# entries across pods in a multi-instance deployment causes other pods to serve
# stale/wrong URLs.
#
# Set CACHE_NAMESPACE (env: CACHE_NAMESPACE) to a unique value per pod (e.g.
# pod name, hostname, or any discriminator). Instance-scoped keys are then
# stored under  "<namespace>:<original_key>", while fully-shared keys (MPD,
# init segments, media segments, locks, stream gates) remain unchanged.


def make_instance_key(key: str) -> str:
    """Prefix *key* with the configured instance namespace.

    Use this for cache/coordination keys that must NOT be shared across pods
    because the underlying data is specific to a pod's outgoing IP (e.g.
    extractor results).  Common content (MPD, init/media segments) should
    never be namespaced.

    If ``settings.cache_namespace`` is not set the key is returned unchanged,
    so single-instance deployments are unaffected.
    """
    ns = settings.cache_namespace
    return f"{ns}:{key}" if ns else key


# =============================================================================
# Stream Gate (Distributed Lock)
# =============================================================================
# Serializes upstream connection handshakes per-URL across all workers.
# Uses SET NX EX for atomic acquire with auto-expiry.

GATE_PREFIX = "mfp:stream_gate:"
GATE_TTL = 15  # seconds - auto-expire if worker crashes mid-request


def _gate_key(url: str) -> str:
    """Generate Redis key for a stream gate."""
    url_hash = hashlib.md5(url.encode()).hexdigest()
    return f"{GATE_PREFIX}{url_hash}"


async def acquire_stream_gate(url: str, timeout: float = 15.0) -> bool:
    """
    Try to acquire a per-URL stream gate (distributed lock).

    Only one worker across all processes can hold the gate for a given URL.
    The gate auto-expires after GATE_TTL seconds to prevent deadlocks.

    If Redis is not available, always returns True (no coordination).

    Args:
        url: The upstream URL to gate
        timeout: Maximum time to wait for the gate (seconds)

    Returns:
        True if gate acquired (or Redis unavailable), False if timeout
    """
    r = await get_redis()
    if r is None:
        # No Redis - no cross-worker coordination, always allow
        return True

    key = _gate_key(url)
    deadline = time.time() + timeout

    while time.time() < deadline:
        # SET NX EX is atomic: only succeeds if key doesn't exist
        if await r.set(key, "1", nx=True, ex=GATE_TTL):
            logger.debug(f"[Redis] Acquired stream gate: {key[:50]}...")
            return True
        # Another worker holds the gate, wait and retry
        await asyncio.sleep(0.05)  # 50ms poll interval

    logger.warning(f"[Redis] Gate acquisition timeout ({timeout}s): {key[:50]}...")
    return False


async def release_stream_gate(url: str):
    """
    Release a per-URL stream gate.

    Safe to call even if gate wasn't acquired or already expired.
    No-op if Redis is not available.
    """
    r = await get_redis()
    if r is None:
        return

    key = _gate_key(url)
    await r.delete(key)
    logger.debug(f"[Redis] Released stream gate: {key[:50]}...")


async def extend_stream_gate(url: str, ttl: int = GATE_TTL):
    """
    Extend the TTL of a stream gate to keep it held during long streams.

    Should be called periodically (e.g., every 10s) while streaming.
    No-op if Redis is not available or gate doesn't exist.
    """
    r = await get_redis()
    if r is None:
        return

    key = _gate_key(url)
    await r.expire(key, ttl)
    logger.debug(f"[Redis] Extended stream gate TTL ({ttl}s): {key[:50]}...")


async def is_stream_gate_held(url: str) -> bool:
    """Check if a stream gate is currently held. Returns False if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return False

    key = _gate_key(url)
    return await r.exists(key) > 0


# =============================================================================
# HEAD Response Cache
# =============================================================================
# Caches upstream response headers so repeated HEAD probes (e.g., from ExoPlayer)
# can be served without any upstream connection. Shared across all workers.

HEAD_CACHE_PREFIX = "mfp:head_cache:"
HEAD_CACHE_TTL = 60  # seconds - Vidoza CDN URLs typically expire in minutes


def _head_cache_key(url: str) -> str:
    """Generate Redis key for HEAD cache entry."""
    url_hash = hashlib.md5(url.encode()).hexdigest()
    return f"{HEAD_CACHE_PREFIX}{url_hash}"


async def get_cached_head(url: str) -> Optional[dict]:
    """
    Get cached HEAD response metadata for a URL.

    Args:
        url: The upstream URL

    Returns:
        Dict with 'headers' and 'status' keys, or None if not cached (or Redis unavailable)
    """
    r = await get_redis()
    if r is None:
        return None

    key = _head_cache_key(url)
    data = await r.get(key)
    if data:
        logger.debug(f"[Redis] HEAD cache hit: {key[:50]}...")
        return json.loads(data)
    return None


async def set_cached_head(url: str, headers: dict, status: int):
    """
    Cache HEAD response metadata for a URL.

    No-op if Redis is not available.

    Args:
        url: The upstream URL
        headers: Response headers dict (will be JSON serialized)
        status: HTTP status code (e.g., 200, 206)
    """
    r = await get_redis()
    if r is None:
        return

    key = _head_cache_key(url)
    # Only cache headers that are useful for HEAD responses
    # Filter to avoid caching large or irrelevant headers
    cached_headers = {}
    for k, v in headers.items():
        k_lower = k.lower()
        if k_lower in (
            "content-type",
            "content-length",
            "accept-ranges",
            "content-range",
            "etag",
            "last-modified",
            "cache-control",
        ):
            cached_headers[k_lower] = v

    payload = json.dumps({"headers": cached_headers, "status": status})
    await r.set(key, payload, ex=HEAD_CACHE_TTL)
    logger.debug(f"[Redis] HEAD cache set ({HEAD_CACHE_TTL}s TTL): {key[:50]}...")


# =============================================================================
# Generic Distributed Lock
# =============================================================================
# For cross-worker coordination (e.g., segment downloads, prebuffering)

LOCK_PREFIX = "mfp:lock:"
DEFAULT_LOCK_TTL = 30  # seconds


def _lock_key(key: str) -> str:
    """Generate Redis key for a lock."""
    key_hash = hashlib.md5(key.encode()).hexdigest()
    return f"{LOCK_PREFIX}{key_hash}"


async def acquire_lock(key: str, ttl: int = DEFAULT_LOCK_TTL, timeout: float = 30.0) -> bool:
    """
    Acquire a distributed lock.

    If Redis is not available, always returns True (no coordination).

    Args:
        key: The lock identifier
        ttl: Lock auto-expiry time in seconds (prevents deadlocks)
        timeout: Maximum time to wait for the lock

    Returns:
        True if lock acquired (or Redis unavailable), False if timeout
    """
    r = await get_redis()
    if r is None:
        return True  # No Redis - no coordination

    lock_key = _lock_key(key)
    deadline = time.time() + timeout

    while time.time() < deadline:
        if await r.set(lock_key, "1", nx=True, ex=ttl):
            logger.debug(f"[Redis] Acquired lock: {key[:60]}...")
            return True
        await asyncio.sleep(0.05)

    logger.warning(f"[Redis] Lock timeout ({timeout}s): {key[:60]}...")
    return False


async def release_lock(key: str):
    """Release a distributed lock. No-op if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return

    lock_key = _lock_key(key)
    await r.delete(lock_key)
    logger.debug(f"[Redis] Released lock: {key[:60]}...")


# =============================================================================
# Extractor Cache
# =============================================================================
# Caches extractor results (JSON) across all workers

EXTRACTOR_CACHE_PREFIX = "mfp:extractor:"
EXTRACTOR_CACHE_TTL = 300  # 5 minutes


def _extractor_key(key: str) -> str:
    """Generate Redis key for extractor cache."""
    key_hash = hashlib.md5(key.encode()).hexdigest()
    return f"{EXTRACTOR_CACHE_PREFIX}{key_hash}"


async def get_cached_extractor(key: str) -> Optional[dict]:
    """Get cached extractor result. Returns None if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return None

    redis_key = _extractor_key(key)
    data = await r.get(redis_key)
    if data:
        logger.debug(f"[Redis] Extractor cache hit: {key[:60]}...")
        return json.loads(data)
    return None


async def set_cached_extractor(key: str, data: dict, ttl: int = EXTRACTOR_CACHE_TTL):
    """Cache extractor result. No-op if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return

    redis_key = _extractor_key(key)
    await r.set(redis_key, json.dumps(data), ex=ttl)
    logger.debug(f"[Redis] Extractor cache set ({ttl}s TTL): {key[:60]}...")


# =============================================================================
# MPD Cache
# =============================================================================
# Caches parsed MPD manifests (JSON) across all workers

MPD_CACHE_PREFIX = "mfp:mpd:"
DEFAULT_MPD_CACHE_TTL = 60  # 1 minute


def _mpd_key(key: str) -> str:
    """Generate Redis key for MPD cache."""
    key_hash = hashlib.md5(key.encode()).hexdigest()
    return f"{MPD_CACHE_PREFIX}{key_hash}"


async def get_cached_mpd(key: str) -> Optional[dict]:
    """Get cached MPD manifest. Returns None if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return None

    redis_key = _mpd_key(key)
    data = await r.get(redis_key)
    if data:
        logger.debug(f"[Redis] MPD cache hit: {key[:60]}...")
        return json.loads(data)
    return None


async def set_cached_mpd(key: str, data: dict, ttl: int | float = DEFAULT_MPD_CACHE_TTL):
    """Cache MPD manifest. No-op if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return

    redis_key = _mpd_key(key)
    # Ensure TTL is an integer (Redis requires int for ex parameter)
    ttl_int = max(1, int(ttl))
    await r.set(redis_key, json.dumps(data), ex=ttl_int)
    logger.debug(f"[Redis] MPD cache set ({ttl_int}s TTL): {key[:60]}...")


# =============================================================================
# Segment Cache (Binary)
# =============================================================================
# Caches HLS/DASH segments across all workers

SEGMENT_CACHE_PREFIX = b"mfp:segment:"
DEFAULT_SEGMENT_CACHE_TTL = 60  # 1 minute


def _segment_key(url: str) -> bytes:
    """Generate Redis key for segment cache."""
    url_hash = hashlib.md5(url.encode()).hexdigest()
    return SEGMENT_CACHE_PREFIX + url_hash.encode()


async def get_cached_segment(url: str) -> Optional[bytes]:
    """Get cached segment data. Returns None if Redis unavailable."""
    r = await get_redis_binary()
    if r is None:
        return None

    key = _segment_key(url)
    data = await r.get(key)
    if data:
        logger.debug(f"[Redis] Segment cache hit: {url[:60]}...")
    return data


async def set_cached_segment(url: str, data: bytes, ttl: int = DEFAULT_SEGMENT_CACHE_TTL):
    """Cache segment data. No-op if Redis unavailable."""
    r = await get_redis_binary()
    if r is None:
        return

    key = _segment_key(url)
    await r.set(key, data, ex=ttl)
    logger.debug(f"[Redis] Segment cache set ({ttl}s TTL, {len(data)} bytes): {url[:60]}...")


# =============================================================================
# Init Segment Cache (Binary)
# =============================================================================
# Caches initialization segments across all workers

INIT_CACHE_PREFIX = b"mfp:init:"
DEFAULT_INIT_CACHE_TTL = 3600  # 1 hour


def _init_key(url: str) -> bytes:
    """Generate Redis key for init segment cache."""
    url_hash = hashlib.md5(url.encode()).hexdigest()
    return INIT_CACHE_PREFIX + url_hash.encode()


async def get_cached_init_segment(url: str) -> Optional[bytes]:
    """Get cached init segment data. Returns None if Redis unavailable."""
    r = await get_redis_binary()
    if r is None:
        return None

    key = _init_key(url)
    data = await r.get(key)
    if data:
        logger.debug(f"[Redis] Init segment cache hit: {url[:60]}...")
    return data


async def set_cached_init_segment(url: str, data: bytes, ttl: int = DEFAULT_INIT_CACHE_TTL):
    """Cache init segment data. No-op if Redis unavailable."""
    r = await get_redis_binary()
    if r is None:
        return

    key = _init_key(url)
    await r.set(key, data, ex=ttl)
    logger.debug(f"[Redis] Init segment cache set ({ttl}s TTL, {len(data)} bytes): {url[:60]}...")


# =============================================================================
# Processed Init Segment Cache (Binary)
# =============================================================================
# Caches DRM-stripped/processed init segments across all workers

PROCESSED_INIT_CACHE_PREFIX = b"mfp:processed_init:"
DEFAULT_PROCESSED_INIT_TTL = 3600  # 1 hour


def _processed_init_key(key: str) -> bytes:
    """Generate Redis key for processed init segment cache."""
    key_hash = hashlib.md5(key.encode()).hexdigest()
    return PROCESSED_INIT_CACHE_PREFIX + key_hash.encode()


async def get_cached_processed_init(key: str) -> Optional[bytes]:
    """Get cached processed init segment data. Returns None if Redis unavailable."""
    r = await get_redis_binary()
    if r is None:
        return None

    redis_key = _processed_init_key(key)
    data = await r.get(redis_key)
    if data:
        logger.debug(f"[Redis] Processed init cache hit: {key[:60]}...")
    return data


async def set_cached_processed_init(key: str, data: bytes, ttl: int = DEFAULT_PROCESSED_INIT_TTL):
    """Cache processed init segment data. No-op if Redis unavailable."""
    r = await get_redis_binary()
    if r is None:
        return

    redis_key = _processed_init_key(key)
    await r.set(redis_key, data, ex=ttl)
    logger.debug(f"[Redis] Processed init cache set ({ttl}s TTL, {len(data)} bytes): {key[:60]}...")


# =============================================================================
# In-flight Request Tracking
# =============================================================================
# Prevents duplicate upstream requests across all workers

INFLIGHT_PREFIX = "mfp:inflight:"
DEFAULT_INFLIGHT_TTL = 60  # seconds


def _inflight_key(key: str) -> str:
    """Generate Redis key for in-flight tracking."""
    key_hash = hashlib.md5(key.encode()).hexdigest()
    return f"{INFLIGHT_PREFIX}{key_hash}"


async def mark_inflight(key: str, ttl: int = DEFAULT_INFLIGHT_TTL) -> bool:
    """
    Mark a request as in-flight (being processed by some worker).

    If Redis is not available, always returns True (this worker is "first").

    Args:
        key: The request identifier
        ttl: Auto-expiry time in seconds

    Returns:
        True if this call marked it (first worker), False if already in-flight
    """
    r = await get_redis()
    if r is None:
        return True  # No Redis - always proceed

    inflight_key = _inflight_key(key)
    result = await r.set(inflight_key, "1", nx=True, ex=ttl)
    if result:
        logger.debug(f"[Redis] Marked in-flight: {key[:60]}...")
    return bool(result)


async def is_inflight(key: str) -> bool:
    """Check if a request is currently in-flight. Returns False if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return False

    inflight_key = _inflight_key(key)
    return await r.exists(inflight_key) > 0


async def clear_inflight(key: str):
    """Clear in-flight marker (call when request completes). No-op if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return

    inflight_key = _inflight_key(key)
    await r.delete(inflight_key)
    logger.debug(f"[Redis] Cleared in-flight: {key[:60]}...")


async def wait_for_completion(key: str, timeout: float = 30.0, poll_interval: float = 0.1) -> bool:
    """
    Wait for an in-flight request to complete.

    If Redis is not available, returns True immediately.

    Args:
        key: The request identifier
        timeout: Maximum time to wait
        poll_interval: Time between checks

    Returns:
        True if completed (inflight marker gone), False if timeout
    """
    r = await get_redis()
    if r is None:
        return True  # No Redis - don't wait

    deadline = time.time() + timeout
    while time.time() < deadline:
        if not await is_inflight(key):
            return True
        await asyncio.sleep(poll_interval)
    return False


# =============================================================================
# Cooldown/Throttle Tracking
# =============================================================================
# Prevents rapid repeated operations (e.g., background refresh throttling)

COOLDOWN_PREFIX = "mfp:cooldown:"


def _cooldown_key(key: str) -> str:
    """Generate Redis key for cooldown tracking."""
    key_hash = hashlib.md5(key.encode()).hexdigest()
    return f"{COOLDOWN_PREFIX}{key_hash}"


async def check_and_set_cooldown(key: str, cooldown_seconds: int) -> bool:
    """
    Check if cooldown has elapsed and set new cooldown if so.

    If Redis is not available, always returns True (no rate limiting).

    Args:
        key: The cooldown identifier
        cooldown_seconds: Duration of the cooldown period

    Returns:
        True if cooldown elapsed (and new cooldown set), False if still in cooldown
    """
    r = await get_redis()
    if r is None:
        return True  # No Redis - no rate limiting

    cooldown_key = _cooldown_key(key)
    # SET NX EX: only succeeds if key doesn't exist
    result = await r.set(cooldown_key, "1", nx=True, ex=cooldown_seconds)
    if result:
        logger.debug(f"[Redis] Cooldown set ({cooldown_seconds}s): {key[:60]}...")
        return True
    return False


async def is_in_cooldown(key: str) -> bool:
    """Check if currently in cooldown period. Returns False if Redis unavailable."""
    r = await get_redis()
    if r is None:
        return False

    cooldown_key = _cooldown_key(key)
    return await r.exists(cooldown_key) > 0


# =============================================================================
# HLS Transcode Session (Cross-Worker)
# =============================================================================
# Per-segment HLS transcode caching.
# Each segment is independently transcoded and cached. Segment output metadata
# (video/audio DTS, sequence number) is stored so consecutive segments can
# maintain timeline continuity without a persistent pipeline.

HLS_SEG_PREFIX = b"mfp:hls_seg:"
HLS_INIT_PREFIX = b"mfp:hls_init:"
HLS_SEG_META_PREFIX = "mfp:hls_smeta:"

HLS_SEG_TTL = 60  # 60 s -- short-lived; only for immediate retry/re-request
HLS_INIT_TTL = 3600  # 1 hour -- stable for the viewing session
HLS_SEG_META_TTL = 3600  # 1 hour -- needed for next-segment continuity


def _hls_seg_key(cache_key: str, seg_index: int) -> bytes:
    return HLS_SEG_PREFIX + f"{cache_key}:{seg_index}".encode()


def _hls_init_key(cache_key: str) -> bytes:
    return HLS_INIT_PREFIX + cache_key.encode()


def _hls_seg_meta_key(cache_key: str, seg_index: int) -> str:
    return f"{HLS_SEG_META_PREFIX}{cache_key}:{seg_index}"


async def hls_get_segment(cache_key: str, seg_index: int) -> Optional[bytes]:
    """Get a cached HLS segment from Redis. Returns None if unavailable."""
    r = await get_redis_binary()
    if r is None:
        return None
    try:
        return await r.get(_hls_seg_key(cache_key, seg_index))
    except Exception:
        return None


async def hls_set_segment(cache_key: str, seg_index: int, data: bytes) -> None:
    """Store an HLS segment in Redis with short TTL. No-op if Redis unavailable."""
    r = await get_redis_binary()
    if r is None:
        return
    try:
        await r.set(_hls_seg_key(cache_key, seg_index), data, ex=HLS_SEG_TTL)
    except Exception:
        logger.debug("[Redis] Failed to cache HLS segment %d", seg_index)


async def hls_get_init(cache_key: str) -> Optional[bytes]:
    """Get the cached HLS init segment from Redis."""
    r = await get_redis_binary()
    if r is None:
        return None
    try:
        return await r.get(_hls_init_key(cache_key))
    except Exception:
        return None


async def hls_set_init(cache_key: str, data: bytes) -> None:
    """Store the HLS init segment in Redis."""
    r = await get_redis_binary()
    if r is None:
        return
    try:
        await r.set(_hls_init_key(cache_key), data, ex=HLS_INIT_TTL)
    except Exception:
        logger.debug("[Redis] Failed to cache HLS init segment")


async def hls_get_segment_meta(cache_key: str, seg_index: int) -> Optional[dict]:
    """
    Get per-segment output metadata from Redis.

    Returns a dict with keys like ``video_dts_ms``, ``audio_dts_ms``,
    ``sequence_number``, or None if unavailable.
    """
    r = await get_redis()
    if r is None:
        return None
    try:
        raw = await r.get(_hls_seg_meta_key(cache_key, seg_index))
        if raw:
            return json.loads(raw)
    except Exception:
        pass
    return None


async def hls_set_segment_meta(cache_key: str, seg_index: int, meta: dict) -> None:
    """
    Store per-segment output metadata in Redis.

    ``meta`` should contain keys like ``video_dts_ms``, ``audio_dts_ms``,
    ``sequence_number`` so the next segment can continue the timeline.
    """
    r = await get_redis()
    if r is None:
        return
    try:
        await r.set(
            _hls_seg_meta_key(cache_key, seg_index),
            json.dumps(meta),
            ex=HLS_SEG_META_TTL,
        )
    except Exception:
        logger.debug("[Redis] Failed to set HLS segment meta %d", seg_index)