Replace ApplicationConfigurer.Handlers() with Routes().

CHANGELOG.md

@@ -12,26 +12,24 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ## [Unreleased]
 
-This releases introduces the `Handlers()` method to the `ApplicationConfigurer`
-interface. Implementors should use `Handlers()` in preference to the existing
-`Register*()` methods, which are now deprecated.
+This releases introduces a `Routes()` method to the `ApplicationConfigurer`
+interface. Application developers should use `Routes()` in preference to the
+existing `Register*()` methods, which are now deprecated.
 
-The `Handlers()` API offers a more extensible interface that allows for future
+The `Routes()` API offers a more extensible interface that allows for future
 changes to handler configuration without introducing interface-level compilation
 errors.
 
 ### Added
 
-- **[ENGINE BC]** Added `Handlers()` method to `ApplicationConfigurer`
-- Added `RegisterAggregate()`
-- Added `RegisterProcess()`
-- Added `RegisterIntegration()`
-- Added `RegisterProjection()`
-- Added `HandlerRegistration` interface
-- Added `AggregateRegistration` type
-- Added `ProcessRegistration` type
-- Added `IntegrationRegistration` type
-- Added `ProjectionRegistration` type
+- **[ENGINE BC]** Added `Routes()` method to `ApplicationConfigurer`.
+- Added `ViaAggregate().`
+- Added `ViaProcess()`.
+- Added `ViaIntegration()`.
+- Added `ViaProjection()`.
+- Added `HandlerRoute` and `MessageRoute` interfaces.
+- Added `ViaAggregateRoute`, `ViaProcessRoute`, `ViaIntegrationRoute` and
+  `ViaProjectionRoute` types.
 
 ### Changed
 
@@ -45,10 +43,15 @@ errors.
 
 ### Deprecated
 
-- Deprecated `ApplicationConfigurer.RegisterAggregate()`
-- Deprecated `ApplicationConfigurer.RegisterProcess()`
-- Deprecated `ApplicationConfigurer.RegisterIntegration()`
-- Deprecated `ApplicationConfigurer.RegisterProjection()`
+- Deprecated `Route`, use `MessageRoute` instead.
+- Deprecated `ApplicationConfigurer.RegisterAggregate()`.
+- Deprecated `ApplicationConfigurer.RegisterProcess()`.
+- Deprecated `ApplicationConfigurer.RegisterIntegration()`.
+- Deprecated `ApplicationConfigurer.RegisterProjection()`.
+- Deprecated `RegisterAggregateOption`.
+- Deprecated `RegisterProcessOption`.
+- Deprecated `RegisterIntegrationOption`.
+- Deprecated `RegisterProjectionOption`.
 
 ## [0.15.0] - 2024-10-03
 

application.go

@@ -23,109 +23,60 @@ type ApplicationConfigurer interface {
 	// Use of hard-coded literals for both values is RECOMMENDED.
 	Identity(n string, k string)
 
-	// Handlers configures the application to route messages to and from
-	// specific message handlers.
-	Handlers(...HandlerRegistration)
+	// Routes configures the application to route messages via specific message
+	// handlers.
+	Routes(...HandlerRoute)
 
 	// RegisterAggregate configures the engine to route messages for an
 	// aggregate.
 	//
-	// Deprecated: Pass the result of [RegisterAggregate] to the Handlers()
-	// method instead.
+	// Deprecated: Pass the result of [ViaAggregate] to the Routes() method
+	// instead.
 	RegisterAggregate(AggregateMessageHandler, ...RegisterAggregateOption)
 
 	// RegisterProcess configures the engine to route messages for a process.
 	//
-	// Deprecated: Pass the result of [RegisterProcess] to the Handlers()
-	// method instead.
+	// Deprecated: Pass the result of [ViaProcess] to the Routes() method
+	// instead.
 	RegisterProcess(ProcessMessageHandler, ...RegisterProcessOption)
 
 	// RegisterIntegration configures the engine to route messages for an
 	// integration.
 	//
-	// Deprecated: Pass the result of [RegisterIntegration] to the Handlers()
-	// method instead.
+	// Deprecated: Pass the result of [ViaIntegration] to the Routes() method
+	// instead.
 	RegisterIntegration(IntegrationMessageHandler, ...RegisterIntegrationOption)
 
 	// RegisterProjection configures the engine to route messages for a
 	// projection.
 	//
-	// Deprecated: Pass the result of [RegisterProjection] to the Handlers()
-	// method instead.
+	// Deprecated: Pass the result of [ViaProjection] to the Routes() method
+	// instead.
 	RegisterProjection(ProjectionMessageHandler, ...RegisterProjectionOption)
 }
 
