@trainstar/synchro-react-native 0.1.2 → 0.3.2

package/src/index.ts

@@ -7,16 +7,48 @@ export type {
   Row,
   ExecResult,
   BatchResult,
+  SQLiteBytes,
+  SQLiteInt64,
+  SQLiteTaggedValue,
+  SQLiteBindValue,
   SQLStatement,
   ColumnDef,
   TableOptions,
+  ReadTransaction,
   Transaction,
-  CheckpointMode,
   SyncStatus,
   SyncStatusType,
+  SyncOperationKind,
+  SyncRecoveryAction,
+  SyncFailureCode,
+  SyncFailure,
+  JSONValue,
+  MutationOperation,
+  LocalMutationStatus,
+  MutationStatus,
+  MutationRejectionCode,
+  SchemaRef,
+  AuthoredMutationField,
+  PendingMutationInspection,
+  RejectedMutationInspection,
+  SchemaAction,
+  SyncSchemaEvent,
+  SyncMutationEvent,
+  SyncRebuildEvent,
+  SyncEvent,
+  ProtocolErrorCode,
   ConflictEvent,
   SynchroConfig,
   Unsubscribe,
+  AsyncUnsubscribe,
+} from './types';
+
+export {
+  SYNC_STATUS_TYPES,
+  SYNC_OPERATION_KINDS,
+  SYNC_RECOVERY_ACTIONS,
+  SYNC_FAILURE_CODES,
+  PROTOCOL_ERROR_CODES,
 } from './types';
 
 export {
@@ -26,16 +58,25 @@ export {
   TableNotSyncedError,
   UpgradeRequiredError,
   SchemaMismatchError,
-  SnapshotRequiredError,
   PushRejectedError,
   NetworkError,
   ServerError,
+  ProtocolError,
+  SyncBlockedError,
+  UnsupportedSchemaError,
+  InvalidStateTransitionError,
   DatabaseError,
   InvalidResponseError,
+  InvalidSeedError,
   AlreadyStartedError,
   NotStartedError,
   TransactionTimeoutError,
+  NATIVE_ERROR_CODES,
   mapNativeError,
 } from './errors';
 
-export type { PushResultItem } from './errors';
+export type {
+  NativeErrorCode,
+  SchemaUnsupportedReason,
+  PushRejectedMutation,
+} from './errors';

package/src/inspection.ts

@@ -0,0 +1,226 @@
+import {
+  configureInspection,
+  nativeForInspection,
+  parseClientStateInspection,
+  parseTransportObservationSnapshot,
+  SynchroClient,
+} from './SynchroClient';
+import { InvalidResponseError, mapNativeError } from './errors';
+import type {
+  ClientStateInspection,
+  TransportObservationSnapshot,
+  TransportOperationClass,
+} from './types';
+
+const TRANSPORT_OPERATION_CLASSES: readonly TransportOperationClass[] = [
+  'connect',
+  'pull',
+  'push',
+  'checkpoint',
+  'schemas',
+  'rebuild',
+  'other',
+];
+
+export interface DurableStateInspection {
+  row_metadata: {
+    table_name: string;
+    record_id: string;
+    server_version: string;
+    row_checksum: string | null;
+  } | null;
+  rebuild_receipts: Array<{
+    rebuild_id_fingerprint: string;
+    page_count: number;
+    returned_record_count: number;
+    request_chain_expected: string[];
+    request_chain_observed: string[];
+    record_identities_hex: string[];
+    received_row_checksums: string[];
+    computed_row_checksums: string[];
+    computed_scope_checksum: string | null;
+    final_scope_checksum: string | null;
+    stored_scope_checksum: string | null;
+    local_scope_checksum: string | null;
+  }>;
+}
+
+export interface SynchroInspectionOptions {
+  transportObservationCapacity?: number;
+  requireNewDatabase?: boolean;
+}
+
+export class SynchroInspection {
+  constructor(
+    private readonly client: SynchroClient,
+    options: SynchroInspectionOptions = {}
+  ) {
+    configureInspection(
+      client,
+      options.transportObservationCapacity ?? 0,
+      options.requireNewDatabase ?? false
+    );
+  }
+
+  async clientState(): Promise<ClientStateInspection> {
+    try {
+      return parseClientStateInspection(parseJSON(await nativeForInspection(this.client).inspectClientState()));
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async durableState(tableName: string, recordID: string): Promise<DurableStateInspection> {
+    if (tableName.length === 0 || recordID.length === 0) {
+      throw new InvalidResponseError('Durable-state identity is invalid');
+    }
+    try {
+      return parseDurableState(
+        parseJSON(await nativeForInspection(this.client).inspectDurableState(tableName, recordID))
+      );
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async processIdentity(): Promise<string> {
+    try {
+      const value = await nativeForInspection(this.client).getProcessIdentity();
+      if (!/^(?:ios|android)-app:[1-9][0-9]*$/.test(value)) {
+        throw new InvalidResponseError('Native bridge returned invalid process identity');
+      }
+      return value;
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async transportObservations(): Promise<TransportObservationSnapshot> {
+    try {
+      return parseTransportObservationSnapshot(
+        parseJSON(await nativeForInspection(this.client).inspectTransportObservations())
+      );
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async armTransportPause(operationClass: TransportOperationClass): Promise<void> {
+    requireTransportOperationClass(operationClass);
+    try {
+      await nativeForInspection(this.client).armTransportPause(operationClass);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async awaitTransportPause(operationClass: TransportOperationClass, timeoutMs: number): Promise<void> {
+    requireTransportOperationClass(operationClass);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000) {
+      throw new InvalidResponseError('Transport pause request is invalid');
+    }
+    try {
+      await nativeForInspection(this.client).awaitTransportPause(operationClass, timeoutMs);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async resumeTransportPause(): Promise<void> {
+    try {
+      await nativeForInspection(this.client).resumeTransportPause();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+}
+
+function parseJSON(source: string): unknown {
+  try {
+    return JSON.parse(source) as unknown;
+  } catch {
+    throw new InvalidResponseError('Native bridge returned malformed inspection JSON');
+  }
+}
+
+function parseDurableState(value: unknown): DurableStateInspection {
+  const proof = requireRecord(value, 'durable state');
+  if (
+    Object.keys(proof).length !== 2 ||
+    !Object.prototype.hasOwnProperty.call(proof, 'row_metadata') ||
+    !Array.isArray(proof.rebuild_receipts)
+  ) {
+    throw new InvalidResponseError('Native bridge returned invalid durable state');
+  }
+  if (proof.row_metadata !== null) {
+    const metadata = requireRecord(proof.row_metadata, 'row metadata');
+    if (
+      Object.keys(metadata).length !== 4 ||
+      typeof metadata.table_name !== 'string' ||
+      typeof metadata.record_id !== 'string' ||
+      typeof metadata.server_version !== 'string' ||
+      (metadata.row_checksum !== null && typeof metadata.row_checksum !== 'string')
+    ) {
+      throw new InvalidResponseError('Native bridge returned invalid row metadata');
+    }
+  }
+  for (const receiptValue of proof.rebuild_receipts) {
+    const receipt = requireRecord(receiptValue, 'rebuild receipt');
+    if (
+      Object.keys(receipt).length !== 12 ||
+      typeof receipt.rebuild_id_fingerprint !== 'string' ||
+      !isNonnegativeSafeInteger(receipt.page_count) ||
+      !isNonnegativeSafeInteger(receipt.returned_record_count) ||
+      !isStringArray(receipt.request_chain_expected) ||
+      !isStringArray(receipt.request_chain_observed) ||
+      !isStringArray(receipt.record_identities_hex) ||
+      !isStringArray(receipt.received_row_checksums) ||
+      !isStringArray(receipt.computed_row_checksums) ||
+      !isNullableString(receipt.computed_scope_checksum) ||
+      !isNullableString(receipt.final_scope_checksum) ||
+      !isNullableString(receipt.stored_scope_checksum) ||
+      !isNullableString(receipt.local_scope_checksum)
+    ) {
+      throw new InvalidResponseError('Native bridge returned invalid rebuild receipt');
+    }
+  }
+  return proof as unknown as DurableStateInspection;
+}
+
+function requireRecord(value: unknown, name: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name}`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function isNonnegativeSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === 'string';
+}
+
+function requireTransportOperationClass(value: TransportOperationClass): void {
+  if (!TRANSPORT_OPERATION_CLASSES.includes(value)) {
+    throw new InvalidResponseError('Transport operation class is invalid');
+  }
+}
+
+export { sha256Hex } from './digest';
+export { isCanonicalBase64Url, isCanonicalInt64 } from './sqliteValues';
+
+export type {
+  ClientStateInspection,
+  RebuildAttemptInspection,
+  ScopeRowInspection,
+  ScopeStateInspection,
+  TransportObservation,
+  TransportObservationSnapshot,
+  TransportOperationClass,
+} from './types';

package/src/sqliteValues.ts

@@ -0,0 +1,105 @@
+import type { SQLiteBindValue } from './types';
+
+const MIN_INT64 = -(BigInt(1) << BigInt(63));
+const MAX_INT64 = (BigInt(1) << BigInt(63)) - BigInt(1);
+
+const BASE64URL_ALPHABET =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function base64urlValue(character: string): number {
+  return BASE64URL_ALPHABET.indexOf(character);
+}
+
+/** Validate an unpadded, canonical RFC 4648 base64url string. */
+export function isCanonicalBase64Url(value: string): boolean {
+  if (!/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) {
+    return false;
+  }
+
+  const remainder = value.length % 4;
+  if (remainder === 2) {
+    const last = base64urlValue(value[value.length - 1]);
+    return (last & 0x0f) === 0;
+  }
+  if (remainder === 3) {
+    const last = base64urlValue(value[value.length - 1]);
+    return (last & 0x03) === 0;
+  }
+  return true;
+}
+
+export function isCanonicalInt64(value: string): boolean {
+  if (!/^(?:0|-?[1-9][0-9]*)$/.test(value)) {
+    return false;
+  }
+
+  try {
+    const parsed = BigInt(value);
+    return parsed >= MIN_INT64 && parsed <= MAX_INT64 && parsed.toString() === value;
+  } catch {
+    return false;
+  }
+}
+
+function invalidBindValue(index: number, reason: string): TypeError {
+  return new TypeError(`Invalid SQL bind value at index ${index}: ${reason}`);
+}
+
+/** Reject malformed tagged values before they cross the native bridge. */
+export function assertValidSQLiteBindValue(
+  value: unknown,
+  index: number
+): asserts value is SQLiteBindValue {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    return;
+  }
+
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw invalidBindValue(index, 'number must be finite');
+    }
+    if (Number.isInteger(value) && Math.abs(value) > Number.MAX_SAFE_INTEGER) {
+      throw invalidBindValue(index, 'integer is outside the safe range');
+    }
+    return;
+  }
+
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw invalidBindValue(index, 'unsupported value type');
+  }
+
+  const keys = Object.keys(value);
+  if (keys.length !== 2 || !keys.includes('type')) {
+    throw invalidBindValue(index, 'tag must contain exactly type and payload fields');
+  }
+
+  const tagged = value as Record<string, unknown>;
+  if (tagged.type === 'bytes') {
+    if (keys.length !== 2 || !keys.includes('base64') || typeof tagged.base64 !== 'string') {
+      throw invalidBindValue(index, 'bytes tag must contain a base64 string');
+    }
+    if (!isCanonicalBase64Url(tagged.base64)) {
+      throw invalidBindValue(index, 'bytes tag must use canonical base64url');
+    }
+    return;
+  }
+
+  if (tagged.type === 'int64') {
+    if (keys.length !== 2 || !keys.includes('value') || typeof tagged.value !== 'string') {
+      throw invalidBindValue(index, 'int64 tag must contain a signed decimal string');
+    }
+    if (!isCanonicalInt64(tagged.value)) {
+      throw invalidBindValue(index, 'int64 tag must contain a canonical signed int64');
+    }
+    return;
+  }
+
+  throw invalidBindValue(index, 'unknown SQL bind tag');
+}
+
+export function assertValidSQLiteBindParams(
+  values: readonly SQLiteBindValue[]
+): readonly SQLiteBindValue[] {
+  values.forEach((value, index) => assertValidSQLiteBindValue(value, index));
+  return values;
+}