Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
7 changes: 7 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 17 additions & 4 deletions client/uniffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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-<hash>.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
Expand Down
87 changes: 87 additions & 0 deletions client/uniffi/check-bindings.sh
Original file line number Diff line number Diff line change
@@ -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
14 changes: 7 additions & 7 deletions client/uniffi/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 },

Expand Down Expand Up @@ -152,10 +152,10 @@ impl From<lz_client::Error> 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 },
}
Expand Down
12 changes: 8 additions & 4 deletions client/uniffi/tests/bindings.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Loading