Stable outbox handler identifiers

[rolandbeisel]

Stable outbox handler identifiers

Problem

Namastack persists a handler identifier on each outbox record. The identifier is later used to find
the handler, fallback handler, and retry policy responsible for that record.

For regular handlers, the current identifier is derived from the concrete target class and handler
method:

com.example.OrderHandler#handle(com.example.OrderCreated)

This is a useful zero-configuration default, but it makes the persisted record depend on application
implementation details. Moving a class to another package, renaming a class or method, or changing a
parameter type changes the identifier. Records written before such a change can then no longer be
routed to their handler.

Lambda handlers have an additional problem: generated lambda class names are not stable across JVM
runs. Mainline Namastack therefore already uses the Spring bean name as the identifier for
interface-based lambda handlers.

The objective is to let applications and integrations opt into a logical identifier without
breaking existing handlers, existing databases, or source compatibility.

Goals

• Preserve the current identifier and behavior unless a user explicitly opts into a stable ID.
• Allow annotation-based and interface-based handlers to declare stable IDs.
• Continue processing records that contain an earlier handler ID.
• Preserve the Spring bean-name behavior for lambda handlers.
• Apply the same routing aliases to handlers, fallback handlers, and retry policies.
• Detect ambiguous IDs at application startup.
• Provide a migration procedure that is safe during rolling deployments.

Non-goals

• Automatically recovering every historical lambda or proxy class name.
• Making automatically assigned Spring bean names stable under all refactorings.
• Transparently making a one-step rolling deployment safe when old instances have never seen the new
  identifier.
• Rewriting persisted records automatically as part of handler registration.

Compatibility model

The feature is optional. Existing declarations remain valid:

@OutboxHandler
fun handle(event: OrderCreated) {
    // ...
}

The annotation attributes have defaults:

annotation class OutboxHandler(
    val id: String = "",
    val aliases: Array<String> = [],
)

Interface handlers receive JVM default methods:

interface OutboxHandler {
    fun getHandlerId(): String? = null
    fun getHandlerAliases(): Set<String> = emptySet()
}

interface OutboxTypedHandler<T> {
    fun getHandlerId(): String? = null
    fun getHandlerAliases(): Set<String> = emptySet()
}

An empty annotation ID or a null interface ID means that the handler has not opted into a stable
ID. Regular handlers then keep the existing class-and-method identifier. This avoids source,
behavioral, and data compatibility breaks.

Terminology

Canonical ID

The identifier written to newly created outbox records.

Routing ID

Any identifier that resolves to a handler. The routing IDs of a handler consist of its canonical ID
and all registered aliases.

Alias

An alternative routing ID that resolves to the same handler but is not written to new records.
Aliases may represent either:

• a legacy ID that remains readable after the canonical ID changes, or
• a future ID registered before a canonical-ID migration.

The second use is required for rolling-deployment-safe migrations. Aliases must therefore be
supported independently of whether an explicit canonical ID is configured.

Identifier resolution

The canonical ID is selected using the following precedence.

Annotation-based handler

@OutboxHandler.id is non-empty
    -> use the configured annotation ID

otherwise
    -> use the existing target-class and method identifier

Examples:

@OutboxHandler
fun handle(event: OrderCreated) {}

com.example.OrderHandler#handle(com.example.OrderCreated)

@OutboxHandler(id = "order-created")
fun handle(event: OrderCreated) {}

order-created

An annotation-based bean may contain multiple handler methods. Explicit IDs are therefore naturally
per method. No Spring bean name is required to distinguish them.

Interface-based handler

getHandlerId() returns a non-null value
    -> use the configured interface ID

otherwise, the target class is a lambda
    -> use the Spring bean name

otherwise
    -> use the existing target-class and method identifier

The explicit interface ID takes precedence over the lambda default if a non-lambda implementation or
wrapper supplies one. A plain Java or Kotlin SAM lambda cannot override additional interface default
methods, so its practical default remains the Spring bean name.

Stable Spring bean names

Spring bean names are unique within their application context, but automatically derived names can
change when a component class or @Bean method is renamed. Applications that rely on a bean name as
a persistent identifier should declare it explicitly:

