How IonStream works

A layered, fully-async .NET platform where each component has a single responsibility — from Raft consensus to memory-mapped segment storage.

Layered architecture

Seven discrete components, zero external dependencies. Each layer exposes clean interfaces used by the layers above.

CLIENTS GATEWAY RUNTIME CONSENSUS STORAGE SECURITY Client SDKs .NET · Go · TypeScript · JavaScript · Python · Rust · Java IonStream.Broker Dashboard · Reverse Proxy (YARP) · REST /api/v1 · Cluster Topology Visibility IonStream.Server gRPC APIs · Producer/Consumer Coordinator · Group Manager · Partition Leader Routing IonStream.Raft Leader Election · Log Replication · Quorum · Vote RPCs IonStream.Abstractions Contracts · Interfaces · Enums IonStream.Core WAL Segments · Sparse Index · Retention · Compaction · ISR Tracking IonStream.Security TLS 1.3 · CA Derivation · PFX Certs Disk: .log segment files · .index sparse offset files · memory-mapped I/O

Raft consensus built-in

IonStream ships with a full Raft implementation. No external coordinators. Leader election, log replication, and quorum management happen entirely inside the cluster.

1
Leader Election

Nodes use randomized election timeouts to avoid split votes. Term numbers ensure stale candidates cannot win.

2
Log Replication

The leader appends entries and fans them out via AppendEntries RPC. Followers acknowledge; the leader advances the commit index once a quorum responds.

3
Dynamic Expansion

New nodes join via PROXY_MANAGERS. Even-count additions join as read-only mirrors; odd-count triggers automatic quorum promotion.

Node 1 ● Leader Term 4 Node 2 ○ Follower Term 4 Node 3 ○ Follower Term 4 AppendEntries AppendEntries ACK ACK Quorum: 2/3 → COMMIT
TOPIC: "events" Partition 0 (Leader: Node 1) seg-000 0→999 seg-001 1000→1999 seg-002 ✎ 2000→ (active) sparse offset index (every Nth message) Partition 1 (Leader: Node 2) seg-000 0→999 seg-001 ✎ 1000→ (active) sparse offset index LOG ENTRY FORMAT GuidV7 ID Offset Timestamp Key Value Headers Memory-mapped I/O · ReadOnlyMemory<byte> · Zero-copy reads Consumer Group Committed Offsets my-group/P0: 1847 · my-group/P1: 923 · Raft-replicated

Append-only log with memory-mapped segments

IonStream's core storage uses memory-mapped file segments for zero-copy reads and kernel-efficient writes. Each topic-partition maintains its own sequence of log segment files paired with sparse offset indexes for fast seek-by-offset.

GuidV7 Message IDs

Every message gets a time-ordered GUID v7. Timestamp extraction is free — no extra field needed for time-based seeks.

Segment Rolling & Retention

Segments roll at a configurable byte threshold. Time-based retention deletes sealed segments automatically. Log compaction merges duplicate keys.

ISR & High-Watermark

In-Sync Replica tracking with configurable min.insync.replicas. Acks.All produce requests block until the required quorum acknowledges.

From producer to consumer

End-to-end message lifecycle — produce, replicate, consume — with ISR acknowledgment and consumer group coordination.

Producer .NET Client Produce RPC Leader Broker Append to WAL Assign Offset Update HW-Mark ● Node 1 ReplicateLog Follower Append + ACK ● Node 2 Follower Append + ACK ● Node 3 Quorum ACK 2/3 ISR acked → COMMITTED ConsumeStream Consumer Group Partition Assignment Offset Tracking IAsyncEnumerable<T>

Every layer, explained

Server

IonStream.Server

The broker node runtime. Exposes gRPC APIs, coordinates produce/consume, manages consumer groups, routes to partition leaders, and assembles all server components.

Server

IonStream.Raft

Full Raft consensus implementation. Handles leader election via RequestVote, log replication via AppendEntries, and dynamic cluster join. Exposes its own gRPC service.

Server

IonStream.Core

The storage engine. Memory-mapped log segments, sparse offset indexes, segment rolling, time-based retention, log compaction, and ISR replica state tracking.

Infra

IonStream.Broker

