Nisp.Core 3.0.0

NISP (.NET Inter-Service Protocol)

NISP is a high-performance communication protocol designed specifically for .NET inter-service communication. It provides fast, efficient serialization and transmission of .NET objects between services with minimal overhead.

Key Features

Quick Start

Define Your Messages

using MemoryPack;

[MemoryPackable]
public partial class UserMessage
{
 public int Id { get; set; }
 public string Message { get; set; } = string.Empty;
 public DateTime Timestamp { get; set; } = DateTime.UtcNow;
}

Configure the Service

var service = new NispService()
 .WithMessageTypes((1, typeof(UserMessage))) // Register message types
 .WithCompression(f => f.UseLZ4()) // Optional: LZ4, ZstdSharp or Snappier compression
 .WithLogging(b => b.AddConsole()); // Optional: logging

Create a Sender

Create a console application that will be a NISP sender that sends fire-and-forget messages

var sender = service.CreateSender("127.0.0.1", 7777);
await sender.ConnectAsync();

await sender.SendAsync(new UserMessage { Message = "Hello, World!" });
await sender.StopAsync();

Create a Receiver

Create a console application that will be a NISP receiver that accepts messages from the sender

var receiver = service.CreateReceiver("127.0.0.1", 7777);
await receiver.ListenAsync();
receiver.StartReceiving(ReceiveErrorBehavior.Ignore);

await foreach (var msg in receiver.ReceiveAsync<UserMessage>())
{
 Console.WriteLine($"Received: {msg.Message}");
}

Create a Bidirectional Peer

Create a console application that will be a NISP peer that initializes a sender to send a message to a remote node, as well as a receiver to receive messages from a remote node.

var peer = service.CreatePeer(new PeerConfig
{
 SenderEndpoint = ("127.0.0.1", 5001),
 ReceiverEndpoint = ("127.0.0.1", 5000),
 ImAliveConfig = new ImAliveConfig { DelayInMilliseconds = 5000 },
 Acknowledge = true
});

await peer.ConnectAsync();
peer.StartReceiving(ReceiveErrorBehavior.Ignore);

// Send and receive simultaneously
await peer.SendAsync(new UserMessage { Message = "Hello" });

await foreach (var msg in peer.ReceiveAsync<UserMessage>())
{
 Console.WriteLine($"Received: {msg.Message}");
 await peer.SendAsync(new UserMessage { Message = "Reply" });
}

Components

NispSender - One-Way Communication

Sends messages to a remote receiver without expecting a response

var sender = service.CreateSender("127.0.0.1", 8080);
await sender.ConnectAsync(retryAttempts: 3, retryDelay: 5000);
await sender.SendAsync(new MyMessage { Data = "Hello" });

NispReceiver - Message Listener

Listens for incoming messages and routes them to type-specific channels

var receiver = service.CreateReceiver("0.0.0.0", 8080);
await receiver.ListenAsync();
receiver.StartReceiving(ReceiveErrorBehavior.Ignore);

// Subscribe to specific message types
await foreach (var msg in receiver.ReceiveAsync<UserMessage>())
{
 ProcessUserMessage(msg);
}

await foreach (var heartbeat in receiver.ReceiveAsync<ImAliveMessage>())
{
 UpdateHealthStatus(heartbeat);
}

NispPeer - Bidirectional Communication

Combines sender and receiver for full-duplex communication. Ideal for microservices that need to both send and receive.

var peer = service.CreatePeer(new PeerConfig
{
 SenderEndpoint = ("service-b.internal", 5001),
 ReceiverEndpoint = ("0.0.0.0", 5000),
 ImAliveConfig = new ImAliveConfig { DelayInMilliseconds = 10000 },
 Acknowledge = true
});

await peer.ConnectAsync();
peer.StartReceiving();

Configuration

Message Type Registration

Each message type must have a unique ushort identifier (1-65535). Both communicating parties must use identical ID-to-Type mappings

var service = new NispService()
 .WithMessageTypes(
 (1, typeof(UserMessage)),
 (2, typeof(OrderMessage)),
 (3, typeof(PaymentMessage)),
 (4, typeof(OtherMessage))
 );

Compression Options

