Proposal: Add a specialized publisher (and routing) for lifecycle vs. domain CloudEvents

[ricardozanini]

Summary

The runtime currently exposes a single EventPublisher contract and a single withEventPublisher(...) builder hook. As a result, engine lifecycle CloudEvents (e.g., io.serverlessworkflow.workflow.*, io.serverlessworkflow.task.*) and domain/user CloudEvents produced by workflow logic are delivered to the same publisher list. Downstream integrations often need to route these categories to different sinks (topics, exchanges, observability pipelines) or disable publishing of one category while keeping the other.

This issue proposes adding a first-class separation (or a simple filter mechanism) so SDK users can register publishers specifically for lifecycle vs. domain events without ad‑hoc filtering.

---

Motivation

• Operational clarity: Lifecycle CEs are primarily observability/monitoring signals; domain CEs represent business integration. Operators typically send them to different systems.
• Config simplicity: Today, frameworks/integrations must implement their own filters (e.g., match type prefix io.serverlessworkflow.*) and duplicate publisher wiring.
• Selective publishing: Users may want domain events only (or vice‑versa) without changing engine internals.
• Backwards compatibility: We can keep existing behavior by default and opt‑in to specialization.

---

Proposed changes

1) Introduce an event category split

Add an enum and utility to standardize detection of lifecycle events:

public enum EventCategory { DOMAIN, LIFECYCLE }

public final class LifecycleEvents {
  public static final String PREFIX = "io.serverlessworkflow."; // or more specific if desired
  public static boolean isLifecycle(CloudEvent ce) {
    String t = ce.getType();
    return t != null && t.startsWith(PREFIX);
  }
  private LifecycleEvents() {}
}

2) New builder hooks (non‑breaking)

Add optional specialized registration methods on WorkflowApplication.Builder:

public Builder withLifecycleEventPublisher(EventPublisher publisher);
public Builder withDomainEventPublisher(EventPublisher publisher);

Internally, the WorkflowApplication would maintain two lists: lifecyclePublishers and domainPublishers, in addition to the existing eventPublishers for backwards compatibility.

Routing rules:

• If LifecycleEvents.isLifecycle(ce) is true:

  • publish to lifecyclePublishers (if any), otherwise fall back to eventPublishers (to avoid breaking existing apps)

• Else (domain CE):

  • publish to domainPublishers (if any), otherwise fall back to eventPublishers

This preserves existing behavior while enabling precise targeting.

3) Alternative: filter-aware registration (single list)

Instead of separate lists, allow publishers to declare the categories they accept, or register with a predicate:

public interface EventPublisher extends AutoCloseable {
  CompletableFuture<Void> publish(CloudEvent event);
  default Set<EventCategory> categories() { return EnumSet.allOf(EventCategory.class); }
  void close();
}

// or on the builder:
public Builder withEventPublisher(EventPublisher publisher, Predicate<CloudEvent> filter);

This is slightly more flexible but a little more complex to reason about in common cases.

---

API sketch (separate lists)

public final class WorkflowApplication {
  // ...
  private final Collection<EventPublisher> eventPublishers;      // legacy
  private final Collection<EventPublisher> lifecyclePublishers;   // new
  private final Collection<EventPublisher> domainPublishers;      // new

  void publishLifecycle(CloudEvent ce) {
    Collection<EventPublisher> targets = lifecyclePublishers.isEmpty() ? eventPublishers : lifecyclePublishers;
    targets.forEach(p -> p.publish(ce));
  }

  void publishDomain(CloudEvent ce) {
    Collection<EventPublisher> targets = domainPublishers.isEmpty() ? eventPublishers : domainPublishers;
    targets.forEach(p -> p.publish(ce));
  }
}

public final class Builder {
  public Builder withLifecycleEventPublisher(EventPublisher p) { /* add to lifecyclePublishers */ return this; }
  public Builder withDomainEventPublisher(EventPublisher p) { /* add to domainPublishers */ return this; }
}

Call sites:

• Lifecycle emissions (e.g., AbstractLifeCyclePublisher.publish(...)) call application.publishLifecycle(ce).
• Domain task emissions (emit/listen actions) call application.publishDomain(ce).
• If refactoring all call sites is not immediately feasible, a temporary internal shim can route based on LifecycleEvents.isLifecycle(ce).

---

Backwards compatibility

• Existing apps using only withEventPublisher(...) continue to receive both lifecycle and domain events.
• New methods are additive.
• Optional: expose a flag to completely disable lifecycle CE generation (already provided by disableLifeCycleCEPublishing()), which remains orthogonal to publishing.

---

Configuration / DX (non-normative example)

Downstream integrations can map publishers to different channels/sinks. For example, in a messaging adapter a user might configure:

• domain → topic flow-out
• lifecycle → topic flow-lifecycle-out

Without this feature, adapters must filter event types manually.

---

Alternatives considered

• Rely on type-prefix filtering in adapters — works but repeats logic across integrations and lacks a canonical definition of lifecycle vs. domain in the SDK.
• Single list + predicate only — more flexible but less obvious for common use; still acceptable if you prefer minimal API surface.

---

Open questions

1. Should lifecycle detection be based on a type prefix, or should the SDK mark such events explicitly (e.g., via metadata/extension)?
2. Should the SDK expose a well-known extension attribute on lifecycle CEs to avoid relying on type naming conventions?
3. Do we want a hard separation (no fallback to eventPublishers) or keep the fallback for compatibility?

---

Requested outcome

• Agree on the approach (separate lists vs. predicate-based registration).

• If agreed, I can contribute a PR with:

  • Builder API additions
  • Internal routing + fallback
  • Minimal refactor of lifecycle emission sites
  • Tests proving split delivery & backwards compatibility

[fjtirado]

@ricardozanini
In my opinion, delegate the routing to the user is the right thing to do
I do not think we should establish a difference between domain and lyfecycle publishers, thats a choise the user should do.
What we can do is to provide an abstract publisher which implements differentiation on type, so users that want to split them can do it more easily.

[ricardozanini]

As in the description, users can opt in to add a generic publisher as it is today or have a different publisher for lifecycle eventing.

This is to add up to the current implementation.

Filtering is a nice to have too.

[fjtirado]

@ricardozanini we can have a FilterByTypeEventPublisher implementation that users might want to customize (and in that implementation, by default, we split betwen domain and lyfecylce because it will be a common differention), but I do not see the need to reflect the distinction between "domain" and "lyfecycle" at applicaiton level. Both are events, users needs to distinguish base on type.

[fjtirado]

I mean, I like 1) but I do not like 2).
And in case we do 2), we only add a new lifeCycleEventsPublishers and if user add it, it means infra wont be added to the domain event publishers list (the current one).
But this is useful for the case in where you want to use a completely different eventing strategy for lyfecycle. For example, write infra ones directly to a db (for reporting queries) while the domain ones are published to Smallrye channels. When you want to route both domain and lyfecycle both to the same infra, the distinction is questionable in my opinion (you will have to filter on type to route to the proper channel in your publisher anywa), thats why Im reluctant to make it explicit

[ricardozanini]

We can have both worlds. Today, we have withEventPublisher(list) with no distinction, and we keep it this way. So we broadcast everything there. If we introduce a new withLifecycleEventPublisher(one), then we route to this publisher only lifecycle events. If users wanna to keep everything the same or add more publishers, so be it.

I'm not saying we have to do one at the detriment of the other; it's just a nice-to-have option.

The general filter would be good to have too if you prefer another issue/PR to split the implementation.