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 🤷

[mkouba]

It seems to me you would prefer the first option, and to declare a catch-all observer, the observer would explicitly have to declare @Any. This would be similar to @Inject @Any Instance<FooBar>, which is not uncommon. It does make sense.

Yes, exactly.

It's actually even more confusing, because since CDI 1.0 the spec contains the sentence: "If the event parameter does not explicitly declare any qualifier, the observer method observes events with no qualifier.".

But at the same time:

"Every event has the qualifier @Any, even if it does not explicitly declare this qualifier."

In other words, "events with no qualifier" may never occur.

Also the javadoc of BeanContainer#isMatchingEvent() is IMO weird:

"For the purpose of observer resolution, the specifiedType is used as the event type directly (because there is no event object in this API) and specifiedQualifiers are used as event qualifiers. In line with the specification for events and observer resolution, the set of event qualifiers is considered to always include @Any. Further, an empty set of specifiedQualifiers is considered to match the set of observedEventQualifiers which contains @Default ."

It basically says that an observer with [@Default] should match an event with qualifiers [] (which may not represent any "real" event, because any event has @Any). And that's against the spec because "The observer method has no event qualifiers or has a subset of the event qualifiers." does not apply here (unless I'm missing something).

I don't mind either approach but the former seems like a lot less hassle and you instantly get users familiar with the API at the cost of allowing unqualified receivers to behave just like they do in CDI.
I guess ultimately I am just not a fan of the current observer resolution effectively being "it's like CDI, buuut ..." 🤷

I personally think that users will be more confused by other differences, e.g. where are my transactional observers, where is ordering, why is my receiver executed on a different request context, etc. And that's fine because it's not CDI events... but I also understand your position. Let's think about this a while longer and we can also discuss with other team members.

[Ladicek]

Also the javadoc of BeanContainer#isMatchingEvent() is IMO weird:

"For the purpose of observer resolution, the specifiedType is used as the event type directly (because there is no event object in this API) and specifiedQualifiers are used as event qualifiers. In line with the specification for events and observer resolution, the set of event qualifiers is considered to always include @Any. Further, an empty set of specifiedQualifiers is considered to match the set of observedEventQualifiers which contains @Default ."

It basically says that an observer with [@Default] should match an event with qualifiers [] (which may not represent any "real" event, because any event has @Any). And that's against the spec because "The observer method has no event qualifiers or has a subset of the event qualifiers." does not apply here (unless I'm missing something).

Two things.

One:

which may not represent any "real" event, because any event has @Any

I think this is one of the reasons why we make a difference between "specified qualifiers" and "event qualifiers". The set of specified qualifiers is the input to this method. It gets transformed in a relatively straightforward way into a set of event qualifiers, which is the input to the observer resolution algorithm. One of the transformations is:

the set of event qualifiers is considered to always include @Any

So this is not an issue, really. The set of event qualifiers always includes @Any, even if the set of specified qualifiers doesn't -- just like in regular CDI usage.

Two:

It basically says that an observer with [@Default] should match an event with qualifiers []. And that's against the spec because "The observer method has no event qualifiers or has a subset of the event qualifiers." does not apply here (unless I'm missing something).

This is true, but see also the end of this chapter: https://jakarta.ee/specifications/cdi/4.1/jakarta-cdi-spec-4.1.html#multiple_event_qualifiers I think we discussed this once on Zulip -- this seems to have been a mistake, but the mistake is the rule now.

[mkouba]

It basically says that an observer with [@Default] should match an event with qualifiers []. And that's against the spec because "The observer method has no event qualifiers or has a subset of the event qualifiers." does not apply here (unless I'm missing something).

This is true, but see also the end of this chapter: https://jakarta.ee/specifications/cdi/4.1/jakarta-cdi-spec-4.1.html#multiple_event_qualifiers I think we discussed this once on Zulip -- this seems to have been a mistake, but the mistake is the rule now.

Yes, this chapter also evolved over time. But my point is that some of the spec parts contradict each other.

[Ladicek]

Yes, this chapter also evolved over time. But my point is that some of the spec parts contradict each other.

Yes, they do. For example, 9. Events says:

An observer method will be notified of an event if the event object is assignable to the observed event type, and if the set of observed event qualifiers is a subset of all the event qualifiers of the event.

While 9.3. Observer resolution says:

The observer method has no event qualifiers or has a subset of the event qualifiers.

:-)

[manovotn]

But my point is that some of the spec parts contradict each other.

Yea, we should clarify that in the CDI spec before we forget it about, again - jakartaee/cdi#965

But my point is that some of the spec parts contradict each other.

True. Unfortunately, there will be more parts like that (outside eventing) I suppose; it is an old spec that keep changing 😅

[cvgaviao]

Hello. I just saw the release notes of 3.36.0 now, I saw Signals and got interested in knowing more.

I just would like to clarify two points. Sorry if it is not the proper place to do it.

Signals is providing an event-bus for a single application. So, if my application is running with multiple replicas, each one will handle its own signals, right?

A message tool (kafka, rabbitmq, etc.) is still the recommended way to handle distributed events, right?

[Ladicek]

Correct on both points.