snapback4-expo 0.1.14

package/README.md

@@ -0,0 +1,31 @@
+# snapback4-expo
+
+Snapback 4's device in Rust, as an Expo module: the partition in its own
+SQLite, the stream applied, the outbox kept, queries and predictions
+answered — the same interpreter the server runs — behind one JSON call.
+`snapback4/native` is the client over it:
+
+```ts
+import { createNativeClient } from "snapback4/native";
+import { nativeAvailable, nativeDevice, documentDirectory } from "snapback4-expo";
+
+const client = nativeAvailable()
+  ? await createNativeClient({ url, guest: true, sessionStore, native: nativeDevice, dataDir: documentDirectory() })
+  : await createLocalClient({ url, guest: true, sessionStore, store: sqliteStore });   // Expo Go: the TypeScript tier
+```
+
+Expo Go loads no custom native code, so the module is present only in a
+development or production build: add `expo-dev-client`, then
+`npx expo run:ios` (the module autolinks; nothing to configure). The
+Rust library ships in the package as `ios/Snapback4Device.xcframework`
+(9.1 MB, a 4.8 MB archive a slice, built by `scripts/build-xcframework.sh`
+from `crates/snapback4-device`); it costs an app 1.7 MB linked, SQLite
+included, and a module call takes about a millisecond.
+
+Proved on the iOS simulator by the repository's witness in a development
+build (`WITNESS_DEV_CLIENT=1 node witness/expo.mjs`, recorded in
+`metrics/witness.jsonl` as `dev-client-native`): a cold sync of 303 rows
+in 31 ms, a reopen in 6 ms, a cold start with no network answering the
+thread from the store in 2 ms, and writes composed offline surviving a
+restart and landing in order. `EXPO_PUBLIC_SNAPBACK_TRACE=1` logs every
+call's op, time and answer size. Android follows.

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["apple"],
+  "apple": {
+    "modules": ["Snapback4Module"]
+  }
+}

package/ios/Snapback4Device.xcframework/Info.plist

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AvailableLibraries</key>
+	<array>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libsnapback4_device.a</string>
+			<key>HeadersPath</key>
+			<string>Headers</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64-simulator</string>
+			<key>LibraryPath</key>
+			<string>libsnapback4_device.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
+		</dict>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libsnapback4_device.a</string>
+			<key>HeadersPath</key>
+			<string>Headers</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64</string>
+			<key>LibraryPath</key>
+			<string>libsnapback4_device.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+		</dict>
+	</array>
+	<key>CFBundlePackageType</key>
+	<string>XFWK</string>
+	<key>XCFrameworkFormatVersion</key>
+	<string>1.0</string>
+</dict>
+</plist>

package/ios/Snapback4Device.xcframework/ios-arm64/Headers/module.modulemap

@@ -0,0 +1,4 @@
+module Snapback4Device {
+  header "snapback4.h"
+  export *
+}

package/ios/Snapback4Device.xcframework/ios-arm64/Headers/snapback4.h

@@ -0,0 +1,42 @@
+/* Snapback 4 on a device: the native module's C ABI. One JSON call.
+ *
+ *   sb4_device *d = sb4_open("/data/bob.sqlite", backend_json);   // GET /schema's JSON
+ *   char *answer = sb4_call(d, "{\"op\":\"query\",\"name\":\"thread\",\"viewer\":\"dev:bob\",\"args\":{\"conversationId\":\"c1\"},\"now\":1789200000000}");
+ *   ... answer is {"ok": ...} or {"denied": {"code","family","message",...}} ...
+ *   sb4_free(answer);
+ *   sb4_close(d);
+ *
+ * Ops: state, adopt {backend}, apply {page, first}, query {name, viewer, args, now},
+ * predict {name, viewer, args, now, newIds, entropy}, withdraw {predicted},
+ * enqueue {entry}, queued, next_submission, dequeue {id}, meta {key},
+ * set_meta {key, value}, clear_rows. Nothing panics across this boundary;
+ * every answer is JSON the caller frees. A device is not thread-safe: one
+ * caller at a time, as the store is one transaction at a time.
+ */
+#ifndef SNAPBACK4_H
+#define SNAPBACK4_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct sb4_device sb4_device;
+
+/* Open the device's store at `path` for the backend; NULL when it refuses
+ * (ask `sb4_open_reason` why). */
+sb4_device *sb4_open(const char *path, const char *backend_json);
+
+/* Why `sb4_open` would refuse, as JSON to free: {"ok":true} when it would open. */
+char *sb4_open_reason(const char *path, const char *backend_json);
+
+/* One call; the answer is JSON to free with `sb4_free`. */
+char *sb4_call(sb4_device *device, const char *request_json);
+
+void sb4_free(char *text);
+void sb4_close(sb4_device *device);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/ios/Snapback4Device.xcframework/ios-arm64-simulator/Headers/module.modulemap

@@ -0,0 +1,4 @@
+module Snapback4Device {
+  header "snapback4.h"
+  export *
+}

package/ios/Snapback4Device.xcframework/ios-arm64-simulator/Headers/snapback4.h

@@ -0,0 +1,42 @@
+/* Snapback 4 on a device: the native module's C ABI. One JSON call.
+ *
+ *   sb4_device *d = sb4_open("/data/bob.sqlite", backend_json);   // GET /schema's JSON
+ *   char *answer = sb4_call(d, "{\"op\":\"query\",\"name\":\"thread\",\"viewer\":\"dev:bob\",\"args\":{\"conversationId\":\"c1\"},\"now\":1789200000000}");
+ *   ... answer is {"ok": ...} or {"denied": {"code","family","message",...}} ...
+ *   sb4_free(answer);
+ *   sb4_close(d);
+ *
+ * Ops: state, adopt {backend}, apply {page, first}, query {name, viewer, args, now},
+ * predict {name, viewer, args, now, newIds, entropy}, withdraw {predicted},
+ * enqueue {entry}, queued, next_submission, dequeue {id}, meta {key},
+ * set_meta {key, value}, clear_rows. Nothing panics across this boundary;
+ * every answer is JSON the caller frees. A device is not thread-safe: one
+ * caller at a time, as the store is one transaction at a time.
+ */
+#ifndef SNAPBACK4_H
+#define SNAPBACK4_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct sb4_device sb4_device;
+
+/* Open the device's store at `path` for the backend; NULL when it refuses
+ * (ask `sb4_open_reason` why). */
+sb4_device *sb4_open(const char *path, const char *backend_json);
+
+/* Why `sb4_open` would refuse, as JSON to free: {"ok":true} when it would open. */
+char *sb4_open_reason(const char *path, const char *backend_json);
+
+/* One call; the answer is JSON to free with `sb4_free`. */
+char *sb4_call(sb4_device *device, const char *request_json);
+
+void sb4_free(char *text);
+void sb4_close(sb4_device *device);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/ios/Snapback4Expo.podspec

@@ -0,0 +1,26 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'Snapback4Expo'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = 'MIT'
+  s.author         = 'Snapback'
+  s.homepage       = 'https://github.com/ccheever/snapback'
+  s.platforms      = { :ios => '16.4' }
+  s.source         = { git: '' }
+  s.static_framework = true
+  s.dependency 'ExpoModulesCore'
+
+  # The Rust module: both iOS targets, the C header and its module map,
+  # built by scripts/build-xcframework.sh.
+  s.vendored_frameworks = 'Snapback4Device.xcframework'
+  s.source_files = '*.swift'
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+end

package/ios/Snapback4Module.swift

@@ -0,0 +1,66 @@
+import ExpoModulesCore
+import Snapback4Device
+
+// The device in Rust, opened once per store and reached through one JSON
+// call; the JavaScript tier (`snapback4/native`) keeps the session, the
+// link and the transport. Handles are small integers the module hands out.
+public final class Snapback4Module: Module {
+  private var devices: [Int: OpaquePointer] = [:]
+  private var nextHandle = 1
+  private let lock = NSLock()
+
+  public func definition() -> ModuleDefinition {
+    Name("Snapback4")
+
+    // Where an app keeps its stores: the documents directory.
+    Constant("documentDirectory") {
+      FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first?.path ?? NSTemporaryDirectory()
+    }
+
+    // Open the device's store at `path` for the backend (`GET /schema`'s
+    // JSON), or on the one it kept when `backend` is nil. Throws with the
+    // module's refusal when it cannot open.
+    AsyncFunction("open") { (path: String, backend: String?) -> Int in
+      guard let device = sb4_open(path, backend) else {
+        let reason = sb4_open_reason(path, backend)
+        let text = reason.map { String(cString: $0) } ?? "{\"denied\":{\"code\":\"E_STORE\",\"family\":\"store\",\"message\":\"the device did not open\"}}"
+        sb4_free(reason)
+        throw Snapback4OpenException(text)
+      }
+      self.lock.lock()
+      defer { self.lock.unlock() }
+      let handle = self.nextHandle
+      self.nextHandle += 1
+      self.devices[handle] = device
+      return handle
+    }
+
+    // One call: `request` is JSON with an `op`; the answer is JSON.
+    AsyncFunction("call") { (handle: Int, request: String) -> String in
+      self.lock.lock()
+      defer { self.lock.unlock() }
+      guard let device = self.devices[handle] else {
+        return "{\"denied\":{\"code\":\"E_INPUT\",\"family\":\"input\",\"message\":\"no device with that handle\"}}"
+      }
+      guard let answer = sb4_call(device, request) else {
+        return "{\"denied\":{\"code\":\"E_STORE\",\"family\":\"store\",\"message\":\"the module answered nothing\"}}"
+      }
+      defer { sb4_free(answer) }
+      return String(cString: answer)
+    }
+
+    Function("close") { (handle: Int) in
+      self.lock.lock()
+      defer { self.lock.unlock() }
+      if let device = self.devices.removeValue(forKey: handle) {
+        sb4_close(device)
+      }
+    }
+  }
+}
+
+internal final class Snapback4OpenException: GenericException<String> {
+  override var reason: String {
+    param
+  }
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "snapback4-expo",
+  "version": "0.1.14",
+  "type": "module",
+  "description": "Snapback 4's native module for Expo: the device in Rust (the partition in its own SQLite, the stream applied, the outbox kept, queries and predictions answered) behind one JSON call, and the opener `snapback4/native` takes.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": ["src", "ios", "expo-module.config.json", "README.md"],
+  "peerDependencies": {
+    "expo": "*",
+    "snapback4": "*"
+  },
+  "devDependencies": {
+    "expo-modules-core": "*",
+    "typescript": "5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// The opener `snapback4/native` takes, over the Expo module: absent in
+// Expo Go (which loads no custom native code), present in a development
+// or production build. An app asks `nativeAvailable()` and falls back to
+// the TypeScript tier (`snapback4/local` over expo-sqlite) when it is not.
+import { requireOptionalNativeModule } from "expo-modules-core";
+import type { NativeCore, NativeOpener } from "snapback4/native";
+
+interface Snapback4Native {
+  readonly documentDirectory: string;
+  open(path: string, backend: string | null): Promise<number>;
+  call(handle: number, request: string): Promise<string>;
+  close(handle: number): void;
+}
+
+const native = requireOptionalNativeModule<Snapback4Native>("Snapback4");
+// EXPO_PUBLIC_SNAPBACK_TRACE=1 logs every call's op, time and answer size.
+const trace = Boolean(process.env.EXPO_PUBLIC_SNAPBACK_TRACE);
+
+export function nativeAvailable(): boolean {
+  return native !== null;
+}
+
+/** The directory the module suggests for an app's stores. */
+export function documentDirectory(): string {
+  if (!native) throw new Error("snapback4-expo: the native module is not in this build");
+  return native.documentDirectory;
+}
+
+export const nativeDevice: NativeOpener = {
+  async open(path, backend): Promise<NativeCore> {
+    if (!native) throw new Error("snapback4-expo: the native module is not in this build (Expo Go loads no custom native code; make a development build)");
+    const handle = await native.open(path, backend ? JSON.stringify(backend) : null);
+    return {
+      async call(request) {
+        const t0 = trace ? Date.now() : 0;
+        const answer = await native.call(handle, JSON.stringify(request));
+        if (trace) console.log(`snapback4-expo ${String((request as { op?: string }).op)} ${Date.now() - t0} ms ${answer.length} B`);
+        return JSON.parse(answer) as Record<string, unknown>;
+      },
+      async close() {
+        native.close(handle);
+      },
+    };
+  },
+};