funflix-api 0.1.1__py3-none-any.whl

funflix_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

funflix_api/app.py

@@ -0,0 +1,87 @@
+"""FastAPI 应用装配。"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from funflix.base.config import get_settings
+from funflix.base.db import dispose_engine, get_engine
+from sqlalchemy import text
+from starlette.middleware.sessions import SessionMiddleware
+
+from funflix_api.v1 import api_router
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    settings = get_settings()
+    logging.basicConfig(
+        level=settings.log_level.upper(),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    # 启动即探一次库，让配置错误在启动时暴露，而不是等第一个请求打进来才 500
+    async with get_engine().connect() as conn:
+        await conn.execute(text("SELECT 1"))
+    logger.info("funflix 启动完成，数据库=%s", settings.database_url.split("://", 1)[0])
+
+    task: asyncio.Task[None] | None = None
+    stop: asyncio.Event | None = None
+    if settings.worker_enabled:
+        from funflix.worker import spawn
+
+        task, stop = spawn(settings)
+        logger.info("进程内后台 worker 已启动")
+    else:
+        logger.info("进程内后台 worker 未启用（FUNFLIX_WORKER_ENABLED=true 开启）")
+
+    try:
+        yield
+    finally:
+        if task is not None and stop is not None:
+            stop.set()
+            # 给它一轮的时间收尾。超时就取消 —— 卡住的多半是某次外部调用，
+            # 等下去没有意义，任务本身有租约兜底，重启后会被重新领取。
+            try:
+                await asyncio.wait_for(task, timeout=10)
+            except (TimeoutError, asyncio.CancelledError):
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+        await dispose_engine()
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    app = FastAPI(
+        title=settings.app_name,
+        version="0.1.0",
+        description="影视资源分享文本的结构化采集、解析与网盘链接校验",
+        lifespan=lifespan,
+        debug=settings.debug,
+    )
+    app.add_middleware(
+        SessionMiddleware,
+        secret_key=settings.session_secret,
+        max_age=settings.session_max_age,
+        same_site="lax",
+        https_only=settings.session_cookie_secure,
+    )
+    app.include_router(api_router, prefix=settings.api_prefix)
+
+    @app.get("/healthz", tags=["ops"])
+    async def healthz() -> dict[str, str]:
+        async with get_engine().connect() as conn:
+            await conn.execute(text("SELECT 1"))
+        return {"status": "ok"}
+
+    return app
+
+
+app = create_app()

funflix_api/cli.py

@@ -0,0 +1,279 @@
+"""funflix-api 命令行入口：API 服务的生命周期管理。
+
+领域逻辑（采集/解析/校验/worker/数据库迁移）由 `funflix` 提供，用 `funflix`
+自己的 CLI 管理；这里只管 HTTP 服务进程本身的 run/start/stop/restart/status。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Annotated, Any, NoReturn
+
+import typer
+from funflix.base.config import get_settings
+
+from funflix_api import __version__
+
+app = typer.Typer(help="funflix-api 服务生命周期", no_args_is_help=True)
+
+#: 命令行 / 配置文件都没给端口时的兜底默认值。
+DEFAULT_SERVER_HOST = "127.0.0.1"
+DEFAULT_SERVER_PORT = 18810
+#: `stop`/`restart` 等多久优雅退出才放弃。
+SERVER_STOP_TIMEOUT_SECONDS = 10
+
+
+def _fail(message: str) -> NoReturn:
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    raise typer.Exit(1)
+
+
+def _ok(message: str) -> None:
+    typer.secho(message, fg=typer.colors.GREEN)
+
+
+def _warn(message: str) -> None:
+    typer.secho(message, fg=typer.colors.YELLOW)
+
+
+def _default_server_config_path() -> Path:
+    """XDG 约定的默认配置文件路径：
+    `${XDG_CONFIG_HOME:-~/.config}/farfarfun/funflix-api/config.toml`。
+
+    生产环境直接把配置文件放在这个路径下即可，`funflix-api start` 不用
+    带任何参数；`--config` 仍然可以显式覆盖，开发时常用来指向仓库内的文件。
+    """
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(xdg_config_home) / "farfarfun" / "funflix-api" / "config.toml"
+
+
+def _server_state_dir() -> Path:
+    """PID/日志统一放在配置目录下，跟 `--config` 默认路径同一棵树管理，
+    不依赖仓库或当前工作目录。"""
+    return _default_server_config_path().parent
+
+
+def _server_pid_file() -> Path:
+    return _server_state_dir() / "server.pid"
+
+
+def _server_log_file() -> Path:
+    return _server_state_dir() / "server.log"
+
+
+def _load_server_config(config: Path | None) -> dict[str, Any]:
+    """按扩展名解析 `--config` 指向的文件：`.toml` / `.json` / `.env`。
+
+    未显式传 `--config` 时落到 XDG 默认路径；那个路径不存在就是没有配置文件、
+    直接用命令行默认值，不算错误。显式传了但文件不存在才报错。
+    """
+    path = config or _default_server_config_path()
+    if not path.exists():
+        if config is not None:
+            _fail(f"配置文件不存在：{path}")
+        return {}
+
+    suffix = path.suffix.lower()
+    if suffix == ".toml":
+        import tomllib
+
+        data: dict[str, Any] = tomllib.loads(path.read_text(encoding="utf-8"))
+    elif suffix == ".json":
+        data = json.loads(path.read_text(encoding="utf-8"))
+    elif suffix == ".env":
+        from dotenv import dotenv_values
+
+        data = dict(dotenv_values(path))
+    else:
+        _fail(f"不支持的配置文件格式：{path.suffix}（仅支持 .toml / .json / .env）")
+    return {str(key).lower(): value for key, value in data.items() if value is not None}
+
+
+def _resolve_server_host_port(
+    host: str | None, port: int | None, config: Path | None
+) -> tuple[str, int]:
+    file_config = _load_server_config(config)
+    resolved_host = host or str(file_config.get("host") or DEFAULT_SERVER_HOST)
+    resolved_port = (
+        port if port is not None else int(file_config.get("port") or DEFAULT_SERVER_PORT)
+    )
+    return resolved_host, resolved_port
+
+
+def _read_server_pid() -> int | None:
+    pid_file = _server_pid_file()
+    if not pid_file.exists():
+        return None
+    try:
+        pid = int(pid_file.read_text().strip())
+    except ValueError:
+        return None
+    return pid if pid > 1 else None
+
+
+def _pid_is_live(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True
+
+
+def _resolve_cli_executable() -> str:
+    """后台启动时重新拉起自己：优先用 PATH 上装好的 `funflix-api`，找不到就退回
+    当前进程的入口脚本——两者对应同一个已安装的包。"""
+    return shutil.which("funflix-api") or sys.argv[0]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version_callback, is_eager=True, help="打印版本号后退出"
+        ),
+    ] = False,
+) -> None:
+    """funflix-api：funflix 的 HTTP API 服务进程。"""
+
+
+@app.command("run")
+def server_run(
+    host: Annotated[str | None, typer.Option(help="监听地址，覆盖配置文件")] = None,
+    port: Annotated[int | None, typer.Option(help="监听端口，覆盖配置文件")] = None,
+    config: Annotated[
+        Path | None,
+        typer.Option("--config", help="配置文件路径（.toml/.json/.env），缺省用 XDG 默认路径"),
+    ] = None,
+    reload: Annotated[
+        bool, typer.Option(help="代码变更自动重载（开发用，不代表托管生命周期）")
+    ] = False,
+) -> None:
+    """前台启动 API 服务，Ctrl-C 停止。
+
+    调试、临时跑一下用这个；要后台常驻用 `funflix-api start`——它内部
+    就是拉一个子进程跑这条命令，只是重定向了输出、写了 PID 文件。
+    """
+    import uvicorn
+
+    resolved_host, resolved_port = _resolve_server_host_port(host, port, config)
+    uvicorn.run(
+        "funflix_api.app:app",
+        host=resolved_host,
+        port=resolved_port,
+        reload=reload,
+        log_level=get_settings().log_level.lower(),
+    )
+
+
+@app.command("start")
+def server_start(
+    host: Annotated[str | None, typer.Option(help="监听地址，覆盖配置文件")] = None,
+    port: Annotated[int | None, typer.Option(help="监听端口，覆盖配置文件")] = None,
+    config: Annotated[
+        Path | None,
+        typer.Option("--config", help="配置文件路径（.toml/.json/.env），缺省用 XDG 默认路径"),
+    ] = None,
+) -> None:
+    """后台启动 API 服务。
+
+    拉一个子进程跑 `run`，PID 写到配置目录下的 `server.pid`，输出
+    重定向到同目录的 `server.log`。停止/重启见 `stop` / `restart`。
+    """
+    existing = _read_server_pid()
+    if existing is not None and _pid_is_live(existing):
+        _fail(f"funflix-api 已在运行（pid {existing}）")
+
+    pid_file = _server_pid_file()
+    log_file = _server_log_file()
+    pid_file.parent.mkdir(parents=True, exist_ok=True)
+
+    command = [_resolve_cli_executable(), "run"]
+    if host is not None:
+        command += ["--host", host]
+    if port is not None:
+        command += ["--port", str(port)]
+    if config is not None:
+        command += ["--config", str(config)]
+
+    with log_file.open("ab") as log:
+        process = subprocess.Popen(
+            command,
+            stdin=subprocess.DEVNULL,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+    pid_file.write_text(f"{process.pid}\n")
+
+    time.sleep(1)
+    if process.poll() is not None:
+        pid_file.unlink(missing_ok=True)
+        _fail(f"funflix-api 启动失败，看日志：{log_file}")
+
+    _, resolved_port = _resolve_server_host_port(host, port, config)
+    _ok(f"funflix-api 已启动（pid {process.pid}，端口 {resolved_port}，日志 {log_file}）")
+
+
+@app.command("stop")
+def server_stop() -> None:
+    """停止后台运行的 API 服务（发 SIGTERM，等它优雅退出）。"""
+    pid_file = _server_pid_file()
+    pid = _read_server_pid()
+    if pid is None:
+        pid_file.unlink(missing_ok=True)
+        _warn("funflix-api 未在运行")
+        return
+    if not _pid_is_live(pid):
+        pid_file.unlink(missing_ok=True)
+        _warn("PID 文件已失效，已清理")
+        return
+
+    os.kill(pid, signal.SIGTERM)
+    deadline = time.monotonic() + SERVER_STOP_TIMEOUT_SECONDS
+    while _pid_is_live(pid):
+        if time.monotonic() >= deadline:
+            _fail(f"funflix-api 在 {SERVER_STOP_TIMEOUT_SECONDS}s 内未退出（pid {pid}）")
+        time.sleep(0.2)
+
+    pid_file.unlink(missing_ok=True)
+    _ok("funflix-api 已停止")
+
+
+@app.command("restart")
+def server_restart(
+    host: Annotated[str | None, typer.Option(help="监听地址，覆盖配置文件")] = None,
+    port: Annotated[int | None, typer.Option(help="监听端口，覆盖配置文件")] = None,
+    config: Annotated[
+        Path | None,
+        typer.Option("--config", help="配置文件路径（.toml/.json/.env），缺省用 XDG 默认路径"),
+    ] = None,
+) -> None:
+    """重启：先 `stop`（没在跑也不报错），再 `start`。"""
+    server_stop()
+    server_start(host=host, port=port, config=config)
+
+
+@app.command("status")
+def server_status() -> None:
+    """查看后台服务是否在跑，以及安装的版本号。"""
+    pid = _read_server_pid()
+    if pid is not None and _pid_is_live(pid):
+        _ok(f"运行中（pid {pid}，版本 {__version__}）")
+    elif _server_pid_file().exists():
+        _warn(f"PID 文件失效（{_server_pid_file()}）")
+    else:
+        typer.secho(f"已停止（版本 {__version__}）", fg=typer.colors.BRIGHT_BLACK)

funflix_api/deps.py

@@ -0,0 +1,69 @@
+"""FastAPI 依赖。"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+from fastapi import Depends, HTTPException, Query, Request, status
+from funflix.base.config import Settings, get_settings
+from funflix.base.db import get_session
+from funflix.models import User
+from funflix.schemas.common import MAX_PAGE_NUMBER, MAX_PAGE_SIZE
+from sqlalchemy.ext.asyncio import AsyncSession
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+SettingsDep = Annotated[Settings, Depends(get_settings)]
+
+
+@dataclass(slots=True)
+class PageParams:
+    """翻页入参。
+
+    四个列表接口曾各写一遍 page/size 的声明与 `(page - 1) * size`，
+    上限已经先漂了一次（两处 100、两处 200）。收敛到这里，
+    翻页语义只有一个定义点。
+    """
+
+    page: int
+    size: int
+
+    @property
+    def offset(self) -> int:
+        return (self.page - 1) * self.size
+
+
+def page_params(
+    page: Annotated[int, Query(ge=1, le=MAX_PAGE_NUMBER, description="页码，从 1 开始")] = 1,
+    size: Annotated[int, Query(ge=1, le=MAX_PAGE_SIZE, description="每页条数")] = 20,
+) -> PageParams:
+    return PageParams(page=page, size=size)
+
+
+PageDep = Annotated[PageParams, Depends(page_params)]
+
+
+async def get_or_404(session: AsyncSession, model: type[Any], pk: Any, detail: str) -> Any:
+    """按主键取，取不到就 404。"""
+    row = await session.get(model, pk)
+    if row is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=detail)
+    return row
+
+
+async def get_current_user(request: Request, session: SessionDep) -> User:
+    """「运维」区接口的鉴权：要求已登录会话。"""
+    user_id = request.session.get("user_id")
+    if not user_id:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="请先登录")
+    user = await session.get(User, uuid.UUID(user_id))
+    if user is None or not user.is_active:
+        request.session.clear()
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED, detail="登录已失效，请重新登录"
+        )
+    return user
+
+
+CurrentUserDep = Annotated[User, Depends(get_current_user)]

funflix_api/v1/__init__.py

@@ -0,0 +1,15 @@
+"""v1 路由聚合。"""
+
+from fastapi import APIRouter
+
+from funflix_api.v1 import auth, media, raw, resources, sources, stats
+
+api_router = APIRouter()
+api_router.include_router(auth.router)
+api_router.include_router(sources.router)
+api_router.include_router(raw.router)
+api_router.include_router(media.router)
+api_router.include_router(resources.router)
+api_router.include_router(stats.router)
+
+__all__ = ["api_router"]

funflix_api/v1/auth.py

@@ -0,0 +1,88 @@
+"""登录 / 登出 / 当前用户 / 注册。
+
+「运维」区其余路由都靠 `CurrentUserDep`（见 `api/deps.py`）挡在会话之后，
+这个模块只负责建立/销毁那个会话。
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, HTTPException, Request, status
+from funflix.models import User
+from funflix.security import hash_password, verify_password
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+
+from funflix_api.deps import SessionDep, SettingsDep
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+class LoginPayload(BaseModel):
+    username: str
+    password: str
+
+
+class RegisterPayload(BaseModel):
+    username: str = Field(min_length=1, max_length=64)
+    password: str = Field(min_length=6, max_length=128)
+
+
+class UserOut(BaseModel):
+    id: uuid.UUID
+    username: str
+
+    model_config = {"from_attributes": True}
+
+
+class AuthConfigOut(BaseModel):
+    registration_enabled: bool
+
+
+@router.get("/config", response_model=AuthConfigOut)
+async def get_auth_config(settings: SettingsDep) -> AuthConfigOut:
+    return AuthConfigOut(registration_enabled=settings.registration_enabled)
+
+
+@router.post("/login", response_model=UserOut)
+async def login(payload: LoginPayload, request: Request, session: SessionDep) -> UserOut:
+    user = await session.scalar(select(User).where(User.username == payload.username))
+    if (
+        user is None
+        or not user.is_active
+        or not verify_password(payload.password, user.password_hash)
+    ):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="用户名或密码错误")
+    request.session["user_id"] = str(user.id)
+    return UserOut.model_validate(user)
+
+
+@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+async def logout(request: Request) -> None:
+    request.session.clear()
+
+
+@router.get("/me", response_model=UserOut | None)
+async def me(request: Request, session: SessionDep) -> UserOut | None:
+    user_id = request.session.get("user_id")
+    if not user_id:
+        return None
+    user = await session.get(User, uuid.UUID(user_id))
+    if user is None or not user.is_active:
+        request.session.clear()
+        return None
+    return UserOut.model_validate(user)
+
+
+@router.post("/register", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+async def register(payload: RegisterPayload, settings: SettingsDep, session: SessionDep) -> UserOut:
+    if not settings.registration_enabled:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="注册入口未开放")
+    existing = await session.scalar(select(User).where(User.username == payload.username))
+    if existing is not None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="用户名已被占用")
+    user = User(username=payload.username, password_hash=hash_password(payload.password))
+    session.add(user)
+    await session.commit()
+    return UserOut.model_validate(user)

funflix_api/v1/media.py

@@ -0,0 +1,103 @@
+"""作品查询接口（DESIGN §7.2）。
+
+列表走 `services.search` 的后端抽象：PG 上是 pg_trgm 模糊匹配，
+其余方言回落 LIKE，调用方无感知。
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, HTTPException, Query, status
+from funflix.base.enums import CheckStatus, MediaType, Provider
+from funflix.models import Media, Resource, media_resource
+from funflix.models.media import UNKNOWN_YEAR
+from funflix.schemas.common import Page
+from funflix.schemas.media import MediaDetail, MediaSummary
+from funflix.services.search import SearchQuery, count_media, search_media
+from sqlalchemy import case, select
+from sqlalchemy.orm import selectinload
+from sqlalchemy.orm.attributes import set_committed_value
+
+from funflix_api.deps import PageDep, SessionDep
+
+#: 详情页最多返回多少条资源。`resource_count` 仍是真实总数。
+MAX_DETAIL_RESOURCES = 200
+
+router = APIRouter(prefix="/media", tags=["media"])
+
+
+@router.get("", response_model=Page[MediaSummary])
+async def list_media(
+    session: SessionDep,
+    paging: PageDep,
+    keyword: str = Query(
+        default="", max_length=128, description="剧名关键词，留空则按入库时间倒序"
+    ),
+    media_type: MediaType | None = None,
+    year: int | None = Query(
+        default=None,
+        ge=UNKNOWN_YEAR,
+        le=2100,
+        description=f"年份；传 {UNKNOWN_YEAR} 查年份未知的作品（出参里这些作品的 year 是 null）",
+    ),
+    valid_only: bool = Query(default=False, description="只要至少有一条校验通过资源的作品"),
+    provider: Annotated[
+        Provider | None, Query(description="只要至少有一条该网盘资源的作品")
+    ] = None,
+) -> Page[MediaSummary]:
+    """搜索 / 浏览作品。"""
+    query = SearchQuery(
+        keyword=keyword.strip(),
+        media_type=media_type,
+        year=year,
+        valid_only=valid_only,
+        provider=provider,
+        limit=paging.size,
+        offset=paging.offset,
+    )
+    total = await count_media(session, query)
+    rows = await search_media(session, query)
+    return Page[MediaSummary](
+        items=[MediaSummary.model_validate(r) for r in rows],
+        total=total,
+        page=paging.page,
+        size=paging.size,
+    )
+
+
+@router.get("/{media_id}", response_model=MediaDetail)
+async def get_media(media_id: uuid.UUID, session: SessionDep) -> MediaDetail:
+    """作品详情，含网盘资源与标签。
+
+    关联对象一律预加载 —— 异步会话下懒加载会在序列化时抛 MissingGreenlet，
+    而不是悄悄多发几条查询。
+
+    资源最多返回 `MAX_DETAIL_RESOURCES` 条，且可用的排在前面。热门剧集会被
+    很多频道反复分享，`media_resource` 只增不删，全量返回能到几 MB ——
+    而使用者要的只是「一条能用的链接」。总数看 `resource_count`。
+    """
+    media = await session.scalar(
+        select(Media).where(Media.id == media_id).options(selectinload(Media.tags))
+    )
+    if media is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="作品不存在")
+
+    rows = list(
+        await session.scalars(
+            select(Resource)
+            .join(media_resource, media_resource.c.resource_id == Resource.id)
+            .where(media_resource.c.media_id == media_id)
+            # 可用的排前面，其余按入库倒序
+            .order_by(
+                case((Resource.check_status == CheckStatus.VALID, 0), else_=1),
+                Resource.id.desc(),
+            )
+            .limit(MAX_DETAIL_RESOURCES)
+        )
+    )
+    # 用 set_committed_value 而不是直接赋值：直接给关系属性赋值会被 ORM 当成
+    # 「这就是全部关联」，flush 时把没列进来的关联行删掉 —— 截断展示会变成截断数据。
+    set_committed_value(media, "resources", rows)
+    return MediaDetail.model_validate(media)