cursus

SDK Overview

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.

SDK Ecosystem

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

Wire Protocol Compatibility

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 Matrix

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

Go Producer Initialization

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.

Go Producer Delivery Errors

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.

Go Consumer Handler Contract

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.

Cluster Consumer Routing

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

Wire v2 Handshake

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.

TLS verification

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.

Go Topic Policy

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.

Go Transactional Producer

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.

Go Consumer Resume Contract

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.

Go Client Authentication

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.

Empty bounded fetches

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.