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/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/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..d87144c --- /dev/null +++ b/client/uniffi/check-bindings.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash +# 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); 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 + +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 --proto '=https' --tlsv1.2 --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" +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/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 }, } 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]