@bod.ee/db 0.7.0 → 0.8.0

package/src/server/VFSEngine.ts

@@ -0,0 +1,172 @@
+import { generatePushId } from './StorageEngine.ts';
+import type { BodDB } from './BodDB.ts';
+import { normalizePath } from '../shared/pathUtils.ts';
+import type { FileStat } from '../shared/protocol.ts';
+
+// --- Backend interface ---
+
+export interface VFSBackend {
+  read(fileId: string): Promise<Uint8Array>;
+  write(fileId: string, data: Uint8Array): Promise<void>;
+  delete(fileId: string): Promise<void>;
+  exists(fileId: string): Promise<boolean>;
+}
+
+// --- LocalBackend ---
+
+export class LocalBackend implements VFSBackend {
+  constructor(private storageRoot: string) {}
+
+  private filePath(fileId: string): string {
+    if (/[\/\\]/.test(fileId)) throw new Error(`Invalid fileId: ${fileId}`);
+    return `${this.storageRoot}/${fileId}`;
+  }
+
+  async read(fileId: string): Promise<Uint8Array> {
+    const f = Bun.file(this.filePath(fileId));
+    if (!(await f.exists())) throw new Error(`File not found: ${fileId}`);
+    return new Uint8Array(await f.arrayBuffer());
+  }
+
+  async write(fileId: string, data: Uint8Array): Promise<void> {
+    await Bun.write(this.filePath(fileId), data);
+  }
+
+  async delete(fileId: string): Promise<void> {
+    const { unlink } = require('fs/promises');
+    try { await unlink(this.filePath(fileId)); } catch {}
+  }
+
+  async exists(fileId: string): Promise<boolean> {
+    return Bun.file(this.filePath(fileId)).exists();
+  }
+}
+
+export type { FileStat };
+
+/** Reserved key for directory/file own metadata under its parent path */
+const META_KEY = '__meta';
+
+// --- VFSEngine ---
+
+export class VFSEngineOptions {
+  storageRoot: string = '.data/vfs';
+  metaPrefix: string = '_vfs';
+}
+
+export class VFSEngine {
+  readonly options: VFSEngineOptions;
+  readonly backend: VFSBackend;
+  private db: BodDB;
+
+  constructor(db: BodDB, options?: Partial<VFSEngineOptions>) {
+    this.options = { ...new VFSEngineOptions(), ...options };
+    this.db = db;
+    this.backend = new LocalBackend(this.options.storageRoot);
+    const { mkdirSync } = require('fs');
+    try { mkdirSync(this.options.storageRoot, { recursive: true }); } catch {}
+  }
+
+  private metaPath(virtualPath: string): string {
+    return `${this.options.metaPrefix}/${normalizePath(virtualPath)}/${META_KEY}`;
+  }
+
+  /** Parent container path (for listing children) */
+  private containerPath(virtualPath: string): string {
+    const np = normalizePath(virtualPath);
+    return np ? `${this.options.metaPrefix}/${np}` : this.options.metaPrefix;
+  }
+
+  async write(virtualPath: string, data: Uint8Array, mime?: string): Promise<FileStat> {
+    const vp = normalizePath(virtualPath);
+    const existing = this.db.get(this.metaPath(vp)) as Record<string, unknown> | null;
+    const fileId = (existing?.fileId as string) || generatePushId();
+
+    await this.backend.write(fileId, data);
+
+    const name = vp.split('/').pop()!;
+    const stat: FileStat = {
+      name,
+      path: vp,
+      size: data.byteLength,
+      mime: mime || guessMime(name),
+      mtime: Date.now(),
+      fileId,
+      isDir: false,
+    };
+    this.db.set(this.metaPath(vp), stat);
+    return stat;
+  }
+
+  async read(virtualPath: string): Promise<Uint8Array> {
+    const vp = normalizePath(virtualPath);
+    const meta = this.db.get(this.metaPath(vp)) as Record<string, unknown> | null;
+    if (!meta?.fileId) throw new Error(`File not found: ${vp}`);
+    return this.backend.read(meta.fileId as string);
+  }
+
+  stat(virtualPath: string): FileStat | null {
+    const vp = normalizePath(virtualPath);
+    const meta = this.db.get(this.metaPath(vp)) as FileStat | null;
+    return meta || null;
+  }
+
+  list(virtualPath: string): FileStat[] {
+    const vp = normalizePath(virtualPath);
+    const children = this.db.getShallow(this.containerPath(vp));
+    const results: FileStat[] = [];
+    for (const c of children) {
+      if (c.key === META_KEY) continue; // skip own metadata
+      const childPath = vp ? `${vp}/${c.key}` : c.key;
+      const meta = this.db.get(this.metaPath(childPath)) as FileStat | null;
+      if (meta) {
+        results.push(meta);
+      } else {
+        // Implicit directory (has children but no explicit metadata)
+        results.push({ name: c.key, path: childPath, size: 0, mime: '', mtime: 0, isDir: true });
+      }
+    }
+    return results;
+  }
+
+  mkdir(virtualPath: string): FileStat {
+    const vp = normalizePath(virtualPath);
+    const name = vp.split('/').pop()!;
+    const stat: FileStat = { name, path: vp, size: 0, mime: '', mtime: Date.now(), isDir: true };
+    this.db.set(this.metaPath(vp), stat);
+    return stat;
+  }
+
+  async remove(virtualPath: string): Promise<void> {
+    const vp = normalizePath(virtualPath);
+    const meta = this.db.get(this.metaPath(vp)) as Record<string, unknown> | null;
+    if (meta?.fileId) {
+      await this.backend.delete(meta.fileId as string);
+    }
+    this.db.delete(this.containerPath(vp));
+  }
+
+  async move(src: string, dst: string): Promise<FileStat> {
+    const srcPath = normalizePath(src);
+    const dstPath = normalizePath(dst);
+    const meta = this.db.get(this.metaPath(srcPath)) as FileStat | null;
+    if (!meta) throw new Error(`File not found: ${srcPath}`);
+
+    const newName = dstPath.split('/').pop()!;
+    const updated: FileStat = { ...meta, name: newName, path: dstPath, mtime: Date.now() };
+    this.db.set(this.metaPath(dstPath), updated);
+    this.db.delete(this.containerPath(srcPath));
+    return updated;
+  }
+}
+
+function guessMime(name: string): string {
+  const ext = name.split('.').pop()?.toLowerCase();
+  const mimes: Record<string, string> = {
+    txt: 'text/plain', html: 'text/html', css: 'text/css', js: 'application/javascript',
+    json: 'application/json', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+    gif: 'image/gif', svg: 'image/svg+xml', pdf: 'application/pdf',
+    zip: 'application/zip', mp3: 'audio/mpeg', mp4: 'video/mp4',
+  };
+  return mimes[ext || ''] || 'application/octet-stream';
+}

