@syncular/server-storage-filesystem 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Filesystem blob storage adapter.
+ *
+ * Stores blobs as files on disk with 2-level hash-based subdirectories.
+ * Uploads/downloads go through the server's blob routes using signed tokens
+ * (same pattern as the database adapter).
+ */
+import type { BlobStorageAdapter } from '@syncular/core';
+export interface BlobTokenSigner {
+    sign(payload: {
+        hash: string;
+        action: 'upload' | 'download';
+        expiresAt: number;
+    }, expiresInSeconds: number): Promise<string>;
+}
+export interface FilesystemBlobStorageAdapterOptions {
+    /** Directory root for blob files */
+    basePath: string;
+    /** Server base URL for upload/download routes (e.g. "/api/sync") */
+    baseUrl: string;
+    /** Token signer for authorization */
+    tokenSigner: BlobTokenSigner;
+}
+/**
+ * Create a filesystem blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createFilesystemBlobStorageAdapter({
+ *   basePath: '/data/blobs',
+ *   baseUrl: 'https://api.example.com/api/sync',
+ *   tokenSigner: createHmacTokenSigner(process.env.BLOB_SECRET!),
+ * });
+ * ```
+ */
+export declare function createFilesystemBlobStorageAdapter(options: FilesystemBlobStorageAdapterOptions): BlobStorageAdapter;
+//# 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;;;;;;GAMG;AAYH,OAAO,KAAK,EAIV,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,eAAe;IAC9B,IAAI,CACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;QAC9B,SAAS,EAAE,MAAM,CAAC;KACnB,EACD,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAOD,MAAM,WAAW,mCAAmC;IAClD,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,WAAW,EAAE,eAAe,CAAC;CAC9B;AAeD;;;;;;;;;;;GAWG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,kBAAkB,CA8HpB"}

package/dist/index.js

