Client Overview

Surgewave provides multiple client options for different use cases.

Client Options

Client Language Protocol Use Case
Surgewave.Client .NET Native Native protocol; direct API access
Surgewave.Confluent.Kafka .NET Auto Drop-in for existing Confluent.Kafka code paths
Confluent.Kafka .NET Kafka Kafka protocol only
gRPC Clients Any gRPC Cross-language

Quick Comparison

Feature Surgewave.Client Surgewave.Confluent.Kafka Confluent.Kafka
Latency Native (target: low) Native or Kafka wire Kafka wire
Throughput 1.25M msg/s Up to 1.25M msg/s* 68K msg/s
Protocol Native Auto/Surgewave/Kafka Kafka
Migration New API Zero code changes Original API

*Depends on protocol selection. Comparative head-to-head numbers will be published with the 1.0 release.

.NET Client (Surgewave.Client)

using Kuestenlogik.Surgewave.Client;
using Kuestenlogik.Surgewave.Client.Native;

// Low-level native client
await using var client = new SurgewaveNativeClient("localhost", 9092);
await client.ConnectAsync();

// Produce
await client.Messaging.Send("orders")
    .WithKey("order-123")
    .WithValue(orderData)
    .ExecuteAsync();

// Typed consumer
await using var consumer = new SurgewaveConsumer<string, Order>(options =>
{
    options.BootstrapServers = "localhost:9092";
    options.GroupId = "order-processor";
});
consumer.Subscribe("orders");
var result = await consumer.ConsumeAsync();
if (result != null) ProcessOrder(result.Value);

Kafka-Compatible (Confluent.Kafka)

using Confluent.Kafka;

// Same code works with Surgewave or Kafka
var config = new ProducerConfig { BootstrapServers = "localhost:9092" };
using var producer = new ProducerBuilder<string, string>(config).Build();
await producer.ProduceAsync("orders", new Message<string, string> { Value = "order" });

API Categories

Producer API

  • Single message produce
  • Batch produce
  • Streaming produce
  • Partitioning strategies

Consumer API

  • Subscribe/consume
  • Manual offset control
  • Consumer groups
  • Rebalancing

Admin Operations

  • Topic management
  • Cluster operations
  • ACL management
  • Configuration

Migration from Kafka

See the Migration Guide for detailed migration paths:

Path Effort Performance
Direct Compatibility None — point existing clients at port 9092 Kafka protocol baseline
API Wrapper Swap NuGet package Native protocol under the same producer/consumer API (target: lower latency than Kafka wire)
Native Client New API surface Full native-protocol feature set

Next Steps

Edit this page