@openclaw-china/shared 0.1.27 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw-china/shared",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/media/index.ts

@@ -35,23 +35,31 @@ export {
 } from "./media-parser.js";
 
 // 媒体 IO
-export {
-  // 类型
-  type MediaReadResult,
-  type MediaReadOptions,
-  type PathSecurityOptions,
-  // 错误类
-  FileSizeLimitError,
-  MediaTimeoutError,
-  PathSecurityError,
+export {
+  // 类型
+  type MediaReadResult,
+  type MediaReadOptions,
+  type DownloadToTempFileResult,
+  type DownloadToTempFileOptions,
+  type FinalizeInboundMediaOptions,
+  type PruneInboundMediaDirOptions,
+  type PathSecurityOptions,
+  // 错误类
+  FileSizeLimitError,
+  MediaTimeoutError,
+  PathSecurityError,
   // 路径安全
   validatePathSecurity,
   getDefaultAllowedPrefixes,
   // MIME 类型
   getMimeType,
   // 媒体读取函数
-  fetchMediaFromUrl,
-  readMediaFromLocal,
-  readMedia,
-  readMediaBatch,
-} from "./media-io.js";
+  fetchMediaFromUrl,
+  readMediaFromLocal,
+  readMedia,
+  readMediaBatch,
+  downloadToTempFile,
+  finalizeInboundMediaFile,
+  pruneInboundMediaDir,
+  cleanupFileSafe,
+} from "./media-io.js";

