feat: WebSocket transport — replace base64 bridge for native (#17)

Products running in a WebView/WKWebView now connect to the Rust core
through the localhost WebSocket bridge instead of a base64-over-
JavascriptInterface (Android) / base64-over-WKScriptMessageHandler (iOS)
shim. The Rust ws_bridge already existed; this commit adds the
matching JS client and strips the obsolete native transport.

@parity/truapi:
- New `createWebSocketProvider(url, opts?)` producing a `Provider` over
  a binary WebSocket. Connects to the localhost endpoint the native
  shell prints via `startWsBridge`.

android/TrUAPIHost.kt:
- Drop `WebViewTransport`, `CoreInbound`, `bootstrapScript`, and all
  base64/JavascriptInterface plumbing.
- `TrUAPIHostCore` keeps its `receiveFromProduct` entrypoint for tests
  and alternative transports; the WS bridge feeds the core internally.

ios/TrUAPIHost.swift:
- Drop `WebViewTransport` (`WKScriptMessageHandler` + base64 path) and
  `CoreInbound` protocol. Drop the `WebKit` import.
- Keep `LocalhostBridgeBootstrap` — its purpose is exactly to publish
  the WS endpoint to the product page so it can call
  `createWebSocketProvider(url)`.

READMEs for both native shells now describe the WS-bridge flow:
1. Host calls `core.startWsBridge()` → gets port + token.
2. Inject the endpoint into the product page (Android: query string;
   iOS: `LocalhostBridgeBootstrap.script()` as a WKUserScript).
3. Product JS reads the URL and passes it to `createWebSocketProvider`.

@parity/truapi build + tests pass with the new export.

Author: pgherveou

android/README.md

@@ -1,6 +1,6 @@
 # TrUAPI Android host adapter
 
-*Thin Kotlin shell over the Rust TrUAPI core (UniFFI) plus an Android `WebView` byte transport. Wire decoding, request routing, and subscription lifecycle stay in the Rust core.*
+*Thin Kotlin shell over the Rust TrUAPI core (UniFFI). Wire decoding, request routing, and subscription lifecycle stay in the Rust core; products connect through the localhost WebSocket bridge.*
 
 This directory is an Android library module: include it from a parent project's `settings.gradle.kts` (e.g. `include(":truapi-android"); project(":truapi-android").projectDir = file("vendor/truapi/android")`). It does not ship with its own Gradle wrapper or root settings — pulling it into a consuming project supplies those.
 
@@ -9,36 +9,24 @@ This directory is an Android library module: include it from a parent project's
 The public surface lives in [`src/main/kotlin/io/parity/truapi/TrUAPIHost.kt`](src/main/kotlin/io/parity/truapi/TrUAPIHost.kt):
 
 - `HostBridge` - callback bundle the embedding app implements. Split into device permissions, remote permissions, navigation, push, feature support, and scoped storage.
-- `TrUAPIHostCore` - owning wrapper around the UniFFI-generated `NativeTrUApiCore`. Implements `CoreInbound`, owns the bridge lifetime, exposes session and WS bridge controls.
-- `WebViewTransport` - base64-over-`JavascriptInterface` byte pipe between a `WebView` and any `CoreInbound`. Injects a `window.trUApi` shim that matches the JS host adapter shape.
-- `bootstrapScript` - the JS shim, exposed so apps can inject it through their own WebView bootstrap path.
+- `HostStorage` - simple read/write/clear interface the host backs with its own persistence.
+- `TrUAPIHostCore` - owning wrapper around the UniFFI-generated `NativeTrUApiCore`. Holds the bridge alive for the lifetime of the core, exposes session controls and the localhost WebSocket bridge.
 
 The generated UniFFI bindings live under `src/main/kotlin/generated/uniffi/truapi_server/`. They are committed (they're large and consumers should not need a Rust toolchain).
 
 ## Architecture
 
 ```text
 product app in WebView
-  Uint8Array frames via window.trUApi
+  Uint8Array frames via @parity/truapi createWebSocketProvider
            |
-           v
-WebViewTransport
-  base64 over Android JS bridge
-           |
-           v
-TrUAPIHostCore (CoreInbound)
-  → uniffi → libtruapi_server.so
+           v   ws://127.0.0.1:<port>/?t=<token>
+TrUAPIHostCore.startWsBridge()
+  → libtruapi_server.so (tokio WS server)
+  → Rust dispatcher
 ```
 
-Inbound flow:
-
-1. Product JS calls `window.trUApi.postMessage(bytes)`
-2. `WebViewTransport` receives base64 through `@JavascriptInterface`
-3. `TrUAPIHostCore.receiveFromProduct(...)` forwards bytes into the Rust dispatcher
-4. The Rust core emits a response frame; `HostBridge.onCoreResponse(...)` fires
-5. The embedder typically pumps the response back through `WebViewTransport.sendToProduct(...)`, which calls `window.__trUApiReceive(...)`
-
-The Rust core also calls `HostBridge` directly for platform capabilities: `navigateTo`, `pushNotification`, `devicePermission`, `remotePermission`, `featureSupported`, and the `storage` slot.
+The product running in the `WebView` opens a `WebSocket` to the localhost port + token returned by `startWsBridge`. From there the Rust core handles the wire protocol directly. Outbound responses and host-side capability callbacks (`navigateTo`, `pushNotification`, `devicePermission`, `remotePermission`, `featureSupported`, `storage`) reach the embedder through `HostBridge`.
 
 ## Permissions split
 
@@ -56,7 +44,6 @@ import android.webkit.WebView
 import io.parity.truapi.HostBridge
 import io.parity.truapi.HostStorage
 import io.parity.truapi.TrUAPIHostCore
-import io.parity.truapi.WebViewTransport
 import uniffi.truapi_server.HostNavigateRejection
 import uniffi.truapi_server.HostRejection
 
@@ -67,27 +54,27 @@ class MyStorage : HostStorage {
     override fun clear(key: String) { map.remove(key) }
 }
 
-class MyBridge(private val transport: WebViewTransport) : HostBridge {
+class MyBridge : HostBridge {
     override val storage = MyStorage()
-    override fun onCoreResponse(frame: ByteArray) = transport.sendToProduct(frame)
+    override fun onCoreResponse(frame: ByteArray) { /* not used in WS-bridge mode */ }
     override fun navigateTo(url: String) { /* open in browser */ }
     override fun pushNotification(payload: ByteArray) { /* show notification */ }
     override fun devicePermission(request: ByteArray): Boolean = TODO("prompt user")
     override fun remotePermission(request: ByteArray): Boolean = TODO("prompt user")
     override fun featureSupported(request: ByteArray): Boolean = false
 }
 
+val core = TrUAPIHostCore(MyBridge())
+val endpoint = core.startWsBridge()
+val wsUrl = "ws://127.0.0.1:${endpoint.port.toInt()}/?t=${endpoint.token}"
+
+// Inject `wsUrl` into the product page (e.g. as a query string or via an
+// initial WKUserScript). Product JS uses `@parity/truapi`'s
+// `createWebSocketProvider(wsUrl)` to open the wire.
 val webView: WebView = existingWebView
-lateinit var transport: WebViewTransport
-val bridge = MyBridge(transport = WebViewTransport(webView, core = object : io.parity.truapi.CoreInbound {
-    override fun receiveFromProduct(frame: ByteArray) = core.receiveFromProduct(frame)
-}).also { transport = it })
-val core = TrUAPIHostCore(bridge)
-transport.attach()
+webView.loadUrl("https://your-product.example/?truapi=${java.net.URLEncoder.encode(wsUrl, "UTF-8")}")
 ```
 
-(In practice, build the `TrUAPIHostCore` first, hand it to a `WebViewTransport`, and have the bridge close back over the same transport instance.)
-
 ## Loading the cdylib
 
 JNA looks for `libtruapi_server.so` in the standard `jniLibs` paths. Bundle the per-ABI builds under:
@@ -98,7 +85,7 @@ src/main/jniLibs/armeabi-v7a/libtruapi_server.so
 src/main/jniLibs/x86_64/libtruapi_server.so
 ```
 
-Build the cdylib with the `ws-bridge` feature if you want `startWsBridge` to be functional:
+Build the cdylib with the `ws-bridge` feature so `startWsBridge` is functional:
 
 ```
 cargo build -p truapi-server --release --features ws-bridge --target <android-target>
@@ -115,3 +102,5 @@ cargo run -p uniffi-bindgen-cli -- generate \
   --language kotlin \
   --out-dir android/src/main/kotlin/generated
 ```
+
+Or run `make uniffi` from the repo root.

android/build.gradle.kts

@@ -1,10 +1,11 @@
 // TrUAPI Android host adapter.
 //
 // Wraps the UniFFI-generated bindings in `src/main/kotlin/generated/uniffi/`
-// behind a thin Kotlin API and provides a WebView byte transport for the
-// product page. The Rust core (compiled to libtruapi_server.so) handles all
-// wire decoding, routing, subscription lifecycle, and host capability
-// dispatch.
+// behind a thin Kotlin API. Products running in a `WebView` connect to the
+// Rust core through its localhost WebSocket bridge (see
+// `TrUAPIHostCore.startWsBridge`); the Rust core (compiled to
+// `libtruapi_server.so`) handles wire decoding, routing, subscription
+// lifecycle, and host capability dispatch.
 
 plugins {
     id("com.android.library")

android/src/main/kotlin/io/parity/truapi/TrUAPIHost.kt

@@ -5,24 +5,24 @@
 // wire protocol, request routing, subscription lifecycle, and platform trait
 // dispatch.
 //
-// This file exposes two things on top of the generated bindings:
+// This file exposes:
 //
-//   * `HostBridge` - a Kotlin-friendly callback interface the embedding app
+//   * `HostBridge` - the Kotlin-friendly callback interface the embedding app
 //     implements. It splits device and remote permissions, mirroring the
 //     `Permissions` platform trait in the Rust core.
-//   * `WebViewTransport` - a thin byte transport that forwards opaque wire
-//     bytes between a `WebView` and the Rust core. Bytes traverse the
-//     `JavascriptInterface` boundary as base64 because the bridge cannot
-//     carry binary types directly.
+//   * `TrUAPIHostCore` - owning wrapper around the UniFFI-generated
+//     `NativeTrUApiCore`. Holds the bridge alive for the lifetime of the
+//     core and exposes session + WS-bridge controls.
 //
-// The transport is independent of the core: tests can stand up a
-// `WebViewTransport` against a non-UniFFI stub by implementing `CoreInbound`.
+// Products running inside a `WebView` connect to the Rust core via the
+// localhost WebSocket bridge. Start it with `core.startWsBridge()` and load
+// the product page with the resulting `ws://127.0.0.1:<port>/?t=<token>` URL
+// passed through to the product's `@parity/truapi` `createWebSocketProvider`
+// call. The base64 `JavascriptInterface` shim previously living here has
+// been removed.
 
 package io.parity.truapi
 
-import android.util.Base64
-import android.webkit.JavascriptInterface
-import android.webkit.WebView
 import uniffi.truapi_server.HostCallbacks
 import uniffi.truapi_server.HostNavigateRejection
 import uniffi.truapi_server.HostRejection
@@ -137,27 +137,28 @@ private class HostCallbackAdapter(private val bridge: HostBridge) : HostCallback
 }
 
 /**
- * Sink for opaque wire frames coming from the WebView. The Rust core is the
- * typical implementor (via [TrUAPIHostCore]); tests may use a stub.
- */
-fun interface CoreInbound {
-    fun receiveFromProduct(frame: ByteArray)
-}
-
-/**
- * Owning wrapper around the Rust-backed [NativeTrUApiCore]. Implements
- * [CoreInbound] so a [WebViewTransport] can deliver inbound frames directly,
- * and exposes session and WS bridge controls.
+ * Owning wrapper around the Rust-backed [NativeTrUApiCore]. Holds the bridge
+ * alive for the lifetime of the core and exposes session + WS-bridge
+ * controls.
  *
- * The wrapper holds a strong reference to the bridge so the JNA callback
- * registration stays alive for the lifetime of the core.
+ * Hosts integrating with a `WebView`-based product call [startWsBridge] and
+ * pass the resulting `ws://127.0.0.1:<port>/?t=<token>` URL to the product
+ * (typically via a query string or page-bootstrap hook). The product wires
+ * that URL into `@parity/truapi`'s `createWebSocketProvider`. Direct
+ * [receiveFromProduct] calls are still available for tests or alternative
+ * transports.
  */
-class TrUAPIHostCore(bridge: HostBridge) : CoreInbound, AutoCloseable {
+class TrUAPIHostCore(bridge: HostBridge) : AutoCloseable {
     @Suppress("unused") // retained to keep JNA callbacks alive
     private val callbackRetainer: HostCallbacks = HostCallbackAdapter(bridge)
     private val inner: NativeTrUApiCore = NativeTrUApiCore(callbackRetainer)
 
-    override fun receiveFromProduct(frame: ByteArray): Unit {
+    /**
+     * Deliver an opaque SCALE-encoded wire frame into the Rust core. The WS
+     * bridge feeds the core internally; this entrypoint is exposed for tests
+     * and alternative transports.
+     */
+    fun receiveFromProduct(frame: ByteArray) {
         inner.receiveFromProduct(frame)
     }
 
@@ -173,7 +174,12 @@ class TrUAPIHostCore(bridge: HostBridge) : CoreInbound, AutoCloseable {
         inner.clearActiveSession()
     }
 
-    /** Start the localhost WebSocket bridge (requires the `ws-bridge` feature in the cdylib). */
+    /**
+     * Start the localhost WebSocket bridge (requires the `ws-bridge` feature
+     * in the cdylib). The returned [WsBridgeEndpoint] carries the port and
+     * session token; build a `ws://127.0.0.1:<port>/?t=<token>` URL and pass
+     * it to the product's `createWebSocketProvider` call.
+     */
     @Throws(WsBridgeStartException::class)
     fun startWsBridge(bindPort: UShort = 0u): WsBridgeEndpoint =
         inner.startWsBridge(bindPort)
@@ -191,77 +197,3 @@ class TrUAPIHostCore(bridge: HostBridge) : CoreInbound, AutoCloseable {
         inner.close()
     }
 }
-
-/**
- * Wraps a [WebView] and forwards opaque wire bytes between JS and [core].
- * Attach with [attach] before loading the page so the JS shim is installed.
- */
-class WebViewTransport(
-    private val webView: WebView,
-    private val core: CoreInbound,
-    private val callbackName: String = "__trUApiReceive",
-    private val interfaceName: String = "TrUApi",
-) {
-    fun attach() {
-        webView.addJavascriptInterface(JsInterface(), interfaceName)
-    }
-
-    fun detach() {
-        webView.removeJavascriptInterface(interfaceName)
-    }
-
-    /**
-     * JS bootstrap to inject at document start so the page exposes a
-     * `window.trUApi` byte-pipe matching the JS host adapter shape.
-     */
-    val bootstrapScript: String = """
-        (function() {
-          var listeners = [];
-          window.$callbackName = function(b64) {
-            try {
-              var bin = atob(b64);
-              var bytes = new Uint8Array(bin.length);
-              for (var i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
-              listeners.forEach(function(l) { l(bytes); });
-            } catch (e) { console.error('trUApi recv error', e); }
-          };
-          function toB64(u8) {
-            var s = '';
-            for (var i = 0; i < u8.length; i++) s += String.fromCharCode(u8[i]);
-            return btoa(s);
-          }
-          window.trUApi = {
-            postMessage: function(bytes) {
-              window.$interfaceName.postMessage(toB64(bytes));
-            },
-            subscribe: function(cb) {
-              listeners.push(cb);
-              return function() {
-                var i = listeners.indexOf(cb);
-                if (i >= 0) listeners.splice(i, 1);
-              };
-            }
-          };
-          window.dispatchEvent(new Event('truapi-native-ready'));
-        })();
-    """.trimIndent()
-
-    /** Called when the core has bytes to push to the product app. */
-    fun sendToProduct(frame: ByteArray) {
-        val b64 = Base64.encodeToString(frame, Base64.NO_WRAP)
-        val js = "window.$callbackName && window.$callbackName('$b64')"
-        webView.post { webView.evaluateJavascript(js, null) }
-    }
-
-    private inner class JsInterface {
-        @JavascriptInterface
-        fun postMessage(b64: String) {
-            val frame = try {
-                Base64.decode(b64, Base64.NO_WRAP)
-            } catch (_: IllegalArgumentException) {
-                return
-            }
-            core.receiveFromProduct(frame)
-        }
-    }
-}