@@ -0,0 +1,145 @@
+/**
+ * Filesystem blob storage adapter.
+ *
+ * Stores blobs as files on disk with 2-level hash-based subdirectories.
+ * Uploads/downloads go through the server's blob routes using signed tokens
+ * (same pattern as the database adapter).
+ */
+import { mkdir, open, readFile, rename, stat, unlink, writeFile, } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+function hasErrnoCode(error, code) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    return error.code === code;
+}
+/**
+ * Resolve hash to a 2-level subdirectory path:
+ * `{basePath}/{hex[0..2]}/{hex[2..4]}/{hex}`
+ */
+function hashToFilePath(basePath, hash) {
+    const hex = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+    return join(basePath, hex.slice(0, 2), hex.slice(2, 4), hex);
+}
+function tmpPath(filePath) {
+    return `${filePath}.${Date.now()}.tmp`;
+}
+/**
+ * Create a filesystem blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createFilesystemBlobStorageAdapter({
+ *   basePath: '/data/blobs',
+ *   baseUrl: 'https://api.example.com/api/sync',
+ *   tokenSigner: createHmacTokenSigner(process.env.BLOB_SECRET!),
+ * });
+ * ```
+ */
+export function createFilesystemBlobStorageAdapter(options) {
+    const { basePath, tokenSigner } = options;
+    const normalizedBaseUrl = options.baseUrl.replace(/\/$/, '');
+    return {
+        name: 'filesystem',
+        async signUpload(opts) {
+            const expiresAt = Date.now() + opts.expiresIn * 1000;
+            const token = await tokenSigner.sign({ hash: opts.hash, action: 'upload', expiresAt }, opts.expiresIn);
+            const url = `${normalizedBaseUrl}/blobs/${encodeURIComponent(opts.hash)}/upload?token=${encodeURIComponent(token)}`;
+            return {
+                url,
+                method: 'PUT',
+                headers: {
+                    'Content-Type': opts.mimeType,
+                    'Content-Length': String(opts.size),
+                },
+            };
+        },
+        async signDownload(opts) {
+            const expiresAt = Date.now() + opts.expiresIn * 1000;
+            const token = await tokenSigner.sign({ hash: opts.hash, action: 'download', expiresAt }, opts.expiresIn);
+            return `${normalizedBaseUrl}/blobs/${encodeURIComponent(opts.hash)}/download?token=${encodeURIComponent(token)}`;
+        },
+        async exists(hash) {
+            try {
+                await stat(hashToFilePath(basePath, hash));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async delete(hash) {
+            try {
+                await unlink(hashToFilePath(basePath, hash));
+            }
+            catch (err) {
+                if (!hasErrnoCode(err, 'ENOENT'))
+                    throw err;
+            }
+        },
+        async getMetadata(hash) {
+            try {
+                const fileStats = await stat(hashToFilePath(basePath, hash));
+                return { size: fileStats.size };
+            }
+            catch {
+                return null;
+            }
+        },
+        async put(hash, data) {
+            const filePath = hashToFilePath(basePath, hash);
+            const tmp = tmpPath(filePath);
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(tmp, data);
+            await rename(tmp, filePath);
+        },
+        async putStream(hash, stream) {
+            const filePath = hashToFilePath(basePath, hash);
+            const tmp = tmpPath(filePath);
+            await mkdir(dirname(filePath), { recursive: true });
+            const fh = await open(tmp, 'w');
+            try {
+                const reader = stream.getReader();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    await fh.write(value);
+                }
+            }
+            finally {
+                await fh.close();
+            }
+            await rename(tmp, filePath);
+        },
+        async get(hash) {
+            try {
+                const data = await readFile(hashToFilePath(basePath, hash));
+                return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+            }
+            catch (err) {
+                if (hasErrnoCode(err, 'ENOENT'))
+                    return null;
+                throw err;
+            }
+        },
+        async getStream(hash) {
+            let data;
+            try {
+                data = await readFile(hashToFilePath(basePath, hash));
+            }
+            catch (err) {
+                if (hasErrnoCode(err, 'ENOENT'))
+                    return null;
+                throw err;
+            }
+            const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+            return new ReadableStream({
+                start(controller) {
+                    controller.enqueue(bytes);
+                    controller.close();
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@syncular/server-storage-filesystem",
+  "version": "0.0.0",
+  "description": "Filesystem blob storage adapter for Syncular server",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/server-storage-filesystem"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "blob",
+    "storage",
+    "filesystem"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test --pass-with-no-tests",
+    "tsgo": "tsgo --noEmit",
+    "build": "tsgo",
+    "release": "bunx syncular-publish"
+  },
+  "dependencies": {
+    "@syncular/core": "0.0.0"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0",
+    "@syncular/server": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { BlobStorageAdapter } from '@syncular/core';
+import { createHmacTokenSigner } from '@syncular/server';
+import { createFilesystemBlobStorageAdapter } from './index';
+
+let basePath: string;
+let adapter: BlobStorageAdapter;
+
+beforeEach(async () => {
+  basePath = await mkdtemp(join(tmpdir(), 'syncular-blob-test-'));
+  adapter = createFilesystemBlobStorageAdapter({
+    basePath,
+    baseUrl: 'https://example.com/api/sync',
+    tokenSigner: createHmacTokenSigner('test-secret'),
+  });
+});
+
+afterEach(async () => {
+  await rm(basePath, { recursive: true, force: true });
+});
+
+const testHash =
+  'sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+const testData = new TextEncoder().encode('hello world');
+
+describe('createFilesystemBlobStorageAdapter', () => {
+  test('put + get round-trip', async () => {
+    await adapter.put!(testHash, testData);
+    const result = await adapter.get!(testHash);
+    expect(result).toEqual(testData);
+  });
+
+  test('putStream + getStream round-trip', async () => {
+    const inputStream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(testData);
+        controller.close();
+      },
+    });
+
+    await adapter.putStream!(testHash, inputStream);
+
+    const outputStream = await adapter.getStream!(testHash);
+    expect(outputStream).not.toBeNull();
+
+    const reader = outputStream!.getReader();
+    const chunks: Uint8Array[] = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    const result = new Uint8Array(chunks.reduce((acc, c) => acc + c.length, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    expect(result).toEqual(testData);
+  });
+
+  test('get returns null for missing blob', async () => {
+    const result = await adapter.get!(testHash);
+    expect(result).toBeNull();
+  });
+
+  test('getStream returns null for missing blob', async () => {
+    const result = await adapter.getStream!(testHash);
+    expect(result).toBeNull();
+  });
+
+  test('exists returns true after put', async () => {
+    expect(await adapter.exists(testHash)).toBe(false);
+    await adapter.put!(testHash, testData);
+    expect(await adapter.exists(testHash)).toBe(true);
+  });
+
+  test('delete removes the blob', async () => {
+    await adapter.put!(testHash, testData);
+    expect(await adapter.exists(testHash)).toBe(true);
+    await adapter.delete(testHash);
+    expect(await adapter.exists(testHash)).toBe(false);
+  });
+
+  test('delete is idempotent for missing blob', async () => {
+    await adapter.delete(testHash);
+  });
+
+  test('getMetadata returns size', async () => {
+    await adapter.put!(testHash, testData);
+    const meta = await adapter.getMetadata!(testHash);
+    expect(meta).toEqual({ size: testData.length });
+  });
+
+  test('getMetadata returns null for missing blob', async () => {
+    const meta = await adapter.getMetadata!(testHash);
+    expect(meta).toBeNull();
+  });
+
+  test('creates hash-based subdirectories', async () => {
+    await adapter.put!(testHash, testData);
+    // hex = abcdef..., so subdirs should be "ab/cd"
+    const firstLevel = await readdir(basePath);
+    expect(firstLevel).toContain('ab');
+    const secondLevel = await readdir(join(basePath, 'ab'));
+    expect(secondLevel).toContain('cd');
+  });
+
+  test('signUpload returns a token URL', async () => {
+    const result = await adapter.signUpload({
+      hash: testHash,
+      size: 100,
+      mimeType: 'application/octet-stream',
+      expiresIn: 60,
+    });
+    expect(result.url).toContain('/blobs/');
+    expect(result.url).toContain('token=');
+    expect(result.method).toBe('PUT');
+  });
+
+  test('signDownload returns a token URL', async () => {
+    const url = await adapter.signDownload({
+      hash: testHash,
+      expiresIn: 60,
+    });
+    expect(url).toContain('/blobs/');
+    expect(url).toContain('token=');
+  });
+});

package/src/index.ts

@@ -0,0 +1,204 @@
+/**
+ * Filesystem blob storage adapter.
+ *
+ * Stores blobs as files on disk with 2-level hash-based subdirectories.
+ * Uploads/downloads go through the server's blob routes using signed tokens
+ * (same pattern as the database adapter).
+ */
+
+import {
+  mkdir,
+  open,
+  readFile,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type {
+  BlobSignDownloadOptions,
+  BlobSignedUpload,
+  BlobSignUploadOptions,
+  BlobStorageAdapter,
+} from '@syncular/core';
+
+export interface BlobTokenSigner {
+  sign(
+    payload: {
+      hash: string;
+      action: 'upload' | 'download';
+      expiresAt: number;
+    },
+    expiresInSeconds: number
+  ): Promise<string>;
+}
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  return (error as { code?: unknown }).code === code;
+}
+
+export interface FilesystemBlobStorageAdapterOptions {
+  /** Directory root for blob files */
+  basePath: string;
+  /** Server base URL for upload/download routes (e.g. "/api/sync") */
+  baseUrl: string;
+  /** Token signer for authorization */
+  tokenSigner: BlobTokenSigner;
+}
+
+/**
+ * Resolve hash to a 2-level subdirectory path:
+ * `{basePath}/{hex[0..2]}/{hex[2..4]}/{hex}`
+ */
+function hashToFilePath(basePath: string, hash: string): string {
+  const hex = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+  return join(basePath, hex.slice(0, 2), hex.slice(2, 4), hex);
+}
+
+function tmpPath(filePath: string): string {
+  return `${filePath}.${Date.now()}.tmp`;
+}
+
+/**
+ * Create a filesystem blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createFilesystemBlobStorageAdapter({
+ *   basePath: '/data/blobs',
+ *   baseUrl: 'https://api.example.com/api/sync',
+ *   tokenSigner: createHmacTokenSigner(process.env.BLOB_SECRET!),
+ * });
+ * ```
+ */
+export function createFilesystemBlobStorageAdapter(
+  options: FilesystemBlobStorageAdapterOptions
+): BlobStorageAdapter {
+  const { basePath, tokenSigner } = options;
+  const normalizedBaseUrl = options.baseUrl.replace(/\/$/, '');
+
+  return {
+    name: 'filesystem',
+
+    async signUpload(opts: BlobSignUploadOptions): Promise<BlobSignedUpload> {
+      const expiresAt = Date.now() + opts.expiresIn * 1000;
+      const token = await tokenSigner.sign(
+        { hash: opts.hash, action: 'upload', expiresAt },
+        opts.expiresIn
+      );
+
+      const url = `${normalizedBaseUrl}/blobs/${encodeURIComponent(opts.hash)}/upload?token=${encodeURIComponent(token)}`;
+
+      return {
+        url,
+        method: 'PUT',
+        headers: {
+          'Content-Type': opts.mimeType,
+          'Content-Length': String(opts.size),
+        },
+      };
+    },
+
+    async signDownload(opts: BlobSignDownloadOptions): Promise<string> {
+      const expiresAt = Date.now() + opts.expiresIn * 1000;
+      const token = await tokenSigner.sign(
+        { hash: opts.hash, action: 'download', expiresAt },
+        opts.expiresIn
+      );
+
+      return `${normalizedBaseUrl}/blobs/${encodeURIComponent(opts.hash)}/download?token=${encodeURIComponent(token)}`;
+    },
+
+    async exists(hash: string): Promise<boolean> {
+      try {
+        await stat(hashToFilePath(basePath, hash));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    async delete(hash: string): Promise<void> {
+      try {
+        await unlink(hashToFilePath(basePath, hash));
+      } catch (err) {
+        if (!hasErrnoCode(err, 'ENOENT')) throw err;
+      }
+    },
+
+    async getMetadata(
+      hash: string
+    ): Promise<{ size: number; mimeType?: string } | null> {
+      try {
+        const fileStats = await stat(hashToFilePath(basePath, hash));
+        return { size: fileStats.size };
+      } catch {
+        return null;
+      }
+    },
+
+    async put(hash: string, data: Uint8Array): Promise<void> {
+      const filePath = hashToFilePath(basePath, hash);
+      const tmp = tmpPath(filePath);
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(tmp, data);
+      await rename(tmp, filePath);
+    },
+
+    async putStream(
+      hash: string,
+      stream: ReadableStream<Uint8Array>
+    ): Promise<void> {
+      const filePath = hashToFilePath(basePath, hash);
+      const tmp = tmpPath(filePath);
+      await mkdir(dirname(filePath), { recursive: true });
+
+      const fh = await open(tmp, 'w');
+      try {
+        const reader = stream.getReader();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          await fh.write(value);
+        }
+      } finally {
+        await fh.close();
+      }
+
+      await rename(tmp, filePath);
+    },
+
+    async get(hash: string): Promise<Uint8Array | null> {
+      try {
+        const data = await readFile(hashToFilePath(basePath, hash));
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      } catch (err) {
+        if (hasErrnoCode(err, 'ENOENT')) return null;
+        throw err;
+      }
+    },
+
+    async getStream(hash: string): Promise<ReadableStream<Uint8Array> | null> {
+      let data: Uint8Array;
+      try {
+        data = await readFile(hashToFilePath(basePath, hash));
+      } catch (err) {
+        if (hasErrnoCode(err, 'ENOENT')) return null;
+        throw err;
+      }
+      const bytes = new Uint8Array(
+        data.buffer,
+        data.byteOffset,
+        data.byteLength
+      );
+      return new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      });
+    },
+  };
+}