router: expose BrokerFactory / DealerFactory hooks on RealmConfig

Final step of the Broker/Dealer interface extraction. Adds two new
factory-function fields on RealmConfig:

  type BrokerFactory func(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Broker, error)
  type DealerFactory func(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Dealer, error)

When unset (default), the router builds the in-process actor-loop
broker/dealer via defaultBrokerFactory / defaultDealerFactory — same
behavior as before. When set, downstream consumers can supply their
own implementations: a clustered Raft-FSM-backed broker, a
metrics-wrapping decorator, a forwarding proxy that routes calls
across nodes, etc. The factory receives the full RealmConfig + logger
so custom impls have everything the defaults need.

Pinned by:
  - TestRealmConfigBrokerAndDealerFactoriesHonored — wraps the default
    impls in probe types and asserts the hooks are actually called.
  - TestRealmConfigUnsetFactoriesUseDefaults — checks the fallback
    path keeps working (concrete *broker / *dealer dynamic types).

This is the seam Phase 2 clustering depends on. The 36-plan spec/
harness, race-checked router suite, and cross-transport test/ matrix
all pass unchanged. Coverage 63.2%.

Step 3 of 3 in gammazero#315 / IRONFLOCK_PLAN §1.2.

Author: Marko Petzold

router/config.go

@@ -90,6 +90,16 @@ type RealmConfig struct {
 	// This value is not set via json config, but is configured when embedding
 	// nexus. A value of nil enables the default filtering.
 	PublishFilterFactory FilterFactory
+
+	// BrokerFactory, if set, supplies a custom Broker implementation for
+	// this realm instead of the default in-process broker. Useful for
+	// clustered backends, metrics-wrapping decorators, or forwarding
+	// proxies. nil means use the default.
+	BrokerFactory BrokerFactory
+
+	// DealerFactory, if set, supplies a custom Dealer implementation for
+	// this realm instead of the default in-process dealer.
+	DealerFactory DealerFactory
 }
 
 type TopicEventHistoryConfig struct {

router/factory_test.go

@@ -0,0 +1,93 @@
+package router //nolint:testpackage
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/gammazero/nexus/v3/stdlog"
+	"github.com/gammazero/nexus/v3/wamp"
+)
+
+// brokerFactoryProbe wraps the default broker but records that the
+// factory was invoked, so the test can assert RealmConfig.BrokerFactory
+// is honored when set.
+type brokerFactoryProbe struct {
+	Broker
+	called bool
+}
+
+// dealerFactoryProbe is the analogous wrapper for Dealer.
+type dealerFactoryProbe struct {
+	Dealer
+	called bool
+}
+
+// TestRealmConfigBrokerAndDealerFactoriesHonored verifies that custom
+// BrokerFactory / DealerFactory hooks on RealmConfig are invoked
+// instead of the default in-process implementations. Critical for
+// downstream consumers (e.g. clustered nexus, ironflock-router) that
+// need to substitute their own broker/dealer.
+func TestRealmConfigBrokerAndDealerFactoriesHonored(t *testing.T) {
+	const realmURI = wamp.URI("nexus.test.factory")
+
+	var brokerProbe *brokerFactoryProbe
+	var dealerProbe *dealerFactoryProbe
+
+	r, err := NewRouter(&Config{
+		RealmConfigs: []*RealmConfig{
+			{
+				URI:       realmURI,
+				StrictURI: false,
+				BrokerFactory: func(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Broker, error) {
+					inner, err := defaultBrokerFactory(cfg, logger, debug)
+					if err != nil {
+						return nil, err
+					}
+					brokerProbe = &brokerFactoryProbe{Broker: inner, called: true}
+					return brokerProbe, nil
+				},
+				DealerFactory: func(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Dealer, error) {
+					inner, err := defaultDealerFactory(cfg, logger, debug)
+					if err != nil {
+						return nil, err
+					}
+					dealerProbe = &dealerFactoryProbe{Dealer: inner, called: true}
+					return dealerProbe, nil
+				},
+			},
+		},
+	}, logger)
+	require.NoError(t, err)
+	t.Cleanup(func() { r.Close() })
+
+	require.NotNil(t, brokerProbe, "BrokerFactory was not called")
+	require.True(t, brokerProbe.called)
+	require.NotNil(t, dealerProbe, "DealerFactory was not called")
+	require.True(t, dealerProbe.called)
+}
+
+// TestRealmConfigUnsetFactoriesUseDefaults exercises the fallback path
+// — when neither factory is set, the realm uses the default in-process
+// broker/dealer. Indirectly verified by every other test in this
+// package, but pinned here so a future refactor that breaks the
+// default selection fails loud at this single test.
+func TestRealmConfigUnsetFactoriesUseDefaults(t *testing.T) {
+	const realmURI = wamp.URI("nexus.test.factory.default")
+
+	r, err := NewRouter(&Config{
+		RealmConfigs: []*RealmConfig{
+			{URI: realmURI, StrictURI: false, AnonymousAuth: true},
+		},
+	}, logger)
+	require.NoError(t, err)
+	t.Cleanup(func() { r.Close() })
+
+	// Reach into the realm to inspect the dynamic types of broker / dealer.
+	rl := r.(*router).realms[realmURI]
+	require.NotNil(t, rl)
+	_, isDefaultBroker := rl.broker.(*broker)
+	require.True(t, isDefaultBroker, "expected default *broker; got %T", rl.broker)
+	_, isDefaultDealer := rl.dealer.(*dealer)
+	require.True(t, isDefaultDealer, "expected default *dealer; got %T", rl.dealer)
+}