-// RegisterAggregate registers an [AggregateMessageHandler] with an
-// [Application].
-//
-// It is used as an argument to the Handlers() method of
-// [ApplicationConfigurer].
-func RegisterAggregate(h AggregateMessageHandler, _ ...RegisterAggregateOption) AggregateRegistration {
-	return AggregateRegistration{h}
-}
-
-// RegisterProcess registers a [ProcessMessageHandler] with an [Application].
-//
-// It is used as an argument to the Handlers() method of
-// [ApplicationConfigurer].
-func RegisterProcess(h ProcessMessageHandler, _ ...RegisterProcessOption) ProcessRegistration {
-	return ProcessRegistration{h}
-}
-
-// RegisterIntegration registers an [IntegrationMessageHandler] with an
-// [Application].
-//
-// It is used as an argument to the Handlers() method of
-// [ApplicationConfigurer].
-func RegisterIntegration(h IntegrationMessageHandler, _ ...RegisterIntegrationOption) IntegrationRegistration {
-	return IntegrationRegistration{h}
-}
-
-// RegisterProjection registers a [ProjectionMessageHandler] with an
-// [Application].
-//
-// It is used as an argument to the Handlers() method of
-// [ApplicationConfigurer].
-func RegisterProjection(h ProjectionMessageHandler, _ ...RegisterProjectionOption) ProjectionRegistration {
-	return ProjectionRegistration{h}
-}
-
-type (
-	// HandlerRegistration is an interface implemented by all handler
-	// registration types.
-	HandlerRegistration interface{ isHandlerRegistration() }
-
-	// AggregateRegistration describes an [AggregateMessageHandler] that is to be
-	// registered with an [Application].
-	AggregateRegistration struct{ Handler AggregateMessageHandler }
-
-	// ProcessRegistration describes a [ProcessMessageHandler] that is to be
-	// registered with an [Application].
-	ProcessRegistration struct{ Handler ProcessMessageHandler }
-
-	// IntegrationRegistration describes an [IntegrationMessageHandler] that is
-	// to be registered with an [Application].
-	IntegrationRegistration struct{ Handler IntegrationMessageHandler }
-
-	// ProjectionRegistration describes a [ProjectionMessageHandler] that is to
-	// be registered with an [Application].
-	ProjectionRegistration struct{ Handler ProjectionMessageHandler }
-)
-
 type (
 	// RegisterAggregateOption is an option that affects the behavior of a call to
 	// the RegisterAggregate() method of the [ApplicationConfigurer] interface.
+	//
+	// Deprecated: Use [ViaAggregateOption] instead.
 	RegisterAggregateOption struct{}
 
 	// RegisterProcessOption is an option that affects the behavior of a call to
 	// the RegisterProcess() method of the [ApplicationConfigurer] interface.
+	//
+	// Deprecated: Use [ViaProcessOption] instead.
 	RegisterProcessOption struct{}
 
 	// RegisterIntegrationOption is an option that affects the behavior of a call to
 	// the RegisterIntegration() method of the [ApplicationConfigurer] interface.
+	//
+	// Deprecated: Use [ViaIntegrationOption] instead.
 	RegisterIntegrationOption struct{}
 
 	// RegisterProjectionOption is an option that affects the behavior of a call to
 	// the RegisterProjection() method of the [ApplicationConfigurer] interface.
+	//
+	// Deprecated: Use [ViaProjectionOption] instead.
 	RegisterProjectionOption struct{}
 )

handlerroute.go

