Interface StreamsGroupTopologyDescriptionPlugin

All Superinterfaces:
AutoCloseable, Configurable

@Public @Evolving public interface StreamsGroupTopologyDescriptionPlugin extends Configurable, AutoCloseable
A broker-side plugin that stores, forwards, or exposes topology descriptions pushed by Kafka Streams clients.

Implementations must be thread-safe. setTopology(String, int, StreamsGroupTopologyDescription) may be called concurrently by multiple members of the same group; calls with the same (groupId, topologyEpoch) carry identical data and must be idempotent. deleteTopology(String) must also be idempotent — it may be called more than once for the same groupId, including when nothing is stored.

  • Method Details

    • setTopology

      CompletableFuture<Void> setTopology(String groupId, int topologyEpoch, StreamsGroupTopologyDescription description)
      Store the topology description for a streams group.

      The returned future completes when the topology has been persisted or forwarded. Failures must be signalled by completing the future exceptionally — implementations must not throw synchronously; a synchronous throw is treated as a permanent failure with a generic client-visible error message. The completion exception drives broker-side behaviour:

      In both cases the caller receives error code STREAMS_TOPOLOGY_DESCRIPTION_UPDATE_FAILED with the exception's message in ErrorMessage; the permanent-vs-transient split is broker-internal state.
    • deleteTopology

      CompletableFuture<Void> deleteTopology(String groupId)
      Remove any topology description stored for this group. Called when the group is deleted or expires. A failure (future completed exceptionally) is reported to the caller of DeleteGroups as GROUP_DELETION_FAILED with the exception message in the per-group ErrorMessage, and the broker does not tombstone the group; a retry of DeleteGroups re-invokes this method idempotently. The periodic-cleanup path treats a failure identically — the group's tombstone is deferred to a future cycle.
    • getTopology

      CompletableFuture<StreamsGroupTopologyDescription> getTopology(String groupId, int topologyEpoch)
      Return the stored topology description for (groupId, topologyEpoch), or null if the plugin no longer has the data (e.g. backend wipe). If the future completes exceptionally, the broker reports a read error for the group.