Make Plugin a marker interface

Make hooks and middleware opt into `Plugin` through their default embedders
and function helpers. Keep `Config.Plugins` as the unified registration path.

Author: brandur

client.go

@@ -25,7 +25,6 @@ import (
 	"github.com/riverqueue/river/internal/middlewarelookup"
 	"github.com/riverqueue/river/internal/notifier"
 	"github.com/riverqueue/river/internal/notifylimiter"
-	"github.com/riverqueue/river/internal/pluginconfig"
 	"github.com/riverqueue/river/internal/rivercommon"
 	"github.com/riverqueue/river/internal/rivermiddleware"
 	"github.com/riverqueue/river/internal/workunit"
@@ -245,6 +244,8 @@ type Config struct {
 	//
 	// If a type in Hooks also implements rivertype.Middleware, it will be
 	// installed as middleware too.
+	//
+	// Deprecated: Use Plugins instead.
 	Hooks []rivertype.Hook
 
 	// Logger is the structured logger to use for logging purposes. If none is
@@ -281,20 +282,22 @@ type Config struct {
 	//
 	// If a type in Middleware also implements rivertype.Hook, it will be
 	// installed as a hook too.
+	//
+	// Deprecated: Use Plugins instead.
 	Middleware []rivertype.Middleware
 
-	// Plugins contains extensions installed globally as both hooks and
-	// middleware.
+	// Plugins contains extensions installed globally as hooks, middleware, or
+	// both.
 	//
-	// A plugin must implement both rivertype.Hook and rivertype.Middleware. It
-	// may embed PluginDefaults, or embed both HookDefaults and
-	// MiddlewareDefaults directly, then implement any operation-specific hook or
-	// middleware interfaces it needs.
+	// A type qualifies as a plugin by implementing [rivertype.Plugin]. Most
+	// existing hook and middleware implementations already do this by embedding
+	// HookDefaults or MiddlewareDefaults. If a type participates on both sides,
+	// it may embed PluginDefaults, or embed both HookDefaults and
+	// MiddlewareDefaults directly and define its own IsPlugin method, then
+	// implement any operation-specific hook or middleware interfaces it needs.
 	//
-	// Hooks and Middleware are still supported. If a type in Hooks also
-	// implements middleware, or a type in Middleware also implements hooks, River
-	// will install it on both sides automatically. The Plugins list exists as a
-	// generic place for new extensions to be registered.
+	// Hooks and Middleware are still supported for backward compatibility, but
+	// Plugins is the preferred place to register new extensions.
 	Plugins []rivertype.Plugin
 
 	// PeriodicJobs are a set of periodic jobs to run at the specified intervals
@@ -542,6 +545,83 @@ func (c *Config) WithDefaults() *Config {
 	}
 }
 
+func effectiveHooksForConfig(config *Config) []rivertype.Hook {
+	configuredMiddleware := middlewareFromConfig(config)
+	hooks := make([]rivertype.Hook, 0, len(config.Hooks)+len(configuredMiddleware)+len(config.Plugins))
+	hooks = append(hooks, config.Hooks...)
+
+	for _, middleware := range configuredMiddleware {
+		if hook, ok := middleware.(rivertype.Hook); ok {
+			hooks = append(hooks, hook)
+		}
+	}
+
+	for _, plugin := range config.Plugins {
+		if plugin == nil {
+			continue
+		}
+
+		if hook, ok := plugin.(rivertype.Hook); ok {
+			hooks = append(hooks, hook)
+		}
+	}
+
+	return hooks
+}
+
+func effectiveMiddlewareForConfig(config *Config) []rivertype.Middleware {
+	configuredMiddleware := middlewareFromConfig(config)
+	middleware := make([]rivertype.Middleware, 0, len(config.Hooks)+len(configuredMiddleware)+len(config.Plugins))
+	middleware = append(middleware, configuredMiddleware...)
+
+	for _, hook := range config.Hooks {
+		if middlewareItem, ok := hook.(rivertype.Middleware); ok {
+			middleware = append(middleware, middlewareItem)
+		}
+	}
+
+	for _, plugin := range config.Plugins {
+		if plugin == nil {
+			continue
+		}
+
+		if middlewareItem, ok := plugin.(rivertype.Middleware); ok {
+			middleware = append(middleware, middlewareItem)
+		}
+	}
+
+	return middleware
+}
+
+func middlewareFromConfig(config *Config) []rivertype.Middleware {
+	middleware := make([]rivertype.Middleware, 0,
+		len(config.Middleware)+len(config.JobInsertMiddleware)+len(config.WorkerMiddleware))
+	middleware = append(middleware, config.Middleware...)
+
+	for _, jobInsertMiddleware := range config.JobInsertMiddleware {
+		middleware = append(middleware, jobInsertMiddleware)
+	}
+
+outerLoop:
+	for _, workerMiddleware := range config.WorkerMiddleware {
+		// Don't add the middleware if it also implements JobInsertMiddleware
+		// and the instance has been added to config.JobInsertMiddleware. This
+		// is a hedge to make sure we don't accidentally double add middleware
+		// as we've converted over to the unified config.Middleware setting.
+		if workerMiddlewareAsJobInsertMiddleware, ok := workerMiddleware.(rivertype.JobInsertMiddleware); ok {
+			for _, jobInsertMiddleware := range config.JobInsertMiddleware {
+				if workerMiddlewareAsJobInsertMiddleware == jobInsertMiddleware {
+					continue outerLoop
+				}
+			}
+		}
+
+		middleware = append(middleware, workerMiddleware)
+	}
+
+	return middleware
+}
+
 func (c *Config) validate() error {
 	if c.CancelledJobRetentionPeriod < -1 {
 		return errors.New("CancelledJobRetentionPeriod time cannot be less than zero, except for -1 (infinite)")
@@ -824,9 +904,8 @@ func NewClient[TTx any](driver riverdriver.Driver[TTx], config *Config) (*Client
 		}
 	}
 
-	configuredMiddleware := middlewareFromConfig(config)
-	effectiveHooks := pluginconfig.Hooks(config.Hooks, configuredMiddleware, config.Plugins)
-	effectiveMiddleware := pluginconfig.Middleware(config.Hooks, configuredMiddleware, config.Plugins)
+	effectiveHooks := effectiveHooksForConfig(config)
+	effectiveMiddleware := effectiveMiddlewareForConfig(config)
 
 	for _, hook := range effectiveHooks {
 		if withBaseService, ok := hook.(baseservice.WithBaseService); ok {
@@ -1075,35 +1154,6 @@ func NewClient[TTx any](driver riverdriver.Driver[TTx], config *Config) (*Client
 	return client, nil
 }
 
-func middlewareFromConfig(config *Config) []rivertype.Middleware {
-	middleware := make([]rivertype.Middleware, 0,
-		len(config.Middleware)+len(config.JobInsertMiddleware)+len(config.WorkerMiddleware))
-	middleware = append(middleware, config.Middleware...)
-
-	for _, jobInsertMiddleware := range config.JobInsertMiddleware {
-		middleware = append(middleware, jobInsertMiddleware)
-	}
-
-outerLoop:
-	for _, workerMiddleware := range config.WorkerMiddleware {
-		// Don't add the middleware if it also implements JobInsertMiddleware
-		// and the instance has been added to config.JobInsertMiddleware. This
-		// is a hedge to make sure we don't accidentally double add middleware
-		// as we've converted over to the unified config.Middleware setting.
-		if workerMiddlewareAsJobInsertMiddleware, ok := workerMiddleware.(rivertype.JobInsertMiddleware); ok {
-			for _, jobInsertMiddleware := range config.JobInsertMiddleware {
-				if workerMiddlewareAsJobInsertMiddleware == jobInsertMiddleware {
-					continue outerLoop
-				}
-			}
-		}
-
-		middleware = append(middleware, workerMiddleware)
-	}
-
-	return middleware
-}
-
 // Start starts the client's job fetching and working loops. Once this is called,
 // the client will run in a background goroutine until stopped. All jobs are
 // run with a context inheriting from the provided context, but with a timeout

client_test.go

@@ -81,6 +81,7 @@ var (
 
 	_ rivertype.HookInsertBegin     = hookMiddlewareValuePlugin{}
 	_ rivertype.JobInsertMiddleware = hookMiddlewareValuePlugin{}
+	_ rivertype.Plugin              = hookMiddlewareValuePlugin{}
 )
 
 type hookMiddlewareEmbeddedDefaultsPlugin struct {
@@ -91,6 +92,8 @@ type hookMiddlewareEmbeddedDefaultsPlugin struct {
 	insertManyCount  int
 }
 
+func (p *hookMiddlewareEmbeddedDefaultsPlugin) IsPlugin() bool { return true }
+
 func (p *hookMiddlewareEmbeddedDefaultsPlugin) InsertBegin(ctx context.Context, params *rivertype.JobInsertParams) error {
 	p.insertBeginCount++
 	return nil
@@ -134,6 +137,8 @@ func (p hookMiddlewareValuePlugin) InsertMany(ctx context.Context, manyParams []
 
 func (p hookMiddlewareValuePlugin) IsHook() bool { return true }
 
+func (p hookMiddlewareValuePlugin) IsPlugin() bool { return true }
+
 func (p hookMiddlewareValuePlugin) IsMiddleware() bool { return true }
 
 type hookMiddlewareValuePluginCounts struct {

example_global_hooks_test.go

@@ -65,7 +65,7 @@ func Example_globalHooks() { //nolint:dupl
 
 	riverClient, err := river.NewClient(riverpgxv5.New(dbPool), initTestConfig(ctx, dbPool, &river.Config{
 		// Order is significant. See output below.
-		Hooks: []rivertype.Hook{
+		Plugins: []rivertype.Plugin{
 			&BothInsertAndWorkBeginHook{},
 			&InsertBeginHook{},
 			&WorkBeginHook{},

example_global_middleware_test.go

@@ -65,7 +65,7 @@ func Example_globalMiddleware() { //nolint:dupl
 
 	riverClient, err := river.NewClient(riverpgxv5.New(dbPool), initTestConfig(ctx, dbPool, &river.Config{
 		// Order is significant. See output below.
-		Middleware: []rivertype.Middleware{
+		Plugins: []rivertype.Plugin{
 			&JobBothInsertAndWorkMiddleware{},
 			&JobInsertMiddleware{},
 			&WorkerMiddleware{},

hook_defaults_funcs.go

@@ -7,12 +7,14 @@ import (
 )
 
 // HookDefaults should be embedded on any hooks implementation. It helps
-// identify a struct as hooks, and guarantee forward compatibility in case
-// additions are necessary to the rivertype.Hook interface.
+// identify a struct as hooks and a plugin, and guarantee forward compatibility
+// in case additions are necessary to the rivertype.Hook interface.
 type HookDefaults struct{}
 
 func (d *HookDefaults) IsHook() bool { return true }
 
+func (d *HookDefaults) IsPlugin() bool { return true }
+
 // HookInsertBeginFunc is a convenience helper for implementing
 // rivertype.HookInsertBegin using a simple function instead of a struct.
 type HookInsertBeginFunc func(ctx context.Context, params *rivertype.JobInsertParams) error
@@ -23,12 +25,16 @@ func (f HookInsertBeginFunc) InsertBegin(ctx context.Context, params *rivertype.
 
 func (f HookInsertBeginFunc) IsHook() bool { return true }
 
+func (f HookInsertBeginFunc) IsPlugin() bool { return true }
+
 // HookPeriodicJobsStartFunc is a convenience helper for implementing
 // rivertype.HookPeriodicJobsStart using a simple function instead of a struct.
 type HookPeriodicJobsStartFunc func(ctx context.Context, params *rivertype.HookPeriodicJobsStartParams) error
 
 func (f HookPeriodicJobsStartFunc) IsHook() bool { return true }
 
+func (f HookPeriodicJobsStartFunc) IsPlugin() bool { return true }
+
 func (f HookPeriodicJobsStartFunc) Start(ctx context.Context, params *rivertype.HookPeriodicJobsStartParams) error {
 	return f(ctx, params)
 }
@@ -37,18 +43,22 @@ func (f HookPeriodicJobsStartFunc) Start(ctx context.Context, params *rivertype.
 // rivertype.HookWorkBegin using a simple function instead of a struct.
 type HookWorkBeginFunc func(ctx context.Context, job *rivertype.JobRow) error
 
+func (f HookWorkBeginFunc) IsHook() bool { return true }
+
+func (f HookWorkBeginFunc) IsPlugin() bool { return true }
+
 func (f HookWorkBeginFunc) WorkBegin(ctx context.Context, job *rivertype.JobRow) error {
 	return f(ctx, job)
 }
 
-func (f HookWorkBeginFunc) IsHook() bool { return true }
-
 // HookWorkEndFunc is a convenience helper for implementing
 // rivertype.HookWorkEnd using a simple function instead of a struct.
 type HookWorkEndFunc func(ctx context.Context, job *rivertype.JobRow, err error) error
 
+func (f HookWorkEndFunc) IsHook() bool { return true }
+
+func (f HookWorkEndFunc) IsPlugin() bool { return true }
+
 func (f HookWorkEndFunc) WorkEnd(ctx context.Context, job *rivertype.JobRow, err error) error {
 	return f(ctx, job, err)
 }
-
-func (f HookWorkEndFunc) IsHook() bool { return true }

internal/pluginconfig/plugin_config.go

@@ -2,11 +2,11 @@ package pluginconfig
 
 import "github.com/riverqueue/river/rivertype"
 
-// Hooks returns the effective hook list from configured hooks, middleware, and
-// plugins. Explicit hooks are preserved first, followed by middleware that also
-// implement hooks, then plugins.
-func Hooks(hooks []rivertype.Hook, middleware []rivertype.Middleware, plugins []rivertype.Plugin) []rivertype.Hook {
-	effectiveHooks := make([]rivertype.Hook, 0, len(hooks)+len(middleware)+len(plugins))
+// Hooks returns the effective hook list from configured hooks and middleware.
+// Explicit hooks are preserved first, followed by middleware that also
+// implement hooks.
+func Hooks(hooks []rivertype.Hook, middleware []rivertype.Middleware) []rivertype.Hook {
+	effectiveHooks := make([]rivertype.Hook, 0, len(hooks)+len(middleware))
 
 	effectiveHooks = append(effectiveHooks, hooks...)
 
@@ -19,18 +19,14 @@ func Hooks(hooks []rivertype.Hook, middleware []rivertype.Middleware, plugins []
 		effectiveHooks = append(effectiveHooks, hook)
 	}
 
-	for _, plugin := range plugins {
-		effectiveHooks = append(effectiveHooks, plugin)
-	}
-
 	return effectiveHooks
 }
 
-// Middleware returns the effective middleware list from configured hooks,
-// middleware, and plugins. Explicit middleware are preserved first, followed by
-// hooks that also implement middleware, then plugins.
-func Middleware(hooks []rivertype.Hook, middleware []rivertype.Middleware, plugins []rivertype.Plugin) []rivertype.Middleware {
-	effectiveMiddleware := make([]rivertype.Middleware, 0, len(hooks)+len(middleware)+len(plugins))
+// Middleware returns the effective middleware list from configured hooks and
+// middleware. Explicit middleware are preserved first, followed by hooks that
+// also implement middleware.
+func Middleware(hooks []rivertype.Hook, middleware []rivertype.Middleware) []rivertype.Middleware {
+	effectiveMiddleware := make([]rivertype.Middleware, 0, len(hooks)+len(middleware))
 
 	effectiveMiddleware = append(effectiveMiddleware, middleware...)
 
@@ -43,9 +39,5 @@ func Middleware(hooks []rivertype.Hook, middleware []rivertype.Middleware, plugi
 		effectiveMiddleware = append(effectiveMiddleware, middlewareItem)
 	}
 
-	for _, plugin := range plugins {
-		effectiveMiddleware = append(effectiveMiddleware, plugin)
-	}
-
 	return effectiveMiddleware
 }

middleware_defaults.go

@@ -7,12 +7,15 @@ import (
 )
 
 // MiddlewareDefaults should be embedded on any middleware implementation. It
-// helps identify a struct as middleware, and guarantees forward compatibility in
-// case additions are necessary to the rivertype.Middleware interface.
+// helps identify a struct as middleware and a plugin, and guarantees forward
+// compatibility in case additions are necessary to the rivertype.Middleware
+// interface.
 type MiddlewareDefaults struct{}
 
 func (d *MiddlewareDefaults) IsMiddleware() bool { return true }
 
+func (d *MiddlewareDefaults) IsPlugin() bool { return true }
+
 // JobInsertMiddlewareDefaults is an embeddable struct that provides default
 // implementations for the rivertype.JobInsertMiddleware. Use of this struct is
 // recommended in case rivertype.JobInsertMiddleware is expanded in the future
@@ -35,6 +38,8 @@ func (f JobInsertMiddlewareFunc) InsertMany(ctx context.Context, manyParams []*r
 
 func (f JobInsertMiddlewareFunc) IsMiddleware() bool { return true }
 
+func (f JobInsertMiddlewareFunc) IsPlugin() bool { return true }
+
 // WorkerInsertMiddlewareDefaults is an embeddable struct that provides default
 // implementations for the rivertype.WorkerMiddleware. Use of this struct is
 // recommended in case rivertype.WorkerMiddleware is expanded in the future so
@@ -51,8 +56,10 @@ func (d *WorkerMiddlewareDefaults) Work(ctx context.Context, job *rivertype.JobR
 // rivertype.WorkerMiddleware using a simple function instead of a struct.
 type WorkerMiddlewareFunc func(ctx context.Context, job *rivertype.JobRow, doInner func(ctx context.Context) error) error
 
+func (f WorkerMiddlewareFunc) IsMiddleware() bool { return true }
+
+func (f WorkerMiddlewareFunc) IsPlugin() bool { return true }
+
 func (f WorkerMiddlewareFunc) Work(ctx context.Context, job *rivertype.JobRow, doInner func(ctx context.Context) error) error {
 	return f(ctx, job, doInner)
 }
-
-func (f WorkerMiddlewareFunc) IsMiddleware() bool { return true }

plugin_defaults.go

@@ -1,10 +1,12 @@
 package river
 
 // PluginDefaults should be embedded on plugin implementations. It helps
-// identify a struct as both hooks and middleware, and guarantees forward
+// identify a struct as both hook and middleware, and guarantees forward
 // compatibility in case additions are necessary to the rivertype.Hook or
 // rivertype.Middleware interfaces.
 type PluginDefaults struct {
 	HookDefaults
 	MiddlewareDefaults
 }
+
+func (d *PluginDefaults) IsPlugin() bool { return true }

plugin_defaults_test.go

@@ -6,4 +6,6 @@ var (
 	_ rivertype.Hook       = &PluginDefaults{}
 	_ rivertype.Middleware = &PluginDefaults{}
 	_ rivertype.Plugin     = &PluginDefaults{}
+	_ rivertype.Plugin     = &HookDefaults{}
+	_ rivertype.Plugin     = &MiddlewareDefaults{}
 )