TechTeaStudio.Protocols.Hyperion 0.1.0

HyperionProtocol

🚀 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 📊

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!