Expand description
§nevo-messaging
A Rust 2024 implementation of the Nevo Messaging protocol. Services written with this crate exchange messages with services built on the original TypeScript/NestJS framework, byte for byte: same envelopes, same NATS subjects, same MessagePack/JSON encoding, same bigint sentinels, compression headers, error codes and built-in signals.
The first transport is NATS. The client, router and resilience layers are written against a
small Transport contract so other brokers can be added without
touching them.
§Highlights
- Request/reply (
query), fire-and-forget (emit), pub/sub (publish/subscribe),broadcast, scatter/gather (request_many), streaming replies, wildcard subscriptions. Router: typed async handlers, method versioning (user.getById@v2), interceptors, replay guard, ACL with optional token verification, rate limiting, claim-before-execute idempotency with pluggable distributed stores, dead-letter routing,nevo.contractand health built-ins.- Client: retry with full jitter and
retryAfterMshints, consecutive or sliding-window circuit breaker, hedging, idempotent response cache, graceful drain. - MessagePack (default) and JSON codecs, per-message codec sniffing, gzip/deflate/zstd with decompression bombs rejected, 4 MiB payload cap.
- Chain-id propagation through Tokio task-locals, optional W3C
traceparent, heartbeat discovery, JetStream helpers with real acks,tracingevents and optionalmetrics. - Verified against the original package:
tests/interop.rsdrives the real@riaskov/nevo-messagingclient and router through Node.js in both directions.
§Requirements
- Rust 1.95 or newer (edition 2024).
- A NATS 2.x server; enable JetStream (
nats-server -js) for the JetStream helpers.
[dependencies]
nevo-messaging = "0.1"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }§A service
use nevo_messaging::prelude::*;
use serde::{Deserialize, Serialize};
#[derive(Deserialize)]
struct GetById { id: BigInt }
#[derive(Serialize)]
struct User { id: BigInt, name: String, email: String }
#[tokio::main]
async fn main() -> Result<()> {
let router = Router::new("user")
.service_version("1.0.0")
.route("user.getById", |_ctx: Context, p: GetById| async move {
Ok(User { id: p.id, name: "John Doe".into(), email: "john@example.com".into() })
})
.route("user.getById@v2", |_ctx: Context, p: GetById| async move {
Ok(serde_json::json!({ "id": p.id, "version": 2 }))
});
let server = NatsServer::builder()
.router(router)
.servers(["nats://127.0.0.1:4222"])
.serve()
.await?;
server.run_until(async { let _ = tokio::signal::ctrl_c().await; }).await
}Handlers are async fn(Context, P) -> Result<R> for any P: Deserialize, R: Serialize.
Context carries the envelope uuid, method, caller identity, tenant, headers and chain id.
§A caller
use futures::StreamExt;
use nevo_messaging::prelude::*;
use std::time::Duration;
let client = NatsClient::builder()
.servers(["nats://127.0.0.1:4222"])
.service_name("coordinator")
.timeout(Duration::from_secs(5))
.retry(RetryPolicy::new().max_attempts(3))
.circuit_breaker(CircuitBreakerConfig::consecutive(5))
.compression(Compression::gzip().threshold(1024))
.connect()
.await?;
let user: User = client.query("user", "user.getById", &GetById { id: BigInt::from(42u8) }).await?;
let v2: serde_json::Value = client
.query_with("user", "user.getById", &GetById { id: BigInt::from(42u8) }, CallOptions::new().version("v2"))
.await?;
client.emit("notifications", "user.created", &user).await?;
client.publish("user", "user.updated", &user).await?;
client.broadcast("system.status", &serde_json::json!({ "ok": true })).await?;
let mut updates = client.subscribe::<User>("user", "user.updated", SubscribeOptions::new()).await?;
while let Some(Ok(msg)) = updates.next().await {
println!("{} from {:?}", msg.params.name, msg.meta.service);
}Errors come back as Error with the peer’s ErrorCode, message, details and service; use
err.code() to branch. Both examples live in examples/.
§Interoperability
The wire protocol is documented in full. In short:
| Concern | Behaviour |
|---|---|
| Subjects | <service>-events, <service>-events.sub.<method>, __broadcast.<method>, __nevo.discovery |
| Codec | MessagePack maps with string keys; JSON alternatively; inbound codec sniffed, reply in kind |
| bigint | BigInt type or #[serde(with = "nevo_messaging::wire::bigint::as_i64")] ↔ @@nevo:bigint:<digits> |
Strings starting with @@nevo: | escaped/unescaped exactly like the TypeScript codecs |
| Compression | content-encoding header; gzip, deflate (zlib), zstd (zstd feature) |
| Errors | numeric codes 0–20, details.retryable, details.retryAfterMs |
| Built-ins | nevo.contract, nevo.health, nevo.live, nevo.ready |
| Identity | meta.service, or a verified token when a verifier is configured |
docs/interop.md maps the TypeScript API onto this crate and lists the
behavioural differences and the features that are not ported yet (Kafka/HTTP/WebSocket
transports, outbox/inbox/saga/workflow, Postgres and Redis stores, DevTools).
§Feature flags
| Feature | Default | Effect |
|---|---|---|
nats | yes | The NATS transport (async-nats) |
msgpack | yes | MessagePack codec; without it JSON is the default |
compression | yes | gzip and deflate via flate2 |
zstd | no | zstd compression |
metrics | no | Emit nevo_messaging_* counters and histograms through the metrics facade |
§Configuration at a glance
Router::new("payments")
.replay_window(Duration::from_secs(300))
.rate_limit(RateLimitConfig::new(100.0, 50.0).key_by([KeyDimension::CallerService]))
.access_control(AccessControl::new()
.rule(AccessRule::new().topic("payments-events").method("pay.refund").allow(["coordinator"]))
.allow_all_by_default(true))
.idempotency(IdempotencyConfig::new().ttl(Duration::from_secs(600)))
.idempotency_store(redis_store) // any `IdempotencyStore`
.dlq(DlqRouter::new().sink(InMemoryDlqStore::shared(1000)))
.health(health_registry)
.interceptor(AuditInterceptor)
.compression(Compression::gzip());Clients accept RetryPolicy, CircuitBreakerConfig, HedgePolicy, IdempotencyConfig,
Compression, DiscoveryConfig and per-call CallOptions (version, idempotency key,
headers, tenant, timeout, hedge, retry override).
§Testing
cargo test # unit tests, no broker needed
NEVO_TEST_NATS_URL=nats://127.0.0.1:4222 cargo test # plus end-to-end tests
(cd tests/interop && npm install) # once, for the TypeScript peer
NEVO_TEST_NATS_URL=nats://127.0.0.1:4222 cargo test --test interopA local broker: docker run --rm -p 4222:4222 nats:2 -js.
§License
MIT, see LICENSE.
Re-exports§
pub use client::CallOptions;pub use client::Client;pub use client::ClientConfig;pub use client::Message;pub use client::SubscribeOptions;pub use client::Subscription;pub use codec::Codec;pub use compression::Compression;pub use compression::Encoding;pub use error::Error;pub use error::ErrorCode;pub use error::ErrorDetails;pub use error::Result;pub use server::Context;pub use server::Handler;pub use server::Interceptor;pub use server::Outcome;pub use server::Router;pub use transport::nats::Nats;natspub use transport::nats::NatsAuth;natspub use transport::nats::NatsClient;natspub use transport::nats::NatsClientBuilder;natspub use transport::nats::NatsConfig;natspub use transport::nats::NatsServer;natspub use transport::nats::NatsServerBuilder;natspub use wire::BigInt;pub use wire::MessageType;pub use wire::Meta;pub use wire::Request;pub use wire::Response;
Modules§
- acl
- Caller-based access control with optional token verification.
- client
- The transport-agnostic client: envelope construction, retry, circuit breaking, idempotent replay, hedging and pub/sub decoding.
- codec
- Envelope codecs. MessagePack is the default, JSON is always available, and inbound payloads can be sniffed so peers need not agree on a codec.
- compression
- Payload compression negotiated through the
content-encodingheader. - context
- Per-task chain context: a correlation id shared by every hop of one logical request, propagated implicitly from inbound handlers to outbound calls.
- contract
- The reflected service description served on the built-in
nevo.contractsignal. - discovery
- Heartbeat-based service discovery on the shared
__nevo.discoverytopic. - dlq
- Dead-letter routing for envelopes that could not be processed.
- error
- filter
- Consumer-side subscription filters over envelope headers and metadata.
- health
- Liveness and readiness probes exposed as the built-in
nevo.health,nevo.liveandnevo.readysignals. - idempotency
- Idempotency: a client-side response cache and the server-side claim-before-execute runtime with an optional distributed store.
- metrics
- Metric names shared with the TypeScript implementation. Emission goes through
the
metricsfacade when themetricsfeature is enabled. - prelude
- The names most services need.
- rate_
limit - Token-bucket rate limiting keyed by caller, tenant, topic or method.
- redact
- Secret redaction for logs and dead letters.
- replay
- Rejects envelopes whose uuid was already seen inside a time window.
- resilience
- Client-side resilience primitives: retry with backoff, circuit breakers and hedging.
- server
- The transport-agnostic request pipeline: replay guard → caller identity → rate limit → ACL → built-ins → idempotency claim → interceptors → handler, with dead-letter and metrics bookkeeping.
- shutdown
- In-flight tracking used to drain work before a client or server closes.
- transport
- The transport contract every broker binding implements. The client, router and resilience layers are written against it, so a Kafka or HTTP binding only needs to map addresses and move bytes.
- wire
- Envelope types shared with the TypeScript implementation.