Separate web-facing proxy and admin dashboard. Uses YARP with a PartitionAwareLoadBalancingPolicy to route to partition leaders and serve follower reads.

Infra

IonStream.Security

Shared TLS utilities used by server, client, and broker. Supports deterministic CA derivation from a shared secret, or externally provided PKCS#12 certificate files.

Infra

IonStream.Abstractions

The shared contract layer. Defines StreamMessage, IProducer, IConsumer, protocol enums, and interceptor interfaces. No runtime dependencies.

Client

IonStream.Client (.NET)

The full .NET SDK. Connection management, metadata refresh, leader-aware routing, connection pooling, Channel<T> APIs, and consumer group protocol.

Client

Multi-Language SDKs

Official clients for Go (REST), TypeScript/JavaScript (gRPC), Python (async gRPC), Rust (async gRPC), and Java (gRPC). All MIT-licensed.

What's implemented today

Core Messaging

  • Topics & partitions with configurable counts
  • Append-only log with memory-mapped segments
  • GuidV7 message IDs with embedded timestamps
  • Idempotent producer API
  • Consumer groups with full rebalancing
  • Seek by offset, timestamp, earliest, latest
  • Committed offset tracking per group
  • Retry queues with configurable backoff stages
  • Dead letter queue with replay & purge
  • MessageHandle ack/nack consume API

Replication & Consensus

  • Full Raft consensus implementation
  • Leader-based produce routing
  • ISR tracking & min.insync.replicas
  • Acks.All with ISR quorum blocking
  • Follower reads via YARP policy
  • Per-partition leader failover (client)
  • Dynamic cluster expansion

Operations & Observability

  • OpenTelemetry metrics + Prometheus exporter
  • Grafana dashboards included
  • Docker Compose observability stack
  • TLS 1.3 with auto cert generation
  • Cross-cluster replication (MirrorMaker)
  • Native AOT binaries (win-x64, linux-x64)
  • Producer/consumer/broker interceptors

Full feature matrix

Feature Kafka Redpanda NATS JetStream Pulsar IonStream
RuntimeJVMC++GoJVM.NET 10 AOT
External DepsZooKeeper (legacy)✓ None✓ NoneZooKeeper + BookKeeper✓ None
Wire ProtocolCustom TCPKafka ProtocolNATS ProtocolCustom BinarygRPC / HTTP/2
ConsensusKRaft / RaftRaftRaftZooKeeperRaft
Log Compaction
Log Retention
ISR EnforcementN/A
Follower Reads
Native .NET ClientConfluent SDKKafka-compat✓ Optimized
Channels API (.NET)
Browser / gRPC-WebPartial✓ REST + gRPC-Web
TLS✓ TLS 1.3
OpenTelemetry / PrometheusVia plugin✓ Built-in
Admin UIExternal✓ Built-in✓ Built-inPulsar Manager✓ Included
Grafana DashboardsCommunityCommunityCommunity✓ Included
Cross-cluster ReplicationMirrorMaker 2Replication✓ Built-in
Native AOT BinaryN/A✓ Go binary✓ win/linux
Retry Queues & DLQExternal pluginPartial (JetStream)Partial✓ Built-in

Client feature matrix

What each client SDK implements today. Preview clients ship as generated gRPC stubs — usable, but without the idiomatic helpers, retries, and high-level abstractions of the full SDKs.

Feature .NET Go TypeScript JavaScript Python Rust Java Browser
Produce Raw gRPC Raw gRPC Raw gRPC
Consume Raw gRPC Raw gRPC Raw gRPC
Ack / Nack Manual Manual Manual
Consumer Groups Manual Manual Manual
Idempotent Producer
Channels / Async Streaming API
Auto-Reconnect Basic Basic Basic
TLS / mTLS HTTPS only
Admin / Metadata REST Raw gRPC Raw gRPC Raw gRPC
Seek (offset / timestamp) Raw gRPC Raw gRPC Raw gRPC
DLQ Operations ✓ Dashboard
Retry Config
License MIT MIT MIT MIT MIT MIT MIT MIT

Raw gRPC = preview clients expose generated protobuf stubs; the operation works but requires manual wiring. Idiomatic helpers land as each client matures.