🚀 HyperionProtocol

A high-performance, chunked TCP messaging protocol for .NET 🌟

📋 Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Architecture
• Testing
• Performance
• API Reference
• Contributing
• License

✨ Features

• 🔥 High Performance: Efficient chunked data transmission
• 📦 Large Data Support: Seamlessly handles files up to several GB
• 🔀 Chunked Protocol: Automatic splitting of large messages into manageable chunks
• 🛡️ Error Handling: Robust error detection and recovery
• ⚡ Async/Await: Fully asynchronous API with cancellation support
• 🧪 Well Tested: Comprehensive test suite with NUnit
• 🔧 Extensible: Pluggable serialization system
• 📊 Packet Integrity: Each message has unique ID and chunk validation

🚀 Quick Start

Server Example

using TechTeaStudio.Protocols.Hyperion; var listener = new TcpListener(IPAddress.Any, 8080); listener.Start(); while (true) { var client = await listener.AcceptTcpClientAsync(); _ = HandleClientAsync(client); } async Task HandleClientAsync(TcpClient client) { using var stream = client.GetStream(); var protocol = new HyperionProtocol(new JsonSerializer()); var message = await protocol.ReceiveAsync<string>(stream); Console.WriteLine($"📨 Received: {message}"); await protocol.SendAsync($"Echo: {message}", stream); }

Client Example

using var client = new TcpClient(); await client.ConnectAsync("localhost", 8080); using var stream = client.GetStream(); var protocol = new HyperionProtocol(new JsonSerializer()); await protocol.SendAsync("Hello HyperionProtocol! 👋", stream); var response = await protocol.ReceiveAsync<string>(stream); Console.WriteLine($"📬 Server replied: {response}");

📥 Installation

Option 1: Clone and Build

git clone https://github.com/yourusername/HyperionProtocol.git cd HyperionProtocol dotnet build

Option 2: Add as Project Reference

1. Copy the TechTeaStudio.Protocols.Hyperion folder to your solution
2. Add project reference:

<ProjectReference Include="..\TechTeaStudio.Protocols.Hyperion\TechTeaStudio.Protocols.Hyperion.csproj" />

🛠️ Usage

Basic Setup

// 1️⃣ Create a serializer var serializer = new DefaultSerializer(); // or implement ISerializer // 2️⃣ Create protocol instance var protocol = new HyperionProtocol(serializer); // 3️⃣ Send/Receive data await protocol.SendAsync(myData, networkStream); var receivedData = await protocol.ReceiveAsync<MyType>(networkStream);

Sending Large Files 📁

var fileBytes = await File.ReadAllBytesAsync("largefile.zip"); await protocol.SendAsync(fileBytes, stream); // File is automatically chunked into 1MB pieces // and reassembled on the receiving end! ✨

Custom Serialization

public class MyCustomSerializer : ISerializer { public byte[] Serialize<T>(T obj) { // Your custom serialization logic return MessagePack.Serialize(obj); } public T Deserialize<T>(byte[] data) { // Your custom deserialization logic return MessagePack.Deserialize<T>(data); } }

Error Handling 🛡️

try { await protocol.SendAsync(data, stream, cancellationToken); } catch (HyperionProtocolException ex) { Console.WriteLine($"🚨 Protocol error: {ex.Message}"); } catch (OperationCanceledException) { Console.WriteLine("⏹️ Operation was cancelled"); }

🏗️ Architecture

Protocol Structure

📦 Packet Structure: ┌─────────────────┬─────────────────┬─────────────────┐ │ Header Length │ JSON Header │ Payload Data │ │ (4 bytes) │ (variable) │ (≤ 1MB) │ └─────────────────┴─────────────────┴─────────────────┘

Header Format

{ "Magic": "TTS", "PacketId": "guid-here", "ChunkNumber": 0, "TotalChunks": 5, "DataLength": 1048576, "Flags": 0 }

Chunk Flow 🌊

Large Message (5MB) ↓ Chunking 📦 ↓ ┌─────────┬─────────┬─────────┬─────────┬─────────┐ │ Chunk 0 │ Chunk 1 │ Chunk 2 │ Chunk 3 │ Chunk 4 │ │ 1MB │ 1MB │ 1MB │ 1MB │ 1MB │ └─────────┴─────────┴─────────┴─────────┴─────────┘ ↓ Network Transfer 🌐 ↓ Reassembly 🔧 ↓ Complete Message ✅

🧪 Testing

Run All Tests

cd TechTeaStudio.Protocols.Hyperion.Tests dotnet test

Run Specific Test Category

# Performance tests dotnet test --filter "Category=Performance" # Basic functionality dotnet test --filter "SendReceive" # Error handling dotnet test --filter "Exception"

Test Console Application

cd ConsoleApp dotnet run

Expected output:

🎯 Starting Hyperion Protocol minimal test... 📡 Server listening on port 6000... 📤 [Client] Sending: Hello HyperionProtocol! 📨 [Server] Received: Hello HyperionProtocol! 📬 [Client] Received: Echo: Hello HyperionProtocol! ✅ Test PASSED

⚡ Performance

Benchmarks 📊

Test Scenario	Data Size	Time	Throughput
Small Message	1KB	~1ms	~1MB/s
Medium File	1MB	~10ms	~100MB/s
Large File	100MB	~500ms	~200MB/s
Huge File	1GB	~3-5s	~200-300MB/s

Memory Usage 💾

• Chunk Size: 1MB (configurable)
• Memory Footprint: ~2-3MB per active connection
• GC Pressure: Minimal due to efficient buffering

📚 API Reference

HyperionProtocol Class

Constructor

public HyperionProtocol(ISerializer serializer)

Methods

SendAsync

public async Task SendAsync<T>(T message, NetworkStream stream, CancellationToken ct = default)

Sends a message through the network stream.

Parameters:

• message: Object to send
• stream: Network stream
• ct: Cancellation token

ReceiveAsync

public async Task<T> ReceiveAsync<T>(NetworkStream stream, CancellationToken ct = default)

Receives a message from the network stream.

Returns: Deserialized object of type T

ISerializer Interface

public interface ISerializer { byte[] Serialize<T>(T obj); T Deserialize<T>(byte[] data); }

HyperionProtocolException

Custom exception thrown when protocol-level errors occur.

public class HyperionProtocolException : Exception { public HyperionProtocolException(string message); public HyperionProtocolException(string message, Exception innerException); }

🏗️ Project Structure

HyperionProtocol/ ├── 📁 src/ │ ├── 📁 TechTeaStudio.Protocols.Hyperion/ # 🎯 Main library │ │ ├── 📄 HyperionProtocol.cs # 🚀 Core protocol │ │ ├── 📄 PacketHeader.cs # 📦 Packet structure │ │ ├── 📄 ISerializer.cs # 🔄 Serialization interface │ │ └── 📄 HyperionProtocolException.cs # 🚨 Custom exceptions │ └── 📁 ConsoleApp/ # 🖥️ Demo application │ ├── 📄 Program.cs # 🎮 Demo code │ └── 📄 DefaultSerializer.cs # 📝 Basic serializer ├── 📁 tests/ │ └── 📁 TechTeaStudio.Protocols.Hyperion.Tests/ # 🧪 Unit tests │ ├── 📄 HyperionProtocolTests.cs # 🔍 Protocol tests │ └── 📄 DefaultSerializerTests.cs # 📊 Serializer tests ├── 📄 README.md # 📖 This file └── 📄 LICENSE # ⚖️ MIT License

🔧 Configuration

Chunk Size

// Default: 1MB (1024 * 1024 bytes) private const int ChunkSize = 1024 * 1024;

Header Limits

// Maximum header size: 64KB private const int MaxHeaderLength = 64 * 1024;

Timeouts ⏰

client.ReceiveTimeout = 30000; // 30 seconds client.SendTimeout = 30000; // 30 seconds

🤝 Contributing

We welcome contributions! 🎉

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing-feature)
3. 💾 Commit your changes (git commit -m 'Add some amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🔄 Open a Pull Request

Development Setup 👨‍💻

# Clone repo git clone https://github.com/yourusername/HyperionProtocol.git cd HyperionProtocol # Restore packages dotnet restore # Build solution dotnet build # Run tests dotnet test # Run demo cd src/ConsoleApp && dotnet run

🔍 Troubleshooting

Common Issues

🚨 "Stream ended while reading header length"

• Ensure server doesn't close connection before client reads response
• Add proper FlushAsync() calls
• Check network connectivity

🐌 Slow performance with large files

• Increase network buffer sizes
• Consider compression for text data
• Monitor memory usage

❌ Serialization errors

• Ensure both ends use compatible serializers
• Handle null values properly
• Check data type compatibility

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with ❤️ using .NET 8-9
• Special thanks to the RonaldRyan

---

Made by TechTeaStudio

⭐ Don't forget to star the repository if you find it useful!