= Rift Realtime Protocol / 1.0 — rifts

image:https://github.com/rift-proto/rift-rust/actions/workflows/ci.yml/badge.svg[CI,link=https://github.com/rift-proto/rifts/actions/workflows/ci.yml] image:https://img.shields.io/crates/v/rifts.svg[Crates.io,link=https://crates.io/crates/rifts] image:https://img.shields.io/badge/License-MIT-blue.svg[License,link=LICENSE-MIT]

The rifts crate is a Rust server implementation of the Rift Realtime Protocol (Rift/1) — a modern, real-time bidirectional messaging protocol designed to replace raw WebSocket + event-string models with stronger semantics, similar to Socket.IO but with explicit guarantees.

== Crate Features

[cols="1,2"] |=== | Feature | Description

| websocket (default) | Standalone WebSocket transport via tokio-tungstenite

| axum | Axum framework WebSocket adapter

| actix-web | Actix-web WebSocket adapter

| warp | Warp framework WebSocket adapter

| ntex | Ntex framework WebSocket adapter

| tokio-frameworks | Shortcut: axum + warp

| all-frameworks | Shortcut: all framework adapters |===

== Quick Start

[source,rust]

use rifts::RiftServer; use std::sync::Arc; use tokio::sync::Notify;

#[tokio::main] async fn main() -> rifts::Result<()> { let shutdown = Arc::new(Notify::new()); let server = RiftServer::builder() .websocket_transport() .build()?; server.run("127.0.0.1:9000".parse().unwrap(), shutdown).await?; Ok(()) }

== Module Structure

[cols="1,2"] |=== | Module | Purpose

| frame | Frame envelope, types, flags, codec, priority

| codec | CBOR + JSON codecs with negotiation

| protocol | Version, close codes, error codes, heartbeat, handshake

| message | Eight message classes (event, command, reply, state, …)

| topic | Topic profiles, retention, ordering, in-memory store

| session | Sessions, auth, resume, offset tracking

| broker | In-memory broker, router, fanout, dedupe, snapshots

| ack | Acknowledgement system (9 ack types)

| flow | Backpressure controller + token-bucket rate limiter

| transport | Transport abstraction + WebSocket, framework adapters

| server | RiftServer builder and event loop

| connection | Per-connection state machine (spec §5 lifecycle) |===

== License

Licensed under either of

• Apache License, Version 2.0 (link:LICENSE-APACHE[LICENSE-APACHE] or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (link:LICENSE-MIT[LICENSE-MIT] or https://opensource.org/licenses/MIT)

at your option.

== Contributing

Contributions are welcome! Please open an issue or pull request.

== Benchmarks

The benches/ directory contains a Criterion-based benchmark suite covering the full crate surface: wire codec, serialization, frame/message models, flow control, fanout engine, topic store, storage backends (memory and optional sled), InMemoryBroker, session/resume, ack/metrics, in-process E2E, loopback WebSocket, and throughput.

[source,sh]

Build the entire suite

cargo bench --no-run --all-features

Run stable benchmarks (no network, no disk)

cargo bench

Feature-gated benchmarks

cargo bench --features sled --bench sled_store cargo bench --features client --bench websocket_loop

Throughput benchmarks (ops/s via Throughput::Elements)

cargo bench --bench throughput

Full benchmark data: link:BenchMark.adoc[BenchMark.adoc] — generated by cargo run --example update_benchmark_readme -- BenchMark.adoc.

Results are from the last local run. They are not performance commitments and vary with CPU, load, compiler version, and system configuration.