Automatic endpointId generation based on routingKey for asynchronous endpoints

[lifinsky]

Description

In Ecotone, when defining an asynchronous CommandHandler or EventHandler, developers currently need to specify both a routingKey and an endpointId manually. This results in unnecessary duplication, as endpointId is often a direct derivative of routingKey.

For example, the following declaration requires specifying endpointId explicitly:

#[CommandHandler(routingKey: 'card.block.verify', endpointId: 'card.block.verify.endpoint')]
#[Asynchronous(MessagingChannel::Internal->value)]
#[Delayed(new TimeSpan(seconds: 30))]
public function verifyCardBlocked(Card $card): void

Since endpointId serves primarily as an identifier for the asynchronous consumer and doesn't necessarily need a separately assigned value, we propose that it be generated automatically based on the routingKey using a predefined convention — unless explicitly provided by the user.

Proposed Solution

If endpointId is not specified, Ecotone should automatically generate it using a standardized rule, such as:

$endpointId = $routingKey . '.endpoint'

So, the example above could be rewritten more concisely:

#[CommandHandler(routingKey: 'card.block.verify')]

This would significantly reduce verbosity while keeping full control for cases where developers want to specify a custom endpointId.

Advantages

• Less Boilerplate – Reduces redundant endpointId declarations.
• Consistency – Ensures endpointId follows a predictable naming convention.
• Backward Compatibility – Developers can still specify a custom endpointId if needed.

[lifinsky]

// AsynchronousModule
                   if (in_array(get_class($annotationForMethod), [CommandHandler::class, EventHandler::class, InternalHandler::class])) {
                        if ($annotationForMethod->isEndpointIdGenerated()) {
                            if ($annotationForMethod->getInputChannelName()) {
                                // regenerate for async endpoint or set
                            } else {
                                throw ConfigurationException::create("{$endpoint} should have endpointId defined for handling asynchronously");
                            }
                        }
                    }

[dgafka]

Since endpointId serves primarily as an identifier for the asynchronous consumer

If we say that Message Consumer is actually Message Channel (as Ecotone for Message Channels does that simplification), then the routing to given channel is based on Asynchronous attribute.
Endpoint Id serves different purpose of second level routing. So as we know where to put the Message based on Asynchronous, we also need to know where to route it after it's consumed from the Channel - and this is endpointId work.

In Ecotone, when defining an asynchronous CommandHandler

So for Command Handler that could work, as there is always single Handler for it. However that still leave us with potential problem if we define it after Messages are already in the queue, however I do think this is acceptable (with a warning on the documentation page).

or EventHandler

For Event Handlers however, remember that Ecotone is aiming for failure isolation. Therefore even if set of Event Handlers subscribe to same Event Message, each of them will receive it's own copy of it.
Each copy of the Message contains of the routing key, therefore if we would have single Event Handler following this automatic convention it would be assigned card.blocked.endpoint automatically. This however becomes problematic when we will add second Event Handler, because now the second Event Handler will get same id. Therefore it will have to force developer to define those endpoint ids, and most likely people would modify both ones (resulting in B/C in case of Messages in the Queue).

Therefore in case of Event Handlers this does not seems feasible, as chance of B/C is much higher than in Command Handlers, which would eventually lead people in defining those endpointId by default anyway.

Wdyt?

[lifinsky]

@dgafka You can define for command handlers and warn about the unsafety of this approach for event handlers in the documentation.

[dgafka]

@lifinsky well for Command Handler it's fine, as it's unlikely that this will be a problem, however for Event Handlers we can't follow behaviour in this format, as we can't assume all developers knowing the internals of the framework. Therefore Ecotone should lead into direction that is safe by default.