"""Shared cache key helpers for embedding inputs.

Multimodal (CN-CLIP) raw keys include ``model_name`` so switching ViT-L / ViT-H does not reuse stale vectors.

- 图片：``embed:{model_name}:txt:norm{0|1}:<url_or_digest>``
- 多模态文本（与 /embed/image 同空间）：``embed:{model_name}:img:norm{0|1}:<text_or_digest>``

TEI/BGE 文本（title_embedding 等）：``embed:norm{0|1}:<text_or_digest>``

超长 URL/文本（按 Unicode 码点计数，超过 ``CACHE_KEY_RAW_BODY_MAX_CHARS``）时，尾部负载改为
``h:sha256:<64 hex>``，避免 Redis key 过长。

`RedisEmbeddingCache` adds the configured key prefix and optional namespace on top.
"""

from __future__ import annotations

import hashlib

# Max length (Unicode codepoints) of the raw URL/text segment before switching to SHA256 digest form.
CACHE_KEY_RAW_BODY_MAX_CHARS = 256


def _stable_body_for_cache_key(body: str, *, max_chars: int | None = None) -> str:
    """
    Return ``body`` unchanged when ``len(body) <= max_chars``; otherwise a fixed-length digest key.

    Hash is SHA-256 over UTF-8 bytes of ``body``; prefix ``h:sha256:`` avoids collision with literals.
    """
    if max_chars is None:
        max_chars = CACHE_KEY_RAW_BODY_MAX_CHARS
    if len(body) <= max_chars:
        return body
    digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
    return f"h:sha256:{digest}"


def build_text_cache_key(text: str, *, normalize: bool) -> str:
    normalized_text = str(text or "").strip()
    payload = _stable_body_for_cache_key(normalized_text)
    return f"embed:norm{1 if normalize else 0}:{payload}"


def build_image_cache_key(url: str, *, normalize: bool, model_name: str) -> str:
    """CN-CLIP 图片向量缓存逻辑键（业务约定段名为 txt）。"""
    normalized_url = str(url or "").strip()
    payload = _stable_body_for_cache_key(normalized_url)
    m = str(model_name or "").strip() or "unknown"
    return f"embed:{m}:txt:norm{1 if normalize else 0}:{payload}"


def build_clip_text_cache_key(text: str, *, normalize: bool, model_name: str) -> str:
    """CN-CLIP 文本塔缓存逻辑键（与图同空间；业务约定段名为 img）。"""
    normalized_text = str(text or "").strip()
    payload = _stable_body_for_cache_key(normalized_text)
    m = str(model_name or "").strip() or "unknown"
    return f"embed:{m}:img:norm{1 if normalize else 0}:{payload}"