@homurajs/storage 0.0.0-stage → 26.10.13

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @homurajs/storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+对象存储/图床：三后端（local-fs / s3 兼容 / supabase）+ `/files/<key>` 代理路由。
+
+```ts
+import { createLocalStorage } from '@homurajs/storage/local'   // 独立形态
+// import { createS3Storage } from '@homurajs/storage/s3'      // minio/oss（AWS SDK 动态加载）
+// import { createSupabaseStorage } from '@homurajs/storage/supabase' // qw-pages（手写 REST）
+
+const storage = createLocalStorage({ rootDir: './data/files' })
+
+// 上传：ns 前缀自动 key；返回代理 URL
+const r = await storage.uploadFile('imgs', 'cat.png', bytes, 'image/png')
+// r.objectKey = 'imgs/files/1760..._cat.png'，r.url = '/files/imgs/files/...'
+
+// 下载 / 删除 / 列举（列举强制 ns 前缀，无法越权）
+const d = await storage.downloadFile(r.objectKey)
+await storage.deleteFile(r.objectKey)
+const files = await storage.listFiles('imgs', '', 20)
+
+// 代理路由（Hono）：统一下载入口，presign 弱后端自动降级到它
+import { createFileProxyRoutes } from '@homurajs/storage/proxy'
+app.route('/', createFileProxyRoutes(storage))
+```
+
+使用示范见模板 `src/server/routes/files.ts`。

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+//#region src/index.d.ts
+/**
+ * 文件存储契约（自 Suzuran storage 适配器平移）：
+ * - 租户/命名空间隔离编码在 key 前缀
+ * - URL 统一走代理路径（/files/<key>），不直接暴露存储地址
+ * - presign 优雅降级：弱后端返回代理路径
+ */
+export interface UploadResult {
+  objectKey: string;
+  /** 平台相对代理路径（/files/<objectKey>） */
+  url: string;
+  size: number;
+  uploadedAt: Date;
+}
+export interface FileInfo {
+  objectKey: string;
+  size: number;
+  updatedAt: Date;
+  contentType?: string;
+}
+export interface FileStorage {
+  /** 业务上传：自动生成 `<ns>/files/<unixNano>_<fileName>` 前缀 key */
+  uploadFile(ns: string, fileName: string, data: FilePayload, contentType: string): Promise<UploadResult>;
+  /** 显式 key 上传（如 code.zip 等精确控制场景） */
+  uploadFileRaw(objectKey: string, data: FilePayload, contentType: string): Promise<UploadResult>;
+  downloadFile(objectKey: string): Promise<{
+    data: Uint8Array;
+    contentType?: string;
+  }>;
+  /** 弱后端降级为代理路径 */
+  getPresignedUrl(objectKey: string, expirySeconds: number): Promise<string>;
+  deleteFile(objectKey: string): Promise<void>;
+  /** 强制 ns 前缀，无法越权列举 */
+  listFiles(ns: string, prefix: string, limit: number): Promise<FileInfo[]>;
+}
+/** 上传载荷（Node 侧 Uint8Array；浏览器 File/Blob 由调用方先转） */
+export type FilePayload = Uint8Array | ReadableStream<Uint8Array>;
+/** object key 校验：禁止路径穿越 */
+export declare function assertSafeObjectKey(key: string): void;
+/** 统一代理路径 */
+export declare function proxyUrl(objectKey: string): string;
+//#endregion

package/dist/index.js

@@ -0,0 +1,11 @@
+//#region src/index.ts
+/** object key 校验：禁止路径穿越 */
+function assertSafeObjectKey(key) {
+	if (key.includes("..") || key.startsWith("/") || key === "") throw new Error(`unsafe object key: ${key}`);
+}
+/** 统一代理路径 */
+function proxyUrl(objectKey) {
+	return `/files/${objectKey}`;
+}
+//#endregion
+export { assertSafeObjectKey, proxyUrl };

package/dist/local.d.ts

