@wener/common 2.0.2 → 2.0.3

package/src/fs/createSandboxFileSystem.ts

@@ -0,0 +1,136 @@
+import { join, normalize, relative, sep } from 'pathe';
+import type { IFileStat, IFileSystem, IServerFileSystem, ReadFileOptions } from './IFileSystem';
+import { getPath } from './utils';
+
+class SandboxSecurityError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'SandboxSecurityError';
+	}
+}
+
+export function createSandboxFileSystem(
+	fs: IServerFileSystem,
+	basePath: string,
+): IServerFileSystem & {
+	fs: IServerFileSystem;
+	basePath: string;
+} {
+	return new SandboxFS(fs, basePath);
+}
+
+class SandboxFS implements IServerFileSystem {
+	fs: IServerFileSystem;
+	basePath: string;
+
+	constructor(fs: IServerFileSystem, basePath: string) {
+		this.fs = fs;
+		this.basePath = normalize(basePath);
+	}
+
+	private _resolvePath(userPath: string): string {
+		const fullPath = join(this.basePath, userPath);
+
+		const normalizedFullPath = normalize(fullPath);
+
+		const rel = relative(this.basePath, normalizedFullPath);
+		if (rel.startsWith('..') || rel === '..') {
+			throw new SandboxSecurityError(`Path traversal attempt detected: ${userPath}`);
+		}
+		return normalizedFullPath;
+	}
+
+	private _stripPath(fullPath: string): string {
+		const relPath = relative(this.basePath, fullPath);
+		// 保证返回的是一个以 '/' 开头的绝对路径（在沙箱内）
+		return sep + relPath.split(sep).join('/');
+	}
+
+	private _processStat(stat: IFileStat): IFileStat {
+		stat.path = this._stripPath(stat.path);
+		stat.directory = this._stripPath(stat.directory);
+		return stat;
+	}
+
+	async stat(path: string, options?: any): Promise<IFileStat> {
+		const fullPath = this._resolvePath(path);
+		const result = await this.fs.stat(fullPath, options);
+		return this._processStat(result);
+	}
+
+	async readdir(dir: string, options?: any): Promise<IFileStat[]> {
+		const fullPath = this._resolvePath(dir);
+		const results = await this.fs.readdir(fullPath, options);
+		return results.map((stat) => this._processStat(stat));
+	}
+
+	async exists(path: string): Promise<boolean> {
+		try {
+			const fullPath = this._resolvePath(path);
+			return await this.fs.exists(fullPath);
+		} catch (e) {
+			if (e instanceof SandboxSecurityError) {
+				return false; // 越界访问视为不存在
+			}
+			throw e;
+		}
+	}
+
+	mkdir(path: string, options?: any): Promise<void> {
+		const fullPath = this._resolvePath(path);
+		return this.fs.mkdir(fullPath, options);
+	}
+
+	readFile(path: string, options?: ReadFileOptions & { encoding: 'text' }): Promise<string>;
+	readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+	readFile(path: string, options?: ReadFileOptions): Promise<string | Uint8Array> {
+		const fullPath = this._resolvePath(path);
+		return this.fs.readFile(fullPath, options);
+	}
+
+	writeFile(path: string, data: any, options?: any): Promise<void> {
+		const fullPath = this._resolvePath(path);
+		return this.fs.writeFile(fullPath, data, options);
+	}
+
+	rm(path: string, options?: any): Promise<void> {
+		const fullPath = this._resolvePath(path);
+		return this.fs.rm(fullPath, options);
+	}
+
+	rename(oldPath: string, newPath: string, options?: any): Promise<void> {
+		const fullOldPath = this._resolvePath(oldPath);
+		const fullNewPath = this._resolvePath(newPath);
+		return this.fs.rename(fullOldPath, fullNewPath, options);
+	}
+
+	copy(src: string, dest: string, options?: any): Promise<void> {
+		const fullSrc = this._resolvePath(src);
+		const fullDest = this._resolvePath(dest);
+		return this.fs.copy(fullSrc, fullDest, options);
+	}
+
+	createReadStream(path: string, options?: any): any {
+		const fullPath = this._resolvePath(path);
+		if (!this.fs.createReadStream) {
+			throw new Error('Underlying filesystem does not support createReadStream');
+		}
+		return this.fs.createReadStream(fullPath, options);
+	}
+
+	createWriteStream(path: string, options?: any): any {
+		const fullPath = this._resolvePath(path);
+		if (!this.fs.createWriteStream) {
+			throw new Error('Underlying filesystem does not support createWriteStream');
+		}
+		return this.fs.createWriteStream(fullPath, options);
+	}
+
+	getUrl(file: IFileStat, options?: any): string | undefined {
+		let path = this._resolvePath(getPath(file.path));
+		if (this.fs.getUrl) {
+			return this.fs.getUrl(path, options);
+		}
+		return;
+	}
+}

