@meshline/sdk 0.0.0-stage → 0.1.0-alpha.1

package/src/protocol/json.ts

@@ -0,0 +1,140 @@
+import { ProtocolError } from '../errors.js';
+import { decodeUtf8, encodeUtf8, validateUnicode } from './encoding.js';
+
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject { [name: string]: JsonValue }
+export const maximumJsonDepth = 16;
+
+/** Checks the exact safe-integer domain used by protocol JSON. */
+export function requireSafeInteger(value: unknown, minimum = -Number.MAX_SAFE_INTEGER): asserts value is number {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || Object.is(value, -0) || value < minimum)
+        throw new ProtocolError('invalid_integer', 'Expected a safe integer in the allowed range.');
+}
+
+/** Parses protocol JSON before duplicate names or numeric spelling can be lost. */
+export function parseJson(input: string | Uint8Array): JsonValue {
+    const source = typeof input === 'string' ? input : decodeUtf8(input);
+    validateUnicode(source);
+    let position = 0;
+    const fail = (message: string): never => { throw new ProtocolError('invalid_json', `${message} At offset ${position}.`); };
+    const whitespace = (): void => { while (/[\x20\t\r\n]/.test(source[position] ?? '') && position < source.length) position++; };
+
+    function string(): string {
+        const start = position++;
+        while (position < source.length) {
+            const character = source[position++]!;
+            if (character === '"') {
+                let result: string;
+                try { result = JSON.parse(source.slice(start, position)) as string; }
+                catch (cause) { throw new ProtocolError('invalid_json', 'Invalid JSON string.', { cause }); }
+                validateUnicode(result);
+                return result;
+            }
+            if (character === '\\') {
+                const escape = source[position++];
+                if (escape === 'u') {
+                    if (!/^[0-9a-fA-F]{4}$/.test(source.slice(position, position + 4))) fail('Invalid Unicode escape.');
+                    position += 4;
+                } else if (escape === undefined || !'"\\/bfnrt'.includes(escape)) fail('Invalid string escape.');
+            } else if (character.charCodeAt(0) < 32) fail('Unescaped control character.');
+        }
+        return fail('Unterminated string.');
+    }
+
+    function value(depth: number): JsonValue {
+        if (depth > maximumJsonDepth) fail('JSON depth exceeds 16.');
+        whitespace();
+        const character = source[position];
+        if (character === '"') return string();
+        if (character === '{') {
+            position++;
+            const result = Object.create(null) as JsonObject;
+            whitespace();
+            if (source[position] === '}') { position++; return result; }
+            while (true) {
+                whitespace();
+                if (source[position] !== '"') fail('Expected an object property name.');
+                const name = string();
+                if (Object.hasOwn(result, name)) fail('Duplicate property name.');
+                whitespace();
+                if (source[position++] !== ':') fail('Expected a colon.');
+                result[name] = value(depth + 1);
+                whitespace();
+                const separator = source[position++];
+                if (separator === '}') return result;
+                if (separator !== ',') fail('Expected an object separator.');
+            }
+        }
+        if (character === '[') {
+            position++;
+            const result: JsonValue[] = [];
+            whitespace();
+            if (source[position] === ']') { position++; return result; }
+            while (true) {
+                result.push(value(depth + 1));
+                whitespace();
+                const separator = source[position++];
+                if (separator === ']') return result;
+                if (separator !== ',') fail('Expected an array separator.');
+            }
+        }
+        for (const [literal, result] of [['true', true], ['false', false], ['null', null]] as const) {
+            if (source.startsWith(literal, position)) { position += literal.length; return result; }
+        }
+        const start = position;
+        while (position < source.length && /[0-9eE+.\-]/.test(source[position]!)) position++;
+        const token = source.slice(start, position);
+        if (!/^-?(0|[1-9][0-9]*)$/.test(token) || token === '-0') fail('Expected a shortest decimal integer.');
+        const result = Number(token);
+        requireSafeInteger(result);
+        return result;
+    }
+
+    const result = value(0);
+    whitespace();
+    if (position !== source.length) fail('Trailing non-whitespace data.');
+    return result;
+}
+
+/** Encodes only JSON data, preserving unknown properties and UTF-16 key ordering. */
+export function canonicalJson(value: JsonValue): string {
+    function encode(input: JsonValue, depth: number): string {
+        if (depth > maximumJsonDepth) throw new ProtocolError('invalid_json', 'JSON depth exceeds 16.');
+        if (input === null) return 'null';
+        if (typeof input === 'string') { validateUnicode(input); return JSON.stringify(input); }
+        if (typeof input === 'boolean') return input ? 'true' : 'false';
+        if (typeof input === 'number') { requireSafeInteger(input); return String(input); }
+        if (Array.isArray(input)) {
+            const parts: string[] = [];
+            for (let index = 0; index < input.length; index++) {
+                if (!Object.hasOwn(input, index)) throw new ProtocolError('invalid_json', 'Sparse arrays are not JSON data.');
+                parts.push(encode(input[index]!, depth + 1));
+            }
+            return `[${parts.join(',')}]`;
+        }
+        if (typeof input !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(input) as object | null))
+            throw new ProtocolError('invalid_json', 'Expected plain JSON data.');
+        if (Object.getOwnPropertySymbols(input).length !== 0)
+            throw new ProtocolError('invalid_json', 'Symbol properties are not JSON data.');
+        const properties = Object.keys(input).sort().map(name => {
+            validateUnicode(name);
+            const descriptor = Object.getOwnPropertyDescriptor(input, name)!;
+            if (!('value' in descriptor)) throw new ProtocolError('invalid_json', 'JSON properties cannot be accessors.');
+            return `${JSON.stringify(name)}:${encode(descriptor.value as JsonValue, depth + 1)}`;
+        });
+        return `{${properties.join(',')}}`;
+    }
+    return encode(value, 0);
+}
+
+/** Encodes canonical protocol JSON as strict UTF-8. */
+export function canonicalBytes(value: JsonValue): Uint8Array {
+    return encodeUtf8(canonicalJson(value));
+}
+
+/** Requires a JSON object; arrays and null do not qualify. */
+export function requireObject(value: JsonValue): JsonObject {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new ProtocolError('invalid_object', 'Expected a JSON object.');
+    return value;
+}

