Working Group Proposal - Unified Event Bus

[cescoffier]

Objective

Design and implement a new Quarkus-native event API that is type-safe, supports multiple messaging patterns (pub/sub, point-to-point, request-response), automatically propagates context, and works without a Vert.x (HTTP) dependency, providing a unified programming model for decoupled component interaction.

The Problem

Quarkus developers who want application components to interact in a decoupled fashion, with no compile-time dependency between interacting components, face a fragmented landscape of three overlapping mechanisms, each with significant limitations.

This problem becomes even more pressing with the rise of modular monolith (modulith) architectures, in which a reliable in-process event bus serves as the primary integration backbone between modules.

1. CDI Events: Type-Safe but Limited

Pros:

• Clear, understandable API with type-safety ("type is the address", observed event types and qualifiers form the routing address)
• Context propagation works for regular (synchronous) observers

Cons:

• Only supports publish/subscribe, no point-to-point or request-response patterns
• Only declarative consumers (observer methods), no programmatic registration at runtime
• Confusing execution model
• Compatibility burden from the CDI specification (e.g., cannot simply say that Uni-returning observers run on the event loop; qualifier matching complexity with BeanManager#fireEvent() deriving types from runtime class)

Async observers (CDI 2.0) make things worse:

• Largely unknown and unused by developers
• Offload execution to a different thread, cannot participate in a reactive pipeline
• Require a completely separate API (@ObservesAsync + Event#fireAsync())
• An observer cannot be both sync and async (forbidden by the spec)
• Async observers always receive a new CDI request context with no context propagation

2. Vert.x Event Bus: Flexible but Unsafe

Pros:

• Supports publish/subscribe, point-to-point, and request-response messaging patterns
• Consumers can be added programmatically at any time

Cons:

• No type-safety: string-based addresses, messages accept any payload type
• Cluster/polyglot constraints from the Vert.x EventBus design
• Context propagation does not work:
• @ConsumeEvent handlers get a new CDI request context (not propagated from sender)
• Normal programmatic consumers have no CDI context at all

3. In-Memory Quarkus Messaging: The wrong tool

SmallRye Reactive Messaging's in-memory transport serves a similar purpose for channel-based communication, adding yet another option to the mix. Developers must understand where in-memory channels, CDI events, and Vert.x event bus each apply.

The Result

• No unified programming model — developers must learn three separate APIs with different trade-offs
• Context propagation is broken or absent in most event-driven scenarios (async CDI observers, Vert.x consumers)
• Type-safety and flexibility are mutually exclusive — CDI events are type-safe but inflexible; Vert.x event bus is flexible but type-unsafe
• Vert.x is a hard dependency for event bus functionality, but not all Quarkus applications use Vert.x (e.g., CLI applications)

The Proposed Solution

A New Quarkus-Native Event API

Design a new event API built specifically for Quarkus with the following properties:

Type-safe routing: The event type is the address. No string-based addressing. The API leverages Java's type system for event routing, similar to CDI events but without the CDI specification's compatibility constraints.

Multi-pattern support: A single API supports:

• Publish/subscribe: one-to-many event distribution
• Point-to-point: one-to-one event delivery
• Request-response: send an event and receive a typed reply

Automatic context propagation: Security, tracing, MDC, and CDI contexts (except the request scope) propagate automatically across event-delivery boundaries, for both synchronous and asynchronous handlers.

No Vert.x HTTP dependency: The API works without vertx-http (Vert.x core may be required - still need to be discussed), making it usable in CLI applications and other non-HTTP scenarios.

Usable by both users and extension developers: The API is designed for application developers writing business logic and for extension developers building framework-level integrations.

Relationship with Existing Mechanisms

• CDI Events: Continue to exist for CDI-specification-level interoperability. The new API does not replace @Observes for standard CDI use cases but provides a superior Quarkus-native alternative for application-level eventing.

• Vert.x Event Bus: The @ConsumeEvent annotation and direct Vert.x event bus usage will be deprecated in favor of the new API. A migration path will be provided.

• In-Memory Quarkus Messaging: The relationship is clearly defined: Quarkus/Reactive Messaging is for stream processing and external messaging integration; the new event API is for in-process decoupled component interaction.

Leverage the Vert.x 5 Migration Window

The Quarkus 4/Vert.x 5 migration provides a natural opportunity for redesign. Since @ConsumeEvent and Vert.x event bus usage patterns will need updates regardless, this is the right time to introduce a unified replacement.

Definition of Done

• A new event API exists with type-based routing (no string addresses)
• The API supports publish/subscribe, point-to-point, and request-response patterns
• Context (security, tracing, MDC) automatically propagates across event delivery (not the request context)
• The API works without Vert.x HTTP dependency (verified in a CLI application)
• Relationship between the new API, CDI events, and in-memory Reactive Messaging is clearly defined and documented
• The API is usable by both application developers and extension developers
• Migration guide from @ConsumeEvent and Vert.x event bus to the new API
• Quarkus guide documenting the unified event programming model
• Both declarative (annotation-based) and programmatic consumer registration are supported
• Integration tests covering all three messaging patterns with context propagation

Scope of Work

In Scope

• API design: type-safe, multi-pattern (pub/sub, P2P, request-response) event API
• Context propagation across event delivery (security, tracing, MDC, CDI contexts)
• Clarify relationship with CDI events and in-memory Quarkus Messaging
• Both declarative and programmatic consumer registration
• Migration guide from @ConsumeEvent / Vert.x event bus
• Comprehensive documentation (Quarkus guide)

Out of Scope

• External messaging systems (Kafka, AMQP, MQTT), this is Quarkus Messaging's domain
• Clustered / distributed event bus
• Event sourcing or CQRS patterns

Organizing the Work

Communication

• Zulip channel: #wg-unified-events
• GitHub discussion: TBD
• Points of contact:: @mkouba, @ozangunalp

Timeline

• Target: Quarkus 4 release cycle

Existing Issues

• #50583 : Unified event bus discussion
• #51959 : Vert.x 5 epic

[cescoffier]

@mkouba, @ozangunalp can you review?
@jponge For your information.

[mkouba]

Automatic context propagation: Security, tracing, MDC, and CDI contexts propagate automatically across event-delivery boundaries, for both synchronous and asynchronous handlers.

I do not think that we want to propagate the CDI request context. As @Ladicek pointed out - Vert.x event bus can be used to escape the context boundaries and I believe that we should preserve this behavior for the new API. Security and tracing should be propagated. I'm not so sure about MDC.

No Vert.x HTTP dependency: The API works without vertx-http (Vert.x core may be required - still need to be discussed), making it usable in CLI applications and other non-HTTP scenarios.

Hm, I believe that our initial implementation should be based on Vert.x event bus, so yes, the Vert.x core could be required.

@cescoffier Other than that 👍!

[cescoffier]

I agree that we should not propagate the request context when using send or publish (definitely not _ publish _, as it will lead to concurrent access). For request/response, it's a bit more blurry. Ideally (that's what I had in mind):

• The sender has its own request context and sends the request.
• The receiver has its own request context and processes the request and sends the response. The request context is terminated.
• The sender "restores" its own request context and receives the response.

BTW, the proposal mentions CDI contexts, but I stayed away from mentioning which ones. I will add a note about the request scope.

[cescoffier]

Amended.

[Ladicek]

• The sender "restores" its own request context and receives the response.

This doesn't necessarily have to be possible, again, depending on whether the event is synchronous or asynchronous, because the original request (such as HTTP request) may have been finished a long time ago. What is possible is to create a new CDI request context.

[cescoffier]

Ah, I see your nuance. Yes, I agree; it depends on whether the sender's request scope has been terminated in the meantime (before the response is received). If the sender "awaits" (using blocking or a Uni) the response to the request, the request scope should be the same.

[mkouba]

So I believe we're all on the same page.

1. All events should be asynchronous, in the sense that the receiver always has its own request context.
2. In case of request/response you will get the Uni<RESPONSE> . You can block/await() and then the original request context is used. You can make the result part of the reactive pipeline - and here it gets a bit complicated (because of emitOn and runSubscriptionOn).

[cescoffier]

The working group has now officially started. See WG - Unified Event Bus (view).

[manovotn]

This piqued my interest, so I started looking into how things works currently and what we could do.
That said, I wasn't there for the original discussion (tried, but my connection was bad :-/) so I am probably missing some parts.

Anyway, I think a good way would be to leverage existing Vert.x event bus and just build an API on top of it to allow users to sidestep the String based address with types. We'd of course need qualifiers to be able to support observing the same type via various consumers.
I also came to a conclusion that if we want to allow runtime consumer registration (which @mkouba mentioned to me), we'll need to have an event dispatcher object at runtime effectively doing typesafe resolution, mapping sent events to their respective underlying Vert.x addresses - this is very much what CDI does with its eventing anyway (minus the address conversion OFC!).

In order to give some shape to my thoughts, I cobbled together a PoC which can be seen here - manovotn#2

This is obviously just one way to handle it and I am not saying it is the best. Just wanted to share the way I thought about it;, we could avoid using Vert.x event bus altogether if we wanted to 🤷

[cescoffier]

@mkouba Look at this, it's nice!

[Ladicek]

I would like to highlight that, regardless of the original comment and the status of the discussion, context propagation is not a solved problem and I assume if we do what the original comment describes, we're signing up for a lot of issues later on. Need to think about it more.

[Ladicek]

OK, I thought about this through the weekend and I'm fairly sure that we cannot propagate any CDI context (except of global contexts, which need no propagation work as they are always active). We don't have a lot of CDI contexts, but we fortunately have 1 for each "kind" of a context:

1. Request context: we must not propagate it, because the very purpose of emitting an async event is to escape the request boundary.
2. Session context (longer than request): we must not propagate it, because the session context is only active when inside a request (and all requests that belong to the same session share the same session context). When escaping the request boundary, we're naturally escaping the session boundary.
   If we had the conversation context as specified by CDI, the same reasoning would apply -- the conversation context is only active when inside a request (and there's sharing), so escaping the request boundary also means escaping the conversation boundary.
3. Transaction context (shorter than request): everything that is shorter than the request is naturally confined by the request boundaries. If we're escaping request boundaries, we must not propagate anything that is confined within the request.

I'm not sure about things like security or MDC (they seem very much tied to the request, so we probably shouldn't, but I'm no expert here and would have to think more). Tracing is a special kind of context that needs to be propagated always.