Errors and Timeouts EN

English · 简体中文

Errors, deadlines and cancellation

Transport errors

rust_raknet::error::Result<T> uses RaknetError, which implements Display and std::error::Error. The variants are:

Variant	First action / interpretation
SetRaknetRawSocketError	Supplied UDP socket initialization failed
NotListen	Call listen before accept
BindAddressError	Check address, port ownership and socket permissions
ConnectionClosed	Treat the session as ended; reconnect according to application policy
NotSupportVersion	Check RakNet handshake version, normally 10 or 11
IncorrectReply	Check peer transport, endpoint and handshake reply
PacketParseError	Inspect malformed or incompatible peer packets
SocketError	Check socket operation and tuning arguments; this enum does not preserve an OS errno
IncorrectReliability	Inspect reliability metadata and supported modes
IncorrectPacketID	Inspect control/application packet identifier
ReadPacketBufferError	Inspect truncated packet input
PacketSizeExceedMTU	Check mode, MTU, fragment count and encoded-byte budgets
PacketHeaderError	Send a nonempty payload whose first byte is 0xfe
SetMotdError	Check offline MOTD update and listener state

These variants are not a complete diagnosis of network failure. A timeout or parse failure does not prove protocol incompatibility. Check both endpoints and sanitized packet traces.

Application deadlines

The async API does not have timeout variants for every operation. Wrap connect, receive, send, flush or accept in tokio::time::timeout when the application needs a deadline. The outer result is a Tokio Elapsed error; the inner result is a transport result.

use rust_raknet::RaknetSocket;
use std::time::Duration;

async fn receive_with_deadline(socket: &RaknetSocket)
    -> Result<Vec<u8>, Box<dyn std::error::Error>>
{
    Ok(tokio::time::timeout(Duration::from_secs(2), socket.recv()).await??)
}

The blocking adapter returns blocking::Error::Timeout for its deadline methods, AsyncContext for unsupported runtime nesting, Runtime(io::Error) for runtime creation failure, and Raknet(RaknetError) for transport failures. SendOptions builders use SendOptionsError; builder validation is separate from application of options to a live socket.

Cancellation is not rollback

• A successful send accepts a message into the transport path. It does not acknowledge that the remote business handler processed it.
• Cancelling or timing out a send can leave queued reliable data delivering; a batch can have sent a prefix. Use request IDs and idempotent application processing before retrying a logical operation.
• Receive calls share a serialized consumer. Concurrent readers must agree on who processes each message. Receive batch output is cleared before draining.
• Timing out flush cancels its wait, not pending delivery. Concurrent senders can prolong flush; stop producers before flushing for shutdown.
• close initiates teardown and is not a substitute for acknowledged delivery. Graceful exit is stop producers → bounded flush → close. Dropping handles is cleanup, not a delivery promise.

Discovery and diagnostics

RaknetSocket::ping returns discovery RTT in milliseconds plus the MOTD, not the µs application-echo RTT used in benchmarks. Async callers should wrap it in an application deadline; blocking callers can use runtime.ping_timeout. Discovery success does not prove session or application login success.

Enable process-wide logs with enable_raknet_log(6) for error + info categories; 1 debug, 2 error, 4 info are bit flags. Debug output can change performance. Record version, negotiated mtu(), raknet_version(), peer/local addresses and external socket/network counters. The public API does not expose a full per-connection statistics or congestion telemetry object.

Lifecycle · Configuration · Troubleshooting