package/src/protocol/validation.ts

@@ -0,0 +1,13 @@
+import { ProtocolError } from '../errors.js';
+import { canonicalJson, type JsonObject, type JsonValue } from './json.js';
+
+/** Complete business objects do not permit null, including extensions, unless their schema explicitly says otherwise. */
+export function validateCompleteObject(value: JsonObject): void {
+    canonicalJson(value);
+    function visit(node: JsonValue): void {
+        if (node === null) throw new ProtocolError('invalid_null', 'Null is not permitted in this complete protocol object.');
+        if (Array.isArray(node)) for (const item of node) visit(item);
+        else if (typeof node === 'object') for (const item of Object.values(node)) visit(item);
+    }
+    visit(value);
+}

package/src/runtime/abort.ts

@@ -0,0 +1,27 @@
+const fallbackReasons = new WeakMap<AbortSignal, DOMException>();
+const aborted = () => new DOMException('The operation was aborted.', 'AbortError');
+
+/** Legacy caller signals cannot expose a reason their runtime already discarded. */
+export function abortReason(signal: AbortSignal): unknown {
+    if (signal.reason !== undefined) return signal.reason;
+    let reason = fallbackReasons.get(signal);
+    if (!reason) { reason = aborted(); fallbackReasons.set(signal, reason); }
+    return reason;
+}
+
+/** Keep the platform's real signal and synchronous abort event, adding reason
+ * only to SDK-owned legacy signals. Globals and caller-owned signals are untouched. */
+export function createAbortController(): AbortController {
+    const controller = new AbortController();
+    if ('reason' in controller.signal) return controller;
+    let reason: unknown;
+    Object.defineProperty(controller.signal, 'reason', { get: () => reason });
+    return {
+        signal: controller.signal,
+        abort(value?: unknown) {
+            if (controller.signal.aborted) return;
+            reason = value === undefined ? aborted() : value;
+            controller.abort();
+        },
+    };
+}