@@ -0,0 +1,99 @@
+package dogma
+
+// ViaAggregate configures an [Application] to route messages to and from the
+// specified [AggregateMessageHandler]. It is used as an argument to the
+// Routes() method of [ApplicationConfigurer].
+//
+// [Command] messages executed using a [CommandExecutor], [ProcessEventScope] or
+// [ProcessTimeoutScope] are routed to h if it has a [HandlesCommandRoute] for
+// that command type.
+//
+// [Event] messages recorded by h using an [AggregateCommandScope] are routed to
+// other handlers according to their route configurations.
+func ViaAggregate(h AggregateMessageHandler, _ ...ViaAggregateOption) ViaAggregateRoute {
+	return ViaAggregateRoute{h}
+}
+
+// ViaProcess configures an [Application] to route messages to and from the
+// specified [ProcessMessageHandler]. It is used as an argument to the Routes()
+// method of [ApplicationConfigurer].
+//
+// [Event] messages recorded using an [AggregateCommandScope] or
+// [IntegrationCommandScope] are routed to h if it has a [HandlesEvent] route
+// for that event type.
+//
+// [Command] messages executed by h using a [ProcessEventScope] or
+// [ProcessTimeoutScope] are routed to other handlers according to their route
+// configurations.
+//
+// [Timeout] messages are always routed back to h itself.
+func ViaProcess(h ProcessMessageHandler, _ ...ViaProcessOption) ViaProcessRoute {
+	return ViaProcessRoute{h}
+}
+
+// ViaIntegration configures an [Application] to route messages to and from the
+// specified [IntegrationMessageHandler]. It is used as an argument to the
+// Routes() method of [ApplicationConfigurer].
+//
+// [Command] messages executed using a [CommandExecutor], [ProcessEventScope] or
+// [ProcessTimeoutScope] are routed to h if it has a [HandlesCommandRoute] for
+// that command type.
+//
+// [Event] messages recorded by h using an [IntegrationCommandScope] are routed
+// to other handlers according to their route configurations.
+func ViaIntegration(h IntegrationMessageHandler, _ ...ViaIntegrationOption) ViaIntegrationRoute {
+	return ViaIntegrationRoute{h}
+}
+
+// ViaProjection configures an [Application] to route messages to the specified
+// [ProjectionMessageHandler]. It is used as an argument to the Routes() method
+// of [ApplicationConfigurer].
+//
+// [Event] messages recorded using an [AggregateCommandScope] or
+// [IntegrationCommandScope] are routed to h if it has a [HandlesEvent] route
+// for that event type.
+func ViaProjection(h ProjectionMessageHandler, _ ...ViaProjectionOption) ViaProjectionRoute {
+	return ViaProjectionRoute{h}
+}
+
+type (
+	// HandlerRoute is an interface for all types that describe a relationship
+	// between an [Application] and the a handler.
+	HandlerRoute interface {
+		isHandlerRoute()
+	}
+
+	// ViaAggregateRoute describes an [AggregateMessageHandler] that is to be
+	// registered with an [Application].
+	ViaAggregateRoute struct{ Handler AggregateMessageHandler }
+
+	// ViaProcessRoute describes a [ProcessMessageHandler] that is to be
+	// registered with an [Application].
+	ViaProcessRoute struct{ Handler ProcessMessageHandler }
+
+	// ViaIntegrationRoute describes an [IntegrationMessageHandler] that is
+	// to be registered with an [Application].
+	ViaIntegrationRoute struct{ Handler IntegrationMessageHandler }
+
+	// ViaProjectionRoute describes a [ProjectionMessageHandler] that is to be
+	// registered with an [Application].
+	ViaProjectionRoute struct{ Handler ProjectionMessageHandler }
+)
+
+type (
+	// ViaAggregateOption is an option that affects the behavior of a call to
+	// the RegisterAggregate() method of the [ApplicationConfigurer] interface.
+	ViaAggregateOption struct{}
+
+	// ViaProcessOption is an option that affects the behavior of a call to
+	// the RegisterProcess() method of the [ApplicationConfigurer] interface.
+	ViaProcessOption struct{}
+
+	// ViaIntegrationOption is an option that affects the behavior of a call to
+	// the RegisterIntegration() method of the [ApplicationConfigurer] interface.
+	ViaIntegrationOption struct{}
+
+	// ViaProjectionOption is an option that affects the behavior of a call to
+	// the RegisterProjection() method of the [ApplicationConfigurer] interface.
+	ViaProjectionOption struct{}
+)

handlerroute_nocoverage.go

@@ -0,0 +1,6 @@
+package dogma
+
+func (ViaAggregateRoute) isHandlerRoute()   {}
+func (ViaProcessRoute) isHandlerRoute()     {}
+func (ViaIntegrationRoute) isHandlerRoute() {}
+func (ViaProjectionRoute) isHandlerRoute()  {}

application_test.go → handlerroute_test.go

@@ -6,44 +6,44 @@ import (
 	. "github.com/dogmatiq/dogma"
 )
 
-func TestRegisterAggregate(t *testing.T) {
+func TestViaAggregate(t *testing.T) {
 	type aggregate struct{ AggregateMessageHandler }
 
 	h := &aggregate{}
-	r := RegisterAggregate(h)
+	r := ViaAggregate(h)
 
 	if r.Handler != h {
 		t.Fatal("unexpected handler")
 	}
 }
 
-func TestRegisterProcess(t *testing.T) {
+func TestViaProcess(t *testing.T) {
 	type process struct{ ProcessMessageHandler }
 
 	h := &process{}
-	r := RegisterProcess(h)
+	r := ViaProcess(h)
 
 	if r.Handler != h {
 		t.Fatal("unexpected handler")
 	}
 }
 
-func TestRegisterIntegration(t *testing.T) {
+func TestViaIntegration(t *testing.T) {
 	type integration struct{ IntegrationMessageHandler }
 
 	h := &integration{}
-	r := RegisterIntegration(h)
+	r := ViaIntegration(h)
 
 	if r.Handler != h {
 		t.Fatal("unexpected handler")
 	}
 }
 
-func TestRegisterProjection(t *testing.T) {
+func TestViaProjection(t *testing.T) {
 	type projection struct{ ProjectionMessageHandler }
 
 	h := &projection{}
-	r := RegisterProjection(h)
+	r := ViaProjection(h)
 
 	if r.Handler != h {
 		t.Fatal("unexpected handler")