docs: demonstrate how to define hooks using depinject

CHANGELOG.md

@@ -52,6 +52,7 @@ Every module contains its own CHANGELOG.md. Please refer to the module you are i
 ### Improvements
 
 * (sims) [#21613](https://github.com/cosmos/cosmos-sdk/pull/21613) Add sims2 framework and factory methods for simpler message factories in modules
+* (testutil/counter)[#21892](https://github.com/cosmos/cosmos-sdk/pull/21892) Add support for hooks injection with depinject.
 
 ### Bug Fixes
 

testutil/x/counter/README.md

@@ -5,3 +5,64 @@ sidebar_position: 1
 # `x/counter`
 
 Counter is a module used for testing purposes within the Cosmos SDK.
+
+## Hooks
+
+The module supports hook injection using `depinject`. Follow these steps to implement hooks:
+
+1. Define the hook interface and a wrapper implementing `depinject.OnePerModuleType`:
+```go
+type CounterHooks interface {
+	AfterIncreaseCount(ctx context.Context, newCount int64) error
+}
+
+type CounterHooksWrapper struct{ CounterHooks }
+
+// IsOnePerModuleType implements the depinject.OnePerModuleType interface.
+func (CounterHooksWrapper) IsOnePerModuleType() {}
+
+```
+2. Add a `CounterHooks` field to the keeper:
+```go
+type Keeper struct{
+	//...
+	hooks CounterHooks
+}
+
+func (k *Keeper) SetHooks(hooks ...CounterHooks){
+	k.hooks = hooks
+}
+```
+3. Create a `depinject` invoker function
+```go
+func InvokeSetHooks(keeper *keeper.Keeper, counterHooks map[string]types.CounterHooksWrapper) error {
+	//...
+    keeper.SetHooks(multiHooks)
+    return nil
+}
+
+```
+4. Inject the hooks during app initialization:
+```go
+appConfig = appconfig.Compose(&appv1alpha1.Config{
+    Modules: []*appv1alpha1.ModuleConfig{
+        // ....
+        {
+            Name:   types.ModuleName,
+            Config: appconfig.WrapAny(&types.Module{}),
+        },
+    }
+})
+appConfig = depinject.Configs(
+    AppConfig(),
+    runtime.DefaultServiceBindings(),
+    depinject.Supply(
+        logger,
+        viper,
+        map[string]types.CounterHooksWrapper{
+            "counter": types.CounterHooksWrapper{&types.Hooks{}},
+        },
+))
+
+```
+By following these steps, you can successfully integrate hooks into the `x/counter` module using `depinject`.

testutil/x/counter/depinject.go

@@ -1,6 +1,10 @@
 package counter
 
 import (
+	"fmt"
+	"maps"
+	"slices"
+
 	"cosmossdk.io/core/appmodule"
 	"cosmossdk.io/depinject"
 	"cosmossdk.io/depinject/appconfig"
@@ -17,6 +21,7 @@ func (am AppModule) IsOnePerModuleType() {}
 func init() {
 	appconfig.RegisterModule(
 		&types.Module{},
+		appconfig.Invoke(InvokeSetHooks),
 		appconfig.Provide(ProvideModule),
 	)
 }
@@ -31,7 +36,7 @@ type ModuleInputs struct {
 type ModuleOutputs struct {
 	depinject.Out
 
-	Keeper keeper.Keeper
+	Keeper *keeper.Keeper
 	Module appmodule.AppModule
 }
 
@@ -44,3 +49,24 @@ func ProvideModule(in ModuleInputs) ModuleOutputs {
 		Module: m,
 	}
 }
+
+func InvokeSetHooks(keeper *keeper.Keeper, counterHooks map[string]types.CounterHooksWrapper) error {
+	if keeper == nil || counterHooks == nil {
+		return nil
+	}
+
+	// Default ordering is lexical by module name.
+	// Explicit ordering can be added to the module config if required.
+	modNames := slices.Sorted(maps.Keys(counterHooks))
+	var multiHooks types.MultiCounterHooks
+	for _, modName := range modNames {
+		hook, ok := counterHooks[modName]
+		if !ok {
+			return fmt.Errorf("can't find hooks for module %s", modName)
+		}
+		multiHooks = append(multiHooks, hook)
+	}
+
+	keeper.SetHooks(multiHooks)
+	return nil
+}

testutil/x/counter/keeper/hooks.go

@@ -0,0 +1,14 @@
+package keeper
+
+import (
+	"context"
+)
+
+type Hooks struct {
+	AfterCounterIncreased bool
+}
+
+func (h *Hooks) AfterIncreaseCount(ctx context.Context, n int64) error {
+	h.AfterCounterIncreased = true
+	return nil
+}

testutil/x/counter/keeper/keeper.go

@@ -21,11 +21,13 @@ type Keeper struct {
 	appmodule.Environment
 
 	CountStore collections.Item[int64]
+
+	hooks types.CounterHooks
 }
 
-func NewKeeper(env appmodule.Environment) Keeper {
+func NewKeeper(env appmodule.Environment) *Keeper {
 	sb := collections.NewSchemaBuilder(env.KVStoreService)
-	return Keeper{
+	return &Keeper{
 		Environment: env,
 		CountStore:  collections.NewItem(sb, collections.NewPrefix(0), "count", collections.Int64Value),
 	}
@@ -67,6 +69,10 @@ func (k Keeper) IncreaseCount(ctx context.Context, msg *types.MsgIncreaseCounter
 		return nil, err
 	}
 
+	if err := k.Hooks().AfterIncreaseCount(ctx, num+msg.Count); err != nil {
+		return nil, err
+	}
+
 	if err := k.EventService.EventManager(ctx).EmitKV(
 		"increase_counter",
 		event.NewAttribute("signer", msg.Signer),
@@ -78,3 +84,23 @@ func (k Keeper) IncreaseCount(ctx context.Context, msg *types.MsgIncreaseCounter
 		NewCount: num + msg.Count,
 	}, nil
 }
+
+// Hooks gets the hooks for counter Keeper
+func (k *Keeper) Hooks() types.CounterHooks {
+	if k.hooks == nil {
+		// return a no-op implementation if no hooks are set
+		return types.MultiCounterHooks{}
+	}
+
+	return k.hooks
+}
+
+// SetHooks sets the hooks for counter
+func (k *Keeper) SetHooks(gh types.CounterHooks) *Keeper {
+	if k.hooks != nil {
+		panic("cannot set governance hooks twice")
+	}
+
+	k.hooks = gh
+	return k
+}

testutil/x/counter/module.go

@@ -17,7 +17,7 @@ var (
 
 // AppModule implements an application module
 type AppModule struct {
-	keeper keeper.Keeper
+	keeper *keeper.Keeper
 }
 
 // IsAppModule implements the appmodule.AppModule interface.
@@ -31,7 +31,7 @@ func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error {
 }
 
 // NewAppModule creates a new AppModule object
-func NewAppModule(keeper keeper.Keeper) AppModule {
+func NewAppModule(keeper *keeper.Keeper) AppModule {
 	return AppModule{
 		keeper: keeper,
 	}

testutil/x/counter/types/expected_keepers.go

@@ -0,0 +1,12 @@
+package types
+
+import "context"
+
+type CounterHooks interface {
+	AfterIncreaseCount(ctx context.Context, newCount int64) error
+}
+
+type CounterHooksWrapper struct{ CounterHooks }
+
+// IsOnePerModuleType implements the depinject.OnePerModuleType interface.
+func (CounterHooksWrapper) IsOnePerModuleType() {}

testutil/x/counter/types/hooks.go

@@ -0,0 +1,26 @@
+package types
+
+import (
+	"context"
+	"errors"
+)
+
+var _ CounterHooks = MultiCounterHooks{}
+
+// MultiCounterHooks is a slice of hooks to be called in sequence.
+type MultiCounterHooks []CounterHooks
+
+// NewMultiCounterHooks returns a MultiCounterHooks from a list of CounterHooks
+func NewMultiCounterHooks(hooks ...CounterHooks) MultiCounterHooks {
+	return hooks
+}
+
+// AfterIncreaseCount calls AfterIncreaseCount on all hooks and collects the errors if any.
+func (ch MultiCounterHooks) AfterIncreaseCount(ctx context.Context, newCount int64) error {
+	var errs error
+	for i := range ch {
+		errs = errors.Join(errs, ch[i].AfterIncreaseCount(ctx, newCount))
+	}
+
+	return errs
+}