Crate soe_protocol 

A Rust implementation of version 3 of the SOE (Sony Online Entertainment) network protocol.

The SOE protocol is a UDP transport layer used by various games (Free Realms, H1Z1, Landmark, PlanetSide 2, etc.). It provides sessions, packet verification (CRC32), optional compression (zlib), reliable/ordered data transmission, and optional encryption (RC4).

Design

This crate is structured as an I/O-agnostic core: the protocol logic is a pure state machine that never touches the network or the clock directly. SoeSession (a single connection) and SoeMultiplexer (many connections demultiplexed by remote address) consume incoming datagrams and the current Instant, and produce outgoing datagrams plus SocketEvents. You drive them from whatever runtime you like.

Ready-made adapters are provided over that core:

• SyncSoeSocket — a blocking, dependency-free driver over std::net::UdpSocket.
• TokioSoeSocket / TokioSoeServer — async drivers behind the tokio feature.

See the examples/ directory for runnable client/server pairs in both styles.

Cargo features

• tokio (off by default) — enables the Tokio adapters (TokioSoeSocket, TokioSoeServer, SoeHandle). With default features the crate has no async runtime dependency.

Quick start

A minimal synchronous client that connects, sends one message, and prints replies:

use std::net::SocketAddr;
use std::time::Duration;

use soe_protocol::SessionParameters;
use soe_protocol::socket::{SocketConfig, SocketEvent, SoeSocket};
use soe_protocol::sync_rt::SyncSoeSocket;

let server: SocketAddr = "127.0.0.1:20260".parse().unwrap();

// Both peers must agree on the application-protocol string.
let config = SocketConfig {
    default_session_params: SessionParameters {
        application_protocol: "MyGame".to_owned(),
        ..SessionParameters::default()
    },
    ..SocketConfig::default()
};

let mut socket = SyncSoeSocket::bind(
    "127.0.0.1:0".parse().unwrap(),
    config,
    Duration::from_millis(5),
)?;
socket.connect(server);

loop {
    for event in socket.step()? {
        match event {
            SocketEvent::SessionOpened { remote } => {
                let _ = socket.enqueue_data(&remote, b"hello");
            }
            SocketEvent::DataReceived { data, .. } => {
                println!("received {} bytes", data.len());
            }
            SocketEvent::SessionClosed { .. } => return Ok(()),
        }
    }
}

Re-exports

pub use error::Error;

pub use error::Result;

pub use protocol::DisconnectReason;

pub use protocol::OpCode;

pub use session::ApplicationParameters;

pub use session::SessionEvent;

pub use session::SessionMode;

pub use session::SessionParameters;

pub use session::SessionState;

pub use session::SoeSession;

pub use socket::RemoteAddr;

pub use socket::SocketConfig;

pub use socket::SocketEvent;

pub use socket::SoeMultiplexer;

pub use socket::SoeSocket;

pub use socket::UdpTransport;

pub use sync_rt::SyncSoeSocket;

pub use tokio_rt::SoeHandle;

pub use tokio_rt::TokioSoeServer;

pub use tokio_rt::TokioSoeSocket;

Modules

channel

Reliable data channels: reassembly/ordering of incoming data, and fragmentation/sequencing of outgoing data.

constants

Constant values and defaults used by this implementation of the SOE protocol.

error

Error types for the SOE protocol crate.

packets

Wire representations of the SOE protocol packets, with (de)serialization.

protocol

Core protocol enumerations: OP codes and disconnect reasons.

session

The session handler: an I/O-agnostic state machine driving a single SOE session.

socket

The socket handler: an I/O-agnostic multiplexer of SOE sessions over a single UDP socket, plus a thin, dependency-free transport adapter to drive it.

sync_rt

A synchronous, dependency-free adapter driving a SoeMultiplexer over a blocking std::net::UdpSocket. Always available; pulls in no async runtime.

tokio_rt

A Tokio-based async adapter driving a SoeMultiplexer over a UDP socket. Enabled by the tokio feature.

Structs

Rc4KeyState

A reusable RC4 key state. The state is advanced as data is transformed, so a single Rc4KeyState represents one continuous cipher stream.