package/src/fs/createWebDavFileSystem.ts

@@ -0,0 +1,172 @@
+import type { Readable, Writable } from 'node:stream';
+import { maybeFunction, type MaybeFunction } from '@wener/utils';
+import type { FileStat, GetDirectoryContentsOptions, ResponseDataDetailed, WebDAVClient } from 'webdav';
+import type {
+	IFileStat,
+	IFileSystem,
+	MkdirOptions,
+	ReaddirOptions,
+	ReadFileOptions,
+	RmOptions,
+	StatOptions,
+} from './IFileSystem';
+
+export function createWebDavFileSystem({ client }: { client: MaybeFunction<WebDAVClient> }): IFileSystem {
+	let fs = new WebdavFS({ client });
+	return fs;
+}
+
+class WebdavFS implements IFileSystem {
+	_client: MaybeFunction<WebDAVClient>;
+
+	constructor({
+		client = () => {
+			throw new Error('WebdavFS client not initialized');
+		},
+	}: {
+		client?: MaybeFunction<WebDAVClient>;
+	}) {
+		this._client = client;
+	}
+
+	set client(client: MaybeFunction<WebDAVClient>) {
+		this._client = client;
+	}
+
+	get client(): WebDAVClient {
+		return maybeFunction(this._client);
+	}
+
+	private toEntry(input: FileStat): IFileStat {
+		const { filename: path, basename, lastmod, type: kind, etag, size, mime } = input;
+		let meta: Record<string, any> = {};
+		if (etag) {
+			meta['etag'] = etag;
+		}
+		if (mime) {
+			meta['mime'] = mime;
+		}
+		return {
+			directory: path.substring(0, path.lastIndexOf('/')) || '/',
+			path,
+			name: basename,
+			mtime: +new Date(lastmod),
+			kind,
+			meta,
+			size,
+		};
+	}
+
+	private getData<T>(input: ResponseDataDetailed<T> | T): T {
+		if (
+			input
+			&& typeof input === 'object'
+			&& 'data' in input
+			// 'headers' in input &&
+			&& 'status' in input
+			&& typeof input.status === 'number'
+		) {
+			return input.data;
+		}
+		return input as T;
+	}
+
+	async readdir(
+		path: string,
+		{ glob, recursive, depth, kind, hidden, signal }: ReaddirOptions = {},
+	): Promise<IFileStat[]> {
+		// webdav depth 只支持 0,1
+		let o: GetDirectoryContentsOptions = {};
+		if (recursive) {
+			o.deep = true;
+		}
+		let res = await this.client.getDirectoryContents(path, {
+			deep: recursive,
+			signal,
+		});
+
+		let out: FileStat[] = this.getData(res);
+
+		if (!recursive && typeof depth === 'number' && depth >= 2) {
+			let l = depth;
+			let cur = out;
+			while (l-- > 1) {
+				let sub = (
+					await Promise.all(
+						cur.map(async (v) => {
+							if (v.type === 'directory') {
+								return this.getData(await this.client.getDirectoryContents(v.filename, { signal }));
+							}
+							return [];
+						}),
+					)
+				).flat();
+				out = out.concat(...sub);
+				cur = sub;
+			}
+		}
+
+		if (glob) {
+			const { default: def, matcher = def.matcher } = await import('micromatch');
+			const match = matcher(glob);
+			out = out.filter((v) => match(v.filename));
+		}
+		if (kind) {
+			out = out.filter((v) => v.type === kind);
+		}
+		if (!hidden) {
+			out = out.filter((v) => !v.basename.startsWith('.'));
+		}
+		return out.map((stat) => this.toEntry(stat));
+	}
+
+	async stat(path: string, { signal }: StatOptions = {}): Promise<IFileStat> {
+		const res = await this.client.stat(path, { details: true, signal });
+		return this.toEntry(this.getData(res));
+	}
+
+	async mkdir(path: string, { recursive, signal }: MkdirOptions = {}): Promise<void> {
+		await this.client.createDirectory(path, { recursive, signal });
+	}
+
+	async readFile(path: string, options: ReadFileOptions = {}): Promise<any> {
+		const format = options.encoding === 'text' ? 'text' : 'binary';
+		const res = await this.client.getFileContents(path, { format, ...options });
+		return this.getData(res);
+	}
+
+	async writeFile(path: string, data: string | Buffer | ArrayBuffer | Readable, options = {}): Promise<void> {
+		await this.client.putFileContents(path, data, options);
+	}
+
+	async rm(path: string, { signal, force, recursive }: RmOptions = {}): Promise<void> {
+		try {
+			await this.client.deleteFile(path);
+		} catch (e: any) {
+			if (force && e.status === 404) {
+				return;
+			}
+			throw e;
+		}
+	}
+
+	async rename(oldPath: string, newPath: string, options = {}): Promise<void> {
+		await this.client.moveFile(oldPath, newPath, options);
+	}
+
+	async exists(path: string): Promise<boolean> {
+		return await this.client.exists(path);
+	}
+
+	async copy(src: string, dest: string, options = {}): Promise<void> {
+		await this.client.copyFile(src, dest, options);
+	}
+
+	createReadStream(path: string, options = {}): Readable {
+		return this.client.createReadStream(path, options);
+	}
+
+	createWriteStream(path: string, options = {}): Writable {
+		return this.client.createWriteStream(path, options);
+	}
+}

