vstp/lib.rs
1//! # VSTP - Vishu's Secure Transfer Protocol
2//!
3//! A general-purpose, binary, extensible application-layer protocol designed to be:
4//!
5//! * **Secure by default** on TCP (TLS 1.3)
6//! * **Fast** on UDP (no TLS initially)
7//! * **Minimal but extensible** with binary headers
8//! * **Easy to implement** across languages
9//!
10//! ## Quick Start
11//!
12//! ```rust
13//! use vstp::easy::{VstpClient, VstpServer};
14//! use serde::{Serialize, Deserialize};
15//!
16//! #[derive(Serialize, Deserialize)]
17//! struct Message {
18//! content: String,
19//! }
20//!
21//! // Start a TCP server
22//! let server = VstpServer::bind_tcp("127.0.0.1:8080").await?;
23//! tokio::spawn(async move {
24//! server.serve(|msg: Message| async move {
25//! println!("Received: {}", msg.content);
26//! Ok(msg) // Echo the message back
27//! }).await
28//! });
29//!
30//! // Connect a client
31//! let mut client = VstpClient::connect_tcp("127.0.0.1:8080").await?;
32//!
33//! // Send a message
34//! let msg = Message { content: "Hello, VSTP!".to_string() };
35//! client.send(msg).await?;
36//!
37//! // Receive the response
38//! let response: Message = client.receive().await?;
39//! println!("Got response: {}", response.content);
40//! # Ok::<(), vstp::VstpError>(())
41//! ```
42//!
43//! ## Protocol Overview
44//!
45//! VSTP frames have the following wire format:
46//!
47//! - MAGIC (2B): Protocol identifier
48//! - VER (1B): Protocol version
49//! - TYPE (1B): Message type
50//! - FLAGS (1B): Bit flags
51//! - HDR_LEN (2B LE): Header section length (little-endian)
52//! - PAY_LEN (4B BE): Payload length (big-endian)
53//! - HEADERS: Variable-length header section
54//! - PAYLOAD: Variable-length payload section
55//! - CRC32: 32-bit checksum
56//!
57//! Where:
58//! - **MAGIC**: `0x56 0x54` ("VT") to identify VSTP
59//! - **VER**: Protocol version (`0x01` for v1)
60//! - **TYPE**: Message type (Hello, Welcome, Data, etc.)
61//! - **FLAGS**: Bit flags (REQ_ACK, CRC, FRAG, COMP)
62//! - **HDR_LEN**: Little-endian header section length
63//! - **PAY_LEN**: Big-endian payload length
64//! - **HEADERS**: Concatenated binary K/V entries
65//! - **PAYLOAD**: Raw bytes (UTF-8 text, JSON, binary, etc.)
66//! - **CHECKSUM**: CRC16-IBM over HEADERS|PAYLOAD (optional)
67//!
68//! ## Transport Modes
69//!
70//! - **TCP mode**: Reliable + encrypted (TLS 1.3 via rustls)
71//! - **UDP mode**: Connectionless + fast (no TLS in v0.1)
72//!
73//! ## Message Types
74//!
75//! | Type | Name | Direction | Description |
76//! |------|---------|-----------------|--------------------------------|
77//! | 0x01 | HELLO | Client → Server | Start of session |
78//! | 0x02 | WELCOME | Server → Client | Server accept |
79//! | 0x03 | DATA | Both | Application data |
80//! | 0x04 | PING | Both | Keepalive request |
81//! | 0x05 | PONG | Both | Keepalive response |
82//! | 0x06 | BYE | Both | Graceful close |
83//! | 0x07 | ACK | Both | Acknowledgement |
84//! | 0x08 | ERR | Both | Error frame |
85
86pub mod codec;
87pub mod easy;
88pub mod frame;
89pub mod tcp;
90pub mod types;
91pub mod udp;
92
93// Re-export main types for convenience
94pub use types::{Flags, Frame, FrameType, Header, SessionId, VstpError, VSTP_MAGIC, VSTP_VERSION};
95
96pub use codec::VstpFrameCodec;
97pub use frame::{encode_frame, try_decode_frame};
98
99// Re-export TCP and UDP modules
100pub use tcp::{VstpTcpClient, VstpTcpServer};
101pub use udp::{VstpUdpClient, VstpUdpServer};
102
103// Re-export easy-to-use API
104pub use easy::{VstpClient, VstpServer};