VSTP Documentation

Protocol Overview

VSTP (Vishu's Secure Transfer Protocol) is a binary, application-layer protocol designed for secure and efficient data transfer. It provides a clean abstraction over TCP and UDP transports with built-in security features.

🎯 Design Goals

• Security: Built-in TLS 1.3 support for TCP
• Performance: Optimized for both TCP and UDP
• Simplicity: Easy to implement and use
• Extensibility: Custom headers and payload types
• Reliability: Built-in error handling and acknowledgments

Wire Format

VSTP frames have a fixed header structure followed by variable-length header and payload sections:

Field	Size	Description
MAGIC	2 bytes	Protocol identifier (0x56 0x54)
VER	1 byte	Protocol version (0x01)
TYPE	1 byte	Frame type (see Frame Types)
FLAGS	1 byte	Bit flags (see Flags)
HDR_LEN	2 bytes	Header section length (little-endian)
PAY_LEN	4 bytes	Payload length (big-endian)
HEADERS	Variable	Header section (see Headers)
PAYLOAD	Variable	Payload data
CRC32	4 bytes	Checksum (optional)

📊 Frame Layout

┌─────────┬─────┬──────┬───────┬─────────┬─────────┬─────────┬─────────┬──────┐
│ MAGIC   │ VER │ TYPE │ FLAGS │ HDR_LEN │ PAY_LEN │ HEADERS │ PAYLOAD │ CRC32 │
│ 2 bytes │ 1B  │ 1B   │ 1B    │ 2B LE   │ 4B BE   │ var     │ var     │ 4B    │
└─────────┴─────┴──────┴───────┴─────────┴─────────┴─────────┴─────────┴──────┘

Frame Types

VSTP defines several frame types for different purposes:

Type	Name	Direction	Description
0x01	HELLO	Client → Server	Start of session
0x02	WELCOME	Server → Client	Server acceptance
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

Flags

VSTP uses bit flags to indicate frame properties:

Bit	Flag	Description
0x01	REQ_ACK	Request acknowledgment
0x02	CRC	Include CRC32 checksum
0x04	FRAG	Fragmented frame
0x08	COMP	Compressed payload

Headers

VSTP supports custom headers in a simple key-value format:

// Header format
struct Header {
    key_len: u16,        // Key length (little-endian)
    key: [u8],           // Key bytes
    value_len: u16,      // Value length (little-endian)
    value: [u8],         // Value bytes
}

// Example headers
"content-type" -> "application/json"
"session-id" -> "abc123"
"priority" -> "high"

Security

VSTP provides security through multiple mechanisms:

🔒 TCP Security

• TLS 1.3 encryption
• Perfect forward secrecy
• Certificate validation
• Secure key exchange

🛡️ UDP Security

• Application-level encryption
• Message authentication
• Replay protection
• Integrity checking

Transport Modes

VSTP supports both TCP and UDP transports with different characteristics:

🌐 TCP Mode

• Reliable delivery
• Ordered messages
• Built-in TLS 1.3
• Connection-oriented
• Automatic retransmission

⚡ UDP Mode

• Low latency
• High throughput
• Connectionless
• Fragmentation support
• Custom reliability

Implementation Notes

• All multi-byte integers use little-endian byte order except PAY_LEN (big-endian)
• Frame parsing should validate MAGIC and VER fields first
• CRC32 is calculated over HEADERS + PAYLOAD when CRC flag is set
• Fragmented frames should be reassembled before processing
• Timeouts should be implemented for all network operations

VSTP Protocol Specification