router/router.go

@@ -370,15 +370,24 @@ func (r *router) addRealm(config *RealmConfig) (*realm, error) {
 		return nil, errors.New("realm already exists: " + string(config.URI))
 	}
 
-	broker, err := newBroker(r.log, config.StrictURI, config.AllowDisclose, r.debug, config.PublishFilterFactory, config.TopicEventHistoryConfigs)
+	brokerFactory := config.BrokerFactory
+	if brokerFactory == nil {
+		brokerFactory = defaultBrokerFactory
+	}
+	dealerFactory := config.DealerFactory
+	if dealerFactory == nil {
+		dealerFactory = defaultDealerFactory
+	}
+
+	broker, err := brokerFactory(config, r.log, r.debug)
+	if err != nil {
+		return nil, err
+	}
+	dealer, err := dealerFactory(config, r.log, r.debug)
 	if err != nil {
 		return nil, err
 	}
-	realm, err := newRealm(
-		config,
-		broker,
-		newDealer(r.log, config.StrictURI, config.AllowDisclose, r.debug),
-		r.log, r.debug)
+	realm, err := newRealm(config, broker, dealer, r.log, r.debug)
 	if err != nil {
 		return nil, err
 	}

router/types.go

@@ -1,6 +1,9 @@
 package router
 
-import "github.com/gammazero/nexus/v3/wamp"
+import (
+	"github.com/gammazero/nexus/v3/stdlog"
+	"github.com/gammazero/nexus/v3/wamp"
+)
 
 // Broker handles publish/subscribe and topic-side meta procedures
 // for a single realm. The default implementation in [broker] is the
@@ -118,3 +121,26 @@ var (
 	_ Broker = (*broker)(nil)
 	_ Dealer = (*dealer)(nil)
 )
+
+// BrokerFactory constructs the Broker for a given realm. Set it on
+// RealmConfig.BrokerFactory to swap in a custom implementation
+// (e.g. clustered, metrics-wrapped, forwarding proxy). When unset
+// the router uses the default in-process Broker.
+type BrokerFactory func(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Broker, error)
+
+// DealerFactory constructs the Dealer for a given realm. Same shape
+// as BrokerFactory.
+type DealerFactory func(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Dealer, error)
+
+// defaultBrokerFactory builds the in-process actor-loop broker used
+// when RealmConfig.BrokerFactory is unset.
+func defaultBrokerFactory(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Broker, error) {
+	return newBroker(logger, cfg.StrictURI, cfg.AllowDisclose, debug,
+		cfg.PublishFilterFactory, cfg.TopicEventHistoryConfigs)
+}
+
+// defaultDealerFactory builds the in-process actor-loop dealer used
+// when RealmConfig.DealerFactory is unset.
+func defaultDealerFactory(cfg *RealmConfig, logger stdlog.StdLog, debug bool) (Dealer, error) {
+	return newDealer(logger, cfg.StrictURI, cfg.AllowDisclose, debug), nil
+}