factorio_rcon/lib.rs
1//! # factorio-rcon
2//!
3//! Async RCON client for Factorio with proper multi-packet response handling.
4//!
5//! Factorio can return large responses (>64KB) that get fragmented across
6//! multiple TCP segments. This crate correctly handles that by reading the
7//! length-prefixed packet header first, then using `read_exact()` to buffer
8//! the complete packet body before parsing.
9//!
10//! ## Features
11//!
12//! - ✅ Async/await with Tokio
13//! - ✅ Correct multi-packet fragmentation handling
14//! - ✅ Strong error types with thiserror
15//! - ✅ Configurable timeouts
16//! - ✅ Lua execution support with serpent serialization
17//!
18//! ## Usage
19//!
20//! ```no_run
21//! use factorio_rcon::RconClient;
22//! use std::time::Duration;
23//!
24//! #[tokio::main]
25//! async fn main() -> factorio_rcon::Result<()> {
26//! // Connect and authenticate
27//! let mut client = RconClient::connect("127.0.0.1:27015", "password").await?;
28//!
29//! // Execute basic commands
30//! let version = client.execute("/version").await?;
31//! println!("Server version: {}", version);
32//!
33//! // Execute Lua code
34//! let tick = client.execute("/c rcon.print(game.tick)").await?;
35//! println!("Current tick: {}", tick);
36//!
37//! // Query with serpent serialization (for structured data)
38//! let _inventory = client.execute(
39//! "/c rcon.print(serpent.line(game.connected_players[1].get_main_inventory()))"
40//! ).await?;
41//!
42//! // Custom timeout for slow queries
43//! let _result = client.execute_with_timeout(
44//! "/c rcon.print(serpent.line(game.surfaces))",
45//! Duration::from_secs(10)
46//! ).await?;
47//!
48//! // Configure default timeout
49//! client.set_timeout(Duration::from_secs(15));
50//!
51//! Ok(())
52//! }
53//! ```
54//!
55//! ## Prerequisites
56//!
57//! Factorio must run as a multiplayer host for RCON to work:
58//!
59//! 1. Launch Factorio
60//! 2. Multiplayer → Host New Game
61//! 3. RCON is automatically enabled (check `config.ini` for port and password)
62//!
63//! Default RCON configuration:
64//! - Port: 27015
65//! - Password: Check `config/config.ini` in your Factorio installation
66//!
67//! ## Error Handling
68//!
69//! The crate provides strongly-typed errors for different failure scenarios:
70//!
71//! ```no_run
72//! use factorio_rcon::{RconClient, RconError};
73//!
74//! # async fn example() {
75//! match RconClient::connect("127.0.0.1:27015", "wrong_password").await {
76//! Ok(_client) => println!("Connected!"),
77//! Err(RconError::ConnectionFailed(e)) => println!("Can't reach server: {}", e),
78//! Err(RconError::AuthFailed) => println!("Wrong password"),
79//! Err(RconError::Timeout(ms)) => println!("Timed out after {}ms", ms),
80//! Err(e) => println!("Other error: {}", e),
81//! }
82//! # }
83//! ```
84
85mod client;
86mod error;
87mod protocol;
88
89pub use client::RconClient;
90pub use error::{RconError, Result};