Table of Contents

Interface IConfluentFormatSerializer

Namespace
Excalibur.Dispatch.Transport.Kafka
Assembly
Excalibur.Dispatch.Transport.Kafka.dll

Serializes messages to Confluent wire format (magic byte + schema ID + payload).

public interface IConfluentFormatSerializer
Extension Methods

Remarks

Implementations produce byte arrays in the Confluent wire format:

  • Byte 0: Magic byte (0x00)
  • Bytes 1-4: Schema ID (big-endian 32-bit integer)
  • Bytes 5+: Serialized message payload

The schema is automatically registered with the Schema Registry if not already present.

Zero-Copy Support: The SerializeToBufferAsync methods provide zero-copy serialization by writing directly to an IBufferWriter<T>, eliminating intermediate byte[] allocations in the hot path.

Methods

SerializeAsync(string, object, Type, CancellationToken)

Serializes a message to Confluent wire format using a runtime type.

Task<byte[]> SerializeAsync(string topic, object message, Type messageType, CancellationToken cancellationToken)

Parameters

topic string

The Kafka topic name (used for subject naming).

message object

The message to serialize.

messageType Type

The runtime type of the message.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<byte[]>

The serialized message in Confluent wire format.

Remarks

This overload is useful when the message type is only known at runtime, such as when dispatching IDispatchAction instances.

Exceptions

SchemaRegistryException

Schema registration failed or the schema is incompatible with existing versions.

SerializeAsync<T>(string, T, CancellationToken)

Serializes a message to Confluent wire format.

Task<byte[]> SerializeAsync<T>(string topic, T message, CancellationToken cancellationToken)

Parameters

topic string

The Kafka topic name (used for subject naming).

message T

The message to serialize.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<byte[]>

The serialized message in Confluent wire format.

Type Parameters

T

The type of message to serialize.

Exceptions

SchemaRegistryException

Schema registration failed or the schema is incompatible with existing versions.

SerializeToBufferAsync(IBufferWriter<byte>, string, object, Type, CancellationToken)

Serializes a message to Confluent wire format directly into a buffer writer using a runtime type (zero-copy).

ValueTask<int> SerializeToBufferAsync(IBufferWriter<byte> writer, string topic, object message, Type messageType, CancellationToken cancellationToken)

Parameters

writer IBufferWriter<byte>

The buffer writer to write the serialized data to.

topic string

The Kafka topic name (used for subject naming).

message object

The message to serialize.

messageType Type

The runtime type of the message.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

ValueTask<int>

The number of bytes written to the buffer.

Remarks

This overload is useful when the message type is only known at runtime, such as when dispatching IDispatchAction instances.

This method provides zero-copy serialization by writing the 5-byte Confluent header and JSON payload directly to the provided buffer, eliminating intermediate allocations.

Exceptions

ArgumentNullException

Thrown when writer, message, or messageType is null.

ArgumentException

Thrown when topic is null, empty, or whitespace.

SchemaRegistryException

Schema registration failed or the schema is incompatible with existing versions.

SerializeToBufferAsync<T>(IBufferWriter<byte>, string, T, CancellationToken)

Serializes a message to Confluent wire format directly into a buffer writer (zero-copy).

ValueTask<int> SerializeToBufferAsync<T>(IBufferWriter<byte> writer, string topic, T message, CancellationToken cancellationToken)

Parameters

writer IBufferWriter<byte>

The buffer writer to write the serialized data to.

topic string

The Kafka topic name (used for subject naming).

message T

The message to serialize.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

ValueTask<int>

The number of bytes written to the buffer.

Type Parameters

T

The type of message to serialize.

Examples

using var bufferWriter = new PooledBufferWriter();
var bytesWritten = await serializer.SerializeToBufferAsync(bufferWriter, "orders-topic", order, ct);
var data = bufferWriter.WrittenMemory;

Remarks

This method provides zero-copy serialization by writing the 5-byte Confluent header and JSON payload directly to the provided buffer, eliminating intermediate allocations.

The caller is responsible for providing a properly sized buffer writer (e.g., PooledBufferWriter or PipeWriter).

Exceptions

ArgumentNullException

Thrown when writer or message is null.

ArgumentException

Thrown when topic is null, empty, or whitespace.

SchemaRegistryException

Schema registration failed or the schema is incompatible with existing versions.