feat(storage): add BucketStore interface, LocalFsStore and PrefixedStore

src/lib/server/storage/local-fs-store.ts

@@ -0,0 +1,77 @@
+import { appendFile, copyFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { assertValidPath, type BucketStore, type StoreEntry } from './store';
+
+function isEnoent(e: unknown): boolean {
+	return typeof e === 'object' && e !== null && (e as { code?: string }).code === 'ENOENT';
+}
+
+/** Directory-backed store for local development and tests. Writes are atomic (temp file + rename). */
+export class LocalFsStore implements BucketStore {
+	constructor(private readonly root: string) {}
+
+	private abs(path: string): string {
+		assertValidPath(path);
+		return join(this.root, ...path.split('/'));
+	}
+
+	async get(path: string): Promise<Uint8Array | null> {
+		try {
+			return new Uint8Array(await readFile(this.abs(path)));
+		} catch (e) {
+			if (isEnoent(e)) return null;
+			throw e;
+		}
+	}
+
+	async put(path: string, bytes: Uint8Array, contentType?: string): Promise<void> {
+		const target = this.abs(path);
+		await mkdir(dirname(target), { recursive: true });
+		const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+		await writeFile(tmp, bytes);
+		await rename(tmp, target);
+	}
+
+	async append(path: string, bytes: Uint8Array): Promise<void> {
+		const target = this.abs(path);
+		await mkdir(dirname(target), { recursive: true });
+		await appendFile(target, bytes);
+	}
+
+	async list(prefix: string): Promise<StoreEntry[]> {
+		const out: StoreEntry[] = [];
+		const walk = async (dir: string): Promise<void> => {
+			let entries;
+			try {
+				entries = await readdir(dir, { withFileTypes: true });
+			} catch (e) {
+				if (isEnoent(e)) return;
+				throw e;
+			}
+			for (const ent of entries) {
+				const full = join(dir, ent.name);
+				if (ent.isDirectory()) {
+					await walk(full);
+				} else if (ent.isFile() && !ent.name.endsWith('.tmp')) {
+					const rel = relative(this.root, full).split(sep).join('/');
+					if (rel.startsWith(prefix)) {
+						const s = await stat(full);
+						out.push({ path: rel, size: s.size, uploadedAt: s.mtime });
+					}
+				}
+			}
+		};
+		await walk(this.root);
+		return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+	}
+
+	async delete(paths: string[]): Promise<void> {
+		for (const p of paths) await rm(this.abs(p), { force: true });
+	}
+
+	async copy(src: string, dst: string): Promise<void> {
+		const target = this.abs(dst);
+		await mkdir(dirname(target), { recursive: true });
+		await copyFile(this.abs(src), target);
+	}
+}

src/lib/server/storage/prefixed-store.ts

@@ -0,0 +1,50 @@
+import { assertValidPath, type BucketStore, type StoreEntry } from './store';
+
+/**
+ * Confines another store to `<prefix>/`, so several apps (or test runs) can share one
+ * bucket under different directories. Paths seen by callers never include the prefix.
+ */
+export class PrefixedStore implements BucketStore {
+	private readonly prefix: string;
+
+	constructor(
+		private readonly inner: BucketStore,
+		prefix: string
+	) {
+		const trimmed = prefix.replace(/^\/+|\/+$/g, '');
+		assertValidPath(trimmed);
+		this.prefix = `${trimmed}/`;
+	}
+
+	private full(path: string): string {
+		assertValidPath(path);
+		return this.prefix + path;
+	}
+
+	get(path: string): Promise<Uint8Array | null> {
+		return this.inner.get(this.full(path));
+	}
+	put(path: string, bytes: Uint8Array, contentType?: string): Promise<void> {
+		return this.inner.put(this.full(path), bytes, contentType);
+	}
+	append(path: string, bytes: Uint8Array): Promise<void> {
+		return this.inner.append(this.full(path), bytes);
+	}
+	async list(prefix: string): Promise<StoreEntry[]> {
+		const entries = await this.inner.list(this.prefix + prefix);
+		return entries.map((e) => ({ ...e, path: e.path.slice(this.prefix.length) }));
+	}
+	delete(paths: string[]): Promise<void> {
+		return this.inner.delete(paths.map((p) => this.full(p)));
+	}
+	copy(src: string, dst: string): Promise<void> {
+		return this.inner.copy(this.full(src), this.full(dst));
+	}
+
+	/** Deletes every object under this store's prefix. Returns how many were deleted. */
+	async wipe(): Promise<number> {
+		const entries = await this.inner.list(this.prefix);
+		await this.inner.delete(entries.map((e) => e.path));
+		return entries.length;
+	}
+}

src/lib/server/storage/store.ts

@@ -0,0 +1,37 @@
+export interface StoreEntry {
+	path: string;
+	size: number;
+	uploadedAt?: Date;
+}
+
+/**
+ * Minimal object-store abstraction. Paths are bucket-relative, use `/` separators,
+ * and never start with `/`.
+ */
+export interface BucketStore {
+	/** Resolves null when the object does not exist. */
+	get(path: string): Promise<Uint8Array | null>;
+	/** Creates or overwrites. */
+	put(path: string, bytes: Uint8Array, contentType?: string): Promise<void>;
+	/** Appends bytes to an existing object, creating it if missing. */
+	append(path: string, bytes: Uint8Array): Promise<void>;
+	/** Lists files whose path starts with `prefix`, sorted by path. */
+	list(prefix: string): Promise<StoreEntry[]>;
+	/** Deletes objects; missing ones are ignored. */
+	delete(paths: string[]): Promise<void>;
+	/** Server-side copy. Rejects if `src` does not exist. */
+	copy(src: string, dst: string): Promise<void>;
+}
+
+const SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+
+export function assertValidPath(path: string): void {
+	if (path.length === 0 || path.length > 512) throw new Error(`Invalid path: ${path}`);
+	if (path.startsWith('/') || path.endsWith('/')) throw new Error(`Invalid path: ${path}`);
+	for (const seg of path.split('/')) {
+		if (seg === '' || seg === '.' || seg === '..' || !SEGMENT_RE.test(seg)) throw new Error(`Invalid path: ${path}`);
+	}
+}
+
+export const encodeText = (s: string): Uint8Array => new TextEncoder().encode(s);
+export const decodeText = (b: Uint8Array): string => new TextDecoder().decode(b);

tests/unit/storage/local-fs-store.test.ts

@@ -0,0 +1,62 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { LocalFsStore } from '../../../src/lib/server/storage/local-fs-store';
+import { assertValidPath } from '../../../src/lib/server/storage/store';
+
+const enc = (s: string) => new TextEncoder().encode(s);
+const dec = (b: Uint8Array | null) => (b ? new TextDecoder().decode(b) : null);
+
+describe('LocalFsStore', () => {
+	let dir: string;
+	let store: LocalFsStore;
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'splitwise-store-'));
+		store = new LocalFsStore(dir);
+	});
+	afterEach(() => rm(dir, { recursive: true, force: true }));
+
+	it('returns null for missing files', async () => {
+		expect(await store.get('nope.json')).toBeNull();
+	});
+
+	it('puts, gets and overwrites', async () => {
+		await store.put('a/b.json', enc('one'), 'application/json');
+		expect(dec(await store.get('a/b.json'))).toBe('one');
+		await store.put('a/b.json', enc('two'));
+		expect(dec(await store.get('a/b.json'))).toBe('two');
+	});
+
+	it('appends, creating the file when missing', async () => {
+		await store.append('log.jsonl', enc('1\n'));
+		await store.append('log.jsonl', enc('2\n'));
+		expect(dec(await store.get('log.jsonl'))).toBe('1\n2\n');
+	});
+
+	it('lists files under a prefix, sorted by path', async () => {
+		await store.put('events/b.json', enc('b'));
+		await store.put('events/a.json', enc('a'));
+		await store.put('other.json', enc('o'));
+		const listed = await store.list('events/');
+		expect(listed.map((e) => e.path)).toEqual(['events/a.json', 'events/b.json']);
+		expect(listed[0].size).toBe(1);
+		expect(await store.list('missing/')).toEqual([]);
+	});
+
+	it('deletes (ignoring missing) and copies', async () => {
+		await store.put('x.txt', enc('x'));
+		await store.copy('x.txt', 'backups/x.txt');
+		expect(dec(await store.get('backups/x.txt'))).toBe('x');
+		await store.delete(['x.txt', 'not-there.txt']);
+		expect(await store.get('x.txt')).toBeNull();
+		await expect(store.copy('gone.txt', 'y.txt')).rejects.toThrow();
+	});
+
+	it('rejects unsafe paths', () => {
+		expect(() => assertValidPath('../etc/passwd')).toThrow();
+		expect(() => assertValidPath('/abs')).toThrow();
+		expect(() => assertValidPath('a//b')).toThrow();
+		expect(() => assertValidPath('ok/path.json')).not.toThrow();
+	});
+});

