Installation

Rust toolchainCopy Anchor Link

wakuwaku is written in Rust edition 2024, which needs Rust 1.85 or newer. Its dependencies raise that floor. At the versions locked for wakuwaku 1.0.0-rc3, the minimum depends on the features you enable:

Newer releases of these dependencies may raise the minimum further, so use the latest stable toolchain:

rustup update stable

Generating gRPC code also needs the Protocol Buffers compiler protoc on your PATH. Quick start shows the build script.

Add wakuwakuCopy Anchor Link

Add wakuwaku with the features you need, plus tokio for the runtime:

[dependencies]
wakuwaku = "1.0.0-rc3" # defaults: grpc, proof
tokio = { version = "1.53", features = ["full"] }

entity is enabled automatically by any of sqlx-pg, sqlx-mysql, redis, and meilisearch. Enable it alone only if you want the query and capability types without a data source, for example in a crate that defines queries for an in-memory store.

Why wakuwaku::depsCopy Anchor Link

A type from one version of a crate is a different type from the same item in another version. If your service depended on sqlx 0.8 while wakuwaku uses sqlx 0.9, the pool you create would not be the pool wakuwaku::entity accepts, and the compiler error would point at a mismatch that is hard to read.

wakuwaku avoids this by re-exporting every third-party crate that appears in its public API:

Import from these paths instead of adding the crates yourself:

use wakuwaku::deps::kanau::processor::Processor;
use wakuwaku::deps::sqlx::PgPool;
use wakuwaku::deps::tonic::{Request, Response, Status};

When you need a direct dependencyCopy Anchor Link

Two situations need a direct dependency anyway. In both, use a version requirement that is compatible with the one wakuwaku uses, so Cargo resolves a single copy of the crate and the types stay identical.

Generated code and derive macros that name a crate by its path. The code that tonic-prost-build generates refers to tonic, tonic_prost, and prost, and kanau's JSON derives expand to ::kanau::... paths. A path through wakuwaku::deps cannot satisfy them:

[dependencies]
# Needed by code generated by tonic-prost-build (see Quick start).
tonic = "0.14"
tonic-prost = "0.14"
prost = "0.14"

# Needed by #[derive(JsonMessageSer, JsonMessageDe)] on event and cache bodies.
kanau = { version = "0.6", features = ["serde_json"] }
serde = { version = "1", features = ["derive"] }

[build-dependencies]
tonic-prost-build = "0.14"

Defining events explains how message bodies are serialized.

Extra features of a re-exported crate. wakuwaku builds sqlx and redis with their default features off: sqlx gets only the Tokio runtime and the database driver, and redis gets only the Tokio connection and scripting support. Neither has TLS. To turn on more features, add the crate with the same major version and only the features you want. Cargo merges the features into the one copy that wakuwaku also uses:

[dependencies]
wakuwaku = { version = "1.0.0-rc3", features = ["sqlx-pg", "redis"] }
sqlx = { version = "0.9", default-features = false, features = ["tls-rustls", "migrate", "uuid"] }
redis = { version = "1", default-features = false, features = ["tokio-rustls-comp"] }

sqlx::PgPool and wakuwaku::deps::sqlx::PgPool are then the same type.

Tokio runtimeCopy Anchor Link

wakuwaku runs on Tokio. Cron jobs, event consumers, and gRPC servers are spawned as Tokio tasks, and starting cron jobs outside a Tokio runtime panics. wakuwaku itself enables Tokio's full feature set, so adding tokio with features = ["full"] costs nothing extra. You need the direct dependency for #[tokio::main], #[tokio::test], and tokio::signal.

InfrastructureCopy Anchor Link

Each feature talks to a server that you run yourself:

The pages for each feature explain the setup in detail: Events, sqlx, Redis, Meilisearch.

Check the setupCopy Anchor Link

Build once to fetch and compile the dependencies:

cargo build

Some checks run only when the code is fully compiled. For example, a cron job with a zero interval passes cargo check and fails cargo build, so use cargo build or cargo test in CI.