package/src/fs/findMimeType.ts

@@ -0,0 +1,23 @@
+import { types } from 'mime-types';
+import pathe from 'pathe';
+
+export function findMimeType(path: string | undefined | null) {
+	// fix extname error
+	// https://github.com/jshttp/mime-types/issues/111
+
+	if (!path || typeof path !== 'string') {
+		return false;
+	}
+
+	// get the extension ("ext" or ".ext" or full path)
+	const extension = pathe
+		.extname('x.' + path)
+		.toLowerCase()
+		.slice(1);
+
+	if (!extension) {
+		return false;
+	}
+
+	return types[extension] || false;
+}

package/src/fs/index.ts

@@ -0,0 +1,8 @@
+export type * from './IFileSystem';
+export { createSandboxFileSystem } from './createSandboxFileSystem';
+export { createMemoryFileSystem } from './createMemoryFileSystem';
+export { createWebDavFileSystem } from './createWebDavFileSystem';
+export { createBrowserFileSystem } from './createBrowserFileSystem';
+export { findMimeType } from './findMimeType';
+export { type FileUrlOptions, FileUrlOptionsSchema } from './types';
+export { FileSystemError, FileSystemErrorCode } from './FileSystemError';

package/src/fs/orpc/FileSystemContract.ts

@@ -0,0 +1,92 @@
+import { oc } from '@orpc/contract';
+import { z } from 'zod/v4';
+import { FileKindSchema } from '../types';
+
+export type FileStat = z.infer<typeof FileStatSchema>;
+export const FileStatSchema = z.object({
+	directory: z.string(),
+	path: z.string(),
+	name: z.string(),
+	kind: FileKindSchema,
+	mtime: z.coerce.date(),
+	size: z.coerce.number().nonnegative().default(0),
+	meta: z.record(z.string(), z.any()),
+});
+export type ReaddirInput = z.infer<typeof ReaddirInputSchema>;
+export const ReaddirInputSchema = z.object({
+	dir: z.string().nonempty(),
+	glob: z.string().optional(),
+	recursive: z.boolean().default(false),
+	depth: z.number().min(0).optional(),
+	kind: FileKindSchema.optional(),
+	cursor: z.string().optional(),
+	hidden: z.boolean().default(false),
+});
+const ReaddirOutputSchema = z.object({
+	data: FileStatSchema.array(),
+});
+const StatInputSchema = z.object({
+	path: z.string(),
+});
+const StatOutputSchema = z.object({
+	data: FileStatSchema,
+});
+const CreateDirectoryInputSchema = z.object({
+	path: z.string(),
+	recursive: z.boolean().nullish(),
+});
+const CreateDirectoryOutputSchema = z.object({}).default({});
+const RenameInputSchema = z.object({
+	oldPath: z.string(),
+	newPath: z.string(),
+	overwrite: z.boolean().nullish(),
+});
+const RenameOutputSchema = z.object({}).default({});
+const ExistsInputSchema = z.object({
+	path: z.string(),
+});
+const ExistsOutputSchema = z.object({
+	data: z.boolean(),
+});
+const CopyInputSchema = z.object({
+	src: z.string(),
+	dest: z.string(),
+	overwrite: z.boolean().nullish(),
+	shallow: z.boolean().nullish(),
+});
+const CopyOutputSchema = z.object({}).default({});
+const ReadFileInputSchema = z.object({
+	path: z.string(),
+});
+const ReadFileOutputSchema = z.object({
+	base64: z.string(),
+});
+const WriteFileInputSchema = z.object({
+	path: z.string(),
+	base64: z.string(),
+	overwrite: z.boolean().optional(),
+});
+const WriteFileOutputSchema = z.object({});
+const RemoveInputSchema = z.object({
+	path: z.string(),
+	recursive: z.boolean().nullish(),
+	force: z.boolean().nullish(),
+});
+const RemoveOutputSchema = z.object({}).default({});
+export const FileSystemContract = {
+	readdir: oc.input(ReaddirInputSchema).output(ReaddirOutputSchema).route({ description: 'List directory contents' }),
+	stat: oc.input(StatInputSchema).output(StatOutputSchema).route({
+		method: 'GET',
+		description: 'Get file or directory status',
+	}),
+	mkdir: oc
+		.input(CreateDirectoryInputSchema)
+		.output(CreateDirectoryOutputSchema)
+		.route({ description: 'Create a directory' }),
+	readFile: oc.input(ReadFileInputSchema).output(ReadFileOutputSchema).route({ description: 'Read file' }),
+	writeFile: oc.input(WriteFileInputSchema).output(WriteFileOutputSchema),
+	rename: oc.input(RenameInputSchema).output(RenameOutputSchema),
+	exists: oc.input(ExistsInputSchema).output(ExistsOutputSchema),
+	copy: oc.input(CopyInputSchema).output(CopyOutputSchema),
+	rm: oc.input(RemoveInputSchema).output(RemoveOutputSchema),
+};

