Skip to content

Publish API or Producer SDK

Producer-side publishing interface — instantiates Topic-Brokered Event Distribution

Gives producers a typed, authenticated entry point for emitting events to topics, enforcing the message contract at publish time so every event on the bus is well-formed and attributable.

A Publish API or Producer SDK is the doorway a producer uses to put an event onto the bus: a client library or endpoint that takes "this happened," stamps it with the producer's identity, serializes it to the agreed message shape, and hands it to the broker under a named topic. Its defining move is to make the producer's side of the contract enforceable at the moment of emission — a malformed or unauthenticated event is refused before it can reach a single subscriber. It knows nothing about who is listening, and that is exactly the point: the decoupling the archetype promises only holds if what enters the bus is already well-formed and attributable, so the producer is the one place cheap enough to check it.

Example

A ride-hailing trip service finishes a ride and needs to announce it. Rather than calling billing, ratings, and receipts directly, it makes one call — publish("trip.completed", payload) — through the producer SDK. The SDK attaches the service's credential, validates the payload against the registered trip.completed contract (and rejects it outright when the fare field is missing), wraps it in a CloudEvents-style envelope with an id and timestamp, and emits to the topic. Billing, ratings, and receipts each receive it through their own subscriptions; the trip service never learns they exist. A quarter later a new fraud-analytics team subscribes to the same topic, and the trip service changes nothing — it was already publishing to the topic, not to an audience.

How it works

  • One typed emit call per event kind, with the payload validated against its contract before it leaves the process — a rejected event fails loudly at the producer, not silently at a consumer.
  • Identity stamping — every event carries the authenticated producer identity, so subscribers and audits can attribute who said this happened.
  • Uniform envelope — id, type, timestamp, and content-type applied the same way for every producer, so the bus is homogeneous even when its publishers are not.
  • Acknowledged handoff — the SDK awaits the broker's accept, with local retry/backoff on transient failures, and surfaces a hard error when the broker will not take the event.

Tuning parameters

  • Validation strictness — reject-on-unknown-field versus accept-and-forward; strict keeps the bus clean but breaks producers the moment the schema drifts.
  • Delivery guarantee — fire-and-forget versus await-broker-ack; a stronger guarantee costs latency on every publish.
  • Batching and buffering — batch size and local buffer depth trade throughput against latency and against how many in-flight events a crash can lose.
  • Identity granularity — one credential per service or per instance; finer identity sharpens audit and revocation but multiplies key management.
  • Client retry policy — how many attempts and how backed-off before a publish failure is handed back to the caller.

When it helps, and when it misleads

Its strength is that a producer emits once and forgets the audience, while the SDK guarantees that what lands on the bus is shaped and signed — the single checkpoint that keeps the whole distribution legible. Its sharp failure mode is the illusion of durability the local buffer creates: an event the SDK accepted can still be lost if the process dies before the broker acknowledges it, or the state change can commit to the database while the publish silently fails — the dual-write trap. The classic misuse is treating a successful SDK call as proof the event is safely distributed. The discipline is to treat only the broker's acknowledgement as commitment[1], and to route events that must not be lost through a Transactional Outbox rather than trusting the emit call alone.

How it implements the components

  • event_message_contract — it enforces the contract at publish time, validating and serializing every event to the agreed shape before the broker will accept it.
  • publisher_authority_profile — it authenticates the producer and stamps its identity onto each event, making emissions attributable and revocable.

It emits and signs events but does not route them (broker_routing_boundary, fan_out_delivery_semantics — that's Topic Exchange or Event Bus), define or evolve the schema it validates against (schema_compatibility_matrix — that's Schema Registry), or guarantee the event survives a crash between commit and publish (that's Transactional Outbox).

References

[1] At-least-once delivery — the guarantee that an accepted event is delivered one or more times, never zero, at the cost of possible duplicates. It is the broker's promise, not the SDK's; only the broker's acknowledgement discharges the producer's obligation, which is why a local send buffer is not the same as a delivered event. ↩