vstp 0.1.0

VSTP - Vishu's Secure Transfer Protocol: A fast, secure, and extensible binary protocol for TCP and UDP
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

//! # VSTP - Vishu's Secure Transfer Protocol
//!
//! A general-purpose, binary, extensible application-layer protocol designed to be:
//!
//! * **Secure by default** on TCP (TLS 1.3)
//! * **Fast** on UDP (no TLS initially)
//! * **Minimal but extensible** with binary headers
//! * **Easy to implement** across languages
//!
//! ## Quick Start
//!
//! ```rust
//! use vstp::{Frame, FrameType, Flags};
//!
//! // Create a simple data frame
//! let frame = Frame::new(FrameType::Data)
//!     .with_header("content-type", "text/plain")
//!     .with_payload(b"Hello, VSTP!".to_vec())
//!     .with_flag(Flags::REQ_ACK);
//!
//! // Encode to bytes
//! let encoded = vstp::frame::encode_frame(&frame)?;
//!
//! // Decode from bytes
//! let mut buf = bytes::BytesMut::from(&encoded[..]);
//! let decoded = vstp::frame::try_decode_frame(&mut buf, 1024)?.unwrap();
//!
//! assert_eq!(frame, decoded);
//! # Ok::<(), vstp::VstpError>(())
//! ```
//!
//! ## Protocol Overview
//!
//! VSTP frames have the following wire format:
//!
//!
//! VSTP frames have the following wire format:
//!
//! - MAGIC (2B): Protocol identifier
//! - VER (1B): Protocol version  
//! - TYPE (1B): Message type
//! - FLAGS (1B): Bit flags
//! - HDR_LEN (2B LE): Header section length (little-endian)
//! - PAY_LEN (4B BE): Payload length (big-endian)
//! - HEADERS: Variable-length header section
//! - PAYLOAD: Variable-length payload section
//! - CRC32: 32-bit checksum
//!
//! Where:
//! - **MAGIC**: `0x56 0x54` ("VT") to identify VSTP
//! - **VER**: Protocol version (`0x01` for v1)
//! - **TYPE**: Message type (Hello, Welcome, Data, etc.)
//! - **FLAGS**: Bit flags (REQ_ACK, CRC, FRAG, COMP)
//! - **HDR_LEN**: Little-endian header section length
//! - **PAY_LEN**: Big-endian payload length
//! - **HEADERS**: Concatenated binary K/V entries
//! - **PAYLOAD**: Raw bytes (UTF-8 text, JSON, binary, etc.)
//! - **CHECKSUM**: CRC16-IBM over HEADERS|PAYLOAD (optional)
//!
//! ## Transport Modes
//!
//! - **TCP mode**: Reliable + encrypted (TLS 1.3 via rustls)
//! - **UDP mode**: Connectionless + fast (no TLS in v0.1)
//!
//! ## Message Types
//!
//! | Type | Name    | Direction       | Description                    |
//! |------|---------|-----------------|--------------------------------|
//! | 0x01 | HELLO   | Client → Server | Start of session              |
//! | 0x02 | WELCOME | Server → Client | Server accept                 |
//! | 0x03 | DATA    | Both            | Application data              |
//! | 0x04 | PING    | Both            | Keepalive request             |
//! | 0x05 | PONG    | Both            | Keepalive response            |
//! | 0x06 | BYE     | Both            | Graceful close                |
//! | 0x07 | ACK     | Both            | Acknowledgement               |
//! | 0x08 | ERR     | Both            | Error frame                   |

pub mod codec;
pub mod frame;
pub mod tcp;
pub mod types;
pub mod udp;

// Re-export main types for convenience
pub use types::{Flags, Frame, FrameType, Header, SessionId, VstpError, VSTP_MAGIC, VSTP_VERSION};

pub use codec::VstpFrameCodec;
pub use frame::{encode_frame, try_decode_frame};

// Re-export TCP and UDP modules
pub use tcp::{VstpTcpClient, VstpTcpServer};
pub use udp::{VstpUdpClient, VstpUdpServer};