@g9tm/syncdata-lynx
Lynx support for @g9tm/syncdata, the TypeScript twin of the G9SyncData client:
G9SyncDataLynxModule— a native module (Lynx Autolink) that decodes the server's Brotli frames off the JS thread: Android with Google'sorg.brotli:dec, iOS 15+ with Apple's Compression framework, Lynxtron with node:zlib (@g9tm/syncdata-lynx/lynxtron).createLynxSyncTransport()— the sync transport over the G9 native WebSocket of@g9tm/signalr-supernetcore-lynx(Lynx release builds have no WebSocket), MessagePack by default, no negotiate round trip.useLynxBrotli()— makes the native decoder the default for every frame the store and the engine read.lynxSnapshotFileSink(databasePath)— the device side of snapshot files (ADR-0072): a site's first download arrives as a SQLite file in 1 MiB segments, and each segment is decompressed, checked against its SHA-256 and written into the staged file by the native module. The file's bytes never come back into JavaScript; the store copies its tables in SQL (ATTACH+ oneINSERT … SELECTper table).
Version 1.2.2, released with @g9tm/syncdata and the .NET packages.
Install
npm install @g9tm/syncdata @g9tm/syncdata-lynx @g9tm/signalr-supernetcore-lynx @g9tm/signalr-supernetcore-client @microsoft/signalr @microsoft/signalr-protocol-msgpack @msgpack/msgpack
Autolink picks up the native modules of @g9tm/syncdata-lynx and @g9tm/signalr-supernetcore-lynx (lynx.lib.json).
iOS: the pods g9tm-syncdata-lynx and g9tm-signalr-lynx (Lynx 4.0.3 registers iOS modules explicitly:
[config registerModule:G9SyncDataLynxModule.class]).
Use
import { G9SyncEngine } from '@g9tm/syncdata';
import { G9SqliteSyncStore } from '@g9tm/syncdata/sqlite';
import { createLynxSyncTransport, lynxSnapshotFileSink, useLynxBrotli } from '@g9tm/syncdata-lynx';
import { createNativeSqliteDriver } from '@g9lynx/native'; // G9LynxControls
useLynxBrotli();
const store = new G9SqliteSyncStore({
driver: createNativeSqliteDriver(),
databasePath,
// null on a platform that cannot take files (an older module): the device then receives rows, as before.
snapshotFiles: await lynxSnapshotFileSink(databasePath),
});
const transport = createLynxSyncTransport({ url: 'https://sync.example.com/g9sync', accessTokenFactory: () => token });
const engine = new G9SyncEngine(store, transport, model);
await engine.initialize();
The store accepts any driver with the G9SqliteDriver shape (@g9tm/syncdata/sqlite); G9LynxControls' native driver
(androidx.sqlite bundled on Android, system SQLite on iOS) is the intended one. A database written by the .NET client
(MAUI) is the same file format, tables and metadata: the Lynx app opens it and continues.
Staged snapshot files go to <the app's cache directory>/g9sync-files/<database name>-<hash of its path>: one folder
per database (two users' databases never sweep each other's files), app-private and outside Android Auto Backup and the
iOS backup. Pass { directory } to choose another place; the store deletes each file after its tables are copied and
sweeps leftovers it wrote itself at the next start - nothing else in that folder is touched.
Native contract
| Method | Reply ({ ok, value } / { ok: false, error: { code, message } }) |
|---|---|
capabilities(callback) | { version, platform, brotli, snapshotFiles, cacheDirectory } |
brotliDecompress(data: ArrayBuffer, expectedLength: number, callback) | an ArrayBuffer of exactly expectedLength bytes; errors G9SYNC-BROTLI-ARG, G9SYNC-BROTLI-INVALID, G9SYNC-BROTLI-UNAVAILABLE |
snapshotFileCreate(path, size, callback) | null; creates the directory too, truncates an existing file |
snapshotFileWriteSegment(path, offset, data: ArrayBuffer, length, sha256, sync, callback) | null; decompresses, checks the length and the SHA-256, THEN writes at offset (sync: flushed to stable storage first - F_FULLFSYNC on iOS); G9SYNC-FILE-INVALID writes nothing |
snapshotFileSize(path, callback) | the size, or null |
snapshotFileHead(path, length, callback) | an ArrayBuffer of the first length bytes |
snapshotFileRemove(path, callback) | null; a missing file is not an error |
snapshotFileList(directory, callback) | the sorted full paths of the directory's files |
File errors: G9SYNC-FILE-ARG, G9SYNC-FILE-INVALID, G9SYNC-FILE-IO (with the system's reason), and on the JS side
G9SYNC-FILE-UNAVAILABLE for a module without the methods. Segment work runs on its own native thread (Android) or
serial queue (iOS), so it never waits behind a frame decode and the writes of one file land in order.
What is proven where, and what still needs a device: Native-Validation-Pending.md.
Tests
npm test # the JS wrapper over fake native modules
npm run test:lynxsim # the whole sync against the real .NET sample server, in a Lynx-shaped sandbox (needs the disposable PostgreSQL)
npm run test:android-jvm # the Kotlin core on a JVM
npm run check:android-module # compiles the module against Lynx 4.1.0, checks the Autolink provider
npm run test:ios-core # the iOS cores (Brotli + snapshot files): Apple clang + Compression on macOS, GNUstep + libbrotlidec on Linux/WSL
License
MIT.