@@ -0,0 +1,8 @@
+import { FileStorage } from "./index.js";
+import { createReadStream } from "node:fs";
+//#region src/local.d.ts
+export declare function createLocalStorage(options: {
+  rootDir: string;
+}): FileStorage;
+//#endregion
+export { createReadStream };

package/dist/local.js

@@ -0,0 +1,105 @@
+import { assertSafeObjectKey, proxyUrl } from "./index.js";
+import { createReadStream, existsSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+//#region src/local.ts
+/**
+* local-fs 后端：独立单机形态的缺省实现。
+* - meta sidecar（<key>.meta.json）记录 contentType/size/uploadedAt
+* - presign 降级为代理路径（接口语义：给我一个可下载 URL）
+*/
+const metaPath = (root, key) => `${resolve(root, key)}.meta.json`;
+async function* walk(dir, base = dir) {
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) yield* walk(full, base);
+		else if (!entry.name.endsWith(".meta.json")) yield full.slice(base.length + 1);
+	}
+}
+function createLocalStorage(options) {
+	const root = resolve(options.rootDir);
+	const put = async (key, data, contentType) => {
+		assertSafeObjectKey(key);
+		const abs = join(root, key);
+		await mkdir(dirname(abs), { recursive: true });
+		await writeFile(abs, data);
+		const uploadedAt = /* @__PURE__ */ new Date();
+		const meta = {
+			contentType,
+			size: data.byteLength,
+			uploadedAt: uploadedAt.toISOString()
+		};
+		await writeFile(metaPath(root, key), JSON.stringify(meta));
+		return {
+			objectKey: key,
+			url: proxyUrl(key),
+			size: data.byteLength,
+			uploadedAt
+		};
+	};
+	return {
+		async uploadFile(ns, fileName, data, contentType) {
+			assertSafeObjectKey(ns);
+			const safeName = fileName.replace(/[/\\]/g, "_");
+			const key = `${ns}/files/${Date.now()}_${safeName}`;
+			return put(key, toBytes(data), contentType);
+		},
+		async uploadFileRaw(objectKey, data, contentType) {
+			return put(objectKey, toBytes(data), contentType);
+		},
+		async downloadFile(objectKey) {
+			const abs = join(root, objectKey);
+			if (!existsSync(abs)) throw new Error(`object not found: ${objectKey}`);
+			const data = await readFile(abs);
+			let contentType;
+			try {
+				contentType = JSON.parse(await readFile(metaPath(root, objectKey), "utf-8")).contentType;
+			} catch {
+				contentType = void 0;
+			}
+			return {
+				data,
+				contentType
+			};
+		},
+		async getPresignedUrl(objectKey) {
+			return proxyUrl(objectKey);
+		},
+		async deleteFile(objectKey) {
+			await rm(join(root, objectKey), { force: true });
+			await rm(metaPath(root, objectKey), { force: true });
+		},
+		async listFiles(ns, prefix, limit) {
+			assertSafeObjectKey(ns);
+			const dir = join(root, ns);
+			if (!existsSync(dir)) return [];
+			const out = [];
+			for await (const rel of walk(dir)) {
+				if (prefix && !rel.startsWith(prefix)) continue;
+				const abs = join(dir, rel);
+				const s = await stat(abs);
+				let contentType;
+				const key = `${ns}/${rel}`;
+				try {
+					contentType = JSON.parse(await readFile(metaPath(root, key), "utf-8")).contentType;
+				} catch {
+					contentType = void 0;
+				}
+				out.push({
+					objectKey: key,
+					size: s.size,
+					updatedAt: s.mtime,
+					contentType
+				});
+				if (out.length >= limit) break;
+			}
+			return out;
+		}
+	};
+}
+function toBytes(data) {
+	if (data instanceof Uint8Array) return data;
+	throw new Error("local 后端不支持流式载荷：请先聚合为 Uint8Array");
+}
+//#endregion
+export { createLocalStorage, createReadStream };

