@chipmobilesdk/rn-local-db 0.1.0

package/src/testing/conformance/attachments.ts

@@ -0,0 +1,136 @@
+import { DiagnosticCodes } from '../../contract/errors';
+import { isCode } from '../../diagnostics/errors';
+import type { ConformanceContext } from './index';
+
+/** US7: artifacts the package owns, and the reconciliation that keeps them honest. */
+export function registerAttachmentConformance(context: ConformanceContext): void {
+	describe('conformance: attachments', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'guest' } as const;
+		const content = Buffer.from('hello attachment', 'utf8').toString('base64');
+
+		it('stores a reference alongside the artifact', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			const reference = await attachments.write({
+				id: 'a1',
+				owner: { collection: 'notes', id: 'n1' },
+				contentType: 'text/plain',
+				content,
+			});
+
+			expect(reference.size).toBe(Buffer.from(content, 'base64').length);
+			expect(await attachments.read('a1')).toBe(content);
+			expect((await attachments.availability('a1')).state).toBe('available');
+			await handle.close();
+		});
+
+		it('reads a byte range without materialising the whole artifact', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
+
+			const slice = await attachments.read('a1', { offset: 0, length: 5 });
+			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('hello');
+			await handle.close();
+		});
+
+		it('lists the attachments belonging to a record', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			await attachments.write({
+				id: 'a1',
+				owner: { collection: 'notes', id: 'n1' },
+				contentType: 'text/plain',
+				content,
+			});
+			await attachments.write({ id: 'a2', contentType: 'text/plain', content });
+
+			const owned = await attachments.listFor({ collection: 'notes', id: 'n1' });
+			expect(owned.map(r => r.id)).toEqual(['a1']);
+			await handle.close();
+		});
+
+		it('reports a missing artifact without making the record unreadable', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.collection('notes').insert({ id: 'n1', data: { title: 'has media' } });
+			const attachments = handle.attachments();
+			await attachments.write({
+				id: 'a1',
+				owner: { collection: 'notes', id: 'n1' },
+				contentType: 'text/plain',
+				content,
+			});
+
+			// Remove the artifact behind the package's back.
+			await context.removeArtifactBehindTheScenes(handle.scopeKey, 'a1');
+
+			expect((await attachments.availability('a1')).state).toBe('missing');
+			expect((await handle.collection('notes').get('n1')).data.title).toBe('has media');
+			await handle.close();
+		});
+
+		it('finds an orphaned artifact and a dangling reference', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
+			await context.removeReferenceBehindTheScenes(handle.scopeKey, 'a1');
+
+			await attachments.write({ id: 'a2', contentType: 'text/plain', content });
+			await context.removeArtifactBehindTheScenes(handle.scopeKey, 'a2');
+
+			const report = await attachments.reconcile();
+			expect(report.orphanedArtifacts).toEqual(['a1']);
+			expect(report.danglingReferences).toEqual(['a2']);
+
+			const removed = await attachments.reconcile({ removeOrphans: true });
+			expect(removed.removedArtifacts).toEqual(['a1']);
+			expect((await attachments.reconcile()).orphanedArtifacts).toEqual([]);
+			await handle.close();
+		});
+
+		it('rolls a reference back with its transaction', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			try {
+				await handle.transaction(async tx => {
+					await tx.collection('notes').insert({ id: 'n1', data: { title: 'x' } });
+					await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
+					throw new Error('injected');
+				});
+			} catch {
+				// Expected.
+			}
+
+			expect(await handle.collection('notes').find('n1')).toBeNull();
+			// The reference is gone; the artifact on disk is not, which is
+			// exactly why reconciliation exists.
+			const report = await handle.attachments().reconcile();
+			expect(report.orphanedArtifacts).toEqual(['a1']);
+			await handle.close();
+		});
+
+		it('rejects an artifact over the size budget', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const huge = Buffer.alloc(101 * 1024 * 1024).toString('base64');
+
+			let thrown: unknown;
+			try {
+				await handle.attachments().write({ id: 'big', contentType: 'application/octet-stream', content: huge });
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.ATTACHMENT_WRITE_FAILED)).toBe(true);
+			await handle.close();
+		});
+
+		it('removes artifacts when the scope is deleted', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
+			await handle.close();
+
+			const outcome = await context.adapter.deleteScopeData(context.scopeTargetFor(scope));
+			expect(outcome.removedArtifacts).toContain('a1');
+		});
+	});
+}

package/src/testing/conformance/encryption.ts

@@ -0,0 +1,150 @@
+import { DiagnosticCodes } from '../../contract/errors';
+import type { KeyProvider } from '../../contract/encryption';
+import { isCode } from '../../diagnostics/errors';
+import type { ConformanceContext } from './index';
+
+/** US10: opt-in encryption, and failures that stay apart from each other. */
+export function registerEncryptionConformance(context: ConformanceContext): void {
+	describe('conformance: encryption', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'identity', id: 'encrypted' } as const;
+		const keyProvider: KeyProvider = { getKey: async () => 'a-correct-key-32-bytes-long-value' };
+
+		const encrypted = { enabled: true as const, keyProvider };
+
+		it('reports its own posture', async () => {
+			const handle = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			expect(handle.isEncrypted).toBe(true);
+			await handle.close();
+
+			const plain = await context.adapter.open(
+				context.configFor({ kind: 'identity', id: 'plain' }, { encryption: undefined }),
+			);
+			expect(plain.isEncrypted).toBe(false);
+			await plain.close();
+		});
+
+		it('stores and returns records unchanged under encryption', async () => {
+			const handle = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			const data = { title: 'secret', score: 1, nested: { deep: [1, null, true] } };
+			await handle.collection('notes').insert({ id: 'a', data });
+			expect((await handle.collection('notes').get('a')).data).toEqual(data);
+			await handle.close();
+
+			const reopened = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			expect((await reopened.collection('notes').get('a')).data).toEqual(data);
+			await reopened.close();
+		});
+
+		it('round-trips an artifact under encryption, including a byte range', async () => {
+			const handle = await context.adapter.open(
+				context.configFor(scope, { encryption: encrypted }),
+			);
+			const content = Buffer.from('hello encrypted attachment', 'utf8').toString('base64');
+			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
+
+			expect(await handle.attachments().read('a1')).toBe(content);
+			const slice = await handle.attachments().read('a1', { offset: 6, length: 9 });
+			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('encrypted');
+			expect((await handle.attachments().availability('a1')).state).toBe('available');
+			await handle.close();
+		});
+
+		it('reports a key-provider failure separately from an invalid key', async () => {
+			let thrown: unknown;
+			try {
+				await context.adapter.open(
+					context.configFor(scope, {
+						encryption: {
+							enabled: true,
+							keyProvider: {
+								getKey: async () => {
+									throw new Error('device is locked');
+								},
+							},
+						},
+					}),
+				);
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.KEY_PROVIDER_FAILED)).toBe(true);
+
+			let empty: unknown;
+			try {
+				await context.adapter.open(
+					context.configFor(scope, {
+						encryption: { enabled: true, keyProvider: { getKey: async () => '' } },
+					}),
+				);
+			} catch (error) {
+				empty = error;
+			}
+			expect(isCode(empty, DiagnosticCodes.KEY_INVALID)).toBe(true);
+		});
+
+		it('reports a posture mismatch rather than opening or converting', async () => {
+			const plain = await context.adapter.open(context.configFor(scope));
+			await plain.collection('notes').insert({ id: 'a', data: { title: 'plaintext' } });
+			await plain.close();
+
+			let thrown: unknown;
+			try {
+				await context.adapter.open(context.configFor(scope, { encryption: encrypted }));
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.ENCRYPTION_MISMATCH)).toBe(true);
+
+			// Nothing was converted, truncated, or discarded.
+			const reopened = await context.adapter.open(context.configFor(scope));
+			expect((await reopened.collection('notes').get('a')).data.title).toBe('plaintext');
+			await reopened.close();
+		});
+
+		it('gives the key provider the scope, so an app can key per identity', async () => {
+			const seen: string[] = [];
+			const recording: KeyProvider = {
+				getKey: async resolved => {
+					seen.push(resolved.key);
+					return `key-for-${resolved.key}`;
+				},
+			};
+
+			for (const id of ['alice', 'bob']) {
+				const handle = await context.adapter.open(
+					context.configFor(
+						{ kind: 'identity', id },
+						{ encryption: { enabled: true, keyProvider: recording } },
+					),
+				);
+				await handle.close();
+			}
+
+			expect(seen).toHaveLength(2);
+			expect(new Set(seen).size).toBe(2);
+			for (const key of seen) {
+				expect(key).toMatch(/^[0-9a-f]{64}$/);
+			}
+		});
+
+		it('keeps an encrypted scope isolated from an unencrypted sibling', async () => {
+			const secure = await context.adapter.open(
+				context.configFor({ kind: 'identity', id: 'secure' }, { encryption: encrypted }),
+			);
+			await secure.collection('notes').insert({ id: 'shared', data: { title: 'secure' } });
+			await secure.close();
+
+			const open = await context.adapter.open(context.configFor({ kind: 'identity', id: 'open' }));
+			expect(await open.collection('notes').find('shared')).toBeNull();
+			await open.close();
+		});
+	});
+}

package/src/testing/conformance/index.ts

@@ -0,0 +1,161 @@
+/**
+ * The conformance suite: the executable definition of what the package
+ * guarantees (FR-092).
+ *
+ * Exported rather than kept internal so a consuming team can run it against
+ * their own adapter if one ever exists, and so both of ours are held to
+ * exactly the same standard rather than to two similar-looking test files.
+ */
+
+import type { StorageAdapter } from '../../contract/adapter';
+import type { DatabaseConfig, ScopeTargetConfig } from '../../contract/config';
+import type { EncryptionConfig } from '../../contract/encryption';
+import type { ScopeDescriptor } from '../../contract/scope';
+import { registerRecordConformance } from './records';
+import { registerScopeConformance } from './scopes';
+import { registerQueryConformance } from './queries';
+import { registerTransactionConformance } from './transactions';
+import { registerMigrationConformance } from './migrations';
+import { registerLifecycleConformance } from './lifecycle';
+import { registerAttachmentConformance } from './attachments';
+import { registerEncryptionConformance } from './encryption';
+
+export type ConformanceContext = {
+	adapter: StorageAdapter;
+	/** A fresh config for the given scope, using the standard test schema. */
+	configFor(scope: ScopeDescriptor, overrides?: Partial<DatabaseConfig>): DatabaseConfig;
+	/**
+	 * How an app names a scope for deletion.
+	 *
+	 * Carries the encryption config when the run is encrypted, because that is
+	 * how a real consumer calls it: `ScopeTargetConfig.encryption` exists so
+	 * deletion can report what it removed rather than guessing at it.
+	 */
+	scopeTargetFor(scope: ScopeDescriptor): ScopeTargetConfig;
+	reset(): Promise<void>;
+	/**
+	 * Reach past the package and delete an artifact the way the operating
+	 * system does when it reclaims storage. Each adapter supplies its own,
+	 * because the suite cannot simulate this through the public API without
+	 * asking the package to break its own guarantee.
+	 */
+	removeArtifactBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void>;
+	/** The other direction: a reference whose artifact survives. */
+	removeReferenceBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void>;
+};
+
+export type ConformanceHooks = Pick<
+	ConformanceContext,
+	'removeArtifactBehindTheScenes' | 'removeReferenceBehindTheScenes'
+>;
+
+export type ConformanceOptions = {
+	/** Sections the adapter knowingly cannot satisfy, with a documented reason. */
+	skip?: ConformanceSection[];
+	/**
+	 * Run every section against an encrypted database (FR-105).
+	 *
+	 * The suite is the contract, so the contract has to hold in both postures
+	 * — an encrypted database that quietly behaved differently would be a
+	 * second implementation nobody tested.
+	 */
+	encryption?: EncryptionConfig;
+};
+
+export type ConformanceSection =
+	| 'records'
+	| 'scopes'
+	| 'queries'
+	| 'transactions'
+	| 'migrations'
+	| 'lifecycle'
+	| 'attachments'
+	| 'encryption';
+
+export const TEST_COLLECTIONS: DatabaseConfig['collections'] = [
+	{
+		name: 'notes',
+		fields: [
+			{ name: 'title', type: 'string' },
+			{ name: 'score', type: 'number' },
+			{ name: 'done', type: 'boolean' },
+			{ name: 'updated', type: 'timestamp' },
+		],
+		indexes: [{ name: 'notes_by_score', fields: ['score'] }],
+		softDelete: true,
+		timestamps: true,
+	},
+	{
+		name: 'plain',
+		fields: [{ name: 'label', type: 'string' }],
+	},
+];
+
+export function makeConformanceContext(
+	adapter: StorageAdapter,
+	reset: () => Promise<void>,
+	hooks: ConformanceHooks,
+	defaults: Partial<DatabaseConfig> = {},
+): ConformanceContext {
+	return {
+		adapter,
+		reset,
+		...hooks,
+		configFor(scope, overrides = {}) {
+			return {
+				name: 'conformance',
+				scope,
+				schemaVersion: 1,
+				collections: TEST_COLLECTIONS,
+				migrations: [{ version: 1, migrate: async () => {} }],
+				...defaults,
+				...overrides,
+			};
+		},
+		scopeTargetFor(scope) {
+			return {
+				name: 'conformance',
+				scope,
+				...(defaults.encryption ? { encryption: defaults.encryption } : {}),
+			};
+		},
+	};
+}
+
+/**
+ * Registers the whole suite against one adapter. Both adapters call this with
+ * the same arguments; any difference in outcome is a divergence that must be
+ * documented under FR-096 or fixed.
+ */
+export function runConformanceSuite(
+	factory: () => StorageAdapter,
+	reset: () => Promise<void>,
+	hooks: ConformanceHooks,
+	options: ConformanceOptions = {},
+): void {
+	const skip = new Set(options.skip ?? []);
+	const context = makeConformanceContext(
+		factory(),
+		reset,
+		hooks,
+		options.encryption ? { encryption: options.encryption } : {},
+	);
+
+	const sections: [ConformanceSection, (c: ConformanceContext) => void][] = [
+		['records', registerRecordConformance],
+		['scopes', registerScopeConformance],
+		['queries', registerQueryConformance],
+		['transactions', registerTransactionConformance],
+		['migrations', registerMigrationConformance],
+		['lifecycle', registerLifecycleConformance],
+		['attachments', registerAttachmentConformance],
+		['encryption', registerEncryptionConformance],
+	];
+
+	for (const [name, register] of sections) {
+		if (skip.has(name)) {
+			continue;
+		}
+		register(context);
+	}
+}

package/src/testing/conformance/lifecycle.ts

@@ -0,0 +1,99 @@
+import type { ScopeDescriptor } from '../../contract/scope';
+import type { ConformanceContext } from './index';
+
+/** US6: sign-out retains; deletion happens only when asked, and only where asked. */
+export function registerLifecycleConformance(context: ConformanceContext): void {
+	describe('conformance: lifecycle', () => {
+		beforeEach(() => context.reset());
+
+		const alice: ScopeDescriptor = { kind: 'identity', id: 'alice' };
+		const bob: ScopeDescriptor = { kind: 'identity', id: 'bob' };
+
+		it('retains data when a handle is closed without a delete request', async () => {
+			const first = await context.adapter.open(context.configFor(alice));
+			await first.collection('notes').insert({ id: 'a', data: { title: 'kept' } });
+			// Closing the handle is what a sign-out looks like to this package.
+			await first.close();
+
+			const second = await context.adapter.open(context.configFor(alice));
+			expect((await second.collection('notes').get('a')).data.title).toBe('kept');
+			await second.close();
+		});
+
+		it('removes every record in the target scope and nothing else', async () => {
+			const a = await context.adapter.open(context.configFor(alice));
+			await a.collection('notes').insert({ id: 'x', data: { title: 'alice' } });
+			await a.collection('plain').insert({ id: 'y', data: { label: 'alice' } });
+			await a.close();
+
+			const b = await context.adapter.open(context.configFor(bob));
+			await b.collection('notes').insert({ id: 'x', data: { title: 'bob' } });
+			await b.close();
+
+			const outcome = await context.adapter.deleteScopeData(context.scopeTargetFor(alice));
+			expect(outcome.removedRecords).toBe(2);
+
+			const reopenedAlice = await context.adapter.open(context.configFor(alice));
+			expect(await reopenedAlice.collection('notes').count()).toBe(0);
+			expect(await reopenedAlice.collection('plain').count()).toBe(0);
+			await reopenedAlice.close();
+
+			const reopenedBob = await context.adapter.open(context.configFor(bob));
+			expect((await reopenedBob.collection('notes').get('x')).data.title).toBe('bob');
+			await reopenedBob.close();
+		});
+
+		it('reports success for a scope holding no data', async () => {
+			const outcome = await context.adapter.deleteScopeData(
+				context.scopeTargetFor({ kind: 'identity', id: 'never-used' }),
+			);
+			expect(outcome.removedRecords).toBe(0);
+			expect(outcome.failedRemovals).toEqual([]);
+		});
+
+		it('reports what it removed rather than a bare success', async () => {
+			const handle = await context.adapter.open(context.configFor(alice));
+			await handle.collection('notes').insert({ id: 'a', data: { title: 'x' } });
+			await handle.close();
+
+			const outcome = await context.adapter.deleteScopeData(context.scopeTargetFor(alice));
+			expect(outcome).toMatchObject({
+				removedRecords: 1,
+				removedArtifacts: [],
+				orphanedReferences: [],
+				failedRemovals: [],
+			});
+		});
+
+		it('makes the whole database behave as a first install after deleteDatabase', async () => {
+			const handle = await context.adapter.open(context.configFor(alice));
+			await handle.collection('notes').insert({ id: 'a', data: { title: 'x' } });
+			await handle.close();
+
+			await context.adapter.deleteDatabase({ name: 'conformance' });
+
+			const reopened = await context.adapter.open(context.configFor(alice));
+			expect(await reopened.collection('notes').count()).toBe(0);
+			await reopened.close();
+		});
+
+		it('recovers exactly one scope with resetScope', async () => {
+			const a = await context.adapter.open(context.configFor(alice));
+			await a.collection('notes').insert({ id: 'x', data: { title: 'alice' } });
+			await a.close();
+			const b = await context.adapter.open(context.configFor(bob));
+			await b.collection('notes').insert({ id: 'x', data: { title: 'bob' } });
+			await b.close();
+
+			await context.adapter.resetScope(context.scopeTargetFor(alice));
+
+			const reopenedAlice = await context.adapter.open(context.configFor(alice));
+			expect(await reopenedAlice.collection('notes').count()).toBe(0);
+			await reopenedAlice.close();
+
+			const reopenedBob = await context.adapter.open(context.configFor(bob));
+			expect(await reopenedBob.collection('notes').count()).toBe(1);
+			await reopenedBob.close();
+		});
+	});
+}