@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/artifacts/store.ts

@@ -1,345 +1,334 @@
-/**
- * Artifacts: the file on disk and the reference to it.
- *
- * The reference lives in the scope's own database, so a reference created
- * inside a transaction rolls back with it (FR-072) — no bookkeeping required,
- * because the connection routes through the transaction in flight.
- *
- * The file does not roll back. A filesystem write is not part of a SQL
- * transaction and cannot be made part of one, so a rolled-back transaction
- * leaves an artifact on disk with nothing pointing at it. That is not a bug
- * to be engineered away; it is why reconciliation exists (FR-073d), and why
- * the write order is deliberate: **the file completes first, then the
- * reference**. The reverse order would produce a reference to a file that
- * does not exist, which is the failure a consumer cannot recover from — it
- * looks like data the app has and does not.
- */
-
-import type {
-	AttachmentInput,
-	AttachmentOwner,
-	AttachmentReference,
-	ByteRange,
-	DeletionOutcome,
-} from '../contract/attachment';
-import { Budgets } from '../contract/config';
-import { DiagnosticCodes } from '../contract/errors';
-import { isStorageError, raise } from '../diagnostics/errors';
-import { throwIfFaulted } from '../diagnostics/faults';
-import { raiseNative } from '../diagnostics/map-native';
-import { fileSystem, removeIfPresent } from '../platform/fs';
-import { base64ToBytes, bytesToBase64, concatBytes } from '../platform/bytes';
-import type { StorageLayout } from '../platform/location';
-import { assertArtifactWithinBudget } from '../query/budgets';
-import {
-	HEADER_BYTES,
-	TAG_BYTES,
-	chunkOffset,
-	chunkPlaintextLength,
-	decodeHeader,
-	decryptChunk,
-	encodeHeader,
-	encryptChunk,
-	headerFor,
-} from '../crypto/chunked-cipher';
-import type { Executor } from '../sqlite/connection';
-import { maybeNum, num, text } from '../sqlite/values';
-import { artifactPath, artifactsDirectory } from './paths';
-
-const CREATE_ATTACHMENTS = `CREATE TABLE IF NOT EXISTS _attachments (
-  id               TEXT PRIMARY KEY,
-  owner_collection TEXT,
-  owner_id         TEXT,
-  content_type     TEXT NOT NULL,
-  size             INTEGER NOT NULL,
-  chunk_size       INTEGER,
-  chunk_count      INTEGER,
-  created_at       INTEGER NOT NULL
-)`;
-
-const CREATE_OWNER_INDEX =
-	'CREATE INDEX IF NOT EXISTS _attachments_owner ON _attachments (owner_collection, owner_id)';
-
-export type ArtifactContext = {
-	executor(): Executor;
-	layout: StorageLayout;
-	scopeKey: string;
-	/** Null when the database is unencrypted. */
-	artifactKey(attachmentId: string): Uint8Array | null;
-	now(): number;
-};
-
-export async function ensureAttachmentTable(executor: Executor): Promise<void> {
-	await executor.execute(CREATE_ATTACHMENTS);
-	await executor.execute(CREATE_OWNER_INDEX);
-}
-
-function toReference(row: Record<string, unknown>): AttachmentReference {
-	const reference: AttachmentReference = {
-		id: text(row.id),
-		contentType: text(row.content_type),
-		size: num(row.size),
-		createdAt: num(row.created_at),
-	};
-	if (row.owner_collection != null && row.owner_id != null) {
-		reference.owner = { collection: text(row.owner_collection), id: text(row.owner_id) };
-	}
-	const chunkSize = maybeNum(row.chunk_size);
-	if (chunkSize !== null) {
-		reference.chunkSize = chunkSize;
-		reference.chunkCount = num(row.chunk_count);
-	}
-	return reference;
-}
-
-export async function readReference(
-	executor: Executor,
-	id: string,
-): Promise<AttachmentReference | null> {
-	const result = await executor.execute('SELECT * FROM _attachments WHERE id = ?', [id]);
-	const row = result.rows[0];
-	return row ? toReference(row) : null;
-}
-
-export async function listReferences(executor: Executor): Promise<AttachmentReference[]> {
-	const result = await executor.execute('SELECT * FROM _attachments ORDER BY id ASC');
-	return result.rows.map(toReference);
-}
-
-export async function listReferencesFor(
-	executor: Executor,
-	owner: AttachmentOwner,
-): Promise<AttachmentReference[]> {
-	const result = await executor.execute(
-		'SELECT * FROM _attachments WHERE owner_collection = ? AND owner_id = ? ORDER BY id ASC',
-		[owner.collection, owner.id],
-	);
-	return result.rows.map(toReference);
-}
-
-async function insertReference(
-	executor: Executor,
-	reference: AttachmentReference,
-): Promise<void> {
-	await executor.execute(
-		`INSERT INTO _attachments
-		 (id, owner_collection, owner_id, content_type, size, chunk_size, chunk_count, created_at)
-		 VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-		 ON CONFLICT(id) DO UPDATE SET
-		   owner_collection = excluded.owner_collection,
-		   owner_id = excluded.owner_id,
-		   content_type = excluded.content_type,
-		   size = excluded.size,
-		   chunk_size = excluded.chunk_size,
-		   chunk_count = excluded.chunk_count,
-		   created_at = excluded.created_at`,
-		[
-			reference.id,
-			reference.owner?.collection ?? null,
-			reference.owner?.id ?? null,
-			reference.contentType,
-			reference.size,
-			reference.chunkSize ?? null,
-			reference.chunkCount ?? null,
-			reference.createdAt,
-		],
-	);
-}
-
-export async function deleteReference(executor: Executor, id: string): Promise<boolean> {
-	const result = await executor.execute('DELETE FROM _attachments WHERE id = ?', [id]);
-	return result.rowsAffected > 0;
-}
-
-async function writePlaintext(path: string, content: string): Promise<void> {
-	await fileSystem().writeFile(path, content, 'base64');
-}
-
-/**
- * Encrypted write, one chunk in flight.
- *
- * The header goes down first because its contents — chunk size, chunk count,
- * plaintext length — are all known from the input length before any
- * encryption happens. Only the tags depend on the ciphertext, and they follow
- * their own chunk, so the whole write is append-only and peak memory is one
- * chunk regardless of artifact size (FR-107a).
- */
-async function writeEncrypted(
-	path: string,
-	key: Uint8Array,
-	plaintext: Uint8Array,
-): Promise<{ chunkSize: number; chunkCount: number }> {
-	const header = headerFor(plaintext.length, Budgets.ARTIFACT_CHUNK_BYTES);
-	await fileSystem().writeFile(path, bytesToBase64(encodeHeader(header)), 'base64');
-
-	for (let index = 0; index < header.chunkCount; index += 1) {
-		const start = index * header.chunkSize;
-		const chunk = plaintext.subarray(start, start + chunkPlaintextLength(header, index));
-		await fileSystem().appendFile(
-			path,
-			bytesToBase64(encryptChunk(key, index, chunk)),
-			'base64',
-		);
-	}
-
-	return { chunkSize: header.chunkSize, chunkCount: header.chunkCount };
-}
-
-export async function writeArtifact(
-	context: ArtifactContext,
-	input: AttachmentInput,
-): Promise<AttachmentReference> {
-	throwIfFaulted('attachmentWrite');
-	const plaintext = base64ToBytes(input.content);
-	assertArtifactWithinBudget(input.id, plaintext.length);
-
-	const path = artifactPath(context.layout, context.scopeKey, input.id);
-	const key = context.artifactKey(input.id);
-
-	let chunking: { chunkSize: number; chunkCount: number } | undefined;
-	try {
-		await fileSystem().mkdir(artifactsDirectory(context.layout, context.scopeKey));
-		if (key) {
-			chunking = await writeEncrypted(path, key, plaintext);
-		} else {
-			await writePlaintext(path, input.content);
-		}
-	} catch (error) {
-		// A partial file with no reference is an orphan reconciliation can
-		// find; a reference to a partial file is data the app believes it has.
-		await removeIfPresent(path);
-		raiseNative(error, { operation: 'attachment' });
-	}
-
-	const reference: AttachmentReference = {
-		id: input.id,
-		contentType: input.contentType,
-		size: plaintext.length,
-		createdAt: context.now(),
-	};
-	if (input.owner) {
-		reference.owner = input.owner;
-	}
-	if (chunking) {
-		reference.chunkSize = chunking.chunkSize;
-		reference.chunkCount = chunking.chunkCount;
-	}
-
-	// Only now. See the note at the top of this file.
-	await insertReference(context.executor(), reference);
-	return reference;
-}
-
-async function readPlaintext(path: string, range?: ByteRange): Promise<string> {
-	if (!range) {
-		return fileSystem().readFile(path, 'base64');
-	}
-	return fileSystem().read(path, range.length, range.offset, 'base64');
-}
-
-async function readEncrypted(
-	path: string,
-	key: Uint8Array,
-	range?: ByteRange,
-): Promise<string> {
-	const headerBytes = base64ToBytes(await fileSystem().read(path, HEADER_BYTES, 0, 'base64'));
-	const header = decodeHeader(headerBytes);
-
-	const from = range?.offset ?? 0;
-	const to = range ? Math.min(header.plaintextSize, from + range.length) : header.plaintextSize;
-	if (to <= from) {
-		return '';
-	}
-
-	const first = Math.floor(from / header.chunkSize);
-	const last = Math.floor((to - 1) / header.chunkSize);
-	const pieces: Uint8Array[] = [];
-
-	for (let index = first; index <= last; index += 1) {
-		const stored = base64ToBytes(
-			await fileSystem().read(
-				path,
-				chunkPlaintextLength(header, index) + TAG_BYTES,
-				chunkOffset(header, index),
-				'base64',
-			),
-		);
-		const decrypted = decryptChunk(key, index, stored);
-		const chunkStart = index * header.chunkSize;
-		pieces.push(
-			decrypted.subarray(
-				Math.max(0, from - chunkStart),
-				Math.min(decrypted.length, to - chunkStart),
-			),
-		);
-	}
-
-	return bytesToBase64(concatBytes(pieces));
-}
-
-export async function readArtifact(
-	context: ArtifactContext,
-	id: string,
-	range?: ByteRange,
-): Promise<string> {
-	const path = artifactPath(context.layout, context.scopeKey, id);
-	const key = context.artifactKey(id);
-	try {
-		return key ? await readEncrypted(path, key, range) : await readPlaintext(path, range);
-	} catch (error) {
-		// A typed error the package already classified — an unreadable header,
-		// a failing tag — says something more specific than "missing" and must
-		// survive. Anything else reaching here is the file not being there.
-		if (isStorageError(error)) {
-			throw error;
-		}
-		raise(DiagnosticCodes.ATTACHMENT_MISSING, {
-			message: 'artifact is missing',
-			detail: { attachmentId: id },
-			cause: error,
-		});
-	}
-}
-
-/**
- * Collects file removals until the transaction that deleted their references
- * commits. A file unlinked inside the transaction is gone even if the
- * transaction then rolls back and the reference returns — a dangling
- * reference to data nobody can recover.
- */
-export type DeferredUnlinks = {
-	add(path: string): void;
-};
-
-export async function removeArtifact(
-	context: ArtifactContext,
-	id: string,
-	deferred?: DeferredUnlinks,
-): Promise<DeletionOutcome> {
-	const path = artifactPath(context.layout, context.scopeKey, id);
-	if (deferred) {
-		// Inside a transaction: the reference goes now and rolls back with it;
-		// the file goes once the transaction commits.
-		const hadReference = await deleteReference(context.executor(), id);
-		if (hadReference) {
-			deferred.add(path);
-		}
-		return {
-			removedRecords: 0,
-			removedArtifacts: hadReference ? [id] : [],
-			orphanedReferences: [],
-			failedRemovals: [],
-		};
-	}
-	const removed = await removeIfPresent(path);
-	const hadReference = await deleteReference(context.executor(), id);
-
-	return {
-		removedRecords: 0,
-		removedArtifacts: removed ? [id] : [],
-		// A reference with no file left behind is worth reporting rather than
-		// rounding up to success (FR-071).
-		orphanedReferences: !removed && hadReference ? [id] : [],
-		failedRemovals: [],
-	};
-}
+/**
+ * Artifacts: the file on disk and the reference to it.
+ *
+ * The reference lives in the scope's own database, so a reference created
+ * inside a transaction rolls back with it (FR-072) — no bookkeeping required,
+ * because the connection routes through the transaction in flight.
+ *
+ * The file does not roll back. A filesystem write is not part of a SQL
+ * transaction and cannot be made part of one, so a rolled-back transaction
+ * leaves an artifact on disk with nothing pointing at it. That is not a bug
+ * to be engineered away; it is why reconciliation exists (FR-073d), and why
+ * the write order is deliberate: **the file completes first, then the
+ * reference**. The reverse order would produce a reference to a file that
+ * does not exist, which is the failure a consumer cannot recover from — it
+ * looks like data the app has and does not.
+ */
+
+import type {
+	AttachmentInput,
+	AttachmentOwner,
+	AttachmentReference,
+	ByteRange,
+	DeletionOutcome,
+} from '../contract/attachment';
+import { Budgets } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import { isStorageError, raise } from '../diagnostics/errors';
+import { throwIfFaulted } from '../diagnostics/faults';
+import { raiseNative } from '../diagnostics/map-native';
+import { fileSystem, removeIfPresent } from '../platform/fs';
+import { base64ToBytes, bytesToBase64, concatBytes } from '../platform/bytes';
+import type { StorageLayout } from '../platform/location';
+import { assertArtifactWithinBudget } from '../query/budgets';
+import {
+	HEADER_BYTES,
+	TAG_BYTES,
+	chunkOffset,
+	chunkPlaintextLength,
+	decodeHeader,
+	decryptChunk,
+	encodeHeader,
+	encryptChunk,
+	headerFor,
+} from '../crypto/chunked-cipher';
+import type { Executor } from '../sqlite/connection';
+import { maybeNum, num, text } from '../sqlite/values';
+import { artifactPath, artifactsDirectory } from './paths';
+
+const CREATE_ATTACHMENTS = `CREATE TABLE IF NOT EXISTS _attachments (
+  id               TEXT PRIMARY KEY,
+  owner_collection TEXT,
+  owner_id         TEXT,
+  content_type     TEXT NOT NULL,
+  size             INTEGER NOT NULL,
+  chunk_size       INTEGER,
+  chunk_count      INTEGER,
+  created_at       INTEGER NOT NULL
+)`;
+
+const CREATE_OWNER_INDEX =
+	'CREATE INDEX IF NOT EXISTS _attachments_owner ON _attachments (owner_collection, owner_id)';
+
+export type ArtifactContext = {
+	executor(): Executor;
+	layout: StorageLayout;
+	scopeKey: string;
+	/** Null when the database is unencrypted. */
+	artifactKey(attachmentId: string): Uint8Array | null;
+	now(): number;
+};
+
+export async function ensureAttachmentTable(executor: Executor): Promise<void> {
+	await executor.execute(CREATE_ATTACHMENTS);
+	await executor.execute(CREATE_OWNER_INDEX);
+}
+
+function toReference(row: Record<string, unknown>): AttachmentReference {
+	const reference: AttachmentReference = {
+		id: text(row.id),
+		contentType: text(row.content_type),
+		size: num(row.size),
+		createdAt: num(row.created_at),
+	};
+	if (row.owner_collection != null && row.owner_id != null) {
+		reference.owner = { collection: text(row.owner_collection), id: text(row.owner_id) };
+	}
+	const chunkSize = maybeNum(row.chunk_size);
+	if (chunkSize !== null) {
+		reference.chunkSize = chunkSize;
+		reference.chunkCount = num(row.chunk_count);
+	}
+	return reference;
+}
+
+export async function readReference(
+	executor: Executor,
+	id: string,
+): Promise<AttachmentReference | null> {
+	const result = await executor.execute('SELECT * FROM _attachments WHERE id = ?', [id]);
+	const row = result.rows[0];
+	return row ? toReference(row) : null;
+}
+
+export async function listReferences(executor: Executor): Promise<AttachmentReference[]> {
+	const result = await executor.execute('SELECT * FROM _attachments ORDER BY id ASC');
+	return result.rows.map(toReference);
+}
+
+export async function listReferencesFor(
+	executor: Executor,
+	owner: AttachmentOwner,
+): Promise<AttachmentReference[]> {
+	const result = await executor.execute(
+		'SELECT * FROM _attachments WHERE owner_collection = ? AND owner_id = ? ORDER BY id ASC',
+		[owner.collection, owner.id],
+	);
+	return result.rows.map(toReference);
+}
+
+async function insertReference(executor: Executor, reference: AttachmentReference): Promise<void> {
+	await executor.execute(
+		`INSERT INTO _attachments
+		 (id, owner_collection, owner_id, content_type, size, chunk_size, chunk_count, created_at)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+		 ON CONFLICT(id) DO UPDATE SET
+		   owner_collection = excluded.owner_collection,
+		   owner_id = excluded.owner_id,
+		   content_type = excluded.content_type,
+		   size = excluded.size,
+		   chunk_size = excluded.chunk_size,
+		   chunk_count = excluded.chunk_count,
+		   created_at = excluded.created_at`,
+		[
+			reference.id,
+			reference.owner?.collection ?? null,
+			reference.owner?.id ?? null,
+			reference.contentType,
+			reference.size,
+			reference.chunkSize ?? null,
+			reference.chunkCount ?? null,
+			reference.createdAt,
+		],
+	);
+}
+
+export async function deleteReference(executor: Executor, id: string): Promise<boolean> {
+	const result = await executor.execute('DELETE FROM _attachments WHERE id = ?', [id]);
+	return result.rowsAffected > 0;
+}
+
+async function writePlaintext(path: string, content: string): Promise<void> {
+	await fileSystem().writeFile(path, content, 'base64');
+}
+
+/**
+ * Encrypted write, one chunk in flight.
+ *
+ * The header goes down first because its contents — chunk size, chunk count,
+ * plaintext length — are all known from the input length before any
+ * encryption happens. Only the tags depend on the ciphertext, and they follow
+ * their own chunk, so the whole write is append-only and peak memory is one
+ * chunk regardless of artifact size (FR-107a).
+ */
+async function writeEncrypted(
+	path: string,
+	key: Uint8Array,
+	plaintext: Uint8Array,
+): Promise<{ chunkSize: number; chunkCount: number }> {
+	const header = headerFor(plaintext.length, Budgets.ARTIFACT_CHUNK_BYTES);
+	await fileSystem().writeFile(path, bytesToBase64(encodeHeader(header)), 'base64');
+
+	for (let index = 0; index < header.chunkCount; index += 1) {
+		const start = index * header.chunkSize;
+		const chunk = plaintext.subarray(start, start + chunkPlaintextLength(header, index));
+		await fileSystem().appendFile(path, bytesToBase64(encryptChunk(key, index, chunk)), 'base64');
+	}
+
+	return { chunkSize: header.chunkSize, chunkCount: header.chunkCount };
+}
+
+export async function writeArtifact(
+	context: ArtifactContext,
+	input: AttachmentInput,
+): Promise<AttachmentReference> {
+	throwIfFaulted('attachmentWrite');
+	const plaintext = base64ToBytes(input.content);
+	assertArtifactWithinBudget(input.id, plaintext.length);
+
+	const path = artifactPath(context.layout, context.scopeKey, input.id);
+	const key = context.artifactKey(input.id);
+
+	let chunking: { chunkSize: number; chunkCount: number } | undefined;
+	try {
+		await fileSystem().mkdir(artifactsDirectory(context.layout, context.scopeKey));
+		if (key) {
+			chunking = await writeEncrypted(path, key, plaintext);
+		} else {
+			await writePlaintext(path, input.content);
+		}
+	} catch (error) {
+		// A partial file with no reference is an orphan reconciliation can
+		// find; a reference to a partial file is data the app believes it has.
+		await removeIfPresent(path);
+		raiseNative(error, { operation: 'attachment' });
+	}
+
+	const reference: AttachmentReference = {
+		id: input.id,
+		contentType: input.contentType,
+		size: plaintext.length,
+		createdAt: context.now(),
+	};
+	if (input.owner) {
+		reference.owner = input.owner;
+	}
+	if (chunking) {
+		reference.chunkSize = chunking.chunkSize;
+		reference.chunkCount = chunking.chunkCount;
+	}
+
+	// Only now. See the note at the top of this file.
+	await insertReference(context.executor(), reference);
+	return reference;
+}
+
+async function readPlaintext(path: string, range?: ByteRange): Promise<string> {
+	if (!range) {
+		return fileSystem().readFile(path, 'base64');
+	}
+	return fileSystem().read(path, range.length, range.offset, 'base64');
+}
+
+async function readEncrypted(path: string, key: Uint8Array, range?: ByteRange): Promise<string> {
+	const headerBytes = base64ToBytes(await fileSystem().read(path, HEADER_BYTES, 0, 'base64'));
+	const header = decodeHeader(headerBytes);
+
+	const from = range?.offset ?? 0;
+	const to = range ? Math.min(header.plaintextSize, from + range.length) : header.plaintextSize;
+	if (to <= from) {
+		return '';
+	}
+
+	const first = Math.floor(from / header.chunkSize);
+	const last = Math.floor((to - 1) / header.chunkSize);
+	const pieces: Uint8Array[] = [];
+
+	for (let index = first; index <= last; index += 1) {
+		const stored = base64ToBytes(
+			await fileSystem().read(
+				path,
+				chunkPlaintextLength(header, index) + TAG_BYTES,
+				chunkOffset(header, index),
+				'base64',
+			),
+		);
+		const decrypted = decryptChunk(key, index, stored);
+		const chunkStart = index * header.chunkSize;
+		pieces.push(
+			decrypted.subarray(
+				Math.max(0, from - chunkStart),
+				Math.min(decrypted.length, to - chunkStart),
+			),
+		);
+	}
+
+	return bytesToBase64(concatBytes(pieces));
+}
+
+export async function readArtifact(
+	context: ArtifactContext,
+	id: string,
+	range?: ByteRange,
+): Promise<string> {
+	const path = artifactPath(context.layout, context.scopeKey, id);
+	const key = context.artifactKey(id);
+	try {
+		return key ? await readEncrypted(path, key, range) : await readPlaintext(path, range);
+	} catch (error) {
+		// A typed error the package already classified — an unreadable header,
+		// a failing tag — says something more specific than "missing" and must
+		// survive. Anything else reaching here is the file not being there.
+		if (isStorageError(error)) {
+			throw error;
+		}
+		raise(DiagnosticCodes.ATTACHMENT_MISSING, {
+			message: 'artifact is missing',
+			detail: { attachmentId: id },
+			cause: error,
+		});
+	}
+}
+
+/**
+ * Collects file removals until the transaction that deleted their references
+ * commits. A file unlinked inside the transaction is gone even if the
+ * transaction then rolls back and the reference returns — a dangling
+ * reference to data nobody can recover.
+ */
+export type DeferredUnlinks = {
+	add(path: string): void;
+};
+
+export async function removeArtifact(
+	context: ArtifactContext,
+	id: string,
+	deferred?: DeferredUnlinks,
+): Promise<DeletionOutcome> {
+	const path = artifactPath(context.layout, context.scopeKey, id);
+	if (deferred) {
+		// Inside a transaction: the reference goes now and rolls back with it;
+		// the file goes once the transaction commits.
+		const hadReference = await deleteReference(context.executor(), id);
+		if (hadReference) {
+			deferred.add(path);
+		}
+		return {
+			removedRecords: 0,
+			removedArtifacts: hadReference ? [id] : [],
+			orphanedReferences: [],
+			failedRemovals: [],
+		};
+	}
+	const removed = await removeIfPresent(path);
+	const hadReference = await deleteReference(context.executor(), id);
+
+	return {
+		removedRecords: 0,
+		removedArtifacts: removed ? [id] : [],
+		// A reference with no file left behind is worth reporting rather than
+		// rounding up to success (FR-071).
+		orphanedReferences: !removed && hadReference ? [id] : [],
+		failedRemovals: [],
+	};
+}