package/dist/proxy.d.ts

@@ -0,0 +1,7 @@
+import { FileStorage } from "./index.js";
+import { Hono } from "hono";
+//#region src/proxy.d.ts
+export declare function createFileProxyRoutes(storage: FileStorage, options?: {
+  mount?: string;
+}): Hono;
+//#endregion

package/dist/proxy.js

@@ -0,0 +1,25 @@
+import { Hono } from "hono";
+//#region src/proxy.ts
+/**
+* Hono 代理路由：/files/<key> 统一下载入口（对冲各后端 URL 策略差异）。
+* 所有后端的 UploadResult.url 都指向本路由——不直接暴露存储地址。
+*/
+function createFileProxyRoutes(storage, options) {
+	const mount = options?.mount ?? "/files";
+	const app = new Hono();
+	app.get(`${mount}/:key{.+}`, async (c) => {
+		const key = c.req.param("key");
+		try {
+			const { data, contentType } = await storage.downloadFile(key);
+			return new Response(data, { headers: {
+				"content-type": contentType ?? "application/octet-stream",
+				"cache-control": "public, max-age=31536000, immutable"
+			} });
+		} catch {
+			return c.text("not found", 404);
+		}
+	});
+	return app;
+}
+//#endregion
+export { createFileProxyRoutes };

package/dist/s3.d.ts

@@ -0,0 +1,15 @@
+import { FileStorage } from "./index.js";
+//#region src/s3.d.ts
+export interface S3StorageOptions {
+  endpoint: string;
+  region: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  /** 自举：bucket 不存在时创建（默认 true） */
+  autoCreateBucket?: boolean;
+  /** 预签名走直连 URL（默认 false：走代理路径降级，避免暴露 endpoint） */
+  presignDirect?: boolean;
+}
+export declare function createS3Storage(options: S3StorageOptions): FileStorage;
+//#endregion

package/dist/s3.js