package/src/shared/protocol.ts

@@ -28,15 +28,26 @@ export type ClientMessage =
   | { id: string; op: 'stream-snapshot'; path: string }
   | { id: string; op: 'stream-materialize'; path: string; keepKey?: string }
   | { id: string; op: 'stream-compact'; path: string; maxAge?: number; maxCount?: number; keepKey?: string }
-  | { id: string; op: 'stream-reset'; path: string };
+  | { id: string; op: 'stream-reset'; path: string }
+  // VFS ops
+  | { id: string; op: 'vfs-upload-init'; path: string; size: number; mime?: string }
+  | { id: string; op: 'vfs-upload-chunk'; transferId: string; data: string; seq: number }
+  | { id: string; op: 'vfs-upload-done'; transferId: string }
+  | { id: string; op: 'vfs-download-init'; path: string }
+  | { id: string; op: 'vfs-stat'; path: string }
+  | { id: string; op: 'vfs-list'; path: string }
+  | { id: string; op: 'vfs-delete'; path: string }
+  | { id: string; op: 'vfs-mkdir'; path: string }
+  | { id: string; op: 'vfs-move'; path: string; dst: string };
 
 // Server → Client messages
 export type ServerMessage =
-  | { id: string; ok: true; data?: unknown }
+  | { id: string; ok: true; data?: unknown; updatedAt?: number }
   | { id: string; ok: false; error: string; code: string }
-  | { type: 'value'; path: string; data: unknown }
+  | { type: 'value'; path: string; data: unknown; updatedAt?: number }
   | { type: 'child'; path: string; key: string; data: unknown; event: ChildEvent }
-  | { type: 'stream'; path: string; groupId: string; events: Array<{ key: string; data: unknown }> };
+  | { type: 'stream'; path: string; groupId: string; events: Array<{ key: string; data: unknown }> }
+  | { type: 'vfs-download-chunk'; transferId: string; data: string; seq: number; done: boolean };
 
 export type SubEvent = 'value' | 'child';
 export type ChildEvent = 'added' | 'changed' | 'removed';
@@ -52,6 +63,16 @@ export interface OrderClause {
   dir: 'asc' | 'desc';
 }
 
+export interface FileStat {
+  name: string;
+  path: string;
+  size: number;
+  mime: string;
+  mtime: number;
+  fileId?: string;
+  isDir: boolean;
+}
+
 export type BatchOp =
   | { op: 'set'; path: string; value: unknown }
   | { op: 'update'; updates: Record<string, unknown> }

package/tests/cached-client.test.ts

