snapback4-expo 0.2.0 → 0.2.2

package/README.md

@@ -11,8 +11,6 @@ import { createLocalClient } from "snapback4/local";
 import { createClient } from "snapback4/client";
 import { nativeAvailable, nativeDevice } from "snapback4-expo";
 
-const safe = (name: string) => name.replace(/[^A-Za-z0-9._-]/g, "_");   // store and session names carry the URL and the viewer
-const sqliteStore = { open: async (name: string, schema: unknown) => openSqlite(expoSqliteDriver(await SQLite.openDatabaseAsync(`${safe(name)}.db`)), schema) };
 const client = nativeAvailable()
   ? await createLocalClient({ url, guest: true, sessionStore, device: nativeDevice })
   : createClient({ url, session });   // Expo Go: the online tier, with a session the app keeps
@@ -27,14 +25,24 @@ 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.
+(about 13.2 MB in 0.2.1, a 6.6 MB archive per slice, built by
+`scripts/build-xcframework.sh` from `crates/snapback4-device`). It includes
+SQLite and the native-query Wasm host. The earlier module measured 1.7 MB
+linked and about a millisecond per call; those measurements predate the
+native-query host.
 
-Proved on the iOS simulator by the repository's witness in a development
+Earlier iOS simulator evidence from 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.
+
+Ordinary media can be retained with `createLocalClient({ ..., device: nativeDevice,
+assets: { keep: "viewed", maxBytes: 67108864 } })`. The opener supplies private
+file storage beside each device store in Documents. Offline `client.asset` and
+`useAsset` return a file URI; online calls revalidate. The client purges bytes
+on home-row revocation, deletion, clearing or expiry and on sign-out; `once`
+bytes never enter file storage. Rebuild the native app to include this storage
+capability. `keep: "none"` (default) retains no bytes.

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

@@ -9,9 +9,13 @@
  * 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.
+ * set_meta {key, value}, clear_rows. Nothing unwinds across this boundary:
+ * unwind builds translate an internal panic to E_STORE; production uses
+ * panic=abort and terminates before unwinding. 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.
+ * `apply.first` must be true on the first page of a snapshot. It defaults
+ * to false so an omitted marker cannot discard a snapshot already staged.
  */
 #ifndef SNAPBACK4_H
 #define SNAPBACK4_H
@@ -26,7 +30,10 @@ typedef struct sb4_device sb4_device;
  * (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. */
+/* Take the refusal recorded by the most recent failed `sb4_open` on this
+ * thread, as JSON to free. This diagnoses that attempt without opening or
+ * mutating the store a second time. The arguments are retained for ABI
+ * compatibility. */
 char *sb4_open_reason(const char *path, const char *backend_json);
 
 /* One call; the answer is JSON to free with `sb4_free`. */

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

@@ -9,9 +9,13 @@
  * 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.
+ * set_meta {key, value}, clear_rows. Nothing unwinds across this boundary:
+ * unwind builds translate an internal panic to E_STORE; production uses
+ * panic=abort and terminates before unwinding. 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.
+ * `apply.first` must be true on the first page of a snapshot. It defaults
+ * to false so an omitted marker cannot discard a snapshot already staged.
  */
 #ifndef SNAPBACK4_H
 #define SNAPBACK4_H
@@ -26,7 +30,10 @@ typedef struct sb4_device sb4_device;
  * (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. */
+/* Take the refusal recorded by the most recent failed `sb4_open` on this
+ * thread, as JSON to free. This diagnoses that attempt without opening or
+ * mutating the store a second time. The arguments are retained for ABI
+ * compatibility. */
 char *sb4_open_reason(const char *path, const char *backend_json);
 
 /* One call; the answer is JSON to free with `sb4_free`. */

package/ios/Snapback4Module.swift

@@ -6,6 +6,7 @@ import Snapback4Device
 // link and the transport. Handles are small integers the module hands out.
 public final class Snapback4Module: Module {
   private var devices: [Int: OpaquePointer] = [:]
+  private var mediaDirectories: [Int: URL] = [:]
   private var nextHandle = 1
   private let lock = NSLock()
 
@@ -32,6 +33,7 @@ public final class Snapback4Module: Module {
       let handle = self.nextHandle
       self.nextHandle += 1
       self.devices[handle] = device
+      self.mediaDirectories[handle] = URL(fileURLWithPath: path + ".media", isDirectory: true)
       return handle
     }
 
@@ -49,14 +51,55 @@ public final class Snapback4Module: Module {
       return String(cString: answer)
     }
 
+    // @ref LLP 3000.007#8 — the opener owns ordinary media in Documents
+    AsyncFunction("readAsset") { (handle: Int, id: String) -> String? in
+      self.lock.lock()
+      defer { self.lock.unlock() }
+      let file = try self.assetFile(handle, id)
+      guard FileManager.default.fileExists(atPath: file.path) else { return nil }
+      return try Data(contentsOf: file).map { String(format: "%02x", $0) }.joined()
+    }
+    AsyncFunction("writeAsset") { (handle: Int, id: String, hex: String) in
+      self.lock.lock()
+      defer { self.lock.unlock() }
+      let file = try self.assetFile(handle, id)
+      let chars = Array(hex.utf8)
+      guard chars.count % 2 == 0 else { throw Snapback4OpenException("invalid media bytes") }
+      var bytes = Data(capacity: chars.count / 2)
+      for i in stride(from: 0, to: chars.count, by: 2) {
+        guard let byte = UInt8(String(bytes: chars[i...i+1], encoding: .utf8) ?? "", radix: 16) else { throw Snapback4OpenException("invalid media bytes") }
+        bytes.append(byte)
+      }
+      try FileManager.default.createDirectory(at: file.deletingLastPathComponent(), withIntermediateDirectories: true)
+      try bytes.write(to: file, options: .atomic)
+    }
+    AsyncFunction("removeAsset") { (handle: Int, id: String) in
+      self.lock.lock()
+      defer { self.lock.unlock() }
+      let file = try self.assetFile(handle, id)
+      if FileManager.default.fileExists(atPath: file.path) { try FileManager.default.removeItem(at: file) }
+    }
+    Function("assetUri") { (handle: Int, id: String) -> String in
+      self.lock.lock()
+      defer { self.lock.unlock() }
+      return try self.assetFile(handle, id).absoluteString
+    }
+
     Function("close") { (handle: Int) in
       self.lock.lock()
       defer { self.lock.unlock() }
+      self.mediaDirectories.removeValue(forKey: handle)
       if let device = self.devices.removeValue(forKey: handle) {
         sb4_close(device)
       }
     }
   }
+  private func assetFile(_ handle: Int, _ id: String) throws -> URL {
+    guard let directory = mediaDirectories[handle], !id.isEmpty,
+      id.utf8.allSatisfy({ ($0 >= 48 && $0 <= 57) || ($0 >= 65 && $0 <= 90) || ($0 >= 97 && $0 <= 122) })
+    else { throw Snapback4OpenException("invalid media id or closed device") }
+    return directory.appendingPathComponent(id)
+  }
 }
 
 internal final class Snapback4OpenException: GenericException<String> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapback4-expo",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",

package/src/index.ts

@@ -10,6 +10,10 @@ interface Snapback4Native {
   open(path: string, backend: string | null): Promise<number>;
   call(handle: number, request: string): Promise<string>;
   close(handle: number): void;
+  readAsset(handle: number, id: string): Promise<string | null>;
+  writeAsset(handle: number, id: string, hex: string): Promise<void>;
+  removeAsset(handle: number, id: string): Promise<void>;
+  assetUri(handle: number, id: string): string;
 }
 
 const native = requireOptionalNativeModule<Snapback4Native>("Snapback4");
@@ -31,6 +35,12 @@ export const nativeDevice: DeviceOpener = {
     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(`${native.documentDirectory.replace(/\/$/, "")}/${name}.sqlite`, backend ? JSON.stringify(backend) : null);
     return {
+      media: {
+        read: (id) => native.readAsset(handle, id),
+        write: (id, hex) => native.writeAsset(handle, id, hex),
+        remove: (id) => native.removeAsset(handle, id),
+        uri: (id) => native.assetUri(handle, id),
+      },
       async call(request) {
         const t0 = trace ? Date.now() : 0;
         const answer = await native.call(handle, JSON.stringify(request));