@Bean("spring-modulith-event-externalizer")
fun eventExternalizer(): OutboxHandler = OutboxHandler { payload, metadata ->
    // ...
}

Alias construction

Configured aliases are always registered, including when no explicit stable ID is configured.

When a regular handler opts into an explicit canonical ID, Namastack also registers its previous
generated target-class and method ID automatically:

Canonical ID:
order-created

Automatic alias:
com.example.OrderHandler#handle(com.example.OrderCreated)

For a regular AOP-proxied handler, the current runtime proxy-class identifier may also be registered
for compatibility with records written by versions that used the runtime proxy class.

Generated lambda class identifiers must not be registered automatically, whether the lambda is
proxied or not. A generated lambda ID is not stable across JVM runs and the class name observed in the
current process may not match a value stored by an earlier process.

Some historical identifiers cannot be reconstructed automatically, including:

• lambda identifiers from an earlier JVM run,
• proxy identifiers whose generated suffix has changed, and
• identifiers from classes that were already renamed or moved.

Known values can be supplied explicitly:

@OutboxHandler(
    id = "order-created",
    aliases = [
        "com.oldpackage.OrderHandler#handle(com.example.OrderCreated)",
    ],
)
fun handle(event: OrderCreated) {}

Registration model

Each logical handler registration consists of:

data class HandlerRegistration(
    val canonicalId: String,
    val aliases: Set<String>,
    val handler: OutboxHandlerMethod,
    val fallback: OutboxFallbackHandlerMethod?,
    val retryPolicy: OutboxRetryPolicy,
)

This does not require the public implementation to use this exact data class, but all three runtime
lookups must share the same routing-ID set:

• primary handler lookup,
• fallback handler lookup, and
• retry-policy lookup.

Otherwise an old record might find its primary handler through an alias while silently receiving the
default retry policy or no fallback handler.

Only canonical IDs are used when scheduling new records and when listing primary handler
descriptors. Aliases are lookup-only metadata.

Uniqueness and validation

Canonical IDs and aliases share one global routing namespace within a Namastack handler registry.
No routing ID may resolve to two different handlers.

The following configuration is invalid:

Handler A canonical ID: order-created
Handler B alias:        order-created

Configured IDs and aliases must not be blank. Duplicate detection must happen at application startup
and report:

• the duplicated routing ID,
• whether each use is canonical or an alias,
• both Spring bean names, and
• both handler method signatures.

Registration must validate the complete canonical-ID and alias set before mutating any handler type
indexes. A rejected handler must not remain partially registered.

Mixed annotation and interface discovery

A bean can implement a handler interface and also declare an @OutboxHandler method. The annotation
and interface scanners may then discover the same logical method.

The implementation must define one deterministic behavior. The recommended behavior is to
deduplicate registrations by bean identity and invocable method, with annotation configuration taking
precedence for that method. If the discoveries describe different logical handlers, they remain
separate and must satisfy the global routing-ID uniqueness rule.

If annotation and interface aliases apply to the same registration, they should be combined rather
than silently discarding one source.

Rolling deployments

The asymmetric compatibility problem

Suppose the old canonical ID is:

com.example.OrderHandler#handle(com.example.OrderCreated)

and the new stable ID is:

order-created

After a one-step rolling deployment, a new instance understands old records because it registers the
old generated ID as an alias. An old instance does not understand records written with
order-created, because that instance has never registered the new ID.

If an old instance claims such a record, handler lookup fails with an exception equivalent to:

No handler with id order-created

The record is not silently lost, but it may accumulate failures, use the default retry policy, lack a
matching fallback, or reach permanent failure before the rollout completes.

Safe two-deployment migration

Aliases allow both old and new application instances to understand both IDs before the write ID is
changed.

Deployment 1: register the future ID as an alias

@OutboxHandler(aliases = ["order-created"])
fun handle(event: OrderCreated) {}

The explicit id remains empty:

Canonical ID written to new records:
com.example.OrderHandler#handle(com.example.OrderCreated)

Accepted alias:
order-created

After this rolling deployment finishes, every instance understands both IDs while all instances still
write the old ID.

Deployment 2: switch the canonical ID