package/src/runtime/async-gate.ts

@@ -0,0 +1,16 @@
+import { throwIfAborted } from './clock.js';
+
+/** Serializes state changes without poisoning subsequent operations after a failure. */
+export class AsyncGate {
+    private tail: Promise<void> = Promise.resolve();
+
+    run<T>(operation: () => T | Promise<T>, signal?: AbortSignal): Promise<T> {
+        const result = this.tail.then(() => {
+            throwIfAborted(signal);
+            return operation();
+        });
+        // Callers receive the original rejection; only the queue tail is recovered.
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}

package/src/runtime/async-pulse.ts

@@ -0,0 +1,20 @@
+import { throwIfAborted } from './clock.js';
+import { abortReason } from './abort.js';
+
+/** One consumer, coalesced wakeups. Pulses received during processing remain pending. */
+export class AsyncPulse {
+    #pending = false;
+    #wake: (() => void) | undefined;
+    pulse(): void { this.#pending = true; this.#wake?.(); }
+    async wait(signal: AbortSignal): Promise<void> {
+        throwIfAborted(signal);
+        if (this.#wake) throw new Error('AsyncPulse supports only one consumer.');
+        if (!this.#pending) await new Promise<void>((resolve, reject) => {
+            const cleanup = (): void => { this.#wake = undefined; signal.removeEventListener('abort', aborted); };
+            const aborted = (): void => { cleanup(); reject(abortReason(signal)); };
+            this.#wake = () => { cleanup(); resolve(); };
+            signal.addEventListener('abort', aborted, { once: true });
+        });
+        throwIfAborted(signal); this.#pending = false;
+    }
+}

package/src/runtime/clock.ts

@@ -0,0 +1,63 @@
+import { abortReason, createAbortController } from './abort.js';
+
+/** Wall time signs timestamps; monotonic time measures session and backoff lifetimes. */
+export interface RuntimeClock {
+    nowSeconds(): number;
+    monotonicMilliseconds(): number;
+    delay(milliseconds: number, signal?: AbortSignal): Promise<void>;
+}
+
+export function throwIfAborted(signal?: AbortSignal): void {
+    if (signal?.aborted) throw abortReason(signal);
+}
+
+export const systemClock: RuntimeClock = {
+    nowSeconds: () => Math.floor(Date.now() / 1000),
+    monotonicMilliseconds: () => performance.now(),
+    delay(milliseconds, signal) {
+        throwIfAborted(signal);
+        if (!Number.isFinite(milliseconds) || milliseconds < 0 || milliseconds > 60_000)
+            throw new RangeError('An individual delay must be between zero and 60000 milliseconds.');
+        return new Promise<void>((resolve, reject) => {
+            const onAbort = (): void => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                reject(abortReason(signal!));
+            };
+            const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, milliseconds);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    },
+};
+
+/** A caller can abandon a shared operation without canceling other callers' work. */
+export function awaitWithSignal<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+    throwIfAborted(signal);
+    if (!signal) return promise;
+    return new Promise<T>((resolve, reject) => {
+        const onAbort = (): void => { signal.removeEventListener('abort', onAbort); reject(abortReason(signal)); };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(value => { signal.removeEventListener('abort', onAbort); resolve(value); }, error => {
+            signal.removeEventListener('abort', onAbort); reject(error);
+        });
+    });
+}
+
+/** Explicit cleanup avoids accumulating listeners or request deadline timers. */
+export function abortScope(signals: readonly (AbortSignal | undefined)[], timeoutMilliseconds?: number): { signal: AbortSignal; dispose(): void } {
+    const controller = createAbortController();
+    const listeners = new Map<AbortSignal, () => void>();
+    for (const signal of signals) {
+        if (!signal || listeners.has(signal)) continue;
+        const onAbort = (): void => controller.abort(abortReason(signal));
+        if (signal.aborted) onAbort();
+        else { signal.addEventListener('abort', onAbort, { once: true }); listeners.set(signal, onAbort); }
+    }
+    const timer = timeoutMilliseconds === undefined ? undefined : setTimeout(() => {
+        controller.abort(new DOMException('The relay request timed out.', 'TimeoutError'));
+    }, timeoutMilliseconds);
+    return {
+        signal: controller.signal,
+        dispose() { clearTimeout(timer); for (const [signal, listener] of listeners) signal.removeEventListener('abort', listener); listeners.clear(); },
+    };
+}

package/src/runtime/events.ts

@@ -0,0 +1,31 @@
+export type EventListener<T> = (value: T) => void | Promise<void>;
+
+/** Typed subscriptions with awaited dispatch or nonblocking notifications. */
+export class EventHub<Events extends object> {
+    readonly #listeners = new Map<keyof Events, Set<EventListener<never>>>();
+    on<K extends keyof Events>(event: K, listener: EventListener<Events[K]>): () => void {
+        let listeners = this.#listeners.get(event);
+        if (!listeners) { listeners = new Set(); this.#listeners.set(event, listeners); }
+        listeners.add(listener as EventListener<never>);
+        return () => { listeners.delete(listener as EventListener<never>); };
+    }
+    async emit<K extends keyof Events>(event: K, value: Events[K]): Promise<void> {
+        const failures: unknown[] = [];
+        for (const listener of [...(this.#listeners.get(event) ?? [])]) {
+            try { await listener(value as never); }
+            catch (error) { failures.push(error); }
+        }
+        if (failures.length !== 0) throw new AggregateError(failures, `A ${String(event)} event handler failed.`);
+    }
+    /** Invoke every subscriber immediately; application async work never delays other subscribers or the publisher. */
+    notify<K extends keyof Events>(event: K, value: Events[K], failed: (error: AggregateError) => void): void {
+        const failures: unknown[] = [];
+        const report = (errors: unknown[]): void => { if (errors.length) failed(new AggregateError(errors, `A ${String(event)} event handler failed.`)); };
+        for (const listener of [...(this.#listeners.get(event) ?? [])]) {
+            try { const result = listener(value as never); if (result) void Promise.resolve(result).catch(error => report([error])); }
+            catch (error) { failures.push(error); }
+        }
+        report(failures);
+    }
+    clear(): void { this.#listeners.clear(); }
+}

package/src/runtime/url.ts

@@ -0,0 +1,17 @@
+import { toASCII } from 'tr46';
+
+/** Normalize domain names before the platform parser, including Expo's ASCII-only URL. */
+export function parseAbsoluteUrl(input: string): URL {
+    const match = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#]*)([\s\S]*)$/i.exec(input);
+    if (!match) return new URL(input);
+    const authority = match[2]!; const at = authority.lastIndexOf('@');
+    const credentials = authority.slice(0, at + 1); const address = authority.slice(at + 1);
+    if (!address || address.startsWith('[')) return new URL(input); // IPv6 belongs to the URL parser.
+    const colon = address.lastIndexOf(':'); const port = colon === -1 ? '' : address.slice(colon);
+    const host = decodeURIComponent(colon === -1 ? address : address.slice(0, colon));
+    const ascii = toASCII(host, { checkBidi: true, checkJoiners: true, checkHyphens: false,
+        transitionalProcessing: false, useSTD3ASCIIRules: false, verifyDNSLength: false });
+    // Prevent escaped or mapped separators from changing authority boundaries.
+    if (!ascii || /[\u0000-\u0020\u007f#%/:<>?@[\\\]^|]/.test(ascii)) throw new TypeError('Invalid international domain name.');
+    return new URL(match[1]! + credentials + ascii + port + match[3]!);
+}

package/src/storage/signed-request.ts

@@ -0,0 +1,26 @@
+import { ProtocolError } from '../errors.js';
+import { validateRelayId } from '../identity/neo.js';
+import { canonicalJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import type { MeshlineStore, RecordKey, StoreMutation } from './store.js';
+import { updateStore } from './transaction.js';
+
+export interface SignedRequest { readonly relayId: string; readonly revision: number; readonly document: JsonObject; readonly pending: boolean }
+export const requestKey = (method: string): RecordKey => ({ collection: 'signed_requests', key: method });
+export function readSignedRequest(value: JsonObject | undefined): SignedRequest | undefined {
+    if (value === undefined) return undefined;
+    if (typeof value.relayId !== 'string' || typeof value.pending !== 'boolean' || value.document === undefined)
+        throw new ProtocolError('invalid_storage', 'Invalid persisted signed request.');
+    validateRelayId(value.relayId); requireSafeInteger(value.revision, 0);
+    return { relayId: value.relayId, revision: value.revision, document: requireObject(value.document), pending: value.pending };
+}
+export function putSignedRequest(method: string, value: SignedRequest): StoreMutation {
+    return { ...requestKey(method), kind: 'put', value: { ...value } };
+}
+/** Never clear a newer request installed by a different component/process. No caller cancellation. */
+export async function finishSignedRequest(store: MeshlineStore, method: string, expected: SignedRequest): Promise<void> {
+    await updateStore(store, [requestKey(method)], snapshot => {
+        const current = readSignedRequest(snapshot.sets[0]![0]?.value);
+        const matches = current?.pending && current.relayId === expected.relayId && canonicalJson(current.document) === canonicalJson(expected.document);
+        return { mutations: matches ? [putSignedRequest(method, { ...current, pending: false })] : [], result: undefined };
+    });
+}

package/src/storage/store.ts

@@ -0,0 +1,90 @@
+import { ProtocolError } from '../errors.js';
+import { validateAccountId } from '../identity/neo.js';
+import { NetworkContext } from '../protocol/context.js';
+import { canonicalJson, parseJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+
+/** A storage instance belongs to one network/account and its persisted local device. */
+export interface StorageBinding { readonly context: string; readonly accountId: string }
+
+export interface RecordKey { readonly collection: string; readonly key: string }
+export interface StoredRecord extends RecordKey { readonly revision: number; readonly value: JsonObject }
+
+/** Keys are canonical ASCII SDK identifiers or sortable indexes, never user-facing text. */
+export interface RecordQuery {
+    readonly collection: string;
+    readonly key?: string;
+    readonly prefix?: string;
+    readonly reverse?: boolean;
+}
+
+export type StoreMutation = (RecordKey & { readonly kind: 'put'; readonly value: JsonObject })
+    | (RecordKey & { readonly kind: 'delete' });
+
+export interface StoreSnapshot { readonly version: number; readonly sets: readonly (readonly StoredRecord[])[] }
+
+/** Fixed at open time. An empty batch marks completion; dispose releases the snapshot. */
+export interface QueryReader<T> {
+    readNext(count: number, signal?: AbortSignal): Promise<readonly T[]>;
+    dispose(): Promise<void>;
+}
+
+/**
+ * Atomic compare-and-commit storage. Computation, signing, and network I/O happen
+ * outside database transactions. A conflicting commit must be recomputed from a
+ * new read; it must never blindly replay an external business request.
+ */
+export interface MeshlineStore {
+    migrate(signal?: AbortSignal): Promise<void>;
+    initialize(binding: StorageBinding, signal?: AbortSignal): Promise<void>;
+    read(queries: readonly RecordQuery[], signal?: AbortSignal): Promise<StoreSnapshot>;
+    commit(expectedVersion: number, mutations: readonly StoreMutation[], signal?: AbortSignal): Promise<number>;
+    openQuery(query: RecordQuery, signal?: AbortSignal): Promise<QueryReader<StoredRecord>>;
+    dispose(): Promise<void>;
+}
+
+export function bindingJson(binding: StorageBinding): string {
+    NetworkContext.parse(binding.context);
+    validateAccountId(binding.accountId);
+    return canonicalJson({ context: binding.context, accountId: binding.accountId });
+}
+
+export function validateRecordKey(value: RecordKey): void {
+    if (typeof value.collection !== 'string' || !/^[a-z][a-z0-9_.-]{0,63}$/.test(value.collection) || /[^a-z0-9_.-]/.test(value.collection))
+        throw new ProtocolError('invalid_storage_key', 'Collection must be a lowercase SDK identifier.');
+    if (typeof value.key !== 'string' || value.key.length > 4096 || /[^\x20-\x7e]/.test(value.key))
+        throw new ProtocolError('invalid_storage_key', 'Record keys must be at most 4096 printable ASCII characters.');
+}
+
+export function validateRecordQuery(query: RecordQuery): void {
+    if (query.key !== undefined && query.prefix !== undefined)
+        throw new ProtocolError('invalid_storage_query', 'Specify either key or prefix.');
+    validateRecordKey({ collection: query.collection, key: query.key ?? query.prefix ?? '' });
+    if (query.reverse !== undefined && typeof query.reverse !== 'boolean') throw new ProtocolError('invalid_storage_query', 'reverse must be boolean.');
+}
+
+/** Copies and validates a commit before an adapter opens its write transaction. */
+export function prepareCommit(expectedVersion: number, mutations: readonly StoreMutation[]): readonly StoreMutation[] {
+    requireSafeInteger(expectedVersion, 0);
+    if (expectedVersion === Number.MAX_SAFE_INTEGER) throw new ProtocolError('revision_exhausted', 'Storage revision is exhausted.');
+    if (mutations.length === 0) throw new ProtocolError('empty_commit', 'A commit requires at least one mutation.');
+    const keys = new Set<string>();
+    return mutations.map(mutation => {
+        validateRecordKey(mutation);
+        const id = mutation.collection + '\0' + mutation.key;
+        if (keys.has(id)) throw new ProtocolError('duplicate_mutation', 'A record may be changed only once per commit.');
+        keys.add(id);
+        if (mutation.kind === 'put') return { ...mutation, value: requireObject(parseJson(canonicalJson(mutation.value))) };
+        if (mutation.kind === 'delete') return { ...mutation };
+        throw new ProtocolError('invalid_mutation', 'Unknown store mutation.');
+    });
+}
+
+export function requireBatchCount(count: number): void { requireSafeInteger(count, 1); }
+
+/** Preserves fixed snapshot semantics while projecting stored rows into domain results. */
+export function mapQueryReader<T, U>(reader: QueryReader<T>, project: (value: T) => U): QueryReader<U> {
+    return {
+        async readNext(count, signal) { return (await reader.readNext(count, signal)).map(project); },
+        dispose() { return reader.dispose(); },
+    };
+}

package/src/storage/transaction.ts

@@ -0,0 +1,17 @@
+import { StateConflictError } from '../errors.js';
+import { throwIfAborted } from '../runtime/clock.js';
+import type { MeshlineStore, RecordQuery, StoreMutation, StoreSnapshot } from './store.js';
+
+/** Recomputes local changes on CAS contention. The planner must be synchronous and side-effect free. */
+export async function updateStore<T>(store: MeshlineStore, queries: readonly RecordQuery[],
+    plan: (snapshot: StoreSnapshot) => { readonly mutations: readonly StoreMutation[]; readonly result: T }, signal?: AbortSignal): Promise<T> {
+    for (let attempt = 0; attempt < 16; attempt++) {
+        throwIfAborted(signal);
+        const snapshot = await store.read(queries, signal);
+        const update = plan(snapshot);
+        if (!update.mutations.length) return update.result;
+        try { await store.commit(snapshot.version, update.mutations, signal); return update.result; }
+        catch (error) { if (!(error instanceof StateConflictError) || attempt === 15) throw error; }
+    }
+    throw new StateConflictError('Storage remained busy.');
+}