tests/unit/storage/prefixed-store.test.ts

@@ -0,0 +1,60 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { LocalFsStore } from '../../../src/lib/server/storage/local-fs-store';
+import { PrefixedStore } from '../../../src/lib/server/storage/prefixed-store';
+import { decodeText, encodeText } from '../../../src/lib/server/storage/store';
+
+describe('PrefixedStore', () => {
+	let dir: string;
+	let inner: LocalFsStore;
+	let a: PrefixedStore;
+	let b: PrefixedStore;
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'splitwise-prefixed-'));
+		inner = new LocalFsStore(dir);
+		a = new PrefixedStore(inner, 'tenants/a');
+		b = new PrefixedStore(inner, '/tenants/b/');
+	});
+	afterEach(() => rm(dir, { recursive: true, force: true }));
+
+	it('stores objects under the prefix and reads them back', async () => {
+		await a.put('users.json', encodeText('A'), 'application/json');
+		expect(decodeText((await a.get('users.json'))!)).toBe('A');
+		expect(decodeText((await inner.get('tenants/a/users.json'))!)).toBe('A');
+		expect(await b.get('users.json')).toBeNull();
+	});
+
+	it('lists with the prefix stripped and never leaks other prefixes', async () => {
+		await a.put('events/1.json', encodeText('1'));
+		await a.put('events/2.json', encodeText('2'));
+		await b.put('events/9.json', encodeText('9'));
+		expect((await a.list('events/')).map((e) => e.path)).toEqual(['events/1.json', 'events/2.json']);
+		expect((await a.list('')).map((e) => e.path)).toEqual(['events/1.json', 'events/2.json']);
+		expect((await b.list('events/')).map((e) => e.path)).toEqual(['events/9.json']);
+	});
+
+	it('appends, copies and deletes inside the prefix', async () => {
+		await a.append('ledger.jsonl', encodeText('x\n'));
+		await a.append('ledger.jsonl', encodeText('y\n'));
+		await a.copy('ledger.jsonl', 'backups/l.jsonl');
+		expect(decodeText((await inner.get('tenants/a/backups/l.jsonl'))!)).toBe('x\ny\n');
+		await a.delete(['ledger.jsonl', 'missing.txt']);
+		expect(await a.get('ledger.jsonl')).toBeNull();
+	});
+
+	it('wipe removes only its own subtree', async () => {
+		await a.put('x.txt', encodeText('x'));
+		await a.put('deep/y.txt', encodeText('y'));
+		await b.put('z.txt', encodeText('z'));
+		expect(await a.wipe()).toBe(2);
+		expect(await a.list('')).toEqual([]);
+		expect(await b.get('z.txt')).not.toBeNull();
+	});
+
+	it('rejects invalid prefixes', () => {
+		expect(() => new PrefixedStore(inner, '')).toThrow();
+		expect(() => new PrefixedStore(inner, '../x')).toThrow();
+	});
+});