fluxar 0.0.1

FLUXAR protocol — universal async bidirectional messaging (RPC + Streaming + PubSub). Work in progress.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# fluxar

> Universal asynchronous bidirectional messaging protocol for Rust.
> RPC + Streaming + PubSub in a single unified protocol.

⚠️ **This crate is under active development and not yet functional.** This is a name reservation for the upcoming Rust implementation of the FLUXAR protocol. See the [specification](https://github.com/fluxar-protocol/spec) for protocol details.

## What is FLUXAR

FLUXAR is a transport-agnostic application protocol that unifies three communication patterns — request-response (RPC), streaming, and publish-subscribe — within a single envelope format.

After a handshake, both peers are equal: either side can call methods, open streams, subscribe to topics, and publish events.

**Core design:**

- 7 message types, 7-field envelope, CBOR serialisation
- The `ref` mechanism — a single field turns any message from request into response
- Fully asynchronous — send and receive are independent, no head-of-line blocking
- Symmetric — no client/server distinction after handshake
- Transport-agnostic — WebSocket, TCP, QUIC, Unix socket

## Planned Features

- Async-first API built on Tokio
- All four transports: WebSocket, TCP, QUIC, Unix socket
- Full streaming lifecycle with state machine (IDLE → ACTIVE → CANCELLING → CLOSED)
- PubSub with three delivery guarantee modes (at-most-once, at-least-once, exactly-once)
- Session resume after connection loss
- Optional Zstd/Gzip compression
- Optional end-to-end encryption (X25519 + AES-256-GCM / ChaCha20-Poly1305)
- Capability negotiation during handshake
- IDL-based code generation for typed clients and servers

## Example (planned API)

```rust
// Server
let server = fluxar::Server::bind("0.0.0.0:9000")
    .transport(fluxar::Transport::WebSocket)
    .build()
    .await?;

server.handle("users.get", |req: Request| async move {
    let user_id: Uuid = req.payload()?;
    let user = db.find_user(user_id).await?;
    Ok(user)
});

server.run().await?;
```

```rust
// Client
let client = fluxar::Client::connect("ws://localhost:9000")
    .auth(fluxar::Auth::bearer(token))
    .build()
    .await?;

let user: User = client.call("users.get", &user_id).await?;
```

```rust
// Streaming
let stream = client.stream("llm.complete", &prompt).await?;

while let Some(chunk) = stream.next().await {
    print!("{}", chunk?.token);
}
```

```rust
// PubSub
client.subscribe("orders.created", |msg: Message| async move {
    println!("New order: {:?}", msg.payload::<Order>()?);
    msg.ack().await
}).await?;
```

> **Note:** The API above is illustrative and subject to change.

## Specification

The full protocol specification is maintained at [github.com/fluxar-protocol/spec](https://github.com/fluxar-protocol/spec).

| Layer | Description |
|-------|-------------|
| L0: Transport | WebSocket, TCP, QUIC, Unix socket |
| L1: Framing | Message boundaries |
| L2: Wire Format | CBOR, optional compression and encryption |
| L3: Message | 7 types, envelope, ref mechanism |
| L4: Session | Handshake, auth, heartbeat, resume |
| L5: Patterns | RPC, Streaming, PubSub |

## Conformance Levels

| Level | Description |
|-------|-------------|
| **FLUXAR Core** | RPC only, one transport — minimal viable implementation |
| **FLUXAR Complete** | Full streaming, PubSub, resume, compression, encryption |

## License

Apache-2.0 — see [LICENSE](LICENSE).