Skip to main content

Crate nevo_messaging

Crate nevo_messaging 

Source
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.contract and health built-ins.
  • Client: retry with full jitter and retryAfterMs hints, 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, tracing events and optional metrics.
  • Verified against the original package: tests/interop.rs drives the real @riaskov/nevo-messaging client 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:

ConcernBehaviour
Subjects<service>-events, <service>-events.sub.<method>, __broadcast.<method>, __nevo.discovery
CodecMessagePack maps with string keys; JSON alternatively; inbound codec sniffed, reply in kind
bigintBigInt type or #[serde(with = "nevo_messaging::wire::bigint::as_i64")] ↔ @@nevo:bigint:<digits>
Strings starting with @@nevo:escaped/unescaped exactly like the TypeScript codecs
Compressioncontent-encoding header; gzip, deflate (zlib), zstd (zstd feature)
Errorsnumeric codes 0–20, details.retryable, details.retryAfterMs
Built-insnevo.contract, nevo.health, nevo.live, nevo.ready
Identitymeta.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

FeatureDefaultEffect
natsyesThe NATS transport (async-nats)
msgpackyesMessagePack codec; without it JSON is the default
compressionyesgzip and deflate via flate2
zstdnozstd compression
metricsnoEmit 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 interop

A 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;nats
pub use transport::nats::NatsAuth;nats
pub use transport::nats::NatsClient;nats
pub use transport::nats::NatsClientBuilder;nats
pub use transport::nats::NatsConfig;nats
pub use transport::nats::NatsServer;nats
pub use transport::nats::NatsServerBuilder;nats
pub 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-encoding header.
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.contract signal.
discovery
Heartbeat-based service discovery on the shared __nevo.discovery topic.
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.live and nevo.ready signals.
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 metrics facade when the metrics feature 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.