// LZ4 - fastest (recommended for most scenarios)
.WithCompression(f => f.UseLZ4())

// Zstd - best compression ratio
.WithCompression(f => f.UseZstdSharp())

// Snappier - Google's algorithm
.WithCompression(f => f.UseSnappier())

Error Handling Behavior

receiver.StartReceiving(ReceiveErrorBehavior.StopAndThrow); // Default - stop and throw an exception
receiver.StartReceiving(ReceiveErrorBehavior.Stop); // Stop gracefully
receiver.StartReceiving(ReceiveErrorBehavior.Ignore); // Skip and continue

SSL/TLS Encryption

// Load certificates
var serverCert = new X509Certificate2("server.pfx", "password");
var clientCert = new X509Certificate2("client.pfx", "password");

// Server-side (receiver)
var receiverSsl = new SslOptions
{
 Certificate = serverCert,
 ClientCertificateRequired = true,
 CheckCertificateRevocation = true
};

// Client-side (sender)
var senderSsl = new SslOptions
{
 Certificate = clientCert,
 RemoteCertificateValidationCallback = (sender, cert, chain, errors) => true
};

var receiver = service.CreateReceiver("0.0.0.0", 443, receiverSsl);
var sender = service.CreateSender("0.0.0.0", 443, senderSsl);

Protocol Details

Packet Structure

┌─────────────┬──────────────┬───────────────┬─────────────────┐
│ Compressed │ TypeId │ PayloadLen │ Payload │
│ 1 byte │ 2 bytes │ 4 bytes │ N bytes │
├─────────────┼──────────────┼───────────────┼─────────────────┤
│ 0x00/0x01 │ ushort LE │ int LE │ Serialized │
└─────────────┴──────────────┴───────────────┴─────────────────┘

• Compressed: 0x01 if payload is compressed, 0x00 otherwise
• TypeId: Message type identifier (must match registered types)
• PayloadLen: Length of the payload in bytes
• Payload: MemoryPack-serialized (and optionally compressed) message

Serialization

NISP uses MemoryPack - the fastest binary serializer for .NET. Your message classes must be marked with [MemoryPackable]:

[MemoryPackable]
public partial class MyMessage
{
 public int Id { get; set; }
 public string Text { get; set; } = string.Empty;
 
 [MemoryPackIgnore]
 public string ComputedField => $"{Id}: {Text}";
}

Advanced Scenarios

Heartbeat Monitoring

var peer = service.CreatePeer(new PeerConfig
{
 SenderEndpoint = ("0.0.0.1", 5001),
 ReceiverEndpoint = ("0.0.0.0", 5000),
 ImAliveConfig = new ImAliveConfig { DelayInMilliseconds = 5000 },
 Acknowledge = false
});

// Monitor remote peer health
await foreach (var alive in peer.ReceiveAsync<ImAliveMessage>())
{
 Console.WriteLine($"Peer {alive.Id} is alive at {alive.DateTime}");
}

Message Acknowledgment

var peer = service.CreatePeer(new PeerConfig
{
 // ... other config
 Acknowledge = true // Automatically send AckMessage for every received message
});

// The sender can wait for acknowledgment
await peer.SendAsync(new ImportantMessage { Data = "critical" });
// AckMessage is sent automatically by the receiver

Multiple Message Handlers

// Handle different message types in parallel
var userTask = Task.Run(async () =>
{
 await foreach (var msg in peer.ReceiveAsync<UserMessage>())
 Console.WriteLine($"User: {msg.Name}");
});

var orderTask = Task.Run(async () =>
{
 await foreach (var msg in peer.ReceiveAsync<OrderMessage>())
 await ProcessOrder(msg);
});

var heartbeatTask = Task.Run(async () =>
{
 await foreach (var msg in peer.ReceiveAsync<ImAliveMessage>())
 Console.WriteLine($"Heartbeat from {msg.Id}");
});

await Task.WhenAll(userTask, orderTask, heartbeatTask);

Performance Tuning

Socket Options (Auto-Configured)

• NoDelay (TCP_NODELAY): Minimizes latency
• KeepAlive: Detects dead connections
• ReuseAddress: Faster reconnection

Requirements

.NET 9.0 or .NET 10.0