@@ -0,0 +1,115 @@
+import { assertSafeObjectKey, proxyUrl } from "./index.js";
+//#region src/s3.ts
+function createS3Storage(options) {
+	let ready = null;
+	async function init() {
+		const [clientMod, presignerMod] = await Promise.all([import("@aws-sdk/client-s3"), import("@aws-sdk/s3-request-presigner")]);
+		const deps = {
+			S3Client: clientMod.S3Client,
+			PutObjectCommand: clientMod.PutObjectCommand,
+			GetObjectCommand: clientMod.GetObjectCommand,
+			DeleteObjectCommand: clientMod.DeleteObjectCommand,
+			ListObjectsV2Command: clientMod.ListObjectsV2Command,
+			HeadBucketCommand: clientMod.HeadBucketCommand,
+			CreateBucketCommand: clientMod.CreateBucketCommand,
+			getSignedUrl: presignerMod.getSignedUrl
+		};
+		const client = new deps.S3Client({
+			endpoint: options.endpoint,
+			region: options.region,
+			forcePathStyle: true,
+			credentials: {
+				accessKeyId: options.accessKeyId,
+				secretAccessKey: options.secretAccessKey
+			}
+		});
+		if (options.autoCreateBucket !== false) try {
+			await client.send(new deps.HeadBucketCommand({ Bucket: options.bucket }));
+		} catch {
+			await client.send(new deps.CreateBucketCommand({ Bucket: options.bucket }));
+		}
+		return {
+			client,
+			deps
+		};
+	}
+	function ensure() {
+		ready ??= init().catch((e) => {
+			ready = null;
+			throw e;
+		});
+		return ready;
+	}
+	const put = async (key, data, contentType) => {
+		assertSafeObjectKey(key);
+		const { client, deps } = await ensure();
+		await client.send(new deps.PutObjectCommand({
+			Bucket: options.bucket,
+			Key: key,
+			Body: data,
+			ContentType: contentType
+		}));
+		return {
+			objectKey: key,
+			url: proxyUrl(key),
+			size: data.byteLength,
+			uploadedAt: /* @__PURE__ */ new Date()
+		};
+	};
+	return {
+		async uploadFile(ns, fileName, data, contentType) {
+			assertSafeObjectKey(ns);
+			const safeName = fileName.replace(/[/\\]/g, "_");
+			return put(`${ns}/files/${Date.now()}_${safeName}`, toBytes(data), contentType);
+		},
+		async uploadFileRaw(objectKey, data, contentType) {
+			return put(objectKey, toBytes(data), contentType);
+		},
+		async downloadFile(objectKey) {
+			const { client, deps } = await ensure();
+			const res = await client.send(new deps.GetObjectCommand({
+				Bucket: options.bucket,
+				Key: objectKey
+			}));
+			if (!res.Body) throw new Error(`s3 object missing body: ${objectKey}`);
+			return {
+				data: await res.Body.transformToByteArray(),
+				contentType: res.ContentType
+			};
+		},
+		async getPresignedUrl(objectKey, expirySeconds) {
+			if (!options.presignDirect) return proxyUrl(objectKey);
+			const { client, deps } = await ensure();
+			return deps.getSignedUrl(client, new deps.GetObjectCommand({
+				Bucket: options.bucket,
+				Key: objectKey
+			}), { expiresIn: expirySeconds });
+		},
+		async deleteFile(objectKey) {
+			const { client, deps } = await ensure();
+			await client.send(new deps.DeleteObjectCommand({
+				Bucket: options.bucket,
+				Key: objectKey
+			}));
+		},
+		async listFiles(ns, prefix, limit) {
+			assertSafeObjectKey(ns);
+			const { client, deps } = await ensure();
+			return ((await client.send(new deps.ListObjectsV2Command({
+				Bucket: options.bucket,
+				Prefix: `${ns}/${prefix}`,
+				MaxKeys: limit
+			}))).Contents ?? []).map((obj) => ({
+				objectKey: obj.Key ?? "",
+				size: obj.Size ?? 0,
+				updatedAt: obj.LastModified ?? /* @__PURE__ */ new Date()
+			}));
+		}
+	};
+}
+function toBytes(data) {
+	if (data instanceof Uint8Array) return data;
+	throw new Error("s3 后端不支持流式载荷：请先聚合为 Uint8Array");
+}
+//#endregion
+export { createS3Storage };

package/dist/supabase.d.ts

@@ -0,0 +1,11 @@
+import { FileStorage } from "./index.js";
+//#region src/supabase.d.ts
+export interface SupabaseStorageOptions {
+  platformUrl: string;
+  /** public bucket 用 anonKey；private bucket 用 service role key */
+  apiKey: string;
+  bucket: string;
+  fetchImpl?: typeof fetch;
+}
+export declare function createSupabaseStorage(options: SupabaseStorageOptions): FileStorage;
+//#endregion

package/dist/supabase.js