package/src/fs/orpc/createContractClientFileSystem.ts

@@ -0,0 +1,115 @@
+import type { Readable, Writable } from 'node:stream';
+import type { ContractRouterClient } from '@orpc/contract';
+import { ArrayBuffers } from '@wener/utils';
+import type {
+	CopyOptions,
+	CreateReadStreamOptions,
+	CreateWriteStreamOptions,
+	IFileSystem,
+	MkdirOptions,
+	ReaddirOptions,
+	ReadFileOptions,
+	RenameOptions,
+	RmOptions,
+	StatOptions,
+	WritableData,
+	WriteFileOptions,
+} from '../IFileSystem';
+import { resolveData } from '../utils';
+import { FileSystemContract } from './FileSystemContract';
+
+type FileSystemContractClient = ContractRouterClient<typeof FileSystemContract>;
+
+export function createContractClientFileSystem(client: FileSystemContractClient): IFileSystem & {
+	client: FileSystemContractClient;
+} {
+	return new ContractFS(client);
+}
+
+class ContractFS implements IFileSystem {
+	client: FileSystemContractClient;
+
+	constructor(client: FileSystemContractClient) {
+		this.client = client;
+	}
+
+	async readdir(dir: string, options: ReaddirOptions = {}) {
+		const { data } = await this.client.readdir({ dir, ...options });
+		return data.map((stat) => ({
+			...stat,
+			mtime: stat.mtime.getTime(),
+		}));
+	}
+
+	async stat(entry: string, options?: StatOptions) {
+		const { data } = await this.client.stat({ path: entry });
+		return {
+			...data,
+			mtime: data.mtime.getTime(),
+		};
+	}
+
+	async mkdir(path: string, options?: MkdirOptions) {
+		await this.client.mkdir({
+			path,
+			recursive: options?.recursive,
+		});
+	}
+
+	readFile(path: string, options?: ReadFileOptions & { encoding: 'text' }): Promise<string>;
+	readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+	async readFile(path: string, options?: ReadFileOptions): Promise<string | Uint8Array> {
+		// Note: The contract doesn't currently support encoding options.
+		const { base64 } = await this.client.readFile({ path });
+		let enc = options?.encoding || 'binary';
+		let buf = ArrayBuffers.fromBase64(base64);
+		switch (enc) {
+			case 'text':
+				return ArrayBuffers.toString(buf);
+		}
+		return buf;
+	}
+
+	async writeFile(path: string, data: WritableData, options?: WriteFileOptions) {
+		let buf = resolveData(data);
+		await this.client.writeFile({ path, base64: ArrayBuffers.toBase64(buf), ...options });
+	}
+
+	async rename(oldPath: string, newPath: string, options?: RenameOptions) {
+		await this.client.rename({
+			oldPath,
+			newPath,
+			overwrite: options?.overwrite,
+		});
+	}
+
+	async exists(path: string) {
+		const { data } = await this.client.exists({ path });
+		return data;
+	}
+
+	async copy(src: string, dest: string, options?: CopyOptions) {
+		await this.client.copy({
+			src,
+			dest,
+			overwrite: options?.overwrite,
+			shallow: options?.shallow,
+		});
+	}
+
+	async rm(path: string, options?: RmOptions) {
+		await this.client.rm({
+			path,
+			recursive: options?.recursive,
+			force: options?.force,
+		});
+	}
+
+	createReadStream(path: string, options?: CreateReadStreamOptions): Readable {
+		throw new Error('createReadStream is not implemented in ContractFS');
+	}
+
+	createWriteStream(path: string, options?: CreateWriteStreamOptions): Writable {
+		throw new Error('createWriteStream is not implemented in ContractFS');
+	}
+}

package/src/fs/orpc/index.ts

@@ -0,0 +1,2 @@
+export { createContractClientFileSystem } from './createContractClientFileSystem';
+export { FileSystemContract } from './FileSystemContract';

package/src/fs/orpc/server/createFileSystemContractImpl.ts

@@ -0,0 +1,64 @@
+import { implement } from '@orpc/server';
+import { ArrayBuffers } from '@wener/utils';
+import type { IFileSystem } from '../../IFileSystem';
+import { FileSystemContract } from '../FileSystemContract';
+
+export function createFileSystemContractImpl(ifs: IFileSystem) {
+	const os = implement(FileSystemContract);
+
+	return {
+		readdir: os.readdir.handler(async ({ input }) => {
+			return {
+				data: await ifs.readdir(input.dir),
+			};
+		}),
+		stat: os.stat.handler(async ({ input }) => {
+			return {
+				data: await ifs.stat(input.path),
+			};
+		}),
+		mkdir: os.mkdir.handler(async ({ input }) => {
+			await ifs.mkdir(input.path, {
+				recursive: input.recursive ?? false,
+			});
+			return {};
+		}),
+		rename: os.rename.handler(async ({ input }) => {
+			await ifs.rename(input.oldPath, input.newPath, {
+				overwrite: input.overwrite ?? false,
+			});
+			return {};
+		}),
+		exists: os.exists.handler(async ({ input }) => {
+			return {
+				data: await ifs.exists(input.path),
+			};
+		}),
+		copy: os.copy.handler(async ({ input }) => {
+			await ifs.copy(input.src, input.dest, {
+				overwrite: input.overwrite ?? false,
+				shallow: input.shallow ?? false,
+			});
+			return {};
+		}),
+		readFile: os.readFile.handler(async ({ input }) => {
+			return {
+				base64: ArrayBuffers.toBase64(await ifs.readFile(input.path, { encoding: 'binary' })),
+			};
+		}),
+		writeFile: os.writeFile.handler(async ({ input }) => {
+			await ifs.writeFile(input.path, Buffer.from(input.base64, 'base64'), {
+				overwrite: input.overwrite,
+			});
+			return {};
+		}),
+
+		rm: os.rm.handler(async ({ input }) => {
+			await ifs.rm(input.path, {
+				recursive: input.recursive ?? undefined,
+				force: input.force ?? undefined,
+			});
+			return {};
+		}),
+	};
+}

package/src/fs/orpc/server/index.ts

@@ -0,0 +1 @@
+export { createFileSystemContractImpl } from './createFileSystemContractImpl';