@@ -0,0 +1,143 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { BodDB } from '../src/server/BodDB.ts';
+import { BodClient, ValueSnapshot } from '../src/client/BodClient.ts';
+import { CachedClient } from '../src/client/CachedClient.ts';
+
+let db: BodDB;
+let client: BodClient;
+let cached: CachedClient;
+
+beforeAll(async () => {
+  db = new BodDB({ port: 0 });
+  const server = db.serve();
+  client = new BodClient({ url: `ws://localhost:${server.port}`, reconnect: false });
+  await client.connect();
+  cached = new CachedClient(client, { enabled: true });
+});
+
+afterAll(() => {
+  client.disconnect();
+  db.close();
+});
+
+describe('CachedClient', () => {
+  test('get() fetches from network on first call', async () => {
+    db.set('cache/test1', { name: 'hello' });
+    const val = await cached.get('cache/test1');
+    expect(val).toEqual({ name: 'hello' });
+  });
+
+  test('get() returns cached value on second call', async () => {
+    db.set('cache/test2', 42);
+    await cached.get('cache/test2');
+    // Modify server-side without going through cached client
+    db.set('cache/test2', 99);
+    // Memory cache still has old value, returns stale + triggers revalidate
+    const val = await cached.get('cache/test2');
+    expect(val).toBe(42); // stale from memory
+  });
+
+  test('subscription updates memory cache', async () => {
+    const values: unknown[] = [];
+    const off = cached.on('cache/sub1', (snap) => {
+      values.push(snap.val());
+    });
+
+    // Wait for initial subscription fire
+    await new Promise(r => setTimeout(r, 100));
+
+    db.set('cache/sub1', 'first');
+    await new Promise(r => setTimeout(r, 100));
+
+    // get() should return cached value from sub
+    const val = await cached.get('cache/sub1');
+    expect(val).toBe('first');
+
+    off();
+  });
+
+  test('set() invalidates cache', async () => {
+    db.set('cache/inv1', 'original');
+    await cached.get('cache/inv1');
+
+    await cached.set('cache/inv1', 'updated');
+    // Cache invalidated, next get() fetches from network
+    const val = await cached.get('cache/inv1');
+    expect(val).toBe('updated');
+  });
+
+  test('delete() invalidates cache', async () => {
+    db.set('cache/del1', 'exists');
+    await cached.get('cache/del1');
+
+    await cached.delete('cache/del1');
+    const val = await cached.get('cache/del1');
+    expect(val).toBeNull();
+  });
+
+  test('update() invalidates affected paths', async () => {
+    db.set('cache/upd/a', 1);
+    db.set('cache/upd/b', 2);
+    await cached.get('cache/upd/a');
+    await cached.get('cache/upd/b');
+
+    await cached.update({ 'cache/upd/a': 10, 'cache/upd/b': 20 });
+    const a = await cached.get('cache/upd/a');
+    const b = await cached.get('cache/upd/b');
+    expect(a).toBe(10);
+    expect(b).toBe(20);
+  });
+
+  test('disabled mode is pure passthrough', async () => {
+    const passthrough = new CachedClient(client, { enabled: false });
+    db.set('cache/pt', 'val');
+    const v1 = await passthrough.get('cache/pt');
+    expect(v1).toBe('val');
+    db.set('cache/pt', 'changed');
+    const v2 = await passthrough.get('cache/pt');
+    expect(v2).toBe('changed');
+  });
+
+  test('memory eviction respects maxMemoryEntries', async () => {
+    const small = new CachedClient(client, { maxMemoryEntries: 3 });
+    for (let i = 0; i < 5; i++) {
+      db.set(`cache/evict/${i}`, i);
+      await small.get(`cache/evict/${i}`);
+    }
+    // Only last 3 should be in memory
+    // Modify server values
+    for (let i = 0; i < 5; i++) db.set(`cache/evict/${i}`, i + 100);
+    // First two should be evicted (network fetch = new value)
+    const v0 = await small.get('cache/evict/0');
+    expect(v0).toBe(100); // evicted, fetched fresh
+    const v4 = await small.get('cache/evict/4');
+    expect(v4).toBe(4); // still cached (stale)
+  });
+
+  test('getSnapshot returns updatedAt', async () => {
+    db.set('cache/meta1', 'val');
+    const snap = await client.getSnapshot('cache/meta1');
+    expect(snap.val()).toBe('val');
+    expect(snap.updatedAt).toBeGreaterThan(0);
+    expect(snap).toBeInstanceOf(ValueSnapshot);
+  });
+
+  test('onChild invalidates parent cache', async () => {
+    db.set('cache/parent2/child1', 'a');
+    await cached.get('cache/parent2');
+
+    const events: string[] = [];
+    const off = cached.onChild('cache/parent2', (e) => {
+      events.push(e.type);
+    });
+
+    // Wait for sub to be established
+    await new Promise(r => setTimeout(r, 50));
+
+    db.set('cache/parent2/child2', 'b');
+    await new Promise(r => setTimeout(r, 150));
+
+    expect(events.length).toBeGreaterThan(0);
+    off();
+  });
+});