nonebot-plugin-parsehub 0.1.0__py3-none-any.whl

nonebot_plugin_parsehub/mediacache.py

@@ -0,0 +1,418 @@
+# Copyright 2026 ByteColtX
+# SPDX-License-Identifier: MIT
+
+"""按作品缓存下载好的媒体。
+
+同一个作品（不管用户发的是短链还是完整链）第二次出现时，直接从本地把卡片和媒体
+发出去，**不解析、不下载、不画卡**。缓存按作品 key 存，跨会话共享——A 群发过的
+视频，B 群再发也是直接发本地那份。
+
+目录结构（``root`` 就是中转服务的根目录，所以协议端能直接来拉）::
+
+    <root>/media/<slug>/card.jpg      信息卡片（有就发）
+    <root>/media/<slug>/caption.txt   没出卡时发的文字
+    <root>/media/<slug>/files/<...>   下载好的媒体文件
+
+只保留 ``ttl_seconds`` 内用过的条目（命中会刷新时间，所以常看的一直在），总量
+超过 ``max_bytes`` 时按最久没用过的先删。模块不依赖 nonebot，方便单独测试。
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import time
+from collections.abc import Iterable
+from pathlib import Path
+
+logger = logging.getLogger("nonebot_plugin_parsehub.mediacache")
+
+# 缓存目录名（放在中转根目录下，协议端要能拉到）。
+CACHE_DIR_NAME = "media"
+
+# 卡片图与文字的文件名。
+CARD_NAME = "card.jpg"
+CAPTION_NAME = "caption.txt"
+
+# 记下这个条目对应哪些作品 key（命中时要把它们一起记进去重，否则同一个作品
+# 换个写法再发会被当成新作品）。
+KEYS_NAME = "keys.txt"
+
+# 条目里媒体的时长（秒），供时长上限在命中缓存时判断，省得为已知的长视频再解析。
+SECONDS_NAME = "seconds.txt"
+
+# 媒体文件放在条目目录的这个子目录里，避免和卡片图混在一起。
+FILES_DIR_NAME = "files"
+
+# 目录名的非法字符（作品 key 里会有 ``:`` 和 ``/``）。
+_UNSAFE = re.compile(r"[^0-9A-Za-z._-]")
+
+
+def slugify(key: str) -> str:
+    """把作品 key 变成安全的目录名。
+
+    Args:
+        key: :func:`nonebot_plugin_parsehub.core.content_key` 生成的 key。
+
+    Returns:
+        只含字母数字和 ``._-`` 的目录名。
+    """
+    return _UNSAFE.sub("_", key)[:120] or "unknown"
+
+
+class MediaCache:
+    """作品级的媒体缓存。
+
+    Attributes:
+        root: 缓存根目录（``<中转根目录>/media``）。
+        ttl_seconds: 条目多久没用就删（秒），小于等于 0 表示不缓存。
+        max_bytes: 总容量上限（字节），小于等于 0 表示不限。
+    """
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        ttl_seconds: int,
+        max_bytes: int,
+    ) -> None:
+        """记住配置，不碰磁盘。
+
+        Args:
+            root: 缓存根目录。
+            ttl_seconds: 条目过期时间（秒）。
+            max_bytes: 总容量上限（字节）。
+        """
+        self.root = root
+        self.ttl_seconds = ttl_seconds
+        self.max_bytes = max_bytes
+
+    @property
+    def enabled(self) -> bool:
+        """有没有开启缓存。
+
+        Returns:
+            开启为 ``True``。
+        """
+        return self.ttl_seconds > 0
+
+    def entry_dir(self, key: str) -> Path:
+        """某个作品对应的目录。
+
+        Args:
+            key: 作品 key。
+
+        Returns:
+            条目目录路径（可能不存在）。
+        """
+        return self.root / slugify(key)
+
+    def get(self, key: str) -> Path | None:
+        """取缓存条目，命中就刷新它的时间戳。
+
+        Args:
+            key: 作品 key。
+
+        Returns:
+            条目目录；没缓存或已过期时为 ``None``。
+        """
+        if not self.enabled:
+            return None
+        path = self.entry_dir(key)
+        if not (path / FILES_DIR_NAME).is_dir():
+            return None
+        try:
+            if time.time() - path.stat().st_mtime > self.ttl_seconds:
+                return None
+            os.utime(path, None)  # 命中即续命，常看的一直留着
+        except OSError:
+            return None
+        if not self.media_files(path):
+            return None
+        return path
+
+    @staticmethod
+    def media_files(entry: Path) -> list[Path]:
+        """列出条目里的媒体文件（按文件名排序）。
+
+        Args:
+            entry: 条目目录。
+
+        Returns:
+            媒体文件列表，不含卡片图和文字。
+        """
+        files_dir = entry / FILES_DIR_NAME
+        if not files_dir.is_dir():
+            return []
+        return sorted(
+            (item for item in files_dir.iterdir() if item.is_file()),
+            key=lambda item: item.name,
+        )
+
+    @staticmethod
+    def card_path(entry: Path) -> Path | None:
+        """条目里的卡片图。
+
+        Args:
+            entry: 条目目录。
+
+        Returns:
+            卡片图路径；没有时为 ``None``。
+        """
+        card = entry / CARD_NAME
+        return card if card.is_file() else None
+
+    @staticmethod
+    def entry_keys(entry: Path) -> list[str]:
+        """条目对应的所有作品 key。
+
+        Args:
+            entry: 条目目录。
+
+        Returns:
+            作品 key 列表；没记录过时为空列表。
+        """
+        keys = entry / KEYS_NAME
+        if not keys.is_file():
+            return []
+        try:
+            return [
+                line.strip()
+                for line in keys.read_text("utf-8").splitlines()
+                if line.strip()
+            ]
+        except OSError:
+            return []
+
+    @staticmethod
+    def entry_seconds(entry: Path) -> int:
+        """条目里媒体的时长（秒）。
+
+        Args:
+            entry: 条目目录。
+
+        Returns:
+            时长（秒）；没记录过或读不出来时返回 0（调用方按「不超限」处理）。
+        """
+        stored = entry / SECONDS_NAME
+        if not stored.is_file():
+            return 0
+        try:
+            return max(0, int(stored.read_text("utf-8").strip() or 0))
+        except (OSError, ValueError):
+            return 0
+
+    @staticmethod
+    def remember_key(entry: Path, key: str) -> None:
+        """把 key 补记到条目里（老条目没有 keys.txt，命中时顺手补上）。
+
+        Args:
+            entry: 条目目录。
+            key: 作品 key。
+        """
+        keys = MediaCache.entry_keys(entry)
+        if key in keys:
+            return
+        keys.append(key)
+        try:
+            (entry / KEYS_NAME).write_text("\n".join(keys), "utf-8")
+        except OSError as exc:
+            logger.warning(f"[parsehub] 缓存 key 补记失败: {exc}")
+
+    @staticmethod
+    def caption_path(entry: Path) -> Path | None:
+        """条目里的文字。
+
+        Args:
+            entry: 条目目录。
+
+        Returns:
+            文字文件路径；没有时为 ``None``。
+        """
+        caption = entry / CAPTION_NAME
+        return caption if caption.is_file() else None
+
+    def store(
+        self,
+        keys: Iterable[str],
+        files: list[Path],
+        *,
+        card: Path | None = None,
+        caption: str = "",
+        seconds: int = 0,
+    ) -> Path | None:
+        """把一个作品存进缓存（多个 key 指向同一份文件）。
+
+        Args:
+            keys: 作品 key，通常同时传「短链 key」和「解析后的 key」。
+            files: 已下载到本地的媒体文件。
+            card: 卡片图路径，没有就传 ``None``。
+            caption: 没出卡时发的文字。
+            seconds: 媒体的时长（秒），0 表示未知。
+
+        Returns:
+            条目目录；没开启缓存或没有媒体时为 ``None``。
+        """
+        if not self.enabled or not files:
+            return None
+        keys = [key for key in keys if key]
+        if not keys:
+            return None
+
+        # 先把文件收进第一个 key 的目录，再给别的 key 建硬链接指向同一份
+        primary = self.entry_dir(keys[0])
+        try:
+            (primary / FILES_DIR_NAME).mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            logger.warning(f"[parsehub] 缓存目录建不出来: {exc}")
+            return None
+
+        for source in files:
+            target = primary / FILES_DIR_NAME / source.name
+            if target.exists():
+                continue
+            try:
+                os.link(source, target)  # 同一个文件系统，硬链接零成本
+            except OSError:
+                try:
+                    shutil.copy2(source, target)
+                except OSError as exc:
+                    logger.warning(f"[parsehub] 缓存文件失败 {source}: {exc}")
+        if not self.media_files(primary):
+            shutil.rmtree(primary, ignore_errors=True)
+            return None
+
+        if card is not None and card.is_file():
+            try:
+                shutil.copy2(card, primary / CARD_NAME)
+            except OSError as exc:
+                logger.warning(f"[parsehub] 缓存卡片失败: {exc}")
+        if caption:
+            try:
+                (primary / CAPTION_NAME).write_text(caption, "utf-8")
+            except OSError as exc:
+                logger.warning(f"[parsehub] 缓存文字失败: {exc}")
+        if seconds > 0:
+            try:
+                (primary / SECONDS_NAME).write_text(str(int(seconds)), "utf-8")
+            except OSError as exc:
+                logger.warning(f"[parsehub] 缓存时长失败: {exc}")
+        try:
+            (primary / KEYS_NAME).write_text("\n".join(keys), "utf-8")
+        except OSError as exc:
+            logger.warning(f"[parsehub] 缓存 key 记录失败: {exc}")
+
+        os.utime(primary, None)
+        for key in keys[1:]:
+            self._alias(primary, self.entry_dir(key))
+        self.sweep()
+        return primary
+
+    def _alias(self, primary: Path, alias: Path) -> None:
+        """让另一个 key 也指向同一份缓存。
+
+        用符号链接指过去，省得再复制一遍文件；符号链接坏了就当没有这条缓存。
+
+        Args:
+            primary: 真正存文件的条目目录。
+            alias: 别名条目目录。
+        """
+        if alias == primary or alias.exists():
+            return
+        try:
+            alias.parent.mkdir(parents=True, exist_ok=True)
+            os.symlink(primary.name, alias)
+        except OSError as exc:
+            logger.warning(f"[parsehub] 缓存别名失败 {alias}: {exc}")
+
+    def total_bytes(self) -> int:
+        """缓存占用的字节数。
+
+        Returns:
+            所有条目加起来的大小。
+        """
+        total = 0
+        for entry in self._entries():
+            for item in entry.rglob("*"):
+                try:
+                    if item.is_file():
+                        total += item.stat().st_size
+                except OSError:
+                    continue
+        return total
+
+    def _entries(self) -> list[Path]:
+        """列出所有条目目录（跳过符号链接别名）。
+
+        Returns:
+            真实存放文件的条目目录列表。
+        """
+        if not self.root.is_dir():
+            return []
+        return sorted(
+            (
+                item
+                for item in self.root.iterdir()
+                if item.is_dir() and not item.is_symlink()
+            ),
+            key=lambda item: self._mtime(item),
+        )
+
+    @staticmethod
+    def _mtime(path: Path) -> float:
+        """取目录的修改时间，取不到就当 0。
+
+        Args:
+            path: 目录路径。
+
+        Returns:
+            时间戳。
+        """
+        try:
+            return path.stat().st_mtime
+        except OSError:
+            return 0.0
+
+    def _drop_broken_aliases(self) -> int:
+        """清掉指向已被删掉条目的别名符号链接。
+
+        Returns:
+            清掉的数量。
+        """
+        if not self.root.is_dir():
+            return 0
+        removed = 0
+        for item in self.root.iterdir():
+            if item.is_symlink() and not item.is_dir():
+                try:
+                    item.unlink()
+                    removed += 1
+                except OSError:
+                    continue
+        return removed
+
+    def sweep(self) -> int:
+        """删掉过期条目，再按容量上限淘汰最久没用过的。
+
+        Returns:
+            删掉的条目数量。
+        """
+        if not self.enabled:
+            return 0
+        removed = 0
+        now = time.time()
+        self._drop_broken_aliases()
+        for entry in self._entries():
+            if now - self._mtime(entry) > self.ttl_seconds:
+                shutil.rmtree(entry, ignore_errors=True)
+                removed += 1
+        if self.max_bytes > 0:
+            while True:
+                entries = self._entries()
+                if not entries or self.total_bytes() <= self.max_bytes:
+                    break
+                shutil.rmtree(entries[0], ignore_errors=True)
+                removed += 1
+        return removed

nonebot_plugin_parsehub/server.py

@@ -0,0 +1,241 @@
+# Copyright 2026 ByteColtX
+# SPDX-License-Identifier: MIT
+
+"""媒体中转服务。
+
+QQ 协议端（NapCat / Lagrange / LLOneBot）通常跑在另一台机器上，读不到本机的
+``file://`` 路径，所以把下载好的媒体用一个随机目录暴露成 http 地址发给它，让它
+自己来拉。
+
+设计约束：
+
+- 只读、只服务一个目录，不列目录；
+- 目录名带随机串，猜不到；
+- 过期文件由 :meth:`MediaRelay.cleanup` 定期清理（清扫任务在插件入口里跑）。
+
+媒体目录按 NoneBot 官方要求交给 ``nonebot-plugin-localstore`` 管理；没装时退回
+系统临时目录，保证插件仍能加载。
+
+模块级单例 ``RELAY`` 是进程内共享的中转服务。
+"""
+
+from __future__ import annotations
+
+import http.server
+import shutil
+import socket
+import tempfile
+import threading
+import time
+import uuid
+from functools import partial
+from pathlib import Path
+from typing import Any
+
+from nonebot import logger, require
+
+# 探测内网 IP 时用的哑地址，只用来让内核选出口网卡，不会真的发包。
+_PROBE_ADDRESS = ("10.255.255.255", 1)
+
+# 每次任务目录名的随机长度（十六进制字符数）。
+_TASK_DIR_RANDOM_LENGTH = 16
+
+
+def _resolve_root() -> Path:
+    """确定媒体文件的根目录。
+
+    优先使用 localstore 提供的插件缓存目录；没有安装 localstore 时退回系统临时
+    目录，并给出警告，而不是让整个插件加载失败。
+
+    Returns:
+        媒体文件根目录。
+    """
+    try:
+        require("nonebot_plugin_localstore")
+
+        import nonebot_plugin_localstore as store
+
+        return store.get_plugin_cache_dir()
+    except Exception:  # noqa: BLE001 - 缺少依赖时降级，不能让插件整体挂掉
+        logger.warning(
+            "[parsehub] 未安装 nonebot-plugin-localstore，"
+            "媒体临时文件改用系统临时目录"
+        )
+        return Path(tempfile.gettempdir()) / "nonebot-plugin-parsehub"
+
+
+def cache_root() -> Path:
+    """返回插件缓存根目录（媒体与字体都放这儿）。
+
+    Returns:
+        缓存根目录。
+    """
+    return _resolve_root()
+
+
+def data_root() -> Path:
+    """返回插件数据目录（需要长期保留的东西放这儿）。
+
+    和 :func:`cache_root` 分开：缓存目录里的任务子目录会被定期清扫，开关状态、
+    配置这类东西不能放进去。
+
+    Returns:
+        数据目录。
+    """
+    try:
+        require("nonebot_plugin_localstore")
+
+        import nonebot_plugin_localstore as store
+
+        return store.get_plugin_data_dir()
+    except Exception:  # noqa: BLE001 - 缺少依赖时降级，不能让插件整体挂掉
+        logger.warning(
+            "[parsehub] 未安装 nonebot-plugin-localstore，"
+            "插件数据改用系统临时目录（重启会丢）"
+        )
+        return Path(tempfile.gettempdir()) / "nonebot-plugin-parsehub-data"
+
+
+class _RelayHandler(http.server.SimpleHTTPRequestHandler):
+    """只读静态文件服务，关掉目录列表和访问日志。"""
+
+    def list_directory(self, path: Any) -> None:
+        """禁止列目录，直接返回 404。
+
+        Args:
+            path: 请求的目录路径，未使用。
+        """
+        self.send_error(404, "Not Found")
+        return None
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """静音访问日志，避免刷屏。
+
+        Args:
+            format: 日志格式串，未使用。
+            *args: 日志参数，未使用。
+        """
+        return
+
+    def end_headers(self) -> None:
+        """补上禁用缓存的响应头。"""
+        self.send_header("Cache-Control", "no-store")
+        super().end_headers()
+
+
+class MediaRelay:
+    """把本地媒体文件暴露成协议端可下载的 http 地址。
+
+    Attributes:
+        root: 媒体文件根目录。
+        _server: 已启动的 HTTP 服务，未启动时为 None。
+        _lock: 保护启动过程的锁。
+    """
+
+    def __init__(self, root: Path) -> None:
+        """初始化中转服务。
+
+        Args:
+            root: 媒体文件根目录。
+        """
+        self.root = root
+        self._server: http.server.ThreadingHTTPServer | None = None
+        self._lock = threading.Lock()
+
+    def start(self, host: str, port: int) -> int:
+        """启动 HTTP 服务（重复调用只启动一次）。
+
+        Args:
+            host: 绑定地址，例如 ``0.0.0.0``。
+            port: 绑定端口。
+
+        Returns:
+            实际监听的端口。
+        """
+        self.root.mkdir(parents=True, exist_ok=True)
+        with self._lock:
+            if self._server is None:
+                handler = partial(_RelayHandler, directory=str(self.root))
+                self._server = http.server.ThreadingHTTPServer(
+                    (host, port), handler
+                )
+                thread = threading.Thread(
+                    target=self._server.serve_forever,
+                    name="parsehub-files",
+                    daemon=True,
+                )
+                thread.start()
+            return int(self._server.server_address[1])
+
+    def new_task_dir(self) -> Path:
+        """为一次解析任务创建随机子目录。
+
+        Returns:
+            新建的子目录路径。
+        """
+        path = self.root / uuid.uuid4().hex[:_TASK_DIR_RANDOM_LENGTH]
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def url_for(self, path: Path, host: str, port: int) -> str:
+        """把本地文件路径转成协议端能下载的地址。
+
+        Args:
+            path: 媒体文件路径，必须位于 :attr:`root` 之下。
+            host: 协议端可访问的地址。
+            port: HTTP 服务端口。
+
+        Returns:
+            形如 ``http://host:port/<随机目录>/<文件名>`` 的地址。
+        """
+        relative = path.resolve().relative_to(self.root.resolve())
+        return f"http://{host}:{port}/{relative.as_posix()}"
+
+    def cleanup(self, keep_seconds: int, skip: set[str] | None = None) -> int:
+        """删除过期的任务目录。
+
+        Args:
+            keep_seconds: 保留时长（秒），早于该时长的目录会被删除。
+            skip: 不参与清扫的子目录名（比如媒体缓存目录）。
+
+        Returns:
+            删除的目录数量。
+        """
+        if not self.root.exists():
+            return 0
+
+        skip = skip or set()
+        now = time.time()
+        removed = 0
+        for child in self.root.iterdir():
+            if child.name in skip:
+                continue
+            try:
+                expired = (
+                    child.is_dir()
+                    and now - child.stat().st_mtime > keep_seconds
+                )
+            except OSError:
+                continue
+            if expired:
+                shutil.rmtree(child, ignore_errors=True)
+                removed += 1
+        return removed
+
+
+def guess_lan_ip() -> str:
+    """探测本机内网 IP。
+
+    Returns:
+        本机在默认出口网卡上的地址；探测失败时返回 ``127.0.0.1``。
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+        try:
+            sock.connect(_PROBE_ADDRESS)
+            return str(sock.getsockname()[0])
+        except OSError:
+            return "127.0.0.1"
+
+
+# 进程内共享的中转服务。
+RELAY = MediaRelay(_resolve_root())