rifts 0.3.10

= 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.