@beignet/provider-storage-local 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-storage-local
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,94 @@
+# @beignet/provider-storage-local
+
+Local filesystem storage provider for Beignet.
+
+The provider installs the app-facing `ctx.ports.storage` port. Use it for
+local development, tests that need durable files, and small deployments where a
+filesystem-backed object store is enough.
+
+## Install
+
+```bash
+bun add @beignet/provider-storage-local
+```
+
+## Provider setup
+
+```typescript
+import { localStorageProvider } from "@beignet/provider-storage-local";
+import { createServer } from "@beignet/core/server";
+
+const server = await createServer({
+  ports: basePorts,
+  providers: [localStorageProvider],
+  createContext: ({ ports }) => ({ ports }),
+  routes,
+});
+```
+
+Environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `STORAGE_ROOT` | Directory where objects are written. Defaults to `storage/app`. |
+| `STORAGE_PUBLIC_BASE_URL` | Optional base URL returned by `publicUrl(...)` for public objects. |
+
+`STORAGE_PUBLIC_BASE_URL` may be an absolute URL such as
+`https://assets.example.com` or an app-relative path such as `/storage`.
+The provider only returns URLs. If you use an app-relative path in a Next.js
+app, serve public objects with `createStorageRoute`:
+
+```typescript
+// app/storage/[...key]/route.ts
+import { createStorageRoute } from "@beignet/next";
+import { server } from "@/server";
+
+export const { GET, HEAD } = createStorageRoute(server.ports.storage, {
+  basePath: "/storage",
+});
+```
+
+## Direct port factory
+
+```typescript
+import { createLocalStorage } from "@beignet/provider-storage-local";
+
+const storage = createLocalStorage({
+  root: "storage/app",
+  publicBaseUrl: "/storage",
+});
+```
+
+The same `StoragePort` works with local files, memory tests, and cloud object
+stores:
+
+```typescript
+await ctx.ports.storage.put("avatars/user_123.png", avatarBytes, {
+  contentType: "image/png",
+  visibility: "public",
+});
+
+const object = await ctx.ports.storage.get("avatars/user_123.png");
+const url = await ctx.ports.storage.publicUrl("avatars/user_123.png");
+```
+
+## Files on disk
+
+Objects are written below `root` using their storage key. Object metadata is
+stored in a `.beignet-storage-meta` sidecar directory below the same root.
+
+Storage keys must be relative object keys: no empty strings, empty path
+segments, leading or trailing `/`, backslashes, or `.` / `..` path segments.
+The `.beignet-storage-meta` path segment is reserved for the provider's sidecar
+metadata.
+
+## Devtools
+
+When `ctx.ports.devtools` is installed, the provider records storage
+operations under the `storage` watcher. Events include operation name, key,
+duration, object size, visibility, and whether a lookup hit. Object bodies are
+never recorded.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import type { StoragePort } from "@beignet/core/ports";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import { z } from "zod";
+export type { StorageBody, StorageMetadata, StorageObject, StorageObjectBody, StoragePort, StorageVisibility, } from "@beignet/core/ports";
+declare const LocalStorageConfigSchema: z.ZodObject<{
+    ROOT: z.ZodDefault<z.ZodString>;
+    PUBLIC_BASE_URL: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 instrumentation target. The provider passes existing app ports
+     * automatically; direct factory users can pass an instrumentation port.
+     */
+    instrumentation?: ProviderInstrumentationTarget;
+}
+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;
+}
+export declare function createLocalStorage(options: LocalStorageOptions): StoragePort;
+export interface LocalStorageProviderPorts {
+    storage: StoragePort;
+}
+export declare function createLocalStorageProvider(options?: LocalStorageProviderOptions): import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    PUBLIC_BASE_URL: z.ZodOptional<z.ZodString>;
+    ROOT: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, {
+    storage: StoragePort;
+}>;
+export declare const localStorageProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    PUBLIC_BASE_URL: z.ZodOptional<z.ZodString>;
+    ROOT: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, {
+    storage: StoragePort;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAKV,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAI7B,QAAA,MAAM,wBAAwB;;;iBAG5B,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAED,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA8UD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,WAAW,CA4Q5E;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC;;;;;GAoC1C;AAED,eAAO,MAAM,oBAAoB;;;;;EAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,527 @@
+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 { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import { z } from "zod";
+const metadataRootName = ".beignet-storage-meta";
+const LocalStorageConfigSchema = z.object({
+    ROOT: z.string().min(1).default("storage/app"),
+    PUBLIC_BASE_URL: z.string().min(1).optional(),
+});
+function copyBytes(bytes) {
+    return new Uint8Array(bytes);
+}
+function bytesToArrayBuffer(bytes) {
+    const buffer = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buffer).set(bytes);
+    return buffer;
+}
+function hasControlCharacter(value) {
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+async function writeStorageBody(filePath, body) {
+    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()), createWriteStream(filePath));
+        return;
+    }
+    await pipeline(Readable.fromWeb(body), createWriteStream(filePath));
+}
+function validateStorageKey(key) {
+    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, key) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const encodedKey = key
+        .split("/")
+        .map((part) => encodeURIComponent(part))
+        .join("/");
+    return `${base}/${encodedKey}`;
+}
+function assertInsideRoot(root, filePath) {
+    const pathFromRoot = relative(root, filePath);
+    if (pathFromRoot === "" ||
+        pathFromRoot.startsWith("..") ||
+        isAbsolute(pathFromRoot)) {
+        throw new Error("Storage key resolved outside the storage root.");
+    }
+}
+function objectPath(root, key) {
+    validateStorageKey(key);
+    const filePath = resolve(root, ...key.split("/"));
+    assertInsideRoot(root, filePath);
+    return filePath;
+}
+function metadataPath(root, key) {
+    validateStorageKey(key);
+    const filePath = `${resolve(root, metadataRootName, ...key.split("/"))}.json`;
+    assertInsideRoot(root, filePath);
+    return filePath;
+}
+async function fileExists(filePath) {
+    try {
+        const fileStat = await statFile(filePath);
+        return fileStat.isFile();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function readMetadata(root, key) {
+    const filePath = metadataPath(root, key);
+    try {
+        const raw = await readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeMetadata(filePath, metadata) {
+    await writeFile(filePath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+}
+function temporaryPath(filePath, purpose) {
+    return `${filePath}.${purpose}.${randomUUID()}`;
+}
+async function renameFileIfExists(from, to) {
+    try {
+        const current = await statFile(from);
+        if (!current.isFile()) {
+            throw new Error(`Storage path is not a file: ${from}`);
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    await rename(from, to);
+    return true;
+}
+async function cleanupFile(filePath) {
+    await rm(filePath, { force: true });
+}
+async function restoreBackup(backupPath, filePath, backedUp) {
+    if (!backedUp)
+        return;
+    await rm(filePath, { force: true });
+    await rename(backupPath, filePath);
+}
+async function writeObjectAndMetadata(filePath, metaPath, body, metadata) {
+    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, size, fallbackLastModified, metadata) {
+    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, filePath) {
+    let bodyUsed = false;
+    function markConsumed() {
+        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));
+        },
+        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) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createLocalStorage(options) {
+    const root = resolve(options.root);
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "storage-local",
+        watcher: "storage",
+    });
+    const recordStorageEvent = (event) => {
+        instrumentation.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) {
+        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.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 = {
+                    ...(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 function createLocalStorageProvider(options = {}) {
+    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,
+                        instrumentation: ports,
+                    }),
+                },
+            };
+        },
+    });
+}
+export const localStorageProvider = createLocalStorageProvider();
+//# sourceMappingURL=index.js.map