@contract-kit/provider-storage-local 1.0.0

package/src/index.ts

@@ -0,0 +1,721 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import {
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat as statFile,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createProviderDevtools } from "@contract-kit/devtools";
+import {
+  createProvider,
+  type StorageBody,
+  type StorageMetadata,
+  type StorageObject,
+  type StorageObjectBody,
+  type StoragePort,
+  type StorageVisibility,
+} from "@contract-kit/ports";
+import { z } from "zod";
+
+export type {
+  StorageBody,
+  StorageMetadata,
+  StorageObject,
+  StorageObjectBody,
+  StoragePort,
+  StorageVisibility,
+} from "@contract-kit/ports";
+
+const metadataRootName = ".ck-storage-meta";
+
+const LocalStorageConfigSchema = z.object({
+  ROOT: z.string().min(1).default("storage/app"),
+  PUBLIC_BASE_URL: z.string().min(1).optional(),
+});
+
+export type LocalStorageConfig = z.infer<typeof LocalStorageConfigSchema>;
+
+export interface LocalStorageOptions {
+  /**
+   * Directory where storage objects are written.
+   */
+  root: string;
+
+  /**
+   * Base URL used by `publicUrl(...)` for public objects.
+   */
+  publicBaseUrl?: string;
+
+  /**
+   * Optional devtools target. The provider passes existing app ports here
+   * automatically; direct factory users can pass a devtools port explicitly.
+   */
+  devtools?: unknown;
+}
+
+export interface LocalStorageProviderOptions {
+  /**
+   * Provider name. Defaults to "storage-local".
+   */
+  name?: string;
+
+  /**
+   * Default root used when STORAGE_ROOT is not set.
+   */
+  root?: string;
+
+  /**
+   * Default public base URL used when STORAGE_PUBLIC_BASE_URL is not set.
+   */
+  publicBaseUrl?: string;
+}
+
+type LocalStorageMetadataFile = {
+  contentType?: string;
+  cacheControl?: string;
+  metadata: StorageMetadata;
+  visibility: StorageVisibility;
+  lastModified: string;
+};
+
+type StorageEvent = {
+  operation: string;
+  key: string;
+  summary: string;
+  details?: Record<string, unknown>;
+};
+
+type NodeWebReadableStream = Parameters<typeof Readable.fromWeb>[0];
+
+function copyBytes(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes);
+}
+
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 31 || code === 127) return true;
+  }
+
+  return false;
+}
+
+async function writeStorageBody(
+  filePath: string,
+  body: StorageBody,
+): Promise<void> {
+  if (typeof body === "string") {
+    await writeFile(filePath, body);
+    return;
+  }
+
+  if (body instanceof Uint8Array) {
+    await writeFile(filePath, copyBytes(body));
+    return;
+  }
+
+  if (body instanceof ArrayBuffer) {
+    await writeFile(filePath, new Uint8Array(body.slice(0)));
+    return;
+  }
+
+  if (body instanceof Blob) {
+    await pipeline(
+      Readable.fromWeb(body.stream() as unknown as NodeWebReadableStream),
+      createWriteStream(filePath),
+    );
+    return;
+  }
+
+  await pipeline(
+    Readable.fromWeb(body as unknown as NodeWebReadableStream),
+    createWriteStream(filePath),
+  );
+}
+
+function validateStorageKey(key: string): void {
+  if (key.length === 0) {
+    throw new Error("Storage key must not be empty.");
+  }
+
+  if (hasControlCharacter(key)) {
+    throw new Error("Storage key must not include control characters.");
+  }
+
+  if (key.startsWith("/")) {
+    throw new Error("Storage key must not start with '/'.");
+  }
+
+  if (key.endsWith("/")) {
+    throw new Error("Storage key must not end with '/'.");
+  }
+
+  if (key.includes("\\")) {
+    throw new Error("Storage key must use '/' separators, not '\\'.");
+  }
+
+  const segments = key.split("/");
+
+  if (segments.some((segment) => segment === "")) {
+    throw new Error("Storage key must not include empty path segments.");
+  }
+
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    throw new Error("Storage key must not include '.' or '..' segments.");
+  }
+
+  if (segments.some((segment) => segment === metadataRootName)) {
+    throw new Error(
+      `Local storage key must not use reserved segment '${metadataRootName}'.`,
+    );
+  }
+}
+
+function joinPublicUrl(baseUrl: string, key: string): string {
+  const base = baseUrl.replace(/\/+$/, "");
+  const encodedKey = key
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+
+  return `${base}/${encodedKey}`;
+}
+
+function assertInsideRoot(root: string, filePath: string): void {
+  const pathFromRoot = relative(root, filePath);
+
+  if (
+    pathFromRoot === "" ||
+    pathFromRoot.startsWith("..") ||
+    isAbsolute(pathFromRoot)
+  ) {
+    throw new Error("Storage key resolved outside the storage root.");
+  }
+}
+
+function objectPath(root: string, key: string): string {
+  validateStorageKey(key);
+  const filePath = resolve(root, ...key.split("/"));
+  assertInsideRoot(root, filePath);
+  return filePath;
+}
+
+function metadataPath(root: string, key: string): string {
+  validateStorageKey(key);
+  const filePath = `${resolve(root, metadataRootName, ...key.split("/"))}.json`;
+  assertInsideRoot(root, filePath);
+  return filePath;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    const fileStat = await statFile(filePath);
+    return fileStat.isFile();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function readMetadata(
+  root: string,
+  key: string,
+): Promise<LocalStorageMetadataFile | null> {
+  const filePath = metadataPath(root, key);
+
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw) as LocalStorageMetadataFile;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function writeMetadata(
+  filePath: string,
+  metadata: LocalStorageMetadataFile,
+): Promise<void> {
+  await writeFile(filePath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+}
+
+function temporaryPath(filePath: string, purpose: "tmp" | "backup"): string {
+  return `${filePath}.${purpose}.${randomUUID()}`;
+}
+
+async function renameFileIfExists(from: string, to: string): Promise<boolean> {
+  try {
+    const current = await statFile(from);
+    if (!current.isFile()) {
+      throw new Error(`Storage path is not a file: ${from}`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+
+  await rename(from, to);
+  return true;
+}
+
+async function cleanupFile(filePath: string): Promise<void> {
+  await rm(filePath, { force: true });
+}
+
+async function restoreBackup(
+  backupPath: string,
+  filePath: string,
+  backedUp: boolean,
+): Promise<void> {
+  if (!backedUp) return;
+  await rm(filePath, { force: true });
+  await rename(backupPath, filePath);
+}
+
+async function writeObjectAndMetadata(
+  filePath: string,
+  metaPath: string,
+  body: StorageBody,
+  metadata: LocalStorageMetadataFile,
+): Promise<number> {
+  const tempFilePath = temporaryPath(filePath, "tmp");
+  const tempMetaPath = temporaryPath(metaPath, "tmp");
+  const backupFilePath = temporaryPath(filePath, "backup");
+  const backupMetaPath = temporaryPath(metaPath, "backup");
+  let objectBackedUp = false;
+  let metadataBackedUp = false;
+  let objectCommitted = false;
+  let metadataCommitted = false;
+
+  try {
+    await Promise.all([
+      mkdir(dirname(filePath), { recursive: true }),
+      mkdir(dirname(metaPath), { recursive: true }),
+    ]);
+
+    await writeStorageBody(tempFilePath, body);
+    const objectStat = await statFile(tempFilePath);
+    if (!objectStat.isFile()) {
+      throw new Error("Storage body did not produce a file.");
+    }
+    await writeMetadata(tempMetaPath, metadata);
+
+    objectBackedUp = await renameFileIfExists(filePath, backupFilePath);
+    metadataBackedUp = await renameFileIfExists(metaPath, backupMetaPath);
+
+    await rename(tempFilePath, filePath);
+    objectCommitted = true;
+    await rename(tempMetaPath, metaPath);
+    metadataCommitted = true;
+
+    await Promise.all([
+      cleanupFile(backupFilePath),
+      cleanupFile(backupMetaPath),
+    ]);
+
+    return objectStat.size;
+  } catch (error) {
+    await Promise.allSettled([
+      cleanupFile(tempFilePath),
+      cleanupFile(tempMetaPath),
+      objectCommitted ? cleanupFile(filePath) : Promise.resolve(),
+      metadataCommitted ? cleanupFile(metaPath) : Promise.resolve(),
+    ]);
+    await Promise.allSettled([
+      restoreBackup(backupFilePath, filePath, objectBackedUp),
+      restoreBackup(backupMetaPath, metaPath, metadataBackedUp),
+    ]);
+    throw error;
+  }
+}
+
+function metadataToObject(
+  key: string,
+  size: number,
+  fallbackLastModified: Date,
+  metadata: LocalStorageMetadataFile | null,
+): StorageObject {
+  return {
+    key,
+    size,
+    ...(metadata?.contentType !== undefined
+      ? { contentType: metadata.contentType }
+      : {}),
+    ...(metadata?.cacheControl !== undefined
+      ? { cacheControl: metadata.cacheControl }
+      : {}),
+    metadata: { ...(metadata?.metadata ?? {}) },
+    visibility: metadata?.visibility ?? "private",
+    lastModified: metadata?.lastModified
+      ? new Date(metadata.lastModified)
+      : fallbackLastModified,
+  };
+}
+
+function createObjectBody(
+  object: StorageObject,
+  filePath: string,
+): StorageObjectBody {
+  let bodyUsed = false;
+
+  function markConsumed(): void {
+    if (bodyUsed) {
+      throw new Error("Storage object body has already been consumed.");
+    }
+
+    bodyUsed = true;
+  }
+
+  return {
+    ...object,
+    get bodyUsed() {
+      return bodyUsed;
+    },
+    stream() {
+      markConsumed();
+      return Readable.toWeb(
+        createReadStream(filePath),
+      ) as unknown as ReadableStream<Uint8Array>;
+    },
+    async bytes() {
+      markConsumed();
+      return copyBytes(await readFile(filePath));
+    },
+    async arrayBuffer() {
+      markConsumed();
+      return bytesToArrayBuffer(await readFile(filePath));
+    },
+    async text() {
+      markConsumed();
+      return readFile(filePath, "utf8");
+    },
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function createLocalStorage(options: LocalStorageOptions): StoragePort {
+  const root = resolve(options.root);
+  const devtools = createProviderDevtools(options.devtools, {
+    providerName: "storage-local",
+    watcher: "storage",
+  });
+
+  const recordStorageEvent = (event: StorageEvent) => {
+    devtools.custom({
+      name: `storage.${event.operation}`,
+      label: `Storage ${event.operation}`,
+      summary: event.summary,
+      details: {
+        operation: event.operation,
+        key: event.key,
+        ...event.details,
+      },
+    });
+  };
+
+  async function statObject(key: string): Promise<StorageObject | null> {
+    const filePath = objectPath(root, key);
+
+    try {
+      const [fileStat, metadata] = await Promise.all([
+        statFile(filePath),
+        readMetadata(root, key),
+      ]);
+
+      if (!fileStat.isFile()) return null;
+
+      return metadataToObject(key, fileStat.size, fileStat.mtime, metadata);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  return {
+    async put(key, body, putOptions) {
+      const startedAt = Date.now();
+
+      try {
+        const filePath = objectPath(root, key);
+        const metaPath = metadataPath(root, key);
+        const lastModified = new Date();
+        const metadata: LocalStorageMetadataFile = {
+          ...(putOptions?.contentType !== undefined
+            ? { contentType: putOptions.contentType }
+            : {}),
+          ...(putOptions?.cacheControl !== undefined
+            ? { cacheControl: putOptions.cacheControl }
+            : {}),
+          metadata: { ...(putOptions?.metadata ?? {}) },
+          visibility: putOptions?.visibility ?? "private",
+          lastModified: lastModified.toISOString(),
+        };
+
+        const size = await writeObjectAndMetadata(
+          filePath,
+          metaPath,
+          body,
+          metadata,
+        );
+
+        const object = metadataToObject(key, size, lastModified, metadata);
+
+        recordStorageEvent({
+          operation: "put",
+          key,
+          summary: "Storage object written",
+          details: {
+            size: object.size,
+            visibility: object.visibility,
+            contentType: object.contentType ?? null,
+            metadataKeys: Object.keys(object.metadata),
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return object;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "put.failed",
+          key,
+          summary: "Storage put failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async get(key) {
+      const startedAt = Date.now();
+
+      try {
+        const object = await statObject(key);
+        const filePath = objectPath(root, key);
+
+        recordStorageEvent({
+          operation: "get",
+          key,
+          summary: object ? "Storage object read" : "Storage object missing",
+          details: {
+            hit: object !== null,
+            size: object?.size ?? null,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        if (!object) return null;
+        return createObjectBody(object, filePath);
+      } catch (error) {
+        recordStorageEvent({
+          operation: "get.failed",
+          key,
+          summary: "Storage get failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async stat(key) {
+      const startedAt = Date.now();
+
+      try {
+        const object = await statObject(key);
+        recordStorageEvent({
+          operation: "stat",
+          key,
+          summary: object ? "Storage object found" : "Storage object missing",
+          details: {
+            hit: object !== null,
+            size: object?.size ?? null,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+        return object;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "stat.failed",
+          key,
+          summary: "Storage stat failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async delete(key) {
+      const startedAt = Date.now();
+
+      try {
+        const filePath = objectPath(root, key);
+        const metaPath = metadataPath(root, key);
+        const existed = await fileExists(filePath);
+
+        await Promise.all([
+          existed ? rm(filePath, { force: true }) : Promise.resolve(),
+          rm(metaPath, { force: true }),
+        ]);
+
+        recordStorageEvent({
+          operation: "delete",
+          key,
+          summary: existed
+            ? "Storage object deleted"
+            : "Storage object missing",
+          details: {
+            deleted: existed,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return existed;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "delete.failed",
+          key,
+          summary: "Storage delete failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async exists(key) {
+      const startedAt = Date.now();
+
+      try {
+        const exists = await fileExists(objectPath(root, key));
+        recordStorageEvent({
+          operation: "exists",
+          key,
+          summary: exists ? "Storage object exists" : "Storage object missing",
+          details: {
+            exists,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+        return exists;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "exists.failed",
+          key,
+          summary: "Storage exists failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async publicUrl(key) {
+      const startedAt = Date.now();
+
+      try {
+        const object = await statObject(key);
+        const url =
+          object?.visibility === "public" && options.publicBaseUrl
+            ? joinPublicUrl(options.publicBaseUrl, key)
+            : null;
+
+        recordStorageEvent({
+          operation: "publicUrl",
+          key,
+          summary: url ? "Storage public URL resolved" : "No public URL",
+          details: {
+            hit: object !== null,
+            visibility: object?.visibility ?? null,
+            hasPublicUrl: url !== null,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return url;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "publicUrl.failed",
+          key,
+          summary: "Storage public URL failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+  };
+}
+
+export interface LocalStorageProviderPorts {
+  storage: StoragePort;
+}
+
+export function createLocalStorageProvider(
+  options: LocalStorageProviderOptions = {},
+) {
+  const ConfigSchema = LocalStorageConfigSchema.extend({
+    ROOT: z
+      .string()
+      .min(1)
+      .default(options.root ?? "storage/app"),
+  });
+
+  return createProvider({
+    name: options.name ?? "storage-local",
+
+    config: {
+      schema: ConfigSchema,
+      envPrefix: "STORAGE_",
+    },
+
+    async setup({ ports, config }) {
+      if (!config) {
+        throw new Error(
+          "[localStorageProvider] Missing storage config. " +
+            "Please set STORAGE_ROOT or use the default storage/app path.",
+        );
+      }
+
+      return {
+        ports: {
+          storage: createLocalStorage({
+            root: config.ROOT,
+            publicBaseUrl: config.PUBLIC_BASE_URL ?? options.publicBaseUrl,
+            devtools: ports,
+          }),
+        } satisfies LocalStorageProviderPorts,
+      };
+    },
+  });
+}
+
+export const localStorageProvider = createLocalStorageProvider();