BlackHole.Messaging 3.1.0

BlackHole Messaging 🕳️

High-performance network messaging for .NET 10. A custom length-prefixed binary protocol over TCP with RPC, Pub/Sub, Streaming and Batching — built on System.IO.Pipelines so the steady state allocates nothing per message.

Built by Gravicode Studios, led by Kang Fadhil.

Bahasa Indonesia · English · Documentation · Benchmarks

<a name="english"></a>

🇬🇧 English

Install

dotnet add package BlackHole.Messaging

The id BlackHole was already taken on nuget.org, so the package ships as BlackHole.Messaging. The assembly and every namespace are still BlackHole.*.

Current release: 3.1.0 — adds Unix domain sockets, named pipes and shared memory alongside TCP. See the changelog.

Thirty seconds

using BlackHole.Hosting;

// Server
await using var server = new BlackHoleServer(5000);
server.Rpc.RegisterText("upper", text => text.ToUpperInvariant());
server.Start();

// Client
await using var client = await BlackHoleClient.ConnectAsync("127.0.0.1", 5000);
string result = await client.Rpc.CallTextAsync("upper", "halo blackhole");   // "HALO BLACKHOLE"

// Pub/Sub, with MQTT-style wildcards
client.PubSub.Received += (topic, payload) => Console.WriteLine($"{topic}: {payload.Length} B");
await client.PubSub.SubscribeAsync("sensor/+/temperature");
await client.PubSub.PublishAsync("sensor/tank-3/temperature", "28.4");

What it does

Measured on this machine

.NET 10.0.11, Windows 11, 8 logical cores, loopback TCP, both ends in one process.

Full numbers, method, and how to reproduce them: docs/benchmarks.md.

Run it

dotnet run --project src/BlackHole.Demo          # every pattern, end to end
dotnet run --project src/BlackHole.IoTGateway    # the Avalonia gateway panel
dotnet test tests/BlackHole.Tests                # 42 tests

Same-machine transports

When both processes are on one machine, TCP is not the only option — and not the fastest one:

var listener = new SharedMemoryListenerHost("blackhole-ipc", slots: 8);   // 3.2 us round trip
var listener = new UnixSocketListenerHost("/tmp/blackhole.sock");         // 29 us, off the network
var listener = new NamedPipeListenerHost("blackhole-gateway");            // 37 us, ACL security

await using var server = new BlackHoleServer(listener);
server.Start();

Shared memory is 18x faster than loopback TCP at 272,000 RPC calls/sec. Everything above the transport is unchanged. See docs/transports.md for the trade-offs.

Client SDKs

Python, Go and Node.js clients speak the same protocol, and each is tested against the real .NET server rather than a mock — see clients/.

pip install blackhole-messaging
go get github.com/DotNetVibeCoderz/Vibe_Messaging/BlackHole/clients/go
npm install @gravicode/blackhole-messaging

async with await connect("127.0.0.1", 5000) as client:
    print(await client.call_text("upper", "halo blackhole"))

The IoT Gateway simulator

An Avalonia desktop panel that runs a real BlackHole gateway and attaches as many simulated sensor devices as you like — each one a genuine client on a genuine socket. Nothing in it is mocked.

dotnet run --project src/BlackHole.IoTGateway -- --demo 12

Every pattern in the library is operable from the panel: devices publish telemetry, the gateway calls RPC methods back down the same connection the device dialled out on, and Firmware uploads 4 MiB as a stream while the traces keep running. See docs/iot-gateway.md.

Documentation

Bahasa Indonesia: docs/id/.

<a name="bahasa-indonesia"></a>

🇮🇩 Bahasa Indonesia

Instalasi

dotnet add package BlackHole.Messaging

Nama BlackHole sudah dipakai orang lain di nuget.org, jadi paket ini bernama BlackHole.Messaging. Nama assembly dan seluruh namespace tetap BlackHole.*.

Rilis terkini: 3.1.0 — menambahkan Unix domain socket, named pipe, dan shared memory di samping TCP. Lihat changelog.

Tiga puluh detik

using BlackHole.Hosting;

// Server
await using var server = new BlackHoleServer(5000);
server.Rpc.RegisterText("upper", text => text.ToUpperInvariant());
server.Start();

// Client
await using var client = await BlackHoleClient.ConnectAsync("127.0.0.1", 5000);
string hasil = await client.Rpc.CallTextAsync("upper", "halo blackhole");   // "HALO BLACKHOLE"

// Pub/Sub, dengan wildcard ala MQTT
client.PubSub.Received += (topik, isi) => Console.WriteLine($"{topik}: {isi.Length} B");
await client.PubSub.SubscribeAsync("sensor/+/temperature");
await client.PubSub.PublishAsync("sensor/tank-3/temperature", "28.4");

Apa saja yang tersedia

Hasil pengukuran di mesin ini

.NET 10.0.11, Windows 11, 8 core logis, TCP loopback, kedua sisi dalam satu proses.

Angka lengkap, metode pengukuran, dan cara mengulanginya: docs/benchmarks.md.

Menjalankannya

dotnet run --project src/BlackHole.Demo          # semua pola, dari ujung ke ujung
dotnet run --project src/BlackHole.IoTGateway    # panel gateway Avalonia
dotnet test tests/BlackHole.Tests                # 42 tes

Transport satu mesin

Kalau kedua proses ada di satu mesin, TCP bukan satu-satunya pilihan — dan bukan yang tercepat:

var listener = new SharedMemoryListenerHost("blackhole-ipc", slots: 8);   // bolak-balik 3,2 us
var listener = new UnixSocketListenerHost("/tmp/blackhole.sock");         // 29 us, di luar jaringan
var listener = new NamedPipeListenerHost("blackhole-gateway");            // 37 us, keamanan ACL

await using var server = new BlackHoleServer(listener);
server.Start();

Shared memory 18× lebih cepat daripada TCP loopback, pada 272.000 panggilan RPC/detik. Semua lapisan di atas transport tidak berubah. Lihat docs/id/transports.md.

SDK Klien

Klien Python, Go, dan Node.js berbicara protokol yang sama, dan masing-masing diuji terhadap server .NET sungguhan — bukan tiruan. Lihat clients/.

pip install blackhole-messaging
go get github.com/DotNetVibeCoderz/Vibe_Messaging/BlackHole/clients/go
npm install @gravicode/blackhole-messaging

Simulator IoT Gateway

Panel desktop Avalonia yang menjalankan gateway BlackHole sungguhan dan menyambungkan sebanyak apa pun perangkat sensor simulasi — masing-masing klien sungguhan di atas soket sungguhan. Tidak ada bagian yang dipalsukan.

dotnet run --project src/BlackHole.IoTGateway -- --demo 12

Semua pola di pustaka ini bisa dioperasikan dari panel: perangkat mengirim telemetri, gateway memanggil metode RPC balik lewat koneksi yang sama yang tadi dibuka perangkat, dan tombol Firmware mengunggah 4 MiB sebagai stream sementara grafiknya tetap berjalan. Lihat docs/id/iot-gateway.md.

Dokumentasi

Dokumentasi berbahasa Indonesia ada di docs/id/: Panduan awal · Arsitektur · Protokol · Pola · Performa · IoT Gateway

License

MIT. See LICENSE.

Built by Gravicode Studios, led by Kang Fadhil.