worker-fs-mount 0.1.0

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * worker-fs-mount
+ *
+ * Mount WorkerEntrypoints as virtual filesystems in Cloudflare Workers.
+ *
+ * ## Setup
+ *
+ * Add the following alias to your wrangler.toml:
+ *
+ * ```toml
+ * [alias]
+ * "node:fs/promises" = "worker-fs-mount/fs"
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { withMounts, mount } from 'worker-fs-mount';
+ * import fs from 'node:fs/promises';
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     return withMounts(async () => {
+ *       // Mount a WorkerEntrypoint (scoped to this request)
+ *       mount('/mnt/storage', env.STORAGE_SERVICE);
+ *
+ *       // Use standard fs operations - they're automatically intercepted
+ *       await fs.writeFile('/mnt/storage/file.txt', 'Hello, World!');
+ *       const content = await fs.readFile('/mnt/storage/file.txt', 'utf8');
+ *
+ *       return new Response(content);
+ *     }); // Mounts automatically cleaned up
+ *   }
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Export public API
+export {
+  isInMountContext,
+  isMounted,
+  mount,
+  unmount,
+  withMounts,
+} from './registry.js';
+
+// Export types
+export type { DirEntry, Stat, WorkerFilesystem } from './types.js';

package/src/registry.ts

@@ -0,0 +1,199 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { WorkerFilesystem } from './types.js';
+import { normalizePath } from './utils.js';
+
+/**
+ * Internal mount structure.
+ */
+interface Mount {
+  path: string;
+  stub: WorkerFilesystem;
+}
+
+/**
+ * Result of finding a mount for a path.
+ */
+interface MountMatch {
+  mount: Mount;
+  relativePath: string;
+}
+
+/**
+ * AsyncLocalStorage for request-scoped mounts.
+ * Each request can have its own isolated mount registry.
+ */
+const mountStorage = new AsyncLocalStorage<Map<string, Mount>>();
+
+/**
+ * Global mount registry (fallback for backwards compatibility).
+ * Used when mount() is called outside of withMounts().
+ */
+const globalMounts = new Map<string, Mount>();
+
+/**
+ * Get the current mount registry (request-scoped or global fallback).
+ */
+function getMountRegistry(): Map<string, Mount> {
+  return mountStorage.getStore() ?? globalMounts;
+}
+
+/**
+ * Reserved paths that cannot be mounted over.
+ */
+const RESERVED_PATHS = ['/bundle', '/tmp', '/dev'];
+
+/**
+ * Validate a mount path.
+ * @throws If the path is invalid
+ */
+function validateMountPath(path: string): void {
+  if (!path.startsWith('/')) {
+    throw new Error(`Mount path must be absolute (start with /): ${path}`);
+  }
+
+  // Check reserved paths
+  for (const reserved of RESERVED_PATHS) {
+    if (path === reserved || path.startsWith(`${reserved}/`)) {
+      throw new Error(`Cannot mount over reserved path: ${reserved}`);
+    }
+  }
+}
+
+/**
+ * Run a function with an isolated mount context.
+ * Mounts created within the callback are scoped to that request
+ * and automatically cleaned up when the callback completes.
+ *
+ * @param fn - The function to run with isolated mounts
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * import { withMounts, mount } from 'worker-fs-mount';
+ * import fs from 'node:fs/promises';
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     return withMounts(async () => {
+ *       const id = env.FILESYSTEM.idFromName('user-123');
+ *       mount('/data', env.FILESYSTEM.get(id));
+ *
+ *       const content = await fs.readFile('/data/file.txt', 'utf8');
+ *       return new Response(content);
+ *     });
+ *   }
+ * };
+ * ```
+ */
+export function withMounts<T>(fn: () => T): T {
+  const requestMounts = new Map<string, Mount>();
+  return mountStorage.run(requestMounts, fn);
+}
+
+/**
+ * Mount a WorkerFilesystem at the specified path.
+ *
+ * When called within withMounts(), the mount is scoped to that context.
+ * When called outside withMounts(), uses a global registry (for backwards compatibility).
+ *
+ * @param path - The mount point (must be absolute, starting with /)
+ * @param stub - The WorkerFilesystem implementation to mount
+ *
+ * @example
+ * ```typescript
+ * import { withMounts, mount } from 'worker-fs-mount';
+ *
+ * // Recommended: use withMounts for request isolation
+ * withMounts(() => {
+ *   mount('/mnt/storage', env.STORAGE_SERVICE);
+ *   // ... use fs operations ...
+ * });
+ * ```
+ */
+export function mount(path: string, stub: WorkerFilesystem): void {
+  const mounts = getMountRegistry();
+  const normalized = normalizePath(path);
+
+  validateMountPath(normalized);
+
+  if (mounts.has(normalized)) {
+    throw new Error(`Path already mounted: ${normalized}`);
+  }
+
+  // Check for overlapping mounts
+  for (const existing of mounts.keys()) {
+    if (normalized.startsWith(`${existing}/`)) {
+      throw new Error(`Cannot mount at ${normalized}: parent path ${existing} is already mounted`);
+    }
+    if (existing.startsWith(`${normalized}/`)) {
+      throw new Error(`Cannot mount at ${normalized}: child path ${existing} is already mounted`);
+    }
+  }
+
+  mounts.set(normalized, { path: normalized, stub });
+}
+
+/**
+ * Unmount a filesystem at the specified path.
+ *
+ * @param path - The mount point to unmount
+ * @returns True if a mount was removed, false if nothing was mounted at that path
+ *
+ * @example
+ * ```typescript
+ * import { mount, unmount } from 'worker-fs-mount';
+ *
+ * mount('/mnt/storage', env.STORAGE_SERVICE);
+ * // ... use fs operations ...
+ * unmount('/mnt/storage');
+ * ```
+ */
+export function unmount(path: string): boolean {
+  const mounts = getMountRegistry();
+  const normalized = normalizePath(path);
+  return mounts.delete(normalized);
+}
+
+/**
+ * Find the mount that handles a given path.
+ *
+ * @param path - The path to look up
+ * @returns The mount and relative path within that mount, or null if not mounted
+ */
+export function findMount(path: string): MountMatch | null {
+  const mounts = getMountRegistry();
+  const normalized = normalizePath(path);
+
+  for (const [mountPath, mountData] of mounts) {
+    if (normalized === mountPath) {
+      return { mount: mountData, relativePath: '/' };
+    }
+    if (normalized.startsWith(`${mountPath}/`)) {
+      return {
+        mount: mountData,
+        relativePath: normalized.slice(mountPath.length),
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a path is under any mount.
+ *
+ * @param path - The path to check
+ * @returns True if the path is mounted
+ */
+export function isMounted(path: string): boolean {
+  return findMount(path) !== null;
+}
+
+/**
+ * Check if currently running within a withMounts() context.
+ *
+ * @returns True if in a request-scoped context, false if using global registry
+ */
+export function isInMountContext(): boolean {
+  return mountStorage.getStore() !== undefined;
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Stat information for a file, directory, or symlink.
+ */
+export interface Stat {
+  type: 'file' | 'directory' | 'symlink';
+  size: number;
+  lastModified?: Date;
+  created?: Date;
+  writable?: boolean;
+}
+
+/**
+ * A directory entry returned by readdir.
+ */
+export interface DirEntry {
+  name: string;
+  type: 'file' | 'directory' | 'symlink';
+}
+
+/**
+ * Stream-first filesystem interface that WorkerEntrypoints must implement.
+ *
+ * This is a minimal core interface - operations like readFile, writeFile,
+ * truncate, cp, access, and rename are automatically derived from these
+ * core streaming primitives by worker-fs-mount.
+ */
+export interface WorkerFilesystem {
+  // === Metadata Operations ===
+
+  /**
+   * Get file/directory metadata.
+   * @param path - Path relative to mount point
+   * @param options - Options for the operation
+   * @returns Stat object or null if not found
+   */
+  stat(path: string, options?: { followSymlinks?: boolean }): Promise<Stat | null>;
+
+  // === Streaming Operations ===
+
+  /**
+   * Create a readable stream for a file.
+   * @param path - Path relative to mount point
+   * @param options - Stream options (start/end for partial reads)
+   * @returns Promise resolving to ReadableStream that yields file chunks
+   */
+  createReadStream(
+    path: string,
+    options?: { start?: number; end?: number }
+  ): Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * Create a writable stream for a file.
+   * @param path - Path relative to mount point
+   * @param options - Stream options (start for offset writes, flags for mode)
+   * @returns Promise resolving to WritableStream
+   */
+  createWriteStream(
+    path: string,
+    options?: { start?: number; flags?: 'w' | 'a' | 'r+' }
+  ): Promise<WritableStream<Uint8Array>>;
+
+  // === Directory Operations ===
+
+  /**
+   * Read directory contents.
+   * @param path - Path relative to mount point
+   * @param options - Readdir options
+   * @returns Array of directory entries
+   */
+  readdir(path: string, options?: { recursive?: boolean }): Promise<DirEntry[]>;
+
+  /**
+   * Create a directory.
+   * @param path - Path relative to mount point
+   * @param options - Mkdir options
+   * @returns The path of the first created directory, or undefined
+   */
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<string | undefined>;
+
+  /**
+   * Remove a file or directory.
+   * @param path - Path relative to mount point
+   * @param options - Remove options
+   */
+  rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
+
+  // === Link Operations ===
+
+  /**
+   * Create a symbolic link.
+   * @param linkPath - Path for the new symlink
+   * @param targetPath - Path the symlink points to
+   */
+  symlink?(linkPath: string, targetPath: string): Promise<void>;
+
+  /**
+   * Read the target of a symbolic link.
+   * @param path - Path relative to mount point
+   * @returns The target path
+   */
+  readlink?(path: string): Promise<string>;
+}

package/src/utils.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared utilities for building WorkerFilesystem implementations.
+ */
+
+/**
+ * Error codes used by the filesystem.
+ */
+export type FsErrorCode =
+  | 'ENOENT'
+  | 'EEXIST'
+  | 'EISDIR'
+  | 'ENOTDIR'
+  | 'ENOTEMPTY'
+  | 'EINVAL'
+  | 'ELOOP';
+
+/**
+ * Error messages for each error code.
+ */
+const ERROR_MESSAGES: Record<FsErrorCode, string> = {
+  ENOENT: 'no such file or directory',
+  EEXIST: 'file already exists',
+  EISDIR: 'illegal operation on a directory',
+  ENOTDIR: 'not a directory',
+  ENOTEMPTY: 'directory not empty',
+  EINVAL: 'invalid argument',
+  ELOOP: 'too many symbolic links',
+};
+
+/**
+ * Create a filesystem error with a POSIX-style error code.
+ * @param code - The error code (ENOENT, EEXIST, etc.)
+ * @param path - The path that caused the error
+ * @returns An Error with the formatted message
+ */
+export function createFsError(code: FsErrorCode, path: string): Error {
+  const message = ERROR_MESSAGES[code];
+  return new Error(`${code}: ${message}, '${path}'`);
+}
+
+/**
+ * Normalize a path by collapsing multiple slashes and removing trailing slashes.
+ * @param path - The path to normalize
+ * @returns The normalized path, always starting with /
+ */
+export function normalizePath(path: string): string {
+  if (!path) return '/';
+  // Collapse multiple slashes and resolve . segments
+  let normalized = path.replace(/\/+/g, '/').replace(/\/\.\//g, '/');
+  // Remove trailing slash unless it's the root
+  if (normalized !== '/' && normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+  // Ensure path starts with /
+  if (!normalized.startsWith('/')) {
+    normalized = `/${normalized}`;
+  }
+  return normalized || '/';
+}
+
+/**
+ * Get the parent directory path.
+ * @param path - The path to get the parent of
+ * @returns The parent path, or / for root-level paths
+ */
+export function getParentPath(path: string): string {
+  const normalized = normalizePath(path);
+  const lastSlash = normalized.lastIndexOf('/');
+  if (lastSlash <= 0) return '/';
+  return normalized.slice(0, lastSlash);
+}
+
+/**
+ * Get the base name (file or directory name) from a path.
+ * @param path - The path to get the base name from
+ * @returns The base name
+ */
+export function getBaseName(path: string): string {
+  const normalized = normalizePath(path);
+  const lastSlash = normalized.lastIndexOf('/');
+  return normalized.slice(lastSlash + 1);
+}
+
+/**
+ * Resolve a potentially relative path against a base directory.
+ * @param basePath - The base directory path
+ * @param relativePath - The relative path to resolve
+ * @returns The resolved absolute path
+ */
+export function resolvePath(basePath: string, relativePath: string): string {
+  if (relativePath.startsWith('/')) {
+    return normalizePath(relativePath);
+  }
+  return normalizePath(`${basePath}/${relativePath}`);
+}