@@ -0,0 +1,109 @@
+import { assertSafeObjectKey, proxyUrl } from "./index.js";
+//#region src/supabase.ts
+/**
+* supabase storage 后端：qw-pages 云形态。
+* 手写 REST（零 SDK 依赖，fetchImpl 可注入测试）：
+* - upload: POST /storage/v1/object/{bucket}/{key}
+* - download: GET /storage/v1/object/{bucket}/{key}
+* - presign: POST /storage/v1/object/sign/{bucket}/{key}
+* - delete: DELETE /storage/v1/object/{bucket}/{key}
+* - list: POST /storage/v1/object/list/{bucket}
+*/
+function createSupabaseStorage(options) {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const base = options.platformUrl.replace(/\/$/, "");
+	const bucket = options.bucket;
+	const headers = () => ({
+		authorization: `Bearer ${options.apiKey}`,
+		apikey: options.apiKey
+	});
+	const put = async (key, data, contentType) => {
+		assertSafeObjectKey(key);
+		const res = await fetchImpl(`${base}/storage/v1/object/${bucket}/${key}`, {
+			method: "POST",
+			headers: {
+				...headers(),
+				"content-type": contentType,
+				"x-upsert": "true"
+			},
+			body: data
+		});
+		if (!res.ok) throw new Error(`supabase upload failed: ${res.status} ${await res.text()}`);
+		const uploadedAt = /* @__PURE__ */ new Date();
+		return {
+			objectKey: key,
+			url: proxyUrl(key),
+			size: data.byteLength,
+			uploadedAt
+		};
+	};
+	return {
+		async uploadFile(ns, fileName, data, contentType) {
+			assertSafeObjectKey(ns);
+			const safeName = fileName.replace(/[/\\]/g, "_");
+			return put(`${ns}/files/${Date.now()}_${safeName}`, toBytes(data), contentType);
+		},
+		async uploadFileRaw(objectKey, data, contentType) {
+			return put(objectKey, toBytes(data), contentType);
+		},
+		async downloadFile(objectKey) {
+			const res = await fetchImpl(`${base}/storage/v1/object/${bucket}/${objectKey}`, { headers: headers() });
+			if (!res.ok) throw new Error(`supabase download failed: ${res.status}`);
+			return {
+				data: new Uint8Array(await res.arrayBuffer()),
+				contentType: res.headers.get("content-type") ?? void 0
+			};
+		},
+		async getPresignedUrl(objectKey, expirySeconds) {
+			const res = await fetchImpl(`${base}/storage/v1/object/sign/${bucket}/${objectKey}`, {
+				method: "POST",
+				headers: {
+					...headers(),
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({ expiresIn: expirySeconds })
+			});
+			if (!res.ok) return proxyUrl(objectKey);
+			const { signedURL } = await res.json();
+			return `${base}/storage/v1${signedURL}`;
+		},
+		async deleteFile(objectKey) {
+			const res = await fetchImpl(`${base}/storage/v1/object/${bucket}/${objectKey}`, {
+				method: "DELETE",
+				headers: headers()
+			});
+			if (!res.ok) throw new Error(`supabase delete failed: ${res.status}`);
+		},
+		async listFiles(ns, prefix, limit) {
+			assertSafeObjectKey(ns);
+			const res = await fetchImpl(`${base}/storage/v1/object/list/${bucket}`, {
+				method: "POST",
+				headers: {
+					...headers(),
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({
+					prefix: `${ns}/${prefix}`,
+					limit,
+					sortBy: {
+						column: "name",
+						order: "asc"
+					}
+				})
+			});
+			if (!res.ok) throw new Error(`supabase list failed: ${res.status}`);
+			return (await res.json()).filter((it) => it.id !== null).map((it) => ({
+				objectKey: `${ns}/${prefix}${it.name}`,
+				size: it.metadata?.size ?? 0,
+				updatedAt: new Date(it.metadata?.lastModified ?? Date.now()),
+				contentType: it.metadata?.mimetype
+			}));
+		}
+	};
+}
+function toBytes(data) {
+	if (data instanceof Uint8Array) return data;
+	throw new Error("supabase 后端不支持流式载荷：请先聚合为 Uint8Array");
+}
+//#endregion
+export { createSupabaseStorage };

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@homurajs/storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "26.10.13",
+  "type": "module",
+  "description": "homura 对象存储/图床适配：supabase-storage / s3 兼容(minio/oss) / local-fs 三后端 + 代理路由",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./local": {
+      "types": "./dist/local.d.ts",
+      "import": "./dist/local.js"
+    },
+    "./s3": {
+      "types": "./dist/s3.d.ts",
+      "import": "./dist/s3.js"
+    },
+    "./supabase": {
+      "types": "./dist/supabase.d.ts",
+      "import": "./dist/supabase.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy.d.ts",
+      "import": "./dist/proxy.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@homurajs/core": "26.10.13"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0.0",
+    "hono": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "hono": "^4.10.0",
+    "tsdown": "^0.23.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }