From 84f7daa0ce2134d5c4bc48e0224f7be130ebe85f Mon Sep 17 00:00:00 2001 From: Ivan FB Date: Thu, 16 Jul 2026 15:41:03 +0200 Subject: [PATCH] docs: make the available operations discoverable; document local use MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consuming apps depend on this crate from a local checkout, and the operations were hard to find: the crate root was `pub use waku_sys::*`, so everything a caller can do was hidden as methods on a glob-exported LogosDeliveryCtx. The crate-root docs now carry an Operations map — node lifecycle, messaging, reliable channels, and the typed event listeners — with the method names and a runnable example, so `cargo doc` and reading lib.rs both show what is callable. The low-level waku_* kernel surface is noted as the tier beneath. The README gains a "Using the crate" section: clone + checkout, the local path dependency, and the Nim/make/Rust build prerequisites. Also fixes stale rustdoc links in the restored store DTOs and a bare URL in the config docs, so the doc build is warning-clean. Co-Authored-By: Claude Opus 4.8 --- README.md | 42 +++++++++++++++ waku-bindings/src/general/store.rs | 4 +- waku-bindings/src/lib.rs | 82 ++++++++++++++++++++++++++---- waku-bindings/src/node/config.rs | 2 +- 4 files changed, 118 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index ba8c5c0..1425ef2 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,48 @@ 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). +## Using the crate + +For now this crate is consumed from a local checkout rather than a registry. + +1. Clone the repo and check out the branch you want: + + ```sh + git clone --recurse-submodules https://github.com/logos-messaging/logos-delivery-rust-bindings + cd logos-delivery-rust-bindings + git checkout + git submodule update --init --recursive + ``` + +2. Point your app at it by path: + + ```toml + # your app's Cargo.toml + [dependencies] + waku-bindings = { path = "../logos-delivery-rust-bindings/waku-bindings" } + ``` + +### Build prerequisites + +`waku-bindings` builds the underlying Nim library from source the first time, +so the toolchain has to be present: + +- **Nim** and **nimble** (installed by the vendored `make` targets, or bring + your own on `PATH`) +- **make** and a C/C++ toolchain +- A **Rust** toolchain (RLN is built from source) + +The first build compiles the whole logos-delivery tree and is slow; subsequent +builds are incremental. + +## What you can call + +Everything is driven through `LogosDeliveryCtx` (re-exported at the crate root). +The crate docs group the available operations — node lifecycle, messaging, +reliable channels, and the typed event listeners — under **Operations**; run +`cargo doc --open -p waku-bindings` for the full, linked method list. A minimal +end-to-end example lives in [`examples/basic`](examples/basic). + ## About Waku [Waku](https://waku.org/) is a family of robust and censorship-resistant communication protocols enabling privacy-focused messaging for Web3 applications. diff --git a/waku-bindings/src/general/store.rs b/waku-bindings/src/general/store.rs index 56233f6..f8bf559 100644 --- a/waku-bindings/src/general/store.rs +++ b/waku-bindings/src/general/store.rs @@ -127,10 +127,10 @@ pub struct StoreResponse { #[allow(unused)] pub status_desc: String, - /// Array of retrieved historical messages in [`WakuMessage`] format + /// Array of retrieved historical messages in `WakuMessage` format // #[serde(default)] pub messages: Vec, - /// Paging information in [`PagingOptions`] format from which to resume further historical queries + /// Paging information in `PagingOptions` format from which to resume further historical queries #[serde(skip_serializing_if = "Option::is_none")] pub pagination_cursor: Option, } diff --git a/waku-bindings/src/lib.rs b/waku-bindings/src/lib.rs index 2eb2f39..b50545d 100644 --- a/waku-bindings/src/lib.rs +++ b/waku-bindings/src/lib.rs @@ -1,16 +1,79 @@ -//! # Waku +//! # waku-bindings //! -//! The FFI surface is generated from the Nim source by nim-ffi and re-exported -//! here wholesale: drive a node through `LogosDeliveryCtx`, and observe it -//! through its typed `add_on_*_listener` methods. What this crate adds on top is -//! the domain layer — [`WakuMessage`], [`WakuContentTopic`], [`MessageHash`] and -//! friends — plus [`WakuNodeConfig`], which serialises to the JSON that -//! `LogosDeliveryCtx::create` expects. +//! Rust bindings for logos-delivery (Waku). A node is driven through +//! [`LogosDeliveryCtx`], generated from the Nim source by nim-ffi and +//! re-exported here; this crate adds the typed domain layer ([`WakuMessage`], +//! [`WakuContentTopic`], [`MessageHash`]) and [`WakuNodeConfig`], which +//! serialises to the JSON [`LogosDeliveryCtx::create`] expects. +//! +//! ## Operations +//! +//! Every operation is an `async` method on [`LogosDeliveryCtx`] (each also has a +//! blocking twin without the `_async` suffix). Events are registered with +//! `add_on_*_listener`, which hand back a typed payload. +//! +//! ### Node lifecycle +//! - [`LogosDeliveryCtx::new_async`] / [`create`](LogosDeliveryCtx::create) — +//! build a node from a [`WakuNodeConfig`] JSON string +//! - [`start_node_async`](LogosDeliveryCtx::start_node_async) / +//! [`stop_node_async`](LogosDeliveryCtx::stop_node_async) +//! - teardown is the `Drop` impl — there is no explicit destroy +//! +//! ### Messaging +//! - [`subscribe_async`](LogosDeliveryCtx::subscribe_async) / +//! [`unsubscribe_async`](LogosDeliveryCtx::unsubscribe_async) — by content topic +//! - [`send_async`](LogosDeliveryCtx::send_async) — takes a [`SendRequest`] +//! +//! ### Reliable channels +//! - [`channel_create_async`](LogosDeliveryCtx::channel_create_async) — +//! `(channel_id, content_topic, sender_id, encryption)`; `encryption` is +//! `"noop"` today +//! - [`channel_send_async`](LogosDeliveryCtx::channel_send_async) — takes a +//! [`ChannelSendRequest`] +//! - [`channel_close_async`](LogosDeliveryCtx::channel_close_async) +//! +//! ### Events (typed listeners) +//! - messaging: `add_on_message_{sent,error,propagated,received}_listener` +//! - connectivity: `add_on_connection_{change,status_change}_listener`, +//! `add_on_topic_health_change_listener` +//! - relay: `add_on_received_message_listener` +//! - channels: `add_on_channel_message_{received,sent,error}_listener` +//! - drop one with [`remove_event_listener`](LogosDeliveryCtx::remove_event_listener) +//! +//! Beneath these sits the lower-level `waku_*` kernel surface (relay publish, +//! filter, store, peer management, discovery) — also on [`LogosDeliveryCtx`], +//! `"use at your own risk"`. +//! +//! ## Example +//! +//! ```no_run +//! use waku_bindings::{LogosDeliveryCtx, WakuNodeConfig}; +//! use std::time::Duration; +//! +//! # async fn run() -> Result<(), String> { +//! let config = serde_json::to_string(&WakuNodeConfig { +//! tcp_port: Some(60000), +//! ..Default::default() +//! }).unwrap(); +//! +//! let node = LogosDeliveryCtx::new_async(config, Duration::from_secs(30)).await?; +//! node.add_on_received_message_listener(|event| { +//! println!("received on {}", event.waku_message.content_topic); +//! }); +//! node.start_node_async().await?; +//! node.waku_relay_subscribe_async("test".to_string()).await?; +//! // node is torn down when dropped +//! # Ok(()) +//! # } +//! ``` + pub mod general; pub mod node; -// The generated bindings: LogosDeliveryCtx, ListenerHandle, and one payload type -// per event. +// The full generated FFI surface: LogosDeliveryCtx and its methods, the request +// types (SendRequest, ChannelSendRequest), and one payload type per event. See +// the Operations section above for the map; browse `LogosDeliveryCtx` in the +// docs for the complete method list. pub use waku_sys::*; // Required so functions inside libwaku can call RLN functions even if we @@ -19,6 +82,7 @@ pub use waku_sys::*; #[allow(unused)] use rln; +// The typed domain layer this crate adds on top of the generated surface. pub use general::contenttopic::{Encoding, WakuContentTopic}; pub use general::store::{StoreQueryRequest, StoreResponse, StoreWakuMessageResponse}; pub use general::{messagehash::MessageHash, Result, WakuMessage, WakuMessageVersion}; diff --git a/waku-bindings/src/node/config.rs b/waku-bindings/src/node/config.rs index 3da8dff..1fb0078 100644 --- a/waku-bindings/src/node/config.rs +++ b/waku-bindings/src/node/config.rs @@ -94,7 +94,7 @@ pub struct RLNConfig { /// On-chain dynamic group management #[serde(skip_serializing_if = "Option::is_none")] pub dynamic: Option, - /// Path to the RLN merkle tree sled db (https://github.com/spacejam/sled) + /// Path to the RLN merkle tree sled db () #[serde(skip_serializing_if = "Option::is_none")] pub tree_path: Option, /// Message rate in bytes/sec after which verification of proofs should happen