package/src/media/media-io.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, describe, expect, it } from "vitest";
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+  FileSizeLimitError,
+  MediaTimeoutError,
+  cleanupFileSafe,
+  downloadToTempFile,
+  finalizeInboundMediaFile,
+  pruneInboundMediaDir,
+} from "./media-io.js";
+
+const tempDirs: string[] = [];
+
+async function createTempDir(prefix: string): Promise<string> {
+  const dir = await fsPromises.mkdtemp(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0, tempDirs.length)) {
+    await fsPromises.rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe("downloadToTempFile", () => {
+  it("downloads HTTP response and stores a temp file", async () => {
+    const dir = await createTempDir("shared-media-io-");
+    const body = Buffer.from("hello-media", "utf8");
+    const fetchFn: typeof globalThis.fetch = async () =>
+      new Response(body, {
+        status: 200,
+        headers: {
+          "content-type": "image/png",
+          "content-length": String(body.length),
+        },
+      });
+
+    const result = await downloadToTempFile("https://example.com/a.png", {
+      fetch: fetchFn,
+      tempDir: dir,
+      tempPrefix: "dingtalk-file",
+    });
+
+    expect(result.path.startsWith(dir)).toBe(true);
+    expect(result.fileName.endsWith(".png")).toBe(true);
+    expect(result.size).toBe(body.length);
+    expect(result.contentType).toBe("image/png");
+
+    const saved = await fsPromises.readFile(result.path);
+    expect(saved.equals(body)).toBe(true);
+  });
+
+  it("throws FileSizeLimitError when Content-Length exceeds maxSize", async () => {
+    const fetchFn: typeof globalThis.fetch = async () =>
+      new Response("too-large", {
+        status: 200,
+        headers: {
+          "content-type": "application/octet-stream",
+          "content-length": "1024",
+        },
+      });
+
+    await expect(
+      downloadToTempFile("https://example.com/too-large.bin", {
+        fetch: fetchFn,
+        maxSize: 100,
+      })
+    ).rejects.toBeInstanceOf(FileSizeLimitError);
+  });
+
+  it("throws MediaTimeoutError on timeout", async () => {
+    const fetchFn: typeof globalThis.fetch = async (_url, init) =>
+      await new Promise<Response>((_resolve, reject) => {
+        const signal = init?.signal;
+        signal?.addEventListener("abort", () => {
+          const err = new Error("aborted");
+          (err as Error & { name: string }).name = "AbortError";
+          reject(err);
+        });
+      });
+
+    await expect(
+      downloadToTempFile("https://example.com/slow.bin", {
+        fetch: fetchFn,
+        timeout: 10,
+      })
+    ).rejects.toBeInstanceOf(MediaTimeoutError);
+  });
+});
+
+describe("cleanupFileSafe", () => {
+  it("removes file and ignores missing file", async () => {
+    const dir = await createTempDir("shared-media-clean-");
+    const filePath = path.join(dir, "a.txt");
+    await fsPromises.writeFile(filePath, "x", "utf8");
+    expect(fs.existsSync(filePath)).toBe(true);
+
+    await cleanupFileSafe(filePath);
+    expect(fs.existsSync(filePath)).toBe(false);
+
+    await expect(cleanupFileSafe(filePath)).resolves.toBeUndefined();
+    await expect(cleanupFileSafe(undefined)).resolves.toBeUndefined();
+  });
+});
+
+describe("inbound media retention", () => {
+  it("finalizes temp media into inbound/YYYY-MM-DD", async () => {
+    const tempDir = await createTempDir("shared-media-temp-");
+    const inboundDir = await createTempDir("shared-media-inbound-");
+    const sourcePath = path.join(tempDir, "img-1.jpg");
+    await fsPromises.writeFile(sourcePath, "abc", "utf8");
+
+    const finalPath = await finalizeInboundMediaFile({
+      filePath: sourcePath,
+      tempDir,
+      inboundDir,
+    });
+
+    expect(finalPath.startsWith(inboundDir)).toBe(true);
+    expect(fs.existsSync(finalPath)).toBe(true);
+    expect(fs.existsSync(sourcePath)).toBe(false);
+  });
+
+  it("does not move files outside tempDir", async () => {
+    const tempDir = await createTempDir("shared-media-temp-");
+    const inboundDir = await createTempDir("shared-media-inbound-");
+    const outsideDir = await createTempDir("shared-media-outside-");
+    const sourcePath = path.join(outsideDir, "a.txt");
+    await fsPromises.writeFile(sourcePath, "x", "utf8");
+
+    const finalPath = await finalizeInboundMediaFile({
+      filePath: sourcePath,
+      tempDir,
+      inboundDir,
+    });
+
+    expect(finalPath).toBe(sourcePath);
+    expect(fs.existsSync(sourcePath)).toBe(true);
+  });
+
+  it("prunes only expired files in date dirs and keeps recent files", async () => {
+    const inboundDir = await createTempDir("shared-media-prune-");
+    const oldDir = path.join(inboundDir, "2024-01-01");
+    const newDir = path.join(inboundDir, "2024-01-02");
+    await fsPromises.mkdir(oldDir, { recursive: true });
+    await fsPromises.mkdir(newDir, { recursive: true });
+
+    const oldFile = path.join(oldDir, "old.jpg");
+    const newFile = path.join(newDir, "new.jpg");
+    const nestedDir = path.join(oldDir, "nested");
+    const nestedFile = path.join(nestedDir, "nested.jpg");
+    await fsPromises.writeFile(oldFile, "old", "utf8");
+    await fsPromises.writeFile(newFile, "new", "utf8");
+    await fsPromises.mkdir(nestedDir, { recursive: true });
+    await fsPromises.writeFile(nestedFile, "nested", "utf8");
+
+    const oldTs = new Date("2024-01-01T00:00:00.000Z");
+    const newTs = new Date("2024-01-02T00:00:00.000Z");
+    await fsPromises.utimes(oldDir, oldTs, oldTs);
+    await fsPromises.utimes(oldFile, oldTs, oldTs);
+    await fsPromises.utimes(newDir, newTs, newTs);
+    await fsPromises.utimes(newFile, newTs, newTs);
+
+    const nowMs = new Date("2024-01-03T00:00:00.000Z").getTime();
+    await pruneInboundMediaDir({
+      inboundDir,
+      keepDays: 1,
+      nowMs,
+    });
+
+    expect(fs.existsSync(oldFile)).toBe(false);
+    expect(fs.existsSync(newFile)).toBe(true);
+    expect(fs.existsSync(nestedFile)).toBe(true);
+    expect(fs.existsSync(oldDir)).toBe(true);
+  });
+});

package/src/media/media-io.ts

@@ -6,11 +6,12 @@
  * @module @openclaw-china/shared/media
  */
 
-import * as fs from "fs";
-import * as fsPromises from "fs/promises";
-import * as path from "path";
-import * as os from "os";
-import { isHttpUrl, normalizeLocalPath, getExtension } from "./media-parser.js";
+import * as fs from "fs";
+import * as fsPromises from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+import { isHttpUrl, normalizeLocalPath, getExtension } from "./media-parser.js";
+import { resolveExtension } from "../file/file-utils.js";
 
 // ============================================================================
 // 类型定义
@@ -19,7 +20,7 @@ import { isHttpUrl, normalizeLocalPath, getExtension } from "./media-parser.js";
 /**
  * 媒体读取结果
  */
-export interface MediaReadResult {
+export interface MediaReadResult {
   /** 文件内容 Buffer */
   buffer: Buffer;
   /** 文件名 */
@@ -28,19 +29,71 @@ export interface MediaReadResult {
   size: number;
   /** MIME 类型（如果可检测） */
   mimeType?: string;
-}
+}
+
+/**
+ * 下载并落盘到临时文件的结果
+ */
+export interface DownloadToTempFileResult {
+  /** 绝对路径 */
+  path: string;
+  /** 写入文件名 */
+  fileName: string;
+  /** MIME 类型 */
+  contentType: string;
+  /** 文件大小（字节） */
+  size: number;
+  /** 来源文件名（若可解析） */
+  sourceFileName?: string;
+}
 
 /**
  * 媒体读取选项
  */
-export interface MediaReadOptions {
+export interface MediaReadOptions {
   /** 超时时间（毫秒），默认 30000 */
   timeout?: number;
   /** 最大文件大小（字节），默认 100MB */
   maxSize?: number;
   /** 自定义 fetch 函数（用于依赖注入） */
   fetch?: typeof globalThis.fetch;
-}
+}
+
+/**
+ * 下载并落盘到临时文件的选项
+ */
+export interface DownloadToTempFileOptions extends MediaReadOptions {
+  /** 目标临时目录，默认 os.tmpdir() */
+  tempDir?: string;
+  /** 文件名前缀，默认 "media" */
+  tempPrefix?: string;
+  /** 来源文件名（优先用于扩展名推断） */
+  sourceFileName?: string;
+}
+
+/**
+ * 归档入站媒体参数
+ */
+export interface FinalizeInboundMediaOptions {
+  /** 当前文件路径 */
+  filePath: string;
+  /** 临时目录（仅该目录下文件会归档） */
+  tempDir: string;
+  /** 入站归档根目录 */
+  inboundDir: string;
+}
+
+/**
+ * 过期清理参数
+ */
+export interface PruneInboundMediaDirOptions {
+  /** 入站归档根目录 */
+  inboundDir: string;
+  /** 保留天数，>=0 生效 */
+  keepDays: number;
+  /** 当前时间（测试用） */
+  nowMs?: number;
+}
 
 /**
  * 路径安全检查选项
@@ -65,17 +118,68 @@ const DEFAULT_TIMEOUT = 30000;
 const DEFAULT_MAX_SIZE = 100 * 1024 * 1024;
 
 /** 默认最大路径长度 */
-const DEFAULT_MAX_PATH_LENGTH = 4096;
+const DEFAULT_MAX_PATH_LENGTH = 4096;
 
 /** 默认允许的路径前缀（Unix） */
-const DEFAULT_UNIX_PREFIXES = [
+const DEFAULT_UNIX_PREFIXES = [
   "/tmp",
   "/var/tmp",
   "/private/tmp",
   "/Users",
   "/home",
   "/root",
-];
+];
+
+function parseContentDispositionFilename(value: string | null): string | undefined {
+  if (!value) return undefined;
+  const utf8Match = value.match(/filename\*=UTF-8''([^;]+)/i);
+  if (utf8Match?.[1]) {
+    try {
+      return decodeURIComponent(utf8Match[1].trim());
+    } catch {
+      return utf8Match[1].trim();
+    }
+  }
+  const plainMatch = value.match(/filename=([^;]+)/i);
+  if (!plainMatch?.[1]) return undefined;
+  const raw = plainMatch[1].trim().replace(/^["']|["']$/g, "");
+  return raw || undefined;
+}
+
+function sanitizeFileName(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) return "file";
+  const normalized = trimmed.replace(/[<>:"/\\|?*\x00-\x1F]/g, "_");
+  return normalized || "file";
+}
+
+function resolveFileNameFromUrl(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    const base = path.basename(parsed.pathname);
+    if (!base || base === "/") return undefined;
+    return base;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeForCompare(value: string): string {
+  return path.resolve(value).replace(/\\/g, "/").toLowerCase();
+}
+
+function isPathUnderDir(filePath: string, dirPath: string): boolean {
+  const f = normalizeForCompare(filePath);
+  const d = normalizeForCompare(dirPath).replace(/\/+$/, "");
+  return f === d || f.startsWith(`${d}/`);
+}
+
+function formatDateDir(date = new Date()): string {
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}`;
+}
 
 /** 扩展名到 MIME 类型映射 */
 const EXT_TO_MIME: Record<string, string> = {
@@ -270,7 +374,7 @@ export function getMimeType(filePath: string): string | undefined {
  * @param options - 读取选项
  * @returns 媒体读取结果
  */
-export async function fetchMediaFromUrl(
+export async function fetchMediaFromUrl(
   url: string,
   options: MediaReadOptions = {}
 ): Promise<MediaReadResult> {
@@ -336,7 +440,106 @@ export async function fetchMediaFromUrl(
   } finally {
     clearTimeout(timeoutId);
   }
-}
+}
+
+/**
+ * 下载 HTTP 媒体并写入临时文件
+ */
+export async function downloadToTempFile(
+  url: string,
+  options: DownloadToTempFileOptions = {}
+): Promise<DownloadToTempFileResult> {
+  if (!isHttpUrl(url)) {
+    throw new Error(`downloadToTempFile expects an HTTP URL, got: ${url}`);
+  }
+
+  const {
+    timeout = DEFAULT_TIMEOUT,
+    maxSize = DEFAULT_MAX_SIZE,
+    fetch: customFetch = globalThis.fetch,
+    tempDir = os.tmpdir(),
+    tempPrefix = "media",
+    sourceFileName,
+  } = options;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await customFetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      const responseBody = await response.text().catch(() => "");
+      throw new Error(`HTTP ${response.status}: ${responseBody}`);
+    }
+
+    const contentType =
+      response.headers.get("content-type")?.split(";")[0].trim() ||
+      "application/octet-stream";
+
+    const contentLength = response.headers.get("content-length");
+    if (contentLength) {
+      const declared = parseInt(contentLength, 10);
+      if (!Number.isNaN(declared) && declared > maxSize) {
+        throw new FileSizeLimitError(declared, maxSize);
+      }
+    }
+
+    const body = response.body;
+    if (!body) {
+      throw new Error("Response body is null");
+    }
+
+    const chunks: Uint8Array[] = [];
+    let totalBytes = 0;
+    const reader = body.getReader();
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        totalBytes += value.length;
+        if (totalBytes > maxSize) {
+          reader.cancel();
+          throw new FileSizeLimitError(totalBytes, maxSize);
+        }
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+
+    const sourceName =
+      sourceFileName ||
+      parseContentDispositionFilename(response.headers.get("content-disposition")) ||
+      resolveFileNameFromUrl(url) ||
+      "file";
+
+    const safePrefix = sanitizeFileName(tempPrefix) || "media";
+    const ext = resolveExtension(contentType, sourceName);
+    const random = Math.random().toString(36).slice(2, 8);
+    const fileName = `${safePrefix}-${Date.now()}-${random}${ext}`;
+    const fullPath = path.join(tempDir, fileName);
+
+    await fsPromises.mkdir(tempDir, { recursive: true });
+    const buffer = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+    await fsPromises.writeFile(fullPath, buffer);
+
+    return {
+      path: fullPath,
+      fileName,
+      contentType,
+      size: totalBytes,
+      sourceFileName: sourceName,
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new MediaTimeoutError(timeout);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
 
 /**
  * 从本地路径读取媒体
@@ -406,7 +609,7 @@ export async function readMedia(
  * @param options - 读取选项
  * @returns 媒体读取结果列表（包含成功和失败的结果）
  */
-export async function readMediaBatch(
+export async function readMediaBatch(
   sources: string[],
   options: MediaReadOptions & PathSecurityOptions = {}
 ): Promise<Array<{ source: string; result?: MediaReadResult; error?: Error }>> {
@@ -414,10 +617,116 @@ export async function readMediaBatch(
     sources.map((source) => readMedia(source, options))
   );
 
-  return results.map((result, index) => {
+  return results.map((result, index) => {
     if (result.status === "fulfilled") {
       return { source: sources[index], result: result.value };
     }
-    return { source: sources[index], error: result.reason as Error };
-  });
-}
+    return { source: sources[index], error: result.reason as Error };
+  });
+}
+
+/**
+ * 将临时媒体文件归档到 inbound/YYYY-MM-DD
+ * - 仅归档 tempDir 下的文件
+ * - 失败时返回原路径，不抛错
+ */
+export async function finalizeInboundMediaFile(
+  options: FinalizeInboundMediaOptions
+): Promise<string> {
+  const current = String(options.filePath ?? "").trim();
+  if (!current) return current;
+
+  if (!isPathUnderDir(current, options.tempDir)) {
+    return current;
+  }
+
+  const datedDir = path.join(options.inboundDir, formatDateDir());
+  const target = path.join(datedDir, path.basename(current));
+
+  try {
+    await fsPromises.mkdir(datedDir, { recursive: true });
+    await fsPromises.rename(current, target);
+    return target;
+  } catch {
+    return current;
+  }
+}
+
+/**
+ * 清理 inbound 目录中过期文件
+ * - 仅处理 YYYY-MM-DD 目录
+ * - 仅删除过期文件，不递归子目录，不删除目录
+ */
+export async function pruneInboundMediaDir(
+  options: PruneInboundMediaDirOptions
+): Promise<void> {
+  const keepDays = Number(options.keepDays);
+  if (!Number.isFinite(keepDays) || keepDays < 0) return;
+
+  const now = options.nowMs ?? Date.now();
+  const cutoff = now - keepDays * 24 * 60 * 60 * 1000;
+
+  let entries: string[] = [];
+  try {
+    entries = await fsPromises.readdir(options.inboundDir);
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(entry)) continue;
+    const dirPath = path.join(options.inboundDir, entry);
+
+    let dirStats;
+    try {
+      dirStats = await fsPromises.stat(dirPath);
+    } catch {
+      continue;
+    }
+    if (!dirStats.isDirectory()) continue;
+
+    const dirTime = dirStats.mtimeMs || dirStats.ctimeMs || 0;
+    if (dirTime >= cutoff) continue;
+
+    let files: string[] = [];
+    try {
+      files = await fsPromises.readdir(dirPath);
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      const fp = path.join(dirPath, file);
+      try {
+        const fst = await fsPromises.stat(fp);
+        if (fst.isFile() && (fst.mtimeMs || fst.ctimeMs || 0) < cutoff) {
+          await fsPromises.unlink(fp);
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+/**
+ * 安全删除文件
+ * - filePath 为空直接返回
+ * - ENOENT 视为成功
+ * - 其他错误可通过 onError 回调记录
+ */
+export async function cleanupFileSafe(
+  filePath: string | undefined,
+  onError?: (error: unknown, filePath: string) => void
+): Promise<void> {
+  if (!filePath) return;
+
+  try {
+    await fsPromises.unlink(filePath);
+  } catch (error) {
+    if (error instanceof Error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    onError?.(error, filePath);
+  }
+}