fallensigh/xserial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: xserial-client with session management, mlua integration, and 238 tests

Browse Source 
- Session: background I/O task with SessionHandle for send/read/close/reconfigure
- SessionManager: multi-session collection with aggregated event broadcast
- Config: serializable SessionConfig/PipelineConfig/FramerConfig/DecoderConfig
- Lua: xserial global (open/list_ports/sleep/log) + session userdata API
- RingBuffer: bounded history buffer with pipeline filtering
- Core: added Serialize/Deserialize+Default to Endian/TextEncoding/PlotFormat
- Core: added Send bound to Framer trait for tokio task compatibility
- 238 tests (193 core + 10 config + 7 Lua + 9 session + 18 pipeline + 1 doctest)
This commit is contained in:
FallenSigh
2026-06-08 00:25:59 +08:00
parent 60c60a8044
commit 530986d068
19 changed files with 1494 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
crates/xserial-client/tests/lua_tests.rs Normal file
View File

@@ -0,0 +1,287 @@
use std::sync::Once;
use mlua::Lua;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
static INIT: Once = Once::new();
fn init_tracing() {
INIT.call_once(|| {
tracing_subscriber::fmt()
.with_env_filter("xserial=trace")
.try_init()
.ok();
});
}
// ── xserial.sleep / xserial.log ──────────────────────────────────
#[tokio::test]
async fn lua_sleep_and_log() {
let lua = Lua::new();
xserial_client::lua::register(&lua).unwrap();
lua.load(
r#"
xserial.log("test start")
xserial.sleep(50)
xserial.log("test end")
"#
)
.exec_async()
.await
.unwrap();
}
// ── xserial.list_ports ───────────────────────────────────────────
#[tokio::test]
async fn lua_list_ports() {
let lua = Lua::new();
xserial_client::lua::register(&lua).unwrap();
let result: Vec<String> = lua
.load(r#"return xserial.list_ports()"#)
.eval_async()
.await
.unwrap();
// Should return a table (possibly empty if no serial ports)
// Just verify it doesn't crash
let _ = result;
}
// ── xserial.open + session:send / session:read / session:close ────
#[tokio::test]
async fn lua_session_open_send_read_close() {
init_tracing();
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
let mut buf = [0u8; 256];
let n = stream.read(&mut buf).await.unwrap();
assert_eq!(&buf[..n], b"hello\n");
stream.write_all(b"world\n").await.unwrap();
});
let lua = Lua::new();
xserial_client::lua::register(&lua).unwrap();
let script = format!(
r#"
local sess = xserial.open({{
transport = {{ Tcp = {{ addr = "{}" }} }},
pipelines = {{{{
name = "text",
framer = {{ Line = {{}} }},
decoder = {{ Text = {{}} }}
}}}}
}})
sess:send("hello\n")
local r = sess:read(5000)
assert(r ~= nil, "expected data")
assert(r.pipeline == "text", "expected text pipeline")
assert(r.data == "world", "expected 'world', got " .. tostring(r.data))
sess:close()
"#,
addr
);
lua.load(&script).exec_async().await.unwrap();
server.await.unwrap();
}
// ── session:read with timeout ────────────────────────────────────
#[tokio::test]
async fn lua_session_read_timeout() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let _server = tokio::spawn(async move {
let (_stream, _) = listener.accept().await.unwrap();
tokio::time::sleep(std::time::Duration::from_secs(10)).await;
});
let lua = Lua::new();
xserial_client::lua::register(&lua).unwrap();
let script = format!(
r#"
local sess = xserial.open({{
transport = {{ Tcp = {{ addr = "{}" }} }},
pipelines = {{{{
name = "text",
framer = {{ Line = {{}} }},
decoder = {{ Text = {{}} }}
}}}}
}})
local r = sess:read(100)
assert(r == nil, "read should time out")
sess:close()
"#,
addr
);
lua.load(&script).exec_async().await.unwrap();
}
// ── xserial.open with hex decoder ────────────────────────────────
#[tokio::test]
async fn lua_session_hex_decoder() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"ABC\n").await.unwrap();
});
let lua = Lua::new();
xserial_client::lua::register(&lua).unwrap();
let script = format!(
r#"
local sess = xserial.open({{
transport = {{ Tcp = {{ addr = "{}" }} }},
pipelines = {{{{
name = "hex",
framer = {{ Line = {{}} }},
decoder = {{ Hex = {{ uppercase = true }} }}
}}}}
}})
local r = sess:read(5000)
assert(r ~= nil)
assert(r.pipeline == "hex")
assert(r.kind == "hex")
assert(r.data == "41 42 43", "expected hex of ABC, got " .. tostring(r.data))
sess:close()
"#,
addr
);
lua.load(&script).exec_async().await.unwrap();
server.await.unwrap();
}
// ── session:on_data callback ─────────────────────────────────────
#[tokio::test]
async fn lua_session_on_data_callback() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"line1\nline2\n").await.unwrap();
});
let lua = Lua::new();
xserial_client::lua::register(&lua).unwrap();
let script = format!(
r#"
local received = {{}}
local sess = xserial.open({{
transport = {{ Tcp = {{ addr = "{}" }} }},
pipelines = {{{{
name = "text",
framer = {{ Line = {{}} }},
decoder = {{ Text = {{}} }}
}}}}
}})
sess:on_data(function(name, data)
table.insert(received, {{ name = name, data = data }})
end)
-- Wait for both lines
xserial.sleep(500)
assert(#received == 2, "expected 2 callbacks, got " .. #received)
assert(received[1].name == "text")
assert(received[1].data == "line1")
assert(received[2].name == "text")
assert(received[2].data == "line2")
sess:close()
"#,
addr
);
lua.load(&script).exec_async().await.unwrap();
server.await.unwrap();
}
// ── session:reconfigure from Lua ─────────────────────────────────
#[tokio::test]
async fn lua_session_reconfigure() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"test\n").await.unwrap();
});
let listener2 = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr2 = listener2.local_addr().unwrap().to_string();
let server2 = tokio::spawn(async move {
let (mut stream, _) = listener2.accept().await.unwrap();
stream.write_all(b"ABC\n").await.unwrap();
});
let lua = Lua::new();
xserial_client::lua::register(&lua).unwrap();
let script = format!(
r#"
local sess = xserial.open({{
transport = {{ Tcp = {{ addr = "{}" }} }},
pipelines = {{{{
name = "text",
framer = {{ Line = {{}} }},
decoder = {{ Text = {{}} }}
}}}}
}})
local r = sess:read(5000)
assert(r.data == "test")
-- Reconfigure to hex on different address
sess:reconfigure({{
transport = {{ Tcp = {{ addr = "{}" }} }},
pipelines = {{{{
name = "hex",
framer = {{ Line = {{}} }},
decoder = {{ Hex = {{ uppercase = true }} }}
}}}}
}})
local r2 = sess:read(5000)
assert(r2.pipeline == "hex")
assert(r2.data == "41 42 43")
sess:close()
"#,
addr, addr2
);
lua.load(&script).exec_async().await.unwrap();
server.await.unwrap();
server2.await.unwrap();
}

330
crates/xserial-client/tests/session_lifecycle.rs Normal file
View File

@@ -0,0 +1,330 @@
use std::time::Duration;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
use xserial_client::config::{
DecoderConfig, FramerConfig, PipelineConfig, SessionConfig,
};
use xserial_client::session::{Session, SessionEvent};
use xserial_client::SessionManager;
use xserial_core::protocol::DecodedData;
use xserial_core::transport::TransportConfig;
fn tcp_config(addr: String) -> SessionConfig {
SessionConfig {
transport: TransportConfig::Tcp { addr },
pipelines: vec![PipelineConfig {
name: "text".into(),
framer: FramerConfig::Line {
strip_cr: true,
max_line_len: 1024 * 1024,
},
decoder: DecoderConfig::Text {
encoding: xserial_core::protocol::text::TextEncoding::Utf8,
},
}],
history_limit: 100,
auto_reconnect: false,
}
}
// ── Session spawn + basic send/read ──────────────────────────────
#[tokio::test]
async fn session_echo_send_and_read() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
let mut buf = [0u8; 256];
let n = stream.read(&mut buf).await.unwrap();
assert_eq!(&buf[..n], b"ping\n");
stream.write_all(b"pong\n").await.unwrap();
});
let handle = Session::spawn(1, tcp_config(addr));
handle.send(b"ping\n".to_vec()).await.unwrap();
let entry = handle.read(5000).await.expect("should receive response");
match entry.data {
DecodedData::Text(s) => assert_eq!(s, "pong"),
other => panic!("expected Text, got {:?}", other),
}
handle.close().await.unwrap();
server.await.unwrap();
}
#[tokio::test]
async fn session_multiple_reads() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"a\nb\nc\n").await.unwrap();
});
let handle = Session::spawn(2, tcp_config(addr));
// Subscribe once and collect all text events
let mut rx = handle.subscribe();
let mut texts = Vec::new();
tokio::time::timeout(Duration::from_secs(5), async {
loop {
match rx.recv().await.unwrap() {
SessionEvent::Data(_, entry) => {
if let DecodedData::Text(s) = entry.data {
texts.push(s);
if texts.len() == 3 { break; }
}
}
_ => {}
}
}
}).await.unwrap();
assert_eq!(texts, vec!["a", "b", "c"]);
handle.close().await.unwrap();
server.await.unwrap();
}
// ── Session with multiple pipelines ──────────────────────────────
#[tokio::test]
async fn session_multi_pipeline_text_and_hex() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"hello\n").await.unwrap();
});
let mut config = tcp_config(addr);
config.pipelines.push(PipelineConfig {
name: "hex".into(),
framer: FramerConfig::Line {
strip_cr: true,
max_line_len: 1024 * 1024,
},
decoder: DecoderConfig::Hex {
uppercase: false,
separator: " ".into(),
bytes_per_group: 1,
endian: xserial_core::protocol::Endian::Big,
},
});
let handle = Session::spawn(3, config);
// Subscribe and collect both pipeline results
let mut rx = handle.subscribe();
let mut results = Vec::new();
tokio::time::timeout(Duration::from_secs(5), async {
loop {
match rx.recv().await.unwrap() {
SessionEvent::Data(_, entry) => {
results.push((entry.pipeline_name.clone(), entry.data.clone()));
if results.len() == 2 { break; }
}
_ => {}
}
}
}).await.unwrap();
assert_eq!(results.len(), 2);
assert_eq!(results[0].0, "text");
assert_eq!(results[1].0, "hex");
assert!(matches!(results[1].1, DecodedData::Hex(_)));
handle.close().await.unwrap();
server.await.unwrap();
}
// ── SessionClose + read timeout ──────────────────────────────────
#[tokio::test]
async fn session_read_timeout_returns_none() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (_stream, _) = listener.accept().await.unwrap();
// Accept but send nothing — client should time out
tokio::time::sleep(Duration::from_secs(10)).await;
});
let handle = Session::spawn(4, tcp_config(addr));
// Short timeout — no data sent by server
let result = handle.read(200).await;
assert!(result.is_none(), "read should time out and return None");
handle.close().await.unwrap();
server.abort();
}
#[tokio::test]
async fn session_close_stops_events() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let _server = tokio::spawn(async move {
let (_stream, _) = listener.accept().await.unwrap();
tokio::time::sleep(Duration::from_secs(10)).await;
});
let handle = Session::spawn(5, tcp_config(addr));
handle.close().await.unwrap();
// After close, read should return None immediately
let result = handle.read(100).await;
assert!(result.is_none());
}
// ── SessionManager ───────────────────────────────────────────────
#[tokio::test]
async fn manager_create_and_list() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let _server = tokio::spawn(async move {
let (_stream, _) = listener.accept().await.unwrap();
tokio::time::sleep(Duration::from_secs(10)).await;
});
let mut mgr = SessionManager::new();
assert_eq!(mgr.count(), 0);
assert!(mgr.list_ids().is_empty());
let h1 = mgr.create(tcp_config(addr.clone()));
assert_eq!(mgr.count(), 1);
assert_eq!(mgr.list_ids(), vec![1]);
let h2 = mgr.create(tcp_config(addr));
assert_eq!(mgr.count(), 2);
assert!(mgr.get(1).is_some());
assert!(mgr.get(2).is_some());
assert!(mgr.get(99).is_none());
mgr.remove(1);
assert_eq!(mgr.count(), 1);
assert!(mgr.get(1).is_none());
h1.close().await.unwrap();
h2.close().await.unwrap();
}
#[tokio::test]
async fn manager_event_subscription() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"data\n").await.unwrap();
});
let mut mgr = SessionManager::new();
let mut rx = mgr.subscribe();
let handle = mgr.create(tcp_config(addr));
// Wait for Connected event
let event = tokio::time::timeout(Duration::from_secs(5), rx.recv())
.await
.unwrap()
.unwrap();
assert!(matches!(event, SessionEvent::Connected(1)));
// Wait for Data event
let event = tokio::time::timeout(Duration::from_secs(5), rx.recv())
.await
.unwrap()
.unwrap();
assert!(matches!(event, SessionEvent::Data(1, _)));
handle.close().await.unwrap();
server.await.unwrap();
}
// ── Reconfigure ──────────────────────────────────────────────────
#[tokio::test]
async fn session_reconfigure_changes_pipeline() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"old\n").await.unwrap();
});
let handle = Session::spawn(6, tcp_config(addr));
let entry = handle.read(5000).await.unwrap();
assert!(matches!(entry.data, DecodedData::Text(s) if s == "old"));
server.await.unwrap();
// Reconfigure to hex pipeline on a new address (don't close first)
let listener2 = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr2 = listener2.local_addr().unwrap().to_string();
let server2 = tokio::spawn(async move {
let (mut stream, _) = listener2.accept().await.unwrap();
stream.write_all(b"ABC\n").await.unwrap();
});
let mut new_cfg = tcp_config(addr2);
new_cfg.pipelines[0].name = "hex".into();
new_cfg.pipelines[0].decoder = DecoderConfig::Hex {
uppercase: true,
separator: " ".into(),
bytes_per_group: 1,
endian: xserial_core::protocol::Endian::Big,
};
handle.reconfigure(new_cfg).await.unwrap();
let entry = handle.read(5000).await.unwrap();
assert!(matches!(entry.data, DecodedData::Hex(s) if s == "41 42 43"));
handle.close().await.unwrap();
server2.await.unwrap();
}
// ── SessionHandle event subscription ─────────────────────────────
#[tokio::test]
async fn session_handle_subscribe_sees_events() {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap().to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
stream.write_all(b"event_test\n").await.unwrap();
});
let handle = Session::spawn(7, tcp_config(addr));
let mut rx = handle.subscribe();
// Should see Connected then Data
let e1 = tokio::time::timeout(Duration::from_secs(5), rx.recv())
.await.unwrap().unwrap();
assert!(matches!(e1, SessionEvent::Connected(7)));
let e2 = tokio::time::timeout(Duration::from_secs(5), rx.recv())
.await.unwrap().unwrap();
match e2 {
SessionEvent::Data(7, entry) => {
assert_eq!(entry.pipeline_name, "text");
}
other => panic!("expected Data, got {:?}", other),
}
handle.close().await.unwrap();
server.await.unwrap();
}