Cursus defines one Wire v2 contract. The in-repository Go SDK is changed and tested atomically with the broker. The separately released Java and Python SDKs also implement the required handshake, correlated frames, compression, structured errors, routing, administration, transactions, event sourcing, and framework helpers. This repository does not provide a legacy protocol mode; every SDK release must pass the shared byte-exact conformance fixture and live-broker tests.
flowchart LR
subgraph "Client SDKs"
GO[Go SDK<br/>sdk/]
JAVA[Java SDK<br/>cursus-java]
PY[Python SDK<br/>cursus-python]
end
subgraph "Cursus Broker"
B1[Broker 1]
B2[Broker 2]
B3[Broker 3]
end
GO --> B1
JAVA --> B2
PY --> B3
B1 <--> B2
B2 <--> B3
B1 <--> B3
Every supported SDK must implement the same wire protocol:
flowchart TB
subgraph "Wire Protocol"
FRAME["Wire v2: 32-byte CRS2 header + payload"]
BATCH["Batch: CBV2 schema + records"]
CMD["Command: header ID + CRQ2 fields"]
end
subgraph "Shared"
ENCODE[Canonical record encoder]
DECODE[Canonical batch decoder]
COMPRESS[gzip / snappy / lz4]
end
GO[Go SDK] --> FRAME
JAVA[Java SDK] --> FRAME
PY[Python SDK] --> FRAME
FRAME --> BATCH
FRAME --> CMD
BATCH --> ENCODE
BATCH --> DECODE
FRAME --> COMPRESS
| Feature | Go SDK | Java SDK | Python SDK |
|---|---|---|---|
| Producer (sync) | ✅ | ✅ | ✅ |
| Producer (async) | — | — | ✅ AsyncProducer |
| Consumer (polling) | ✅ | ✅ | ✅ |
| Consumer (streaming) | ✅ | ✅ | ✅ |
| Consumer Groups | ✅ | ✅ | ✅ |
| EventStore | ✅ | ✅ | ✅ |
| Compression (gzip) | ✅ | ✅ | ✅ |
| Compression (snappy) | ✅ | ✅ | ✅ (extras) |
| Compression (lz4) | ✅ | ✅ | ✅ (extras) |
| TLS | ✅ | ✅ | ✅ |
| FindCoordinator | ✅ | ✅ | ✅ |
| Partition Leader Routing | ✅ | ✅ | ✅ |
Broker-owned offset resume / auto_offset_reset |
✅ | ✅ | ✅ |
Explicit read_committed / read_uncommitted |
✅ | ✅ | ✅ |
| Required Wire v2 handshake | ✅ | ✅ | ✅ |
| Typed structured broker errors | ✅ | ✅ | ✅ |
| High-level broker transactions | ✅ | ✅ | ✅ |
| Admin client | ✅ | ✅ | ✅ |
| Event framework and saga helpers | ✅ | ✅ | ✅ |
| Client metrics | ✅ | ✅ | ✅ |
| Connection authentication | ✅ | ✅ | ✅ |
| Framework Integration | — | Spring Boot | FastAPI |
| Iterator Pattern | — | — | ✅ for/async for |
NewProducerWithContext applies its context throughout connection establishment, authentication, optional topic creation, metadata discovery, and partition connections. Cancellation closes initialization sockets and returns a context error; sender workers start only after initialization succeeds. After success, canceling the context closes the producer.
AckTimeoutMS also bounds each producer CREATE and METADATA exchange, including connection establishment and authentication. Zero uses 5000 ms for these control requests. A metadata request timeout allows discovery to try the next bootstrap address; canceling the constructor context stops initialization.
TLS settings apply to every connection, including AutoCreateTopics initialization. The connection address supplies the TLS verification hostname when no explicit server name is configured. Certificate and hostname verification remain enabled.
The default Go producer uses Acks="all" and EnableIdempotence=true. This
allows the SDK to retry the same producer epoch and sequence range when an
acknowledgement is lost without appending the record twice. The broker’s
effective min_in_sync_replicas still determines how many replicas must be in
sync before acks=all can accept the batch.
Producer delivery is bounded to MaxRetries + 1 attempts for each logical batch, including attempts that reconnect or refresh partition routing. Backoff and replacement connections run only when another attempt remains. The final failed connection is discarded without another dial or handshake. When the budget is exhausted, the producer does not put the batch back into its local queue; Flush and Close return the underlying structured broker or transport error so the application can decide whether to retry or dead-letter the records.
Producer.Flush() error waits for queued batches and returns a drain timeout
or the first permanent delivery failure. Producer.Close() error also reports
that failure, including when shutdown times out. Check both return values:
accepting a message into the local buffer is not proof of broker delivery.
Permanent delivery errors remain visible for the lifetime of the producer.
For acknowledged batches, success requires an OK acknowledgement matching
the batch’s producer ID, epoch, and complete sequence range. Read timeouts,
partial writes, incomplete responses, and invalid acknowledgements discard the
partition connection. They are retried only when the encoded request carries
the end-to-end idempotence contract.
An application can explicitly select weaker delivery with both
Acks="1" and EnableIdempotence=false. In that mode the SDK retries only a
failure proven to occur before broker acceptance, such as a connection failure
before the write or an explicit NOT_LEADER/outcome=not_accepted response.
After a partial write or missing acknowledgement it returns
*sdk.ProducerOutcomeUnknownError, which matches
sdk.ErrProducerOutcomeUnknown through errors.Is. Reconcile application
state before publishing that record again. Acks="0" does not wait for broker
acknowledgement and cannot establish delivery.
Retain the original records until delivery is confirmed. For example, keep a
caller-owned batch in durable storage, call Send for its records, and check both
Flush and Close before removing that batch. A terminal authorization or
validation rejection can be reported or dead-lettered. A transport failure,
missing acknowledgement, or interrupted shutdown can mean the broker accepted
some records: reconcile delivery or use application-level deduplication before
resubmitting, especially with a new producer identity. An error alone does not
prove that resubmission is safe from duplicates.
The producer lifecycle is observable through Producer.State() as Open,
Closing, or Closed. A Flush() that races with or follows Close() waits
for the same bounded drain and returns the same final delivery or cleanup
error. It cannot report success while a message accepted before shutdown is
still waiting for its configured acknowledgement.
Consumer.Start requires a non-nil message handler in polling and streaming modes. It returns sdk.ErrConsumerHandlerRequired and closes the consumer before coordinator discovery, group membership, or broker I/O when the handler is missing. A partition advances or automatically commits its next offset only after the handler successfully processes every preceding record in that batch. Disable EnableAutoCommit and call CommitOffset after the application’s durable side effect when processing and offset acknowledgement must share an application-controlled boundary.
Coordinator redirects, cache refreshes, reconnects, bounded labels, and recommended PromQL are documented in Go SDK consumer coordinator observability.
sequenceDiagram
participant SDK as Any SDK
participant ANY as Any Broker
participant COORD as Coordinator
participant LEADER as Partition Leader
SDK->>ANY: FIND_COORDINATOR group=G
ANY-->>SDK: OK host=H port=P
SDK->>COORD: JOIN_GROUP topic=T group=G member=M
COORD-->>SDK: OK member=M-1234 generation=N assignments=[0,1,2]
SDK->>COORD: SYNC_GROUP topic=T group=G member=M-1234 generation=N
COORD-->>SDK: OK member=M-1234 generation=N assignments=[0,1,2]
SDK->>ANY: METADATA topic=T
ANY-->>SDK: OK leaders=L0,L1,L2
loop Per Partition
SDK->>LEADER: CONSUME topic=T partition=P offset=O
LEADER-->>SDK: batch(messages)
end
loop Heartbeat
SDK->>COORD: HEARTBEAT topic=T group=G member=M-1234 generation=N
COORD-->>SDK: OK member=M-1234 generation=N
end
Every Go SDK connection performs the required Wire v2 binary handshake before authentication or application requests. Compression is negotiated during this handshake and the temporary deadline is cleared before the request lifecycle begins:
cfg := sdk.NewDefaultConsumerConfig()
cfg.CompressionType = "lz4"
cfg.HandshakeTimeoutMS = 5000
The handshake runs for every newly opened or reconnected TCP connection. HandshakeTimeoutMS bounds it; zero uses 5000 ms and negative values fail configuration validation. A version or compression mismatch closes the connection before use. The SDK has no application-level feature negotiation or legacy protocol mode.
ConsumerConfig.RequestTimeoutMS defaults to 10000 ms and bounds offset, metadata, group lifecycle, heartbeat, and commit exchanges after the handshake. ListOffsetsContext accepts an earlier caller deadline; cancellation closes a blocked socket so the connection cannot be reused after a partial frame. The non-Context ListOffsets method uses the configured default.
EventStore applies a 10-second default to connection establishment, command writes, and every response frame, including the second frame of ReadStream. Use NewEventStoreWithTimeout to select another positive default and the CreateTopicContext, AppendContext, ReadStreamContext, ReadStreamFromContext, SaveSnapshotContext, ReadSnapshotContext, and StreamVersionContext methods for caller cancellation. A connection interrupted during I/O is closed. If an append was fully written but its response cannot be read, the SDK returns *RequestOutcomeUnknownError; reconcile the stream version before retrying.
Observation methods send BROWSE_MESSAGES and READ_STREAM_HISTORY directly
after that handshake. AdminClient.Capabilities uses the read-only HELP
command and maps the exposed command families to Wire v2 feature names; its
Version is 2. This describes command availability, not the caller’s permissions.
The retained NegotiateProtocol API performs the same capability query and
local feature filtering. Its optional Version must be 2, and it never sends
an application NEGOTIATE command or enables server-side connection features.
Go, Java, and Python encode the same canonical conformance vectors for negotiation, requests, batches, stream controls, errors, and compression. The fixture protects byte-level compatibility; it does not replace each SDK’s required live-broker producer, consumer, administration, transaction, and EventStore tests.
Producer, consumer, and administration connections share one verified TLS
configuration. Set UseTLS for server-authenticated TLS. TLSCAPath can point
to a private PEM CA bundle; its certificates extend the platform trust store.
Set TLSServerName when the certificate name differs from the host used to
dial the broker, as is common with Kubernetes service names or load balancers.
When it is empty, the dialed host is verified. Hostname verification cannot be
disabled.
TLSCertPath and TLSKeyPath are an optional client identity for mutual TLS.
They must either both be empty or both be set:
cfg := sdk.NewDefaultPublisherConfig()
cfg.UseTLS = true
cfg.TLSCAPath = "/var/run/secrets/cursus/ca.crt"
cfg.TLSServerName = "broker.cursus.svc.cluster.local"
// Add these only when the broker requires mutual TLS.
cfg.TLSCertPath = "/var/run/secrets/cursus/tls.crt"
cfg.TLSKeyPath = "/var/run/secrets/cursus/tls.key"
Certificate files are loaded when a client is created. Applications should replace and drain SDK clients after rotating mounted certificate files.
Broker failures returned by application requests are available as *sdk.BrokerError:
var brokerErr *sdk.BrokerError
if errors.As(err, &brokerErr) {
if brokerErr.Retryable {
// Apply bounded backoff or redirect handling before retrying.
}
}
BrokerError exposes Code, Class, Retryable, Fields, and the raw response. Wire v2 requires explicit class and retryable fields; unstructured error text is rejected. Typed errors match ErrTopicNotFound, ErrInvalidPartition, and ErrNotLeader through errors.Is.
Producer.CreateTopic is the minimal convenience API. Disabled idempotence and unspecified policy values are omitted so repeated provisioning does not clear an existing definition. Use CreateTopicWithOptions for an explicit non-zero producer provisioning contract:
err := producer.CreateTopicWithOptions("player-state", sdk.TopicOptions{
Partitions: 12,
CleanupPolicy: sdk.TopicCleanupCompact,
RetentionHours: 168,
Partitioner: "hash_key",
})
For administrative create/update flows, use AdminClient. TopicDefinitionPatch uses pointers so callers can intentionally send zero, false, or an empty ACL while leaving nil fields unchanged:
cfg := sdk.NewDefaultAdminConfig()
cfg.BrokerAddrs = []string{"broker-1:9000", "broker-2:9000", "broker-3:9000"}
admin, err := sdk.NewAdminClient(cfg)
if err != nil {
return err
}
retentionHours := 0
emptyReaders := []string{}
definition, err := admin.UpdateTopic("player-state", sdk.TopicDefinitionPatch{
RetentionHours: &retentionHours,
ReadACL: &emptyReaders,
})
deleted, err := admin.DeleteTopic("retired-player-state", sdk.DeleteTopicOptions{
IfExists: true,
})
truncated, err := admin.TruncateTopic(definition.Topic, sdk.TruncateTopicOptions{
ExpectedRevision: definition.Revision,
ExpectedInstance: definition.InstanceID,
})
AdminClient validates values locally, returns the broker’s complete TopicDefinition for create/update, a DeleteTopicResult for delete, and a TruncateTopicResult for reset. Attempts are bounded by MaxRetries + 1 and rotate across configured brokers for retryable routing/availability and pre-submission transport failures. The SDK canonicalizes compact,delete to delete,compact, enforces the portable topic-name contract, and rejects unsafe command values, zero expected revisions, negative retention, or unknown policy enums before opening a broker connection. Compact policies require a non-event-sourcing application topic; the broker enforces the additional distributed safety gates. EventStore.CreateTopic explicitly declares cleanup_policy=delete.
DeleteTopic and TruncateTopic exist only on the admin client. IfExists=true permits ambiguous delete retries. For truncate, a nonempty ExpectedInstance selects TRUNCATE_INSTANCE and permits bounded retries of the exact instance/revision pair after a lost reply. Persist that pair before submission; never fetch a fresh revision to retry an unknown outcome. A proven replay returns Replayed=true and the historical reset offsets without deleting new records or groups. The receipt survives restart and snapshots until another definition revision; a changed definition, deleted/recreated topic, or missing proof returns a conflict. The broker requires lifecycle protocol 7 on every active broker, and the SDK never falls back to legacy truncate on an unsupported server.
Omitting ExpectedInstance preserves legacy TRUNCATE: a successful old-revision retry conflicts and an ambiguous transport failure is not automatically retried. CleanupPending distinguishes committed intent from unfinished local materialization; its absence does not certify every replica. Check broker readiness and per-broker materialization before resuming traffic. Desired-list omission never authorizes delete or truncate; only an explicit destructive action may call these APIs. See the truncate recovery contract and upgrade runbook.
Legacy requests cannot distinguish a recreated topic with a reused revision.
For instance-bound calls, the retry limit is MaxRetries + 1 total attempts,
also bounded by context and request deadlines. Exhaustion returns an error;
it never infers success. The SDK validates the response’s topic, instance,
next revision, successful reset flag, post-reset epoch and zero historical
LEO/HWM. Invalid receipts return an error without falling back to legacy or
refreshing the revision. See the current acceptance audit
for tested scope and remaining issue-level conditions.
The Go SDK exposes both the existing low-level transaction commands and a
session-preserving TransactionalProducer:
cfg := sdk.NewDefaultConsumerConfig()
cfg.BrokerAddrs = []string{"broker-1:9000", "broker-2:9000"}
client, err := sdk.NewConsumerClient(cfg)
if err != nil {
return err
}
producer, err := client.NewTransactionalProducer("game-server-events")
if err != nil {
return err
}
if err := producer.Begin(); err != nil {
return err
}
if err := producer.Publish("events", -1, sdk.Message{
SeqNum: 1,
Key: "match-42",
Payload: payload,
}); err != nil {
_ = producer.Abort()
return err
}
if err := producer.SendOffsets(
"events",
groupID,
memberID,
generation,
map[int]uint64{partition: lastProcessedOffset + 1},
); err != nil {
_ = producer.Abort()
return err
}
return producer.Commit()
The broker allocates and fences the producer ID and epoch. The high-level
producer retains that session across reconnects and serializes lifecycle calls.
A successful Commit or Abort consumes the current epoch; the next Begin
automatically reinitializes the session and obtains a higher epoch. Retrying an
uncertain finalization continues to use the same epoch, preserving idempotency. Once the broker reports state=prepare_commit, retry Commit; do not switch that epoch to abort.
For multi-topic input, register with RegisterGroupSubscription, join with JoinGroupSubscription, and stage all offsets with SendTopicOffsets. Returned sdk.Message values include Topic and Partition so handlers can preserve source identity. Exactly-once processing covers Cursus offsets and Cursus output records; external effects are not included.
NOT_COORDINATOR responses update a per-transaction coordinator cache and are
retried with a bounded delay. Fencing, authorization, validation, and ambiguous
network failures are returned to the caller as errors rather than retried. The
broker is authoritative for final transaction state; Describe returns the
typed state, message count, and offset count.
One transaction may publish to multiple output partitions, but staged consumer
offsets must share one (topic, group, member, generation) scope. Duplicate
partition entries merge monotonically and the scope commits through one fenced
bulk offset update. Use separate transactions for separate consumer scopes.
Commit writes idempotent output records, appends partition transaction markers,
applies the bulk source offset update, then persists the final coordinator
decision. read_committed requires both marker and decision, so output stays
hidden during a recoverable crash window before finalization.
The Go consumer fetches the broker-owned committed nextOffset after
assignment and rejoin. Applications that commit after processing should commit
lastProcessedOffset + 1. Reconnects roll back the local fetch position to the
last broker-committed offset, providing at-least-once processing.
AutoOffsetResetEarliest and AutoOffsetResetLatest are sent as
autoOffsetReset=earliest|latest in polling and streaming commands.
When a broker-owned committed offset has fallen outside the retained readable
range, the broker applies that policy before reading without overwriting the
committed offset; a successful handler commit advances it normally.
AutoOffsetResetError leaves reset selection disabled and surfaces an
out-of-range condition as *sdk.ConsumerOffsetOutOfRangeError. The consumer
enters the failed state, stops every assignment worker, completes cleanup, and
returns the retained cause from Start. Consumer.Err() keeps the first fatal
cause available after Done() closes.
Record handler failures are retried on the same partition and record. The
default is three retries after the first attempt, starting at 100 ms and capped
at 1 second. Configure HandlerMaxRetries, HandlerRetryBackoff, and
HandlerRetryMaxBackoff to change that budget. When it is exhausted, Start
returns *sdk.ConsumerHandlerError; the failed batch is not committed and no
rebalance is used as an implicit retry loop. A later consumer restart resumes
from the last broker-committed offset, so handlers must remain safe for
at-least-once delivery.
Consumer.Done() closes only after assignment, commit, lifecycle, connection,
and group cleanup has completed and Consumer.State() is
ConsumerStateClosed. Code waiting for full shutdown can receive from Done()
and then inspect Consumer.Err(). Close() waits for the coordinator’s
LEAVE_GROUP acknowledgement and returns the same cleanup error to every
concurrent or repeated caller.
After each metadata refresh the consumer records whether the authoritative
cleanup_policy includes compact. Forward jumps on such a topic are valid
logical holes and increment
cursus_consumer_compacted_offsets_skipped_total{topic,group}; they do not
increment cursus_consumer_offset_gap_total. The same jump on a non-compacted
topic remains an unexpected offset gap. Missing or invalid cleanup policy
metadata clears the compaction classification instead of weakening gap
detection.
ConsumerConfig.ReadIsolation selects sdk.ReadCommitted or
sdk.ReadUncommitted; the default is ReadCommitted. The SDK sends the value
explicitly on both CONSUME and STREAM. Committed reads expose
non-transactional records and transaction records only after both the matching
partition marker and final coordinator decision are durable. They skip aborted
transactions and stop at the earliest unresolved transaction. Uncommitted reads
return the raw committed partition log, including transaction control records.
ConsumerConfig.BatchSize and MaxPollRecords must each be between 1 and
sdk.MaxConsumerBatchRecords (8,192). The SDK rejects larger values before it
opens a broker connection, matching the broker’s CONSUME and STREAM limit.
Publisher and consumer configs accept connection credentials:
cfg.Principal = "game-server"
cfg.AuthToken = os.Getenv("CURSUS_AUTH_TOKEN")
When both fields are set, every new or reconnected SDK connection performs
AUTH principal=<principal> token=<token> after protocol negotiation and
before application commands. The two fields must be configured together.
Authentication and authorization failures are returned as typed
*sdk.BrokerError values. TLS remains required when credentials cross an
untrusted network.
An empty CONSUME batch can indicate an elapsed long poll or a scan page containing
only invisible transactional records. Continue polling on the same connection so
the broker can resume its bounded scan. Reconnecting resolves the requested or
committed offset again and may rescan that history. Empty batches do not commit
consumer offsets. Request payload capacity rejection closes the connection;
reconnect with backoff rather than opening an unbounded retry loop.