@meshline/expo 0.1.0-alpha.1

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@meshline/expo",
+  "version": "0.1.0-alpha.1",
+  "description": "Expo native adapters for the Meshline TypeScript SDK",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "android",
+    "ios",
+    "compatibility",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "meshline-expo-android-compat": "compatibility/apply-android-fix.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@meshline/sdk": "0.1.0-alpha.1",
+    "expo": "57.0.25",
+    "expo-crypto": "^57.0.3",
+    "expo-file-system": "^57.0.7",
+    "expo-modules-core": "57.0.19",
+    "expo-sqlite": "^57.0.3",
+    "react-native": ">=0.86.3 <0.87.0"
+  },
+  "devDependencies": {
+    "expo": "57.0.25",
+    "expo-crypto": "57.0.3",
+    "expo-file-system": "57.0.7",
+    "expo-modules-core": "57.0.19",
+    "expo-sqlite": "57.0.3",
+    "react-native": "0.86.3",
+    "react": "19.2.3",
+    "@types/react-native__assets-registry": "0.84.0",
+    "@types/react": "^19.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meshline-network/sdk.git",
+    "directory": "typescript/packages/expo"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/database-path.ts

@@ -0,0 +1,17 @@
+/** Both Expo SQLite and FileSystem consume file URIs on Android and iOS. */
+export function databaseLocation(directory: string, name: string): { directoryUri: string; encodedName: string; fileUri: string } {
+    if (!name.trim() || name === '.' || name === '..' || /[\x00-\x1f\x7f/\\:?]/.test(name)) throw new TypeError('Expected a persistent SQLite database basename.');
+    if (typeof directory !== 'string' || directory.length === 0) throw new Error('A native SQLite database directory is required.');
+    let path = directory;
+    if (directory.startsWith('file:///')) {
+        if (/[?#]/.test(directory)) throw new TypeError('A database directory URI cannot contain a query or fragment.');
+        path = decodeURIComponent(directory.slice('file://'.length));
+    }
+    if (!path.startsWith('/') || /[\x00-\x1f\x7f\\]/.test(path)) throw new TypeError('Expected an absolute local database directory or file URI.');
+    // Android's defaultDatabaseDirectory is an absolute path without a URI scheme.
+    // Escape each component once so #, %, spaces and Unicode name the same file
+    // in the existence probe and in SQLite's native URI-to-path conversion.
+    const directoryUri = `file://${path.split('/').map(encodeURIComponent).join('/').replace(/\/+$/, '')}`;
+    const encodedName = encodeURIComponent(name);
+    return { directoryUri, encodedName, fileUri: `${directoryUri}/${encodedName}` };
+}

package/src/http.ts

@@ -0,0 +1,44 @@
+import { throwIfAborted, type RelayFetch, type RelayFetchInit, type RelayFetchResponse } from '@meshline/sdk';
+
+interface NativeResponse extends Omit<RelayFetchResponse, 'body'> { readonly body: ReadableStream<Uint8Array> | null }
+
+/** Read the abort/error-aware stream, not Expo's native arrayBuffer fast path:
+ * that path can remain pending when native state becomes ERROR_RECEIVED. */
+export function createExpoRelayFetch(fetch: (url: string, init: RelayFetchInit) => Promise<NativeResponse>): RelayFetch {
+    return async (url, init) => {
+        throwIfAborted(init.signal);
+        const response = await fetch(url, { ...init, headers: { ...init.headers, 'Cache-Control': 'no-store, no-cache', Pragma: 'no-cache' }, credentials: 'omit', redirect: 'error' });
+        const body = response.body; let consumed = false;
+        return {
+            status: response.status, headers: response.headers,
+            ...(response.redirected === undefined ? {} : { redirected: response.redirected }), ...(response.type === undefined ? {} : { type: response.type }),
+            body: body ? { async cancel() { consumed = true; await body.cancel(); } } : null,
+            async arrayBuffer() {
+                throwIfAborted(init.signal);
+                if (consumed) throw new TypeError('Response body has already been consumed.'); consumed = true;
+                if (!body) return new ArrayBuffer(0);
+                const reader = body.getReader(); const chunks: Uint8Array[] = []; let length = 0;
+                let cancellation: Promise<void> | undefined; let cancellationFailure: { error: unknown } | undefined;
+                const abort = () => {
+                    // Observe cancellation immediately, then propagate any failure
+                    // in finally after the pending read settles and its lock releases.
+                    cancellation = reader.cancel(init.signal.reason).then(() => undefined, error => { cancellationFailure = { error }; });
+                };
+                init.signal.addEventListener('abort', abort, { once: true });
+                try {
+                    for (;;) {
+                        const chunk = await reader.read(); throwIfAborted(init.signal);
+                        if (chunk.done) break; chunks.push(chunk.value); length += chunk.value.byteLength;
+                    }
+                    const bytes = new Uint8Array(length); let offset = 0;
+                    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+                    return bytes.buffer;
+                } finally {
+                    init.signal.removeEventListener('abort', abort);
+                    try { await cancellation; if (cancellationFailure) throw cancellationFailure.error; }
+                    finally { reader.releaseLock(); }
+                }
+            },
+        };
+    };
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+import { fetch as nativeFetch } from 'expo/fetch';
+import { getRandomValues } from 'expo-crypto';
+import { File } from 'expo-file-system';
+import { defaultDatabaseDirectory, openDatabaseAsync } from 'expo-sqlite';
+import { type RandomSource } from '@meshline/sdk';
+import { NativeSqliteStore } from './sqlite-store.js';
+import { requireNativeModule } from 'expo';
+import { nativeSocketFactory, type NativeSocketModule } from './socket.js';
+import type { RelaySocketFactory } from '@meshline/sdk';
+import { databaseLocation } from './database-path.js';
+import { createExpoRelayFetch } from './http.js';
+
+/** Requires a development/production build containing this package's native module. */
+export function createExpoSocketFactory(): RelaySocketFactory {
+    return nativeSocketFactory(requireNativeModule<NativeSocketModule>('MeshlineRelaySocket'));
+}
+
+export interface ExpoSqliteStoreOptions {
+    /** Persistent database basename, not an absolute path or SQLite connection URI. */
+    readonly databaseName: string;
+    /** Absolute app-private directory path or local file URI. Omit to use expo-sqlite's default. */
+    readonly directory?: string;
+}
+
+/** Native SQLite storage for Expo Modules applications; constructors never open or create files. */
+export class ExpoSqliteStore extends NativeSqliteStore {
+    constructor(options: ExpoSqliteStoreOptions) {
+        const location = databaseLocation(options.directory ?? defaultDatabaseDirectory, options.databaseName);
+        super({
+            async exists() { return new File(location.fileUri).exists; },
+            open() { return openDatabaseAsync(location.encodedName, { useNewConnection: true }, location.directoryUri); },
+        });
+    }
+}
+
+/** This API always uses the native cryptographic source, including development builds. */
+export const expoRandom: RandomSource = {
+    bytes(length) {
+        if (!Number.isSafeInteger(length) || length < 0) throw new RangeError('Invalid random byte count.');
+        const bytes = new Uint8Array(length);
+        for (let offset = 0; offset < length; offset += 65536) getRandomValues(bytes.subarray(offset, offset + 65536));
+        return bytes;
+    },
+};
+
+/** Uses expo/fetch explicitly: React Native's legacy global fetch cannot enforce these transport policies. */
+export const expoRelayFetch = createExpoRelayFetch((url, init) => nativeFetch(url, init));

package/src/socket.ts

@@ -0,0 +1,93 @@
+import { encodeUtf8, webEndpoint, type RelaySocket, type RelaySocketEvents, type RelaySocketFactory } from '@meshline/sdk';
+
+/** Internal Expo Modules contract, separated from module loading for adapter tests. */
+export interface NativeSocketEvent {
+    readonly id: number;
+    readonly type: 'open' | 'text' | 'binary' | 'error' | 'close';
+    readonly text?: string;
+    readonly message?: string;
+    readonly code?: number;
+    readonly reason?: string;
+}
+export interface NativeSocketModule {
+    connect(id: number, endpoint: string): void;
+    send(id: number, text: string): void;
+    close(id: number, code: number, reason: string): void;
+    cancel(id: number): void;
+    bufferedAmount(id: number): number;
+    addListener(event: 'socket', listener: (event: NativeSocketEvent) => void): { remove(): void };
+}
+
+let nextId = 0;
+
+/** The native implementation owns TLS, cookie/redirect policy and actual RFC close codes. */
+export function nativeSocketFactory(module: NativeSocketModule): RelaySocketFactory {
+    return endpoint => {
+        const normalized = webEndpoint(endpoint, 'wss:').href;
+        if (nextId === Number.MAX_SAFE_INTEGER) throw new Error('Native socket identifiers are exhausted.');
+        const id = ++nextId;
+        let state = 0; let connected = false; let timer: ReturnType<typeof setTimeout> | undefined;
+        const listeners = new Map<keyof RelaySocketEvents, Set<(value: never) => void>>();
+        function emit<K extends keyof RelaySocketEvents>(event: K, value: RelaySocketEvents[K]): void {
+            for (const listener of [...listeners.get(event) ?? []]) listener(value as never);
+        }
+        function finish(code: number, reason: string): void {
+            if (state === 3) return;
+            state = 3; clearTimeout(timer); subscription.remove();
+            try { emit('close', { code, reason }); } finally { listeners.clear(); }
+        }
+        function fail(error: unknown): void {
+            if (state === 3) return;
+            try { emit('error', error instanceof Error ? error : new Error(String(error))); }
+            finally {
+                try { if (connected) module.cancel(id); }
+                finally { finish(1006, 'Native WebSocket failed.'); }
+            }
+        }
+        const subscription = module.addListener('socket', event => {
+            if (event.id !== id || state === 3) return;
+            switch (event.type) {
+                case 'open': if (state === 0) { state = 1; emit('open', undefined); } break;
+                case 'text': if (state === 1) emit('message', event.text); break;
+                case 'binary': if (state === 1) emit('message', new Uint8Array()); break;
+                case 'error': fail(new Error(event.message ?? 'Native WebSocket failed.')); break;
+                case 'close': finish(event.code ?? 1006, event.reason ?? ''); break;
+            }
+        });
+        // RpcConnection installs all event handlers before native callbacks can fire.
+        queueMicrotask(() => {
+            if (state !== 0) return;
+            connected = true;
+            try { module.connect(id, normalized); } catch (error) { fail(error); }
+        });
+        const socket: RelaySocket = {
+            get readyState() { return state; },
+            get bufferedAmount() { return connected && state !== 3 ? module.bufferedAmount(id) : 0; },
+            send(text) {
+                if (state !== 1) throw new Error('Native WebSocket is not open.');
+                // Reject malformed UTF-16 before a native bridge can replace it.
+                encodeUtf8(text); module.send(id, text);
+            },
+            close(code, reason) {
+                if (!Number.isInteger(code) || !([1000, 1001, 1002, 1003, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014].includes(code) || code >= 3000 && code <= 4999)) throw new RangeError('Invalid WebSocket close code.');
+                if (encodeUtf8(reason).length > 123) throw new RangeError('WebSocket close reason exceeds 123 UTF-8 bytes.');
+                if (state >= 2) return code;
+                state = 2;
+                if (!connected) { queueMicrotask(() => finish(code, reason)); return code; }
+                try { module.close(id, code, reason); } catch (error) { fail(error); throw error; }
+                if (state !== 3) timer = setTimeout(() => {
+                    try { module.cancel(id); } catch (error) { emit('error', error instanceof Error ? error : new Error(String(error))); }
+                    finally { finish(1006, 'Native WebSocket close handshake timed out.'); }
+                }, 3000);
+                return code;
+            },
+            on(event, listener) {
+                if (state === 3) return () => {};
+                let set = listeners.get(event); if (!set) { set = new Set(); listeners.set(event, set); }
+                set.add(listener as (value: never) => void);
+                return () => { set.delete(listener as (value: never) => void); };
+            },
+        };
+        return socket;
+    };
+}

package/src/sqlite-store.ts

@@ -0,0 +1,187 @@
+import {
+    AsyncGate, StateConflictError, bindingJson, canonicalJson, parseJson, prepareCommit, requireBatchCount,
+    requireObject, throwIfAborted, validateRecordQuery, type MeshlineStore, type QueryReader, type RecordQuery,
+    type StorageBinding, type StoredRecord, type StoreMutation, type StoreSnapshot,
+} from '@meshline/sdk';
+
+/** Private adapter boundary, also exercised against a real SQLite driver in contract tests. */
+export interface SqliteDatabase {
+    execAsync(sql: string): Promise<void>;
+    runAsync(sql: string, ...parameters: (string | number | null)[]): Promise<unknown>;
+    getFirstAsync<T>(sql: string, ...parameters: (string | number | null)[]): Promise<T | null>;
+    getAllAsync<T>(sql: string, ...parameters: (string | number | null)[]): Promise<T[]>;
+    closeAsync(): Promise<void>;
+}
+export interface SqliteRuntime {
+    exists(): Promise<boolean>;
+    /** Every call MUST return a new, private native connection. Never use Expo's shared connection cache. */
+    open(): Promise<SqliteDatabase>;
+}
+interface Row { collection: string; key: string; revision: number; value: string }
+function decodeRow(row: Row): StoredRecord { return { collection: row.collection, key: row.key, revision: row.revision, value: requireObject(parseJson(row.value)) }; }
+function selection(query: RecordQuery) {
+    validateRecordQuery(query);
+    let where = 'collection = ?'; const parameters: (string | number | null)[] = [query.collection];
+    if (query.key !== undefined) { where += ' AND key = ?'; parameters.push(query.key); }
+    else if (query.prefix !== undefined) { where += ' AND key >= ? AND key < ?'; parameters.push(query.prefix, query.prefix + '\uffff'); }
+    return { where, parameters, order: query.reverse ? 'DESC' : 'ASC' };
+}
+
+/** Serialized private writer and independent WAL snapshots, with no transaction spanning application callbacks. */
+export class NativeSqliteStore implements MeshlineStore {
+    readonly #gate = new AsyncGate();
+    readonly #readers = new Set<NativeReader>();
+    #database: SqliteDatabase | undefined;
+    #disposed = false;
+    #disposal: Promise<void> | undefined;
+    constructor(readonly runtime: SqliteRuntime) {}
+
+    migrate(signal?: AbortSignal): Promise<void> {
+        this.#check();
+        return this.#gate.run(async () => {
+            this.#check(); throwIfAborted(signal);
+            if (this.#database) throw new Error('Migrate before initializing storage.');
+            const database = await this.runtime.open();
+            try {
+                await database.execAsync('PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL;');
+                await transaction(database, 'IMMEDIATE', async () => {
+                    const version = (await database.getFirstAsync<{ user_version: number }>('PRAGMA user_version'))!.user_version;
+                    if (version > 1) throw new Error(`Unsupported database schema ${version}.`);
+                    if (version === 0) await database.execAsync(`
+                        CREATE TABLE meshline_meta (id INTEGER PRIMARY KEY CHECK(id = 1), binding TEXT, version INTEGER NOT NULL CHECK(version >= 0));
+                        INSERT INTO meshline_meta VALUES (1, NULL, 0);
+                        CREATE TABLE meshline_records (collection TEXT NOT NULL, key TEXT NOT NULL, revision INTEGER NOT NULL, value TEXT NOT NULL,
+                            PRIMARY KEY(collection, key)) WITHOUT ROWID;
+                        PRAGMA user_version = 1;
+                    `);
+                }, signal);
+            } finally { await database.closeAsync(); }
+        }, signal);
+    }
+
+    initialize(binding: StorageBinding, signal?: AbortSignal): Promise<void> {
+        this.#check(); const encoded = bindingJson(binding);
+        return this.#gate.run(async () => {
+            this.#check(); throwIfAborted(signal);
+            if (this.#database) {
+                const existing = await this.#database.getFirstAsync<{ binding: string }>('SELECT binding FROM meshline_meta WHERE id = 1');
+                if (existing?.binding !== encoded) throw new Error('Database is bound to another network or account.');
+                return;
+            }
+            if (!await this.runtime.exists()) throw new Error('Database must be explicitly migrated before initialization.');
+            const database = await this.runtime.open();
+            try {
+                const version = (await database.getFirstAsync<{ user_version: number }>('PRAGMA user_version'))!.user_version;
+                if (version !== 1) throw new Error('Database must be explicitly migrated before initialization.');
+                await database.execAsync('PRAGMA busy_timeout = 5000; PRAGMA synchronous = FULL;');
+                await transaction(database, 'IMMEDIATE', async () => {
+                    const current = await database.getFirstAsync<{ binding: string | null }>('SELECT binding FROM meshline_meta WHERE id = 1');
+                    if (!current) throw new Error('Missing Meshline database metadata.');
+                    if (current.binding !== null && current.binding !== encoded) throw new Error('Database is bound to another network or account.');
+                    if (current.binding === null) await database.runAsync('UPDATE meshline_meta SET binding = ? WHERE id = 1', encoded);
+                }, signal);
+                this.#database = database;
+            } catch (error) { await database.closeAsync(); throw error; }
+        }, signal);
+    }
+
+    read(queries: readonly RecordQuery[], signal?: AbortSignal): Promise<StoreSnapshot> {
+        this.#check(); const selected = queries.map(selection);
+        return this.#gate.run(async () => {
+            const database = this.#connection();
+            return transaction(database, 'DEFERRED', async () => {
+                const version = (await database.getFirstAsync<{ version: number }>('SELECT version FROM meshline_meta WHERE id = 1'))!.version;
+                const sets: StoredRecord[][] = [];
+                for (const query of selected) sets.push((await database.getAllAsync<Row>(`SELECT * FROM meshline_records WHERE ${query.where} ORDER BY key ${query.order}`, ...query.parameters)).map(decodeRow));
+                return { version, sets };
+            }, signal);
+        }, signal);
+    }
+
+    commit(expectedVersion: number, mutations: readonly StoreMutation[], signal?: AbortSignal): Promise<number> {
+        this.#check(); const changes = prepareCommit(expectedVersion, mutations);
+        return this.#gate.run(async () => {
+            const database = this.#connection();
+            return transaction(database, 'IMMEDIATE', async () => {
+                const version = (await database.getFirstAsync<{ version: number }>('SELECT version FROM meshline_meta WHERE id = 1'))!.version;
+                if (version !== expectedVersion) throw new StateConflictError('Database revision changed before commit.');
+                const next = expectedVersion + 1;
+                for (const change of changes) {
+                    throwIfAborted(signal);
+                    if (change.kind === 'put') await database.runAsync('INSERT INTO meshline_records VALUES (?, ?, ?, ?) ON CONFLICT(collection, key) DO UPDATE SET revision = excluded.revision, value = excluded.value', change.collection, change.key, next, canonicalJson(change.value));
+                    else await database.runAsync('DELETE FROM meshline_records WHERE collection = ? AND key = ?', change.collection, change.key);
+                }
+                await database.runAsync('UPDATE meshline_meta SET version = ? WHERE id = 1', next);
+                return next;
+            }, signal);
+        }, signal);
+    }
+
+    openQuery(query: RecordQuery, signal?: AbortSignal): Promise<QueryReader<StoredRecord>> {
+        this.#check(); const selected = selection(query);
+        return this.#gate.run(async () => {
+            this.#connection(); throwIfAborted(signal);
+            const database = await this.runtime.open();
+            try {
+                await database.execAsync('PRAGMA busy_timeout = 5000; PRAGMA query_only = ON; BEGIN DEFERRED;');
+                // Reading a real table pins the WAL snapshot before returning to application code.
+                await database.getFirstAsync('SELECT version FROM meshline_meta WHERE id = 1');
+                throwIfAborted(signal);
+                const reader = new NativeReader(database, selected, () => this.#readers.delete(reader));
+                this.#readers.add(reader); return reader;
+            } catch (error) { await database.closeAsync(); throw error; }
+        }, signal);
+    }
+
+    #check(): void { if (this.#disposed) throw new Error('Store is disposed.'); }
+    #connection(): SqliteDatabase { this.#check(); if (!this.#database) throw new Error('Store is not initialized.'); return this.#database; }
+    dispose(): Promise<void> {
+        this.#disposed = true;
+        return this.#disposal ??= this.#gate.run(async () => {
+            const failures: unknown[] = [];
+            for (const reader of this.#readers) { try { await reader.dispose(); } catch (error) { failures.push(error); } }
+            try { await this.#database?.closeAsync(); } catch (error) { failures.push(error); }
+            this.#database = undefined;
+            if (failures.length) throw new AggregateError(failures, 'Failed to dispose native SQLite storage.');
+        });
+    }
+}
+
+async function transaction<T>(database: SqliteDatabase, mode: 'IMMEDIATE' | 'DEFERRED', action: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    throwIfAborted(signal); await database.execAsync(`BEGIN ${mode}`);
+    try {
+        const result = await action(); throwIfAborted(signal);
+        await database.execAsync('COMMIT'); return result;
+    } catch (error) {
+        try { await database.execAsync('ROLLBACK'); }
+        catch (rollbackError) { throw new AggregateError([error, rollbackError], 'SQLite operation and rollback both failed.'); }
+        throw error;
+    }
+}
+
+class NativeReader implements QueryReader<StoredRecord> {
+    readonly #gate = new AsyncGate();
+    #offset = 0;
+    #completed = false;
+    #disposed = false;
+    #disposal: Promise<void> | undefined;
+    constructor(readonly database: SqliteDatabase, readonly query: ReturnType<typeof selection>, readonly released: () => void) {}
+    readNext(count: number, signal?: AbortSignal): Promise<readonly StoredRecord[]> {
+        requireBatchCount(count);
+        return this.#gate.run(async () => {
+            if (this.#disposed) throw new Error('Reader is disposed.');
+            throwIfAborted(signal); if (this.#completed) return [];
+            const rows = await this.database.getAllAsync<Row>(`SELECT * FROM meshline_records WHERE ${this.query.where} ORDER BY key ${this.query.order} LIMIT ? OFFSET ?`, ...this.query.parameters, count, this.#offset);
+            const records = rows.map(decodeRow); throwIfAborted(signal);
+            this.#offset += records.length; this.#completed = records.length < count;
+            return records;
+        }, signal);
+    }
+    dispose(): Promise<void> {
+        this.#disposed = true;
+        return this.#disposal ??= this.#gate.run(async () => {
+            try { await this.database.execAsync('ROLLBACK'); }
+            finally { try { await this.database.closeAsync(); } finally { this.released(); } }
+        });
+    }
+}