rifts 0.3.3

Rift Realtime Protocol / 1.0 — server-side implementation
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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Transport abstraction layer.
//!
//! This module defines the trait hierarchy that decouples the Rift protocol
//! implementation from any particular network transport. The server works
//! exclusively with these traits, while framework-specific adapters (axum,
//! actix-web, warp, ntex) provide concrete implementations.
//!
//! # Trait hierarchy
//!
//! - [`Transport`] — a transport binding that can listen on a socket address.
//! - [`TransportListener`] — a bound listener that accepts incoming connections.
//! - [`TransportConnection`] — a single bidirectional connection that can read
//!   and write [`Frame`](crate::frame::Frame)s.
//!
//! # Built-in adapters
//!
//! | Feature flag  | Module       | Description                          |
//! |---------------|-------------|--------------------------------------|
//! | `websocket`   | [`websocket`] | Standalone WebSocket via tungstenite |
//! | `axum`        | [`axum`]      | Axum WebSocket adapter               |
//! | `actix-web`   | [`actix`]     | Actix-web WebSocket adapter          |
//! | `warp`        | [`warp`]      | Warp WebSocket adapter               |
//! | `ntex`        | [`ntex`]      | Ntex WebSocket adapter               |
//!
//! The [`bridge`] module (used by actix-web and ntex) provides a channel-based
//! bridge for frameworks whose WebSocket types are `!Send`.

pub mod frame_codec;

// Channel bridge for non-Send WS types (actix-web, ntex).
#[cfg(any(feature = "actix-web", feature = "ntex"))]
pub mod bridge;

#[cfg(feature = "actix-web")]
pub mod actix;
#[cfg(feature = "axum")]
pub mod axum;
#[cfg(feature = "ntex")]
pub mod ntex;
#[cfg(feature = "warp")]
pub mod warp;
#[cfg(feature = "websocket")]
pub mod websocket;

use async_trait::async_trait;
use std::net::SocketAddr;

use crate::error::Result;
use crate::frame::Frame;
use crate::protocol::close::CloseCode;

/// A transport binding — the entry point for listening on a network address.
///
/// Implementations are lightweight and cloneable. The server holds one
/// `Transport` and calls [`bind`](Transport::bind) to create a
/// [`TransportListener`] when it starts accepting connections.
///
/// Built-in implementations: [`WebSocketTransport`](websocket::WebSocketTransport).
/// Additional implementations can be added for WebTransport, TCP, Unix
/// sockets, or any other bidirectional byte-stream transport.
#[async_trait]
pub trait Transport: Send + Sync {
    /// Bind a listener on the given socket address.
    ///
    /// Returns a boxed [`TransportListener`] that can accept incoming
    /// connections. The address is typically `0.0.0.0:<port>` or
    /// `127.0.0.1:<port>`.
    async fn bind(&self, addr: SocketAddr) -> Result<Box<dyn TransportListener>>;

    /// Human-readable name of this transport (e.g. `"websocket"`,
    /// `"webtransport"`, `"tcp"`).
    fn name(&self) -> &'static str;
}

/// A bound transport listener that accepts incoming connections.
///
/// Created by [`Transport::bind`]. Each call to [`accept`](TransportListener::accept)
/// yields the next incoming [`TransportConnection`], or an error if the
/// listener has failed.
#[async_trait]
pub trait TransportListener: Send {
    /// Accept the next incoming connection.
    ///
    /// This method blocks (asynchronously) until a connection is
    /// available or an error occurs.
    async fn accept(&mut self) -> Result<Box<dyn TransportConnection>>;

    /// The local address the listener is bound to.
    ///
    /// Useful for logging and for discovering the ephemeral port when
    /// the server is bound to port 0.
    fn local_addr(&self) -> Result<SocketAddr>;
}

/// A single bidirectional transport connection.
///
/// Implementations read and write [`Frame`](crate::frame::Frame)s using
/// the binary or text wire format defined in
/// [`frame_codec`](crate::transport::frame_codec). The connection is
/// consumed by [`Connection::run`](crate::connection::Connection::run).
#[async_trait]
pub trait TransportConnection: Send {
    /// Read the next frame from the remote peer.
    ///
    /// Returns an error if the connection has been closed or the frame
    /// is malformed. Implementations must handle WebSocket control
    /// frames (ping/pong/close) transparently and only surface data
    /// frames to the caller.
    async fn read_frame(&mut self) -> Result<Frame>;

    /// Write a frame to the remote peer.
    ///
    /// The frame is encoded using the transport's wire format (binary
    /// or text envelope) before being sent. Returns an error if the
    /// write fails.
    async fn write_frame(&mut self, frame: &Frame) -> Result<()>;

    /// Close the connection with a structured close code and human-readable
    /// reason string.
    ///
    /// The close code is mapped to the transport's native close mechanism
    /// (e.g. a WebSocket close frame). After this call the connection
    /// should not be used for further reads or writes.
    async fn close(&mut self, code: CloseCode, reason: &str) -> Result<()>;

    /// The peer's socket address, if known.
    ///
    /// Returns `None` when the transport does not expose peer addressing
    /// (e.g. some proxied configurations).
    fn peer_addr(&self) -> Option<SocketAddr>;
}