@openclaw-china/shared 0.1.37 → 0.1.39

package/src/media/media-io.ts

@@ -6,12 +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 { resolveExtension } from "../file/file-utils.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";
 
 // ============================================================================
 // 类型定义
@@ -20,7 +20,7 @@ import { resolveExtension } from "../file/file-utils.js";
 /**
  * 媒体读取结果
  */
-export interface MediaReadResult {
+export interface MediaReadResult {
   /** 文件内容 Buffer */
   buffer: Buffer;
   /** 文件名 */
@@ -29,71 +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 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;
-}
+}
+
+/**
+ * 下载并落盘到临时文件的选项
+ */
+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;
+}
 
 /**
  * 路径安全检查选项
@@ -118,68 +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}`;
-}
+];
+
+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> = {
@@ -374,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> {
@@ -440,106 +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);
-  }
-}
+}
+
+/**
+ * 下载 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);
+  }
+}
 
 /**
  * 从本地路径读取媒体
@@ -609,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 }>> {
@@ -617,116 +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 };
-  });
-}
-
-/**
- * 将临时媒体文件归档到 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);
-  }
-}
+    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);
+  }
+}