As a user, I want to register interceptors for service task workers so I can add cross-cutting concerns without replacing the delivery layer

[emaarco]

Scenario

I want to add cross-cutting concerns (logging, APM/OpenTelemetry tracing, auditing)
around every service task worker execution without having to replace the entire ExternalServiceTaskDelivery
bean or rely on Spring AOP (which cannot easily access TaskInformation and variables).

The library supports two registration paths:

1. Annotation-based (@ProcessEngineWorker) via process-engine-worker
2. Manual — directly calling TaskSubscriptionApi.subscribeForTask(SubscribeForTaskCmd(..., action: TaskHandler))

A solution must cover both paths.

Current Behaviour

There is no first-class interceptor concept. To intercept worker execution, users must either:

• Replace the entire ExternalServiceTaskDelivery bean (large surface area, error-prone, engine-specific)
• Use Spring AOP (hard or impossible to access TaskInformation + variables + topic name)
• Implement a custom ParameterResolutionStrategy or ResultResolutionStrategy (worker-lib only, no lifecycle hooks)

Wanted Behaviour

A ServiceTaskInterceptor interface that allows users to register one or more Spring beans to be applied
around every service task execution — regardless of whether the subscription was created via
@ProcessEngineWorker or via a manual subscribeForTask() call.

Proposed API:

fun interface ServiceTaskInterceptor {
  fun intercept(context: ServiceTaskInterceptorContext, chain: ServiceTaskInterceptorChain)
}

data class ServiceTaskInterceptorContext(
  val taskInformation: TaskInformation,
  val payload: Map<String, Any?>,
  val taskDescriptionKey: String?,
  val taskType: TaskType
)

fun interface ServiceTaskInterceptorChain {
  fun proceed()
}

Example logging interceptor:

@Component
class LoggingServiceTaskInterceptor : ServiceTaskInterceptor {
  private val log = LoggerFactory.getLogger(this::class.java)
  override fun intercept(ctx: ServiceTaskInterceptorContext, chain: ServiceTaskInterceptorChain) {
    log.info("Executing [{}] with {} variables", ctx.taskDescriptionKey, ctx.payload.size)
    chain.proceed()
    log.info("Completed [{}]", ctx.taskDesclingKey)
  }
}

The right interception point is inside AbstractTaskSubscriptionApiImpl.subscribeForTask() — wrapping the
action TaskHandler before storing the TaskSubscriptionHandle. This makes it transparent to all delivery
implementations (pull or push) and covers both registration paths automatically. Interceptors are ordered
via @Order/Ordered. When no interceptors are registered, behaviour is identical to today (zero overhead).

Possible Workarounds

• Provide a custom ExternalServiceTaskDelivery bean (engine-specific, complex, replaces entire delivery layer)
• Spring AOP on @ProcessEngineWorker methods (does not work for manual TaskHandler registrations; TaskInformation and variables are not directly accessible as method parameters in all cases)
• Custom ParameterResolutionStrategy (worker-lib only, no pre/post hooks around the actual execution)

[emaarco]

what do you think about this @zambrovski. any other ideas on how to solve an issue like this in the current implementation of the lib?

[zambrovski]

I believe you plan is too close to the implementation. The API has no dependencies to Spring at all. Please let define the scope properly. If it has to be Spring, we might want to implement this inside the starters of adapters or inside of the worker.

Another question is: what does the term interceptor means to you? what does it intercept? Given I register an interceptor when does it get called by the adapter implementation?

You title says "interceptor for a service task worker" - a worker is a concept only present in the process-engine-worker but it doesn't exist on the API layer.

Please try to provide more use case context (and let the technical implementation ideas out on the description of the requirements).

[emaarco]

@zambrovski - Interceptor in this case means for me that, we have a set of classes that is executed before we execute the concrete taskHandler. Comparable with for example the following: https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-config/interceptors.html

The code-example above is a bit miss-leading in case of spring-usage. My first naive suggestion was somehow like that:

• engine-api: holds types & probably a generic class (without spring) that handles the execution of the chain (from the idea, comparable with ´InMemSubscriptionRepository`)
• user-application: defines interceptors
• adapter(s): use engine-api & call the interceptors before executing the job