@OutboxHandler(id = "order-created")
fun handle(event: OrderCreated) {}

The routing configuration becomes:

Canonical ID written to new records:
order-created

Automatic legacy alias:
com.example.OrderHandler#handle(com.example.OrderCreated)

During the second rolling deployment:

Instance version	Writes	Accepts
Deployment 1	old generated ID	old generated ID and order-created
Deployment 2	order-created	order-created and old generated ID

Every instance can therefore process every record.

The same procedure applies to interface handlers by returning the future ID from
getHandlerAliases() in the first deployment and returning it from getHandlerId() in the second.

Alternatives

If two application deployments are not practical, an application may instead:

• perform a coordinated deployment without overlapping versions,
• pause old workers before new instances begin writing the new ID,
• drain pending records before switching IDs, or
• rely on retries only when the retry window is guaranteed to outlive the rollout.

A database migration can normalize old records after the switch, but it does not by itself make a
mixed-version rollout safe: old instances still cannot understand newly written IDs unless processing
is paused or the future ID was registered in advance.

Removing aliases

Aliases should not necessarily remain part of the application contract forever. A typical lifecycle
is:

1. register the future ID as an alias,
2. switch it to the canonical ID,
3. allow old records to drain or migrate their stored IDs,
4. verify that no records reference the legacy ID, and
5. remove the legacy alias in a later deployment.

Operators should be able to group pending records by handler ID before removing an alias. The exact
query depends on the persistence module and configured table names, but is conceptually:

select handler_id, count(*)
from outbox_record
group by handler_id;

Failure behavior

An unknown handler ID is a routing or configuration failure, not an exception thrown by application
handler code. Namastack should preserve the record and surface a clear diagnostic containing the
record ID and handler ID.

Retries can be useful during deployments, but they are not a replacement for bidirectional ID
compatibility. The behavior of fallback processing for an unknown handler must be deliberate: a
fallback associated with a known handler cannot be selected until the handler ID itself resolves.

Required test coverage

Compatibility

• An annotation without id retains the existing generated ID.
• A regular interface handler without getHandlerId() retains the existing generated ID.
• Existing Java and Kotlin interface implementations need not implement the new default methods.
• Multiple annotation handlers on one bean continue to work without explicit IDs.

Explicit IDs and aliases

• An annotation ID becomes the canonical ID.
• An interface-provided ID becomes the canonical ID.
• A configured alias is registered even when no explicit ID is configured.
• A regular handler with an explicit ID automatically accepts its previous generated ID.
• Handler, fallback, and retry-policy lookup all work through every alias.

Lambdas and proxies

• A non-proxied interface lambda uses its Spring bean name.
• An AOP-proxied interface lambda uses its Spring bean name.
• Neither case registers a generated lambda class ID as an alias.
• A regular proxied handler retains the supported proxy compatibility alias behavior.

Validation

• Blank explicit IDs and aliases are rejected.
• Canonical-to-canonical, canonical-to-alias, and alias-to-alias collisions are rejected.
• Collision rejection does not partially update handler indexes.
• Diagnostics identify both conflicting handlers.

Migration

• A deployment-1 registration writes the old ID and resolves the future ID.
• A deployment-2 registration writes the future ID and resolves the old ID.
• Records written by either deployment can be processed by either registration.

Documentation requirements

The public handler documentation must include:

• the complete identifier precedence table,
• the distinction between canonical IDs and aliases,
• the special default for lambda handlers,
• the recommendation to use explicit Spring bean names for persistent lambda identities,
• limitations of automatically reconstructed legacy IDs,
• the safe two-deployment migration procedure, and
• guidance for determining when a legacy alias can be removed.

Decision summary

Handler kind	Explicit stable ID	Canonical ID
Annotation method	no	existing target-class and method ID
Annotation method	yes	annotation id
Regular interface handler	no	existing target-class and method ID
Regular interface handler	yes	getHandlerId()
Interface lambda	no	Spring bean name
Interface lambda through a named wrapper	yes	getHandlerId()

This design keeps current applications unchanged by default, gives integrations a stable logical
routing contract when they opt in, and supports both backward-compatible record processing and safe
rolling migrations through bidirectional aliases.