From 647a3a2b84a49ee8025ddab4090c1a9260a7b092 Mon Sep 17 00:00:00 2001 From: Gregory Fong Date: Wed, 11 Nov 2026 17:25:22 -0800 Subject: [PATCH 1/2] client/uniffi: rename LzError's `message` fields; compile the bindings in CI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `LzError::Lease` and `LzError::Registration` had a field named `message`. UniFFI makes each variant a Kotlin exception class, where that property clashes with `Throwable.message`, so the generated Kotlin didn't compile. Rename the field to `reason`. This changes the Swift and Kotlin API, which v0 allows (spec §7). Add `client/uniffi/check-bindings.sh` and a CI job that runs it: it generates the bindings, compiles the Kotlin against JNA (pinned compiler and JNA, checked by SHA-256), and typechecks the Swift against the generated header. The README also says what to do with the stray `liblz_client_uniffi-.so` that cargo-ndk copies into `jniLibs` for an app crate that depends on this one. Fixes #14 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 13 ++++++ client/uniffi/README.md | 21 +++++++-- client/uniffi/check-bindings.sh | 82 +++++++++++++++++++++++++++++++++ client/uniffi/src/lib.rs | 14 +++--- 4 files changed, 119 insertions(+), 11 deletions(-) create mode 100755 client/uniffi/check-bindings.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4c902a4..ae8fba3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -49,6 +49,19 @@ jobs: - if: matrix.toolchain == '1.89' run: cargo +1.89 test --workspace --locked + # The generated Swift and Kotlin bindings compile (client/uniffi). + uniffi-bindings: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # The pinned toolchain (rust-toolchain.toml), which the script's cargo uses. + - run: rustup toolchain install + - run: client/uniffi/check-bindings.sh + env: + CARGO_FLAGS: --locked + # Integration tests against real Zebra and Zaino on a private regtest # chain (deploy/regtest). regtest: diff --git a/client/uniffi/README.md b/client/uniffi/README.md index 270b8e0..9c1a401 100644 --- a/client/uniffi/README.md +++ b/client/uniffi/README.md @@ -6,10 +6,10 @@ that have no Rust library of their own: native apps, and React Native or other cross-platform apps through a native module over these. **Status: prototype.** Tested in Rust against a stand-in OHTTP gateway -(`tests/bindings.rs`), and the generated Swift compiles and runs against -the static library on macOS. The Kotlin is generated but not yet compiled. -Not yet built for iOS or Android targets in CI, and not yet used in an -app. +(`tests/bindings.rs`). CI generates the Swift and Kotlin and compiles +both (`check-bindings.sh`: Kotlin against JNA, Swift against the +generated header), and the Swift runs against the static library on +macOS. Not yet built for iOS or Android targets in CI. **Wallet SDKs don't need this.** If the app already ships a Rust library (as ZODL's SDKs do), compile `lz-client` into it and expose it through @@ -77,6 +77,19 @@ from it, and runs `generate --library` on that library: UniFFI's library mode generates bindings for every crate in it. The app still links one Rust library. +On Android, `cargo-ndk` copies every shared library the build produced +into `jniLibs`. This crate is also a `cdylib` (for apps that use it on +its own), so next to the app's library you get a +`liblz_client_uniffi-.so`. Nothing loads it, since the app's +library already contains the crate, so delete it from `jniLibs` after +the build rather than shipping a second Rust library. + +To check that the bindings still compile after changing the exported +API, run `client/uniffi/check-bindings.sh` (needs a JDK; downloads a +pinned Kotlin compiler and JNA). Some names break only one language: a +field named `message` or `cause` clashes with Kotlin's `Throwable` +(issue #14). + ## Versioning The bindings track `lz-client` and the protocol version. v0 has no diff --git a/client/uniffi/check-bindings.sh b/client/uniffi/check-bindings.sh new file mode 100755 index 0000000..4c16574 --- /dev/null +++ b/client/uniffi/check-bindings.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash +# Generates the Swift and Kotlin bindings and compiles both, so a change +# to the exported API that breaks one language fails here, not in an app +# (issue #14: a field named `message` clashed with `Throwable.message`). +# +# Needs: cargo, a JDK (java on PATH or JAVA_HOME), curl, unzip. Swift is +# checked when `swiftc` is on PATH (Xcode on macOS, preinstalled on +# GitHub's Ubuntu runners). The Kotlin compiler and JNA are downloaded at +# pinned versions and checked against their published SHA-256 sums. +# +# Usage: client/uniffi/check-bindings.sh [work-dir] +set -euo pipefail + +KOTLIN_VERSION=2.4.21 +KOTLIN_SHA256=7cc140e76daf416a0424a5557f99afd7ca89ebd463ea1101261e3e01c33e75cd +JNA_VERSION=5.17.0 +JNA_SHA256=b3a9408e7c51e08ef0e3bfcc08f443f6ec0f6191ba8cd7c18d53d2b22e5bdbc0 + +root=$(cd "$(dirname "$0")/../.." && pwd) +work=${1:-"$root/target/uniffi-check"} +mkdir -p "$work" +work=$(cd "$work" && pwd) +cd "$root" + +sha256() { + if command -v sha256sum >/dev/null; then sha256sum "$1"; else shasum -a 256 "$1"; fi | cut -d' ' -f1 +} + +# fetch URL FILE SHA256: download once, verify every time. +fetch() { + if [[ ! -f "$work/$2" ]]; then + curl -fsSL --retry 3 -o "$work/$2.part" "$1" + mv "$work/$2.part" "$work/$2" + fi + local got + got=$(sha256 "$work/$2") + if [[ "$got" != "$3" ]]; then + echo "check-bindings: $2 has SHA-256 $got, expected $3" >&2 + rm -f "$work/$2" + exit 1 + fi +} + +case "$(uname -s)" in + Darwin) lib=liblz_client_uniffi.dylib ;; + *) lib=liblz_client_uniffi.so ;; +esac + +# shellcheck disable=SC2086 # CARGO_FLAGS is a list of flags +cargo build -p lz-client-uniffi ${CARGO_FLAGS:-} +out="$work/out" +rm -rf "$out" +# shellcheck disable=SC2086 +cargo run -p lz-client-uniffi --features bindgen --bin uniffi-bindgen ${CARGO_FLAGS:-} -- \ + generate --library "target/debug/$lib" \ + --language swift --language kotlin --no-format --out-dir "$out" + +# Kotlin: compile against JNA, as an Android app does. +fetch "https://github.com/JetBrains/kotlin/releases/download/v$KOTLIN_VERSION/kotlin-compiler-$KOTLIN_VERSION.zip" \ + "kotlin-compiler-$KOTLIN_VERSION.zip" "$KOTLIN_SHA256" +fetch "https://repo1.maven.org/maven2/net/java/dev/jna/jna/$JNA_VERSION/jna-$JNA_VERSION.jar" \ + "jna-$JNA_VERSION.jar" "$JNA_SHA256" +kotlinc="$work/kotlinc-$KOTLIN_VERSION/bin/kotlinc" +if [[ ! -x "$kotlinc" ]]; then + rm -rf "$work/kotlinc-$KOTLIN_VERSION" "$work/kotlinc" + unzip -q "$work/kotlin-compiler-$KOTLIN_VERSION.zip" -d "$work" + mv "$work/kotlinc" "$work/kotlinc-$KOTLIN_VERSION" +fi +rm -rf "$work/classes" +"$kotlinc" -nowarn -cp "$work/jna-$JNA_VERSION.jar" \ + "$out/uniffi/lz_client_uniffi/lz_client_uniffi.kt" -d "$work/classes" +echo "check-bindings: Kotlin compiles" + +# Swift: typecheck against the generated C header and module map. +if command -v swiftc >/dev/null; then + swiftc -typecheck -I "$out" \ + -Xcc -fmodule-map-file="$out/lz_client_uniffiFFI.modulemap" \ + "$out/lz_client_uniffi.swift" + echo "check-bindings: Swift typechecks" +else + echo "check-bindings: no swiftc on PATH; Swift not checked" >&2 +fi diff --git a/client/uniffi/src/lib.rs b/client/uniffi/src/lib.rs index eff0d7f..6a0b1eb 100644 --- a/client/uniffi/src/lib.rs +++ b/client/uniffi/src/lib.rs @@ -87,12 +87,12 @@ pub enum LzError { KeyConfigInconsistent, #[error("Tor transport needs a .onion server")] OnionOnly, - /// The lease breaks a rule of spec §4.2 (`message` says which). - #[error("invalid lease: {message}")] - Lease { message: String }, + /// The lease breaks a rule of spec §4.2 (`reason` says which). + #[error("invalid lease: {reason}")] + Lease { reason: String }, /// The device registration breaks a rule of spec §4.1. - #[error("invalid registration: {message}")] - Registration { message: String }, + #[error("invalid registration: {reason}")] + Registration { reason: String }, #[error("server error {status} ({problem})")] Server { status: u16, problem: String }, @@ -152,10 +152,10 @@ impl From for LzError { E::KeyConfigInconsistent => Self::KeyConfigInconsistent, E::OnionOnly => Self::OnionOnly, E::Lease(l) => Self::Lease { - message: l.to_string(), + reason: l.to_string(), }, E::Registration(r) => Self::Registration { - message: r.to_string(), + reason: r.to_string(), }, E::Server { status, problem } => Self::Server { status, problem }, } From 1cddd91abb241781d20f18c97afd841c39b45c50 Mon Sep 17 00:00:00 2001 From: Gregory Fong Date: Wed, 11 Nov 2026 18:51:55 -0800 Subject: [PATCH 2/2] client/uniffi: review fixes for the bindings check - The lease test checks that `reason` carries the core's text, not only the variant. - check-bindings.sh fails in CI when `swiftc` is missing instead of skipping Swift, downloads over HTTPS only, and says the Swift is typechecked rather than compiled. - CONTRIBUTING.md lists the script for changes to what client/uniffi exports. Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 7 +++++++ client/uniffi/check-bindings.sh | 17 +++++++++++------ client/uniffi/tests/bindings.rs | 12 ++++++++---- 3 files changed, 26 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 425e3ca..e68e82e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,6 +150,13 @@ Optional binaries for a full local match to CI lint: [`cargo-machete`](https://github.com/bnjbvr/cargo-machete), [`typos`](https://github.com/crate-ci/typos) (`cargo install typos-cli --locked`). +If you change what `client/uniffi` exports, also check that the +generated Swift and Kotlin still compile (needs a JDK; CI runs it too): + +```sh +client/uniffi/check-bindings.sh +``` + If you change the chain follower, scanner, or mempool code, also run the regtest tests against real Zebra and Zaino (needs Docker; CI runs them too). This starts a chain of its own, so it won't disturb one already running diff --git a/client/uniffi/check-bindings.sh b/client/uniffi/check-bindings.sh index 4c16574..d87144c 100755 --- a/client/uniffi/check-bindings.sh +++ b/client/uniffi/check-bindings.sh @@ -1,12 +1,14 @@ #!/usr/bin/env bash -# Generates the Swift and Kotlin bindings and compiles both, so a change -# to the exported API that breaks one language fails here, not in an app -# (issue #14: a field named `message` clashed with `Throwable.message`). +# Generates the Swift and Kotlin bindings, compiles the Kotlin, and +# typechecks the Swift, so a change to the exported API that breaks one +# language fails here, not in an app (issue #14: a field named `message` +# clashed with `Throwable.message`). # # Needs: cargo, a JDK (java on PATH or JAVA_HOME), curl, unzip. Swift is # checked when `swiftc` is on PATH (Xcode on macOS, preinstalled on -# GitHub's Ubuntu runners). The Kotlin compiler and JNA are downloaded at -# pinned versions and checked against their published SHA-256 sums. +# GitHub's Ubuntu runners); in CI (`CI` set) a missing `swiftc` is an +# error. The Kotlin compiler and JNA are downloaded at pinned versions and +# checked against their published SHA-256 sums before anything runs. # # Usage: client/uniffi/check-bindings.sh [work-dir] set -euo pipefail @@ -29,7 +31,7 @@ sha256() { # fetch URL FILE SHA256: download once, verify every time. fetch() { if [[ ! -f "$work/$2" ]]; then - curl -fsSL --retry 3 -o "$work/$2.part" "$1" + curl -fsSL --proto '=https' --tlsv1.2 --retry 3 -o "$work/$2.part" "$1" mv "$work/$2.part" "$work/$2" fi local got @@ -77,6 +79,9 @@ if command -v swiftc >/dev/null; then -Xcc -fmodule-map-file="$out/lz_client_uniffiFFI.modulemap" \ "$out/lz_client_uniffi.swift" echo "check-bindings: Swift typechecks" +elif [[ -n "${CI:-}" ]]; then + echo "check-bindings: no swiftc on PATH" >&2 + exit 1 else echo "check-bindings: no swiftc on PATH; Swift not checked" >&2 fi diff --git a/client/uniffi/tests/bindings.rs b/client/uniffi/tests/bindings.rs index 938c5b9..05e5c05 100644 --- a/client/uniffi/tests/bindings.rs +++ b/client/uniffi/tests/bindings.rs @@ -208,10 +208,14 @@ fn leases_are_checked_before_sending() { spend_alerts: false, alert_mode: AlertMode::Private, }; - assert!(matches!( - c.wake(NOW, Some(full)), - Err(LzError::Lease { .. }) - )); + let err = c.wake(NOW, Some(full)).unwrap_err(); + let LzError::Lease { reason } = &err else { + panic!("expected a lease error, got {err:?}"); + }; + // `reason`, not `message`: that name clashes with Kotlin's + // `Throwable.message` (issue #14). + assert!(!reason.is_empty()); + assert_eq!(err.to_string(), format!("invalid lease: {reason}")); } #[test]