diff --git a/.gitmodules b/.gitmodules index aa143c0..d5f2df2 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,3 @@ [submodule "waku-sys/vendor"] path = waku-sys/vendor - url = https://github.com/logos-messaging/logos-messaging-nim + url = https://github.com/logos-messaging/logos-delivery diff --git a/README.md b/README.md index ba8c5c0..bae5a79 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Waku Rust bindings +# logos-delivery Rust Bindings [![Crates.io][crates-badge]][crates-url] [![Documentation][docs-badge]][docs-url] @@ -9,18 +9,98 @@ [crates-url]: https://crates.io/crates/waku-bindings [docs-badge]: https://docs.rs/waku-bindings/badge.svg [docs-url]: https://docs.rs/waku-bindings -[actions-badge]: https://github.com/logos-messaging/logos-messaging-rust-bindings/workflows/CI/badge.svg -[actions-url]: https://github.com/logos-messaging/logos-messaging-rust-bindings/actions/workflows/main.yml?query=workflow%3ACI+branch%3Amaster -[codecov-badge]: https://codecov.io/github/logos-messaging/logos-messaging-rust-bindings/branch/main/graph/badge.svg?token=H4CQWRUCUS -[codecov-url]: https://codecov.io/github/logos-messaging/logos-messaging-rust-bindings +[actions-badge]: https://github.com/logos-messaging/logos-delivery-rust-bindings/workflows/CI/badge.svg +[actions-url]: https://github.com/logos-messaging/logos-delivery-rust-bindings/actions/workflows/main.yml?query=workflow%3ACI+branch%3Amaster +[codecov-badge]: https://codecov.io/github/logos-messaging/logos-delivery-rust-bindings/branch/main/graph/badge.svg?token=H4CQWRUCUS +[codecov-url]: https://codecov.io/github/logos-messaging/logos-delivery-rust-bindings -Rust layer on top of [`logos-messaging-nim`](https://github.com/logos-messaging/logos-messaging-nim) [C FFI bindings](https://github.com/logos-messaging/logos-messaging-nim/blob/master/library/libwaku.h). +Rust bindings for [logos-delivery](https://github.com/logos-messaging/logos-delivery) (Waku) v0.38.0-beta, +built on top of the [C FFI](https://github.com/logos-messaging/logos-delivery/blob/master/library/libwaku.h). +## Prerequisites + +- **Rust** (stable) — [rustup.rs](https://rustup.rs) +- **Nim 2.x** — required to compile the native `libwaku` library +- **Make** +- **GCC or Clang** + +## Setup + +Clone the repository: + +```bash +git clone https://github.com/logos-messaging/logos-delivery-rust-bindings.git +cd logos-delivery-rust-bindings +``` + +The first `cargo build` / `cargo run` automatically: +1. Initializes and updates git submodules +2. Compiles the native `libwaku` static library via `make libwaku STATIC=1` +3. Generates Rust FFI bindings via `bindgen` + +## Running the Examples + +### basic + +Two Waku nodes in the same process. Node 1 publishes a message; node 2 receives it via relay subscription. + +```bash +cd examples/basic +cargo run +``` + +### toy-chat + +Multi-participant chat room over Waku relay. Pass your nickname as argument. + +```bash +cd examples/toy-chat +cargo run "Alice" +``` + +Start another instance in a separate terminal (or on another machine) to chat: + +```bash +cargo run "Bob" +``` + +### tic-tac-toe-gui + +Multiplayer tic-tac-toe with a native GUI (eframe). Start two instances — locally or on separate machines. + +```bash +cd examples/tic-tac-toe-gui +cargo run +``` + +## Running the Tests + +Tests start real Waku nodes and bind to local TCP ports, so they **must run serially**: + +```bash +# from repo root +cargo test -p waku-bindings -- --test-threads=1 + +# or from waku-bindings/ +cd waku-bindings +cargo test +``` + +To see log output: + +```bash +cargo test -- --nocapture +``` + +## Crates + +| Crate | Description | +|-------|-------------| +| [`waku-bindings`](waku-bindings/) | High-level Rust API | +| [`waku-sys`](waku-sys/) | Low-level bindgen FFI bindings | ## About Waku -[Waku](https://waku.org/) is a family of robust and censorship-resistant communication protocols enabling privacy-focused messaging for Web3 applications. - -Private. Secure. Runs anywhere. +[Waku](https://waku.org/) is a family of robust, censorship-resistant communication protocols for Web3. Private. Secure. Runs anywhere. Read the [Waku docs](https://docs.waku.org/) diff --git a/waku-bindings/Cargo.toml b/waku-bindings/Cargo.toml index 8e11726..581dba3 100644 --- a/waku-bindings/Cargo.toml +++ b/waku-bindings/Cargo.toml @@ -9,7 +9,7 @@ authors = [ ] description = "Waku networking library" license = "MIT OR Apache-2.0" -repository = "https://github.com/logos-messaging/logos-messaging-rust-bindings" +repository = "https://github.com/logos-messaging/logos-delivery-rust-bindings" keywords = ["waku", "peer-to-peer", "libp2p", "networking"] categories = ["network-programming"] diff --git a/waku-bindings/README.md b/waku-bindings/README.md index 742f4f2..0ce42a9 100644 --- a/waku-bindings/README.md +++ b/waku-bindings/README.md @@ -1,11 +1,12 @@ # Waku Rust bindings -[github](https://github.com/logos-messaging/logos-messaging-rust-bindings) +[github](https://github.com/logos-messaging/logos-delivery-rust-bindings) [crates.io](https://crates.io/crates/waku-bindings) [docs.rs](https://docs.rs/waku-bindings) -[build status](https://github.com/logos-messaging/logos-messaging-rust-bindings/actions/workflows/main.yml?query=branch%3Amaster) +[build status](https://github.com/logos-messaging/logos-delivery-rust-bindings/actions/workflows/main.yml?query=branch%3Amaster) -Rust api on top of [`waku-sys`](https://crates.io/crates/waku-sys) bindgen bindings to [c ffi bindings](https://github.com/status-im/go-waku/blob/v0.2.2/library/README.md). +High-level Rust API on top of [`waku-sys`](https://crates.io/crates/waku-sys) bindgen bindings to the +[logos-delivery C FFI](https://github.com/logos-messaging/logos-delivery/blob/master/library/libwaku.h). ## Usage @@ -14,28 +15,86 @@ Add this to your `Cargo.toml`: ```toml [dependencies] -waku-bindings = "0.1.0" +waku-bindings = "1.0.0" ``` +## Testing + +### Prerequisites + +- **Rust** (stable) — [rustup.rs](https://rustup.rs) +- **Nim 2.x** — required to compile the native `libwaku` library +- **Make** +- **GCC or Clang** + +### Setup + +Clone the repository: + +```bash +git clone https://github.com/logos-messaging/logos-delivery-rust-bindings.git +cd logos-delivery-rust-bindings +``` + +The first `cargo build` / `cargo test` automatically: +1. Initializes and updates git submodules +2. Builds the native `libwaku` static library via `make libwaku STATIC=1` +3. Generates Rust FFI bindings via `bindgen` + +### Running the tests + +From the repo root or the `waku-bindings/` directory: + +```bash +cargo test +``` + +> Tests must run **serially** — they spin up real Waku nodes that bind to local TCP ports. Running them in +> parallel causes port conflicts. The `serial_test` crate enforces this automatically. + +To run a specific test: + +```bash +cargo test +``` + +For example: + +```bash +cargo test default_echo +cargo test node_restart +``` + +To see log output: + +```bash +cargo test -- --nocapture +``` + +### What the tests cover + +| Test | Description | +|------|-------------| +| `default_echo` | Creates two nodes, subscribes both to a relay topic, publishes a message from node 1, and verifies node 2 receives it | +| `node_restart` | Creates a node, starts and stops it three times in a row to verify lifecycle correctness | + + ## About [Waku](https://waku.org/) Waku is the communication layer for Web3. Decentralized communication that scales. Private. Secure. Runs anywhere. -### What is Waku? - Waku is a suite of privacy-preserving, peer-to-peer messaging protocols. Waku removes centralized third parties from messaging, enabling private, secure, censorship-free communication with no single point of failure. -Waku provides privacy-preserving capabilities, such as sender anonymity,metadata protection and unlinkability to personally identifiable information. +Waku provides privacy-preserving capabilities, such as sender anonymity, metadata protection and unlinkability to personally identifiable information. Waku is designed for generalized messaging, enabling human-to-human, machine-to-machine or hybrid communication. Waku runs everywhere: desktop, server, including resource-restricted devices, such as mobile devices and browsers. -How does it work? The first version of Waku had its origins in the Whisper protocol, with optimizations for scalability and usability. Waku v2 is a complete rewrite. Its relay protocol implements pub/sub over libp2p, and also introduces additional capabilities: @@ -45,6 +104,4 @@ The first version of Waku had its origins in the Whisper protocol, with optimiza This makes it ideal for running a p2p protocol on mobile, or in other similarly resource-restricted environments. - - -Read the [Waku docs](https://docs.wakuconnect.dev/) \ No newline at end of file +Read the [Waku docs](https://docs.waku.org/) diff --git a/waku-bindings/src/macros.rs b/waku-bindings/src/macros.rs index 4ad9608..7594e9f 100644 --- a/waku-bindings/src/macros.rs +++ b/waku-bindings/src/macros.rs @@ -1,7 +1,7 @@ use crate::general::libwaku_response::LibwakuResponse; use std::{slice, str}; -use waku_sys::WakuCallBack; +use waku_sys::FFICallBack; unsafe extern "C" fn trampoline( ret_code: ::std::os::raw::c_int, @@ -26,7 +26,7 @@ unsafe extern "C" fn trampoline( closure(result); } -pub fn get_trampoline(_closure: &F) -> WakuCallBack +pub fn get_trampoline(_closure: &F) -> FFICallBack where F: FnMut(LibwakuResponse), { @@ -57,10 +57,10 @@ macro_rules! handle_ffi_call { let code = unsafe { let cb = get_trampoline(&closure); $waku_fn( - $ctx, // Pass the context - $($($arg),*,)? // Expand the variadic arguments if provided - cb, // Pass the callback trampoline - &mut closure as *mut _ as *mut c_void + $ctx, // Pass the context + cb, // Pass the callback trampoline + &mut closure as *mut _ as *mut c_void // Pass the user data + $(, $($arg),*)? // Expand the variadic arguments if provided ) }; diff --git a/waku-bindings/src/node/context.rs b/waku-bindings/src/node/context.rs index 87afae5..9395e5e 100644 --- a/waku-bindings/src/node/context.rs +++ b/waku-bindings/src/node/context.rs @@ -49,7 +49,7 @@ impl WakuNodeContext { *boxed_closure = Box::new(closure); unsafe { let cb = get_trampoline(&(*boxed_closure)); - waku_sys::waku_set_event_callback( + waku_sys::set_event_callback( self.obj_ptr, cb, &mut (*boxed_closure) as *mut _ as *mut c_void, diff --git a/waku-sys/Cargo.toml b/waku-sys/Cargo.toml index 6bac827..b4673ba 100644 --- a/waku-sys/Cargo.toml +++ b/waku-sys/Cargo.toml @@ -9,7 +9,7 @@ authors = [ ] description = "Waku networking library generated bindings" license = "MIT OR Apache-2.0" -repository = "https://github.com/logos-messaging/logos-messaging-rust-bindings" +repository = "https://github.com/logos-messaging/logos-delivery-rust-bindings" keywords = ["waku", "peer-to-peer", "libp2p", "networking"] categories = ["network-programming"] diff --git a/waku-sys/README.md b/waku-sys/README.md index 59580fe..224b163 100644 --- a/waku-sys/README.md +++ b/waku-sys/README.md @@ -1,21 +1,22 @@ # Waku rust bindgen bindings -[github](https://github.com/logos-messaging/logos-messaging-rust-bindings) +[github](https://github.com/logos-messaging/logos-delivery-rust-bindings) [crates.io](https://crates.io/crates/waku-sys) [docs.rs](https://docs.rs/waku-sys) -[build status](https://github.com/logos-messaging/logos-messaging-rust-bindings/actions/workflows/main.yml?query=branch%3Amaster) +[build status](https://github.com/logos-messaging/logos-delivery-rust-bindings/actions/workflows/main.yml?query=branch%3Amaster) -Rust layer on top of [`go-waku`](https://github.com/status-im/go-waku) [c ffi bindings](https://github.com/status-im/go-waku/blob/v0.2.2/library/README.md). +Auto-generated Rust FFI bindings (via `bindgen`) on top of the +[logos-delivery C FFI](https://github.com/logos-messaging/logos-delivery/blob/master/library/libwaku.h). ## Usage -These are autogenerated, if you are looking for a proper Rust API version check on [`waku-bindings`](https://crates.io/crates/waku-bindings) +These are low-level auto-generated bindings. For a proper Rust API check [`waku-bindings`](https://crates.io/crates/waku-bindings). Add this to your `Cargo.toml`: ```toml [dependencies] -waku-sys = "0.1.0" +waku-sys = "1.0.0" ``` @@ -25,27 +26,4 @@ Waku is the communication layer for Web3. Decentralized communication that scale Private. Secure. Runs anywhere. -### What is Waku? - -Waku is a suite of privacy-preserving, peer-to-peer messaging protocols. - -Waku removes centralized third parties from messaging, enabling private, secure, censorship-free communication with no single point of failure. - -Waku provides privacy-preserving capabilities, such as sender anonymity,metadata protection and unlinkability to personally identifiable information. - -Waku is designed for generalized messaging, enabling human-to-human, machine-to-machine or hybrid communication. - -Waku runs everywhere: desktop, server, including resource-restricted devices, such as mobile devices and browsers. -How does it work? - -The first version of Waku had its origins in the Whisper protocol, with optimizations for scalability and usability. Waku v2 is a complete rewrite. Its relay protocol implements pub/sub over libp2p, and also introduces additional capabilities: - -1. Retrieving historical messages for mostly-offline devices. -2. Adaptive nodes, allowing for heterogeneous nodes to contribute. -3. Bandwidth preservation for light nodes. - -This makes it ideal for running a p2p protocol on mobile, or in other similarly resource-restricted environments. - - - -Read the [Waku docs](https://docs.wakuconnect.dev/) \ No newline at end of file +Read the [Waku docs](https://docs.waku.org/) diff --git a/waku-sys/vendor b/waku-sys/vendor index 4117449..104ce6e 160000 --- a/waku-sys/vendor +++ b/waku-sys/vendor @@ -1 +1 @@ -Subproject commit 4117449b9af6c0304a6115dd4bc0d1d745159685 +Subproject commit 104ce6e5ac16b9c5e818788e2fb2858c36f36bbf