emdash 0.0.0-b → 0.0.2

package/src/storage/local.ts

@@ -0,0 +1,249 @@
+/**
+ * Local Filesystem Storage Implementation
+ *
+ * For development and testing. Stores files in a local directory.
+ */
+
+import { createReadStream, existsSync } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { Readable } from "node:stream";
+
+import mime from "mime/lite";
+
+/** Type guard for Node.js ErrnoException */
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+import type {
+	Storage,
+	LocalStorageConfig,
+	UploadResult,
+	DownloadResult,
+	ListResult,
+	ListOptions,
+	SignedUploadUrl,
+	SignedUploadOptions,
+} from "./types.js";
+import { EmDashStorageError } from "./types.js";
+
+/** Pattern to remove leading slashes */
+const LEADING_SLASH_PATTERN = /^\//;
+
+/** Pattern to remove trailing slashes */
+const TRAILING_SLASH_PATTERN = /\/$/;
+
+/**
+ * Local filesystem storage implementation
+ */
+export class LocalStorage implements Storage {
+	/** Resolved absolute base directory for all stored files */
+	private directory: string;
+	private baseUrl: string;
+
+	constructor(config: LocalStorageConfig) {
+		this.directory = path.resolve(config.directory);
+		this.baseUrl = config.baseUrl.replace(TRAILING_SLASH_PATTERN, "");
+	}
+
+	/**
+	 * Resolve a storage key to an absolute file path, ensuring it stays
+	 * within the configured storage directory. Uses path.resolve() for
+	 * canonical resolution rather than regex stripping.
+	 *
+	 * @throws EmDashStorageError if the resolved path escapes the base directory
+	 */
+	private getFilePath(key: string): string {
+		const normalizedKey = key.replace(LEADING_SLASH_PATTERN, "");
+		const resolved = path.resolve(this.directory, normalizedKey);
+
+		// Verify the resolved path is within the base directory
+		if (!resolved.startsWith(this.directory + path.sep) && resolved !== this.directory) {
+			throw new EmDashStorageError("Invalid file path", "INVALID_PATH");
+		}
+
+		return resolved;
+	}
+
+	async upload(options: {
+		key: string;
+		body: Buffer | Uint8Array | ReadableStream<Uint8Array>;
+		contentType: string;
+	}): Promise<UploadResult> {
+		try {
+			const filePath = this.getFilePath(options.key);
+			const dir = path.dirname(filePath);
+
+			// Ensure directory exists
+			await fs.mkdir(dir, { recursive: true });
+
+			// Convert body to buffer
+			let buffer: Buffer;
+			if (options.body instanceof ReadableStream) {
+				const chunks: Uint8Array[] = [];
+				const reader = options.body.getReader();
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					chunks.push(value);
+				}
+				buffer = Buffer.concat(chunks);
+			} else if (options.body instanceof Uint8Array) {
+				buffer = Buffer.from(options.body);
+			} else {
+				buffer = options.body;
+			}
+
+			await fs.writeFile(filePath, buffer);
+
+			return {
+				key: options.key,
+				url: this.getPublicUrl(options.key),
+				size: buffer.length,
+			};
+		} catch (error) {
+			throw new EmDashStorageError(`Failed to upload file: ${options.key}`, "UPLOAD_FAILED", error);
+		}
+	}
+
+	async download(key: string): Promise<DownloadResult> {
+		try {
+			const filePath = this.getFilePath(key);
+
+			if (!existsSync(filePath)) {
+				throw new EmDashStorageError(`File not found: ${key}`, "NOT_FOUND");
+			}
+
+			const stat = await fs.stat(filePath);
+			const nodeStream = createReadStream(filePath);
+
+			// Convert Node.js stream to web ReadableStream
+			// Readable.toWeb returns ReadableStream (which is ReadableStream<unknown>),
+			// but Node ReadStreams produce Buffer/Uint8Array chunks
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Readable.toWeb returns ReadableStream<unknown>; Node ReadStreams produce Uint8Array chunks
+			const webStream: ReadableStream<Uint8Array> = Readable.toWeb(
+				nodeStream,
+			) as ReadableStream<Uint8Array>;
+
+			// Infer content type from extension
+			const ext = path.extname(key).toLowerCase();
+			const contentType = getContentType(ext);
+
+			return {
+				body: webStream,
+				contentType,
+				size: stat.size,
+			};
+		} catch (error) {
+			if (error instanceof EmDashStorageError) throw error;
+			throw new EmDashStorageError(`Failed to download file: ${key}`, "DOWNLOAD_FAILED", error);
+		}
+	}
+
+	async delete(key: string): Promise<void> {
+		try {
+			const filePath = this.getFilePath(key);
+			await fs.unlink(filePath);
+		} catch (error) {
+			// Ignore "file not found" errors (idempotent delete)
+			if (!isNodeError(error) || error.code !== "ENOENT") {
+				throw new EmDashStorageError(`Failed to delete file: ${key}`, "DELETE_FAILED", error);
+			}
+		}
+	}
+
+	async exists(key: string): Promise<boolean> {
+		try {
+			const filePath = this.getFilePath(key);
+			await fs.access(filePath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	async list(options: ListOptions = {}): Promise<ListResult> {
+		try {
+			const prefix = options.prefix || "";
+			const searchDir = path.resolve(this.directory, path.dirname(prefix));
+
+			// Validate the search directory stays within the base directory
+			if (!searchDir.startsWith(this.directory + path.sep) && searchDir !== this.directory) {
+				throw new EmDashStorageError("Invalid list prefix", "INVALID_PATH");
+			}
+
+			const prefixBase = path.basename(prefix);
+
+			// Ensure directory exists
+			try {
+				await fs.access(searchDir);
+			} catch {
+				return { files: [] };
+			}
+
+			const entries = await fs.readdir(searchDir, { withFileTypes: true });
+			const files: ListResult["files"] = [];
+
+			for (const entry of entries) {
+				if (entry.isFile() && entry.name.startsWith(prefixBase)) {
+					const key = path.join(path.dirname(prefix), entry.name);
+					const filePath = path.join(searchDir, entry.name);
+					const stat = await fs.stat(filePath);
+
+					files.push({
+						key,
+						size: stat.size,
+						lastModified: stat.mtime,
+					});
+				}
+			}
+
+			// Sort by last modified (newest first)
+			files.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+
+			// Apply limit and cursor (simple implementation)
+			const startIndex = options.cursor ? parseInt(options.cursor, 10) : 0;
+			const limit = options.limit || 1000;
+			const paginatedFiles = files.slice(startIndex, startIndex + limit);
+			const hasMore = startIndex + limit < files.length;
+
+			return {
+				files: paginatedFiles,
+				nextCursor: hasMore ? String(startIndex + limit) : undefined,
+			};
+		} catch (error) {
+			throw new EmDashStorageError("Failed to list files", "LIST_FAILED", error);
+		}
+	}
+
+	async getSignedUploadUrl(_options: SignedUploadOptions): Promise<SignedUploadUrl> {
+		// Local storage doesn't support signed URLs
+		throw new EmDashStorageError(
+			"Local storage does not support signed upload URLs. " +
+				"Upload files directly through the API.",
+			"NOT_SUPPORTED",
+		);
+	}
+
+	getPublicUrl(key: string): string {
+		return `${this.baseUrl}/${key}`;
+	}
+}
+
+/**
+ * Get content type from file extension
+ */
+function getContentType(ext: string): string {
+	return mime.getType(ext) ?? "application/octet-stream";
+}
+
+/**
+ * Create local storage adapter
+ * This is the factory function called at runtime
+ */
+export function createStorage(config: Record<string, unknown>): Storage {
+	const directory = typeof config.directory === "string" ? config.directory : "";
+	const baseUrl = typeof config.baseUrl === "string" ? config.baseUrl : "";
+	return new LocalStorage({ directory, baseUrl });
+}

package/src/storage/s3.ts

@@ -0,0 +1,263 @@
+/**
+ * S3-Compatible Storage Implementation
+ *
+ * Uses the AWS SDK v3 for S3 operations.
+ * Works with AWS S3, Cloudflare R2, Minio, and other S3-compatible services.
+ */
+
+import {
+	S3Client,
+	PutObjectCommand,
+	GetObjectCommand,
+	DeleteObjectCommand,
+	HeadObjectCommand,
+	ListObjectsV2Command,
+	type ListObjectsV2Response,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+import type {
+	Storage,
+	S3StorageConfig,
+	UploadResult,
+	DownloadResult,
+	ListResult,
+	ListOptions,
+	SignedUploadUrl,
+	SignedUploadOptions,
+} from "./types.js";
+import { EmDashStorageError } from "./types.js";
+
+const TRAILING_SLASH_PATTERN = /\/$/;
+
+/** Type guard for AWS SDK errors (have a `name` property) */
+function hasErrorName(error: unknown): error is Error & { name: string } {
+	return error instanceof Error && typeof error.name === "string";
+}
+
+/**
+ * S3-compatible storage implementation
+ */
+export class S3Storage implements Storage {
+	private client: S3Client;
+	private bucket: string;
+	private publicUrl?: string;
+	private endpoint: string;
+
+	constructor(config: S3StorageConfig) {
+		this.bucket = config.bucket;
+		this.publicUrl = config.publicUrl;
+		this.endpoint = config.endpoint;
+
+		this.client = new S3Client({
+			endpoint: config.endpoint,
+			region: config.region || "auto",
+			credentials: {
+				accessKeyId: config.accessKeyId,
+				secretAccessKey: config.secretAccessKey,
+			},
+			// Required for R2 and some S3-compatible services
+			forcePathStyle: true,
+		});
+	}
+
+	async upload(options: {
+		key: string;
+		body: Buffer | Uint8Array | ReadableStream<Uint8Array>;
+		contentType: string;
+	}): Promise<UploadResult> {
+		try {
+			// Convert ReadableStream to Buffer if needed
+			let body: Buffer | Uint8Array;
+			if (options.body instanceof ReadableStream) {
+				const chunks: Uint8Array[] = [];
+				const reader = options.body.getReader();
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					chunks.push(value);
+				}
+				body = Buffer.concat(chunks);
+			} else {
+				body = options.body;
+			}
+
+			await this.client.send(
+				new PutObjectCommand({
+					Bucket: this.bucket,
+					Key: options.key,
+					Body: body,
+					ContentType: options.contentType,
+				}),
+			);
+
+			return {
+				key: options.key,
+				url: this.getPublicUrl(options.key),
+				size: body.length,
+			};
+		} catch (error) {
+			throw new EmDashStorageError(`Failed to upload file: ${options.key}`, "UPLOAD_FAILED", error);
+		}
+	}
+
+	async download(key: string): Promise<DownloadResult> {
+		try {
+			const response = await this.client.send(
+				new GetObjectCommand({
+					Bucket: this.bucket,
+					Key: key,
+				}),
+			);
+
+			if (!response.Body) {
+				throw new EmDashStorageError(`File not found: ${key}`, "NOT_FOUND");
+			}
+
+			// Convert SDK stream to web ReadableStream
+			const body = response.Body.transformToWebStream();
+
+			return {
+				body,
+				contentType: response.ContentType || "application/octet-stream",
+				size: response.ContentLength || 0,
+			};
+		} catch (error) {
+			if (
+				error instanceof EmDashStorageError ||
+				(hasErrorName(error) && error.name === "NoSuchKey")
+			) {
+				throw new EmDashStorageError(`File not found: ${key}`, "NOT_FOUND", error);
+			}
+			throw new EmDashStorageError(`Failed to download file: ${key}`, "DOWNLOAD_FAILED", error);
+		}
+	}
+
+	async delete(key: string): Promise<void> {
+		try {
+			await this.client.send(
+				new DeleteObjectCommand({
+					Bucket: this.bucket,
+					Key: key,
+				}),
+			);
+		} catch (error) {
+			// S3 delete is idempotent, so we ignore "not found" errors
+			if (!hasErrorName(error) || error.name !== "NoSuchKey") {
+				throw new EmDashStorageError(`Failed to delete file: ${key}`, "DELETE_FAILED", error);
+			}
+		}
+	}
+
+	async exists(key: string): Promise<boolean> {
+		try {
+			await this.client.send(
+				new HeadObjectCommand({
+					Bucket: this.bucket,
+					Key: key,
+				}),
+			);
+			return true;
+		} catch (error) {
+			if (hasErrorName(error) && error.name === "NotFound") {
+				return false;
+			}
+			throw new EmDashStorageError(`Failed to check file existence: ${key}`, "HEAD_FAILED", error);
+		}
+	}
+
+	async list(options: ListOptions = {}): Promise<ListResult> {
+		try {
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- S3 client.send returns generic output; narrowing to ListObjectsV2Response
+			const response = (await this.client.send(
+				new ListObjectsV2Command({
+					Bucket: this.bucket,
+					Prefix: options.prefix,
+					MaxKeys: options.limit,
+					ContinuationToken: options.cursor,
+				}),
+			)) as ListObjectsV2Response;
+
+			return {
+				files: (response.Contents || []).map(
+					(item: { Key?: string; Size?: number; LastModified?: Date; ETag?: string }) => ({
+						key: item.Key!,
+						size: item.Size || 0,
+						lastModified: item.LastModified || new Date(),
+						etag: item.ETag,
+					}),
+				),
+				nextCursor: response.NextContinuationToken,
+			};
+		} catch (error) {
+			throw new EmDashStorageError("Failed to list files", "LIST_FAILED", error);
+		}
+	}
+
+	async getSignedUploadUrl(options: SignedUploadOptions): Promise<SignedUploadUrl> {
+		try {
+			const expiresIn = options.expiresIn || 3600; // 1 hour default
+
+			const command = new PutObjectCommand({
+				Bucket: this.bucket,
+				Key: options.key,
+				ContentType: options.contentType,
+				ContentLength: options.size,
+			});
+
+			const url = await getSignedUrl(this.client, command, { expiresIn });
+
+			const expiresAt = new Date(Date.now() + expiresIn * 1000).toISOString();
+
+			return {
+				url,
+				method: "PUT",
+				headers: {
+					"Content-Type": options.contentType,
+					...(options.size ? { "Content-Length": String(options.size) } : {}),
+				},
+				expiresAt,
+			};
+		} catch (error) {
+			throw new EmDashStorageError(
+				`Failed to generate signed URL for: ${options.key}`,
+				"SIGNED_URL_FAILED",
+				error,
+			);
+		}
+	}
+
+	getPublicUrl(key: string): string {
+		if (this.publicUrl) {
+			return `${this.publicUrl.replace(TRAILING_SLASH_PATTERN, "")}/${key}`;
+		}
+		// Default to endpoint + bucket + key
+		return `${this.endpoint.replace(TRAILING_SLASH_PATTERN, "")}/${this.bucket}/${key}`;
+	}
+}
+
+/**
+ * Create S3 storage adapter
+ * This is the factory function called at runtime
+ */
+export function createStorage(config: Record<string, unknown>): Storage {
+	const { endpoint, bucket, accessKeyId, secretAccessKey, region, publicUrl } = config;
+	if (
+		typeof endpoint !== "string" ||
+		typeof bucket !== "string" ||
+		typeof accessKeyId !== "string" ||
+		typeof secretAccessKey !== "string"
+	) {
+		throw new Error(
+			"S3Storage requires 'endpoint', 'bucket', 'accessKeyId', and 'secretAccessKey' string config values",
+		);
+	}
+	return new S3Storage({
+		endpoint,
+		bucket,
+		accessKeyId,
+		secretAccessKey,
+		region: typeof region === "string" ? region : undefined,
+		publicUrl: typeof publicUrl === "string" ? publicUrl : undefined,
+	});
+}

package/src/storage/types.ts

@@ -0,0 +1,204 @@
+/**
+ * Storage Layer Types
+ *
+ * Defines the interface for S3-compatible storage backends.
+ * Works with R2, AWS S3, Minio, and other S3-compatible services.
+ */
+
+/**
+ * Storage configuration for S3-compatible backends
+ */
+export interface S3StorageConfig {
+	/** S3 endpoint URL (e.g., "https://xxx.r2.cloudflarestorage.com") */
+	endpoint: string;
+	/** Bucket name */
+	bucket: string;
+	/** AWS access key ID */
+	accessKeyId: string;
+	/** AWS secret access key */
+	secretAccessKey: string;
+	/** Optional region (defaults to "auto" for R2) */
+	region?: string;
+	/** Optional public URL prefix for generated URLs (e.g., CDN URL) */
+	publicUrl?: string;
+}
+
+/**
+ * Local filesystem storage for development
+ */
+export interface LocalStorageConfig {
+	/** Directory path for storing files */
+	directory: string;
+	/** Base URL for serving files */
+	baseUrl: string;
+}
+
+/**
+ * Storage adapter descriptor (serializable config)
+ */
+export interface StorageDescriptor {
+	/** Module path exporting createStorage function */
+	entrypoint: string;
+	/** Serializable config passed to createStorage at runtime */
+	config: Record<string, unknown>;
+}
+
+/**
+ * Factory function signature for storage adapters
+ *
+ * Each adapter accesses its own bindings directly:
+ * - R2: imports from cloudflare:workers
+ * - S3: uses credentials from config
+ * - Local: uses filesystem path from config
+ */
+export type CreateStorageFn = (config: Record<string, unknown>) => Storage;
+
+/**
+ * Upload result
+ */
+export interface UploadResult {
+	/** Storage key (path within bucket) */
+	key: string;
+	/** Public URL to access the file */
+	url: string;
+	/** File size in bytes */
+	size: number;
+}
+
+/**
+ * Download result
+ */
+export interface DownloadResult {
+	/** File content as readable stream */
+	body: ReadableStream<Uint8Array>;
+	/** MIME type */
+	contentType: string;
+	/** File size in bytes */
+	size: number;
+}
+
+/**
+ * Signed URL for direct upload
+ */
+export interface SignedUploadUrl {
+	/** Signed URL for PUT request */
+	url: string;
+	/** HTTP method (always PUT) */
+	method: "PUT";
+	/** Headers to include in the upload request */
+	headers: Record<string, string>;
+	/** URL expiration time (ISO string) */
+	expiresAt: string;
+}
+
+/**
+ * Options for generating signed upload URL
+ */
+export interface SignedUploadOptions {
+	/** Storage key (path within bucket) */
+	key: string;
+	/** MIME type of the file */
+	contentType: string;
+	/** File size in bytes (for content-length validation) */
+	size?: number;
+	/** URL expiration in seconds (default: 3600) */
+	expiresIn?: number;
+}
+
+/**
+ * File listing result
+ */
+export interface ListResult {
+	/** List of files */
+	files: FileInfo[];
+	/** Cursor for next page (if more results) */
+	nextCursor?: string;
+}
+
+/**
+ * File info from listing
+ */
+export interface FileInfo {
+	/** Storage key */
+	key: string;
+	/** File size in bytes */
+	size: number;
+	/** Last modified date */
+	lastModified: Date;
+	/** ETag (content hash) */
+	etag?: string;
+}
+
+/**
+ * Options for listing files
+ */
+export interface ListOptions {
+	/** Filter by key prefix */
+	prefix?: string;
+	/** Maximum results per page */
+	limit?: number;
+	/** Cursor from previous list call */
+	cursor?: string;
+}
+
+/**
+ * Storage interface
+ *
+ * All storage backends must implement this interface.
+ */
+export interface Storage {
+	/**
+	 * Upload a file to storage
+	 */
+	upload(options: {
+		key: string;
+		body: Buffer | Uint8Array | ReadableStream<Uint8Array>;
+		contentType: string;
+	}): Promise<UploadResult>;
+
+	/**
+	 * Download a file from storage
+	 */
+	download(key: string): Promise<DownloadResult>;
+
+	/**
+	 * Delete a file from storage
+	 * Idempotent - does not throw if file doesn't exist
+	 */
+	delete(key: string): Promise<void>;
+
+	/**
+	 * Check if a file exists
+	 */
+	exists(key: string): Promise<boolean>;
+
+	/**
+	 * List files in storage
+	 */
+	list(options?: ListOptions): Promise<ListResult>;
+
+	/**
+	 * Generate a signed URL for direct upload
+	 * Client uploads directly to storage, bypassing the server
+	 */
+	getSignedUploadUrl(options: SignedUploadOptions): Promise<SignedUploadUrl>;
+
+	/**
+	 * Get public URL for a file
+	 */
+	getPublicUrl(key: string): string;
+}
+
+/**
+ * Storage error with additional context
+ */
+export class EmDashStorageError extends Error {
+	constructor(
+		message: string,
+		public code: string,
+		public override cause?: unknown,
+	) {
+		super(message);
+		this.name = "EmDashStorageError";
+	}
+}