UHD_Media_Tool/apps/server/src/modules/cache/index.ts

import { join } from "node:path";
import { createRoute, type RouteConfig } from "@hono/zod-openapi";
import {
  Api,
  apiResponse,
  DEFAULT_SETTINGS,
  type EndpointDef,
  type TmdbCacheItem,
  type TmdbCacheList,
} from "@umt/contracts";
import { sql } from "@umt/db";
import type { z } from "zod";
import { dataPaths } from "../../config.ts";
import { externalFetch } from "../../egress.ts";
import { requireScope } from "../../http/auth.ts";
import { errorBody } from "../../http/errors.ts";
import { CACHE_REGIONS, sharedCache, storageSettings, tmdbCachePolicy } from "../../shared-cache.ts";
import { registerScheduledJob } from "../schedules/registry.ts";
import type { ModuleApp, ServerContext, ServerModule } from "../types.ts";
import { ImageCache, ImageProxyError } from "./images.ts";

/**
 * C2-A 缓存(docs/runbook/cache.md):
 * - PG 缓存 kv_cache(UNLOGGED,移植 MP TTLCache)的过期行物理清理任务 cache.sweep(每 10 分钟);
 * - TMDB 缓存管理(对照 MP tmdb_cache_items / tmdb_cache_clear):GET /cache/tmdb、POST /cache/tmdb/clear;
 * - 图片代理 GET /img/tmdb/{size}/{file}(会话或 API Key read,移植 MP ImageHelper / fetch_image)+ DATA_DIR/cache/images 落盘,
 *   用量 / 清空 GET /cache/images、POST /cache/images/clear,按保留天数清理的任务 cache.images_clean(每天);
 * - CACHE-2:图片缓存容量 LRU 任务 cache.images_lru(30 分钟,预算 storage.budgets.imagesGb,超出删最久未访问)。
 */
export interface CacheModuleOptions {
  /** 图片上游 fetch(测试注入) */
  imageFetch?: typeof globalThis.fetch;
  /** 图片上游基址(测试指向 mock) */
  imageUpstreamBase?: string;
  /** 图片缓存目录;缺省 DATA_DIR/cache/images */
  imageDir?: string;
}

type Infer<T> = T extends z.ZodType ? z.infer<T> : Record<string, never>;

function route<D extends EndpointDef>(
  app: ModuleApp,
  def: D,
  handler: (i: { query: Infer<D["query"]>; params: Infer<D["params"]> }) => Promise<unknown>,
) {
  const request: RouteConfig["request"] = {};
  if (def.query) request.query = def.query as never;
  if (def.params) request.params = def.params as never;
  const r = createRoute({
    method: def.method,
    path: def.path,
    summary: def.summary,
    tags: ["cache"],
    middleware: [requireScope(def.scope)] as never,
    request,
    responses: {
      200: { description: def.summary, content: { "application/json": { schema: apiResponse(def.response) } } },
    },
  });
  // biome-ignore lint/suspicious/noExplicitAny: 路由泛型在封装里擦除,入参已由 zod-openapi 校验
  app.openapi(r, (async (c: any) => {
    const data = def.response.parse(
      await handler({
        query: def.query ? c.req.valid("query") : {},
        params: def.params ? c.req.valid("param") : {},
      } as never),
    );
    return c.json({ ok: true, data }, 200);
    // biome-ignore lint/suspicious/noExplicitAny: 同上
  }) as any);
}

const str = (v: unknown) => (typeof v === "string" && v ? v : null);

export function createCacheModule(opts: CacheModuleOptions = {}): ServerModule & {
  images(ctx: ServerContext): ImageCache;
} {
  const imageCaches = new WeakMap<object, ImageCache>();
  const images = (ctx: ServerContext) => {
    let c = imageCaches.get(ctx);
    if (!c) {
      c = new ImageCache({
        dir: opts.imageDir ?? join(dataPaths(ctx.config).dataDir, "cache", "images"),
        // 外网请求:显式按环境变量走代理(CF-2 出口表)
        fetch: opts.imageFetch ?? externalFetch,
        ...(opts.imageUpstreamBase ? { upstreamBase: opts.imageUpstreamBase } : {}),
      });
      imageCaches.set(ctx, c);
    }
    return c;
  };
  const cacheSettings = (ctx: ServerContext) => ctx.settings.get("cache").catch(() => DEFAULT_SETTINGS.cache);

  return {
    name: "cache",
    images,
    registerRoutes(app, ctx) {
      // 图片代理:不进 OpenAPI(二进制响应);<img> 带 cookie 会话即可,API Key 需 read
      app.get("/img/tmdb/:size/:file", requireScope("read"), async (c) => {
        const s = await cacheSettings(ctx);
        try {
          // MP cache_img:GLOBAL_IMAGE_CACHE 开启才读磁盘缓存
          return await images(ctx).serve(
            c.req.param("size"),
            c.req.param("file"),
            s.globalImageCache ?? false,
            c.req.header("if-none-match") ?? null,
          );
        } catch (e) {
          if (e instanceof ImageProxyError) {
            return c.json(errorBody(e.status === 400 ? "bad_request" : "upstream_unavailable", e.message), e.status);
          }
          throw e;
        }
      });

      route(app, Api.cache.tmdb, async ({ query }) => {
        const cache = sharedCache(ctx);
        const policy = await tmdbCachePolicy(ctx);
        const want = (k: "request" | "recognize") => !query.kind || query.kind === k;
        const items: TmdbCacheItem[] = [];
        if (want("recognize")) {
          for (const r of await cache.items<Record<string, unknown>>(CACHE_REGIONS.tmdbRecognize, query.limit)) {
            const v = r.value ?? {};
            const t = v.type === "movie" || v.type === "tv" ? v.type : "unknown";
            items.push({
              kind: "recognize",
              key: r.key,
              expiresAt: r.expiresAt.toISOString(),
              updatedAt: r.updatedAt.toISOString(),
              bytes: r.bytes,
              tmdbId: typeof v.id === "number" ? v.id : Number(v.id) || 0,
              title: str(v.title),
              year: str(v.year),
              mediaType: t,
              posterPath: str(v.poster_path),
            });
          }
        }
        if (want("request")) {
          for (const r of await cache.items(CACHE_REGIONS.tmdbRequest, query.limit)) {
            items.push({
              kind: "request",
              key: r.key,
              expiresAt: r.expiresAt.toISOString(),
              updatedAt: r.updatedAt.toISOString(),
              bytes: r.bytes,
              tmdbId: null,
              title: null,
              year: null,
              mediaType: null,
              posterPath: null,
            });
          }
        }
        const out: TmdbCacheList = {
          items,
          counts: {
            request: await cache.count(CACHE_REGIONS.tmdbRequest),
            recognize: await cache.count(CACHE_REGIONS.tmdbRecognize),
          },
          maxSize: policy.maxsize,
          ttlHours: Math.round(policy.ttl / 3600),
          emptyResultTtlSec: policy.emptyTtl,
        };
        return out;
      });
      route(app, Api.cache.tmdbClear, async () => {
        const cache = sharedCache(ctx);
        const deleted =
          (await cache.clear(CACHE_REGIONS.tmdbRecognize)) + (await cache.clear(CACHE_REGIONS.tmdbRequest));
        ctx.logger.info({ deleted }, "TMDB 缓存已清空");
        return { deleted };
      });
      route(app, Api.cache.images, async () => {
        const s = await cacheSettings(ctx);
        const img = images(ctx);
        const u = await img.usage();
        return {
          enabled: s.globalImageCache ?? false,
          days: s.globalImageCacheDays ?? DEFAULT_SETTINGS.cache.globalImageCacheDays,
          usedBytes: u.bytes,
          files: u.files,
          dir: img.dir,
        };
      });
      route(app, Api.cache.imagesClear, async () => ({ deleted: await images(ctx).clear() }));
      // 通用缓存按区统计与清空(设置 → 缓存);图片缓存在磁盘上,走上面两个接口
      route(app, Api.cache.regions, async () => {
        const r = await sql<{ region: string; entries: number; expired: number; bytes: string; last: Date | null }>`
          select region,
                 count(*) filter (where expires_at > now())::int as entries,
                 count(*) filter (where expires_at <= now())::int as expired,
                 coalesce(sum(pg_column_size(value) + pg_column_size(key)), 0)::text as bytes,
                 max(updated_at) as last
            from kv_cache group by region order by region`.execute(ctx.db);
        return {
          items: r.rows.map((x) => ({
            region: x.region,
            entries: Number(x.entries),
            expired: Number(x.expired),
            bytes: Number(x.bytes),
            lastWriteAt: x.last ? new Date(x.last).toISOString() : null,
          })),
        };
      });
      route(app, Api.cache.regionClear, async ({ params }) => {
        const deleted = await sharedCache(ctx).clear(params.region);
        ctx.logger.info({ region: params.region, deleted }, "缓存区已清空");
        return { deleted };
      });
    },
    registerTasks() {},
    start(ctx: ServerContext) {
      registerScheduledJob(ctx, {
        key: "cache.sweep",
        lane: "maintenance",
        defaults: {
          name: "缓存清理",
          description: "删除过期的 TMDB 与识别缓存",
          group: "maintain",
          schedule: { type: "interval", everyMs: 10 * 60_000 },
          firstRun: "after_interval",
        },
        run: async () => ({ summary: `删除 ${await sharedCache(ctx).sweep()} 条过期缓存` }),
      });
      registerScheduledJob(ctx, {
        key: "cache.images_clean",
        lane: "maintenance",
        defaults: {
          name: "图片缓存清理",
          description: "删除过期的海报缓存",
          group: "maintain",
          schedule: { type: "interval", everyMs: 24 * 3_600_000 },
        },
        run: async () => {
          const s = await cacheSettings(ctx);
          const n = await images(ctx).clean(s.globalImageCacheDays ?? DEFAULT_SETTINGS.cache.globalImageCacheDays);
          return { summary: `删除 ${n} 张过期图片` };
        },
      });
      registerScheduledJob(ctx, {
        key: "cache.images_lru",
        lane: "maintenance",
        defaults: {
          name: "图片缓存容量控制",
          description: "海报缓存超过容量上限时，删掉最久没用的",
          group: "maintain",
          schedule: { type: "interval", everyMs: 30 * 60_000 },
          firstRun: "after_interval",
        },
        run: async () => {
          const { imagesGb } = (await storageSettings(ctx)).budgets;
          const r = await images(ctx).enforceBudget(Math.round(imagesGb * 1024 ** 3));
          const gb = (b: number) => `${Math.round((b / 1024 ** 3) * 100) / 100} GB`;
          return {
            summary: r.deleted
              ? `删除 ${r.deleted} 张最久未访问的图片，释放 ${gb(r.freedBytes)}，现用 ${gb(r.usedBytes)}`
              : `现用 ${gb(r.usedBytes)}，未超过预算 ${imagesGb} GB`,
          };
        },
      });
    },
  };
}

export const cacheModule = createCacheModule();