Added support for route change events with webhook notifier (#560)

Author: itzg

AGENTS.md

@@ -75,7 +75,7 @@ Wakers/sleepers (`WakerFunc`/`SleeperFunc` in `routes.go`) are attached per rout
 - `github.com/gorilla/mux` — HTTP routing (API server)
 - `github.com/prometheus/client_golang` — Prometheus metrics
 - `golang.ngrok.com/ngrok` — ngrok tunnel integration
-- `github.com/stretchr/testify` — Test assertions
+- `github.com/stretchr/testify` — Test assertions and mocking
 
 ### Concurrency Model
 
@@ -93,6 +93,11 @@ The maintainer is gradually moving the codebase **away from package-level global
 - **Scope helpers to their type.** Package-level functions that operate on or return a type's data should be methods on that type (or live in a nested package), not free functions in `server/`.
 - **Prefer a single config surface.** Where an `action` field can discriminate behavior (e.g. one webhook URL for both up/down), favor that over two parallel flags, matching the notifier webhook.
 
+### Testing Conventions
+
+- Use `testify` for assertions and mocking
+- Table-driven tests with subtests (`t.Run()`) for multiple scenarios
+
 ### Error Handling
 
 - Wrap with context: `fmt.Errorf("message: %w", err)`

README.md

@@ -821,6 +821,54 @@ In this case the `status` is `"failed-backend-connection"` indicating that a bac
 }
 ```
 
+#### Route added
+
+> [!NOTE] This event type is disabled by default
+
+```json
+{
+  "event": "route-added",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00",
+  "server": "localhost",
+  "backend": "localhost:25566"
+}
+```
+
+#### Route removed
+
+> [!NOTE] This event type is disabled by default
+
+```json
+{
+  "event": "route-removed",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00",
+  "server": "localhost"
+}
+```
+
+#### Default route set
+
+> [!NOTE] This event type is disabled by default
+
+```json
+{
+  "event": "default-route-set",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00",
+  "backend": "localhost:25566"
+}
+```
+
+#### Default route removed
+
+> [!NOTE] This event type is disabled by default
+
+```json
+{
+  "event": "default-route-removed",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00"
+}
+```
+
 ## Community Solutions
 
 - **[MC Router Discovery](https://github.com/Seedloaf/mc-router-discovery):** A lightweight sidecar to ensure mc-router is in sync with your list of running servers.

go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/go-kit/kit v0.13.0
 	github.com/gorilla/mux v1.8.1
 	github.com/influxdata/influxdb1-client v0.0.0-20220302092344-a9ab5670611c
-	github.com/itzg/go-flagsfiller v1.18.0
+	github.com/itzg/go-flagsfiller v1.19.0
 	github.com/juju/ratelimit v1.0.2
 	github.com/pires/go-proxyproto v0.12.0
 	github.com/pkg/errors v0.9.1

go.sum

@@ -80,8 +80,8 @@ github.com/inconshreveable/log15/v3 v3.0.0-testing.5 h1:h4e0f3kjgg+RJBlKOabrohjH
 github.com/inconshreveable/log15/v3 v3.0.0-testing.5/go.mod h1:3GQg1SVrLoWGfRv/kAZMsdyU5cp8eFc1P3cw+Wwku94=
 github.com/influxdata/influxdb1-client v0.0.0-20220302092344-a9ab5670611c h1:qSHzRbhzK8RdXOsAdfDgO49TtqC1oZ+acxPrkfTxcCs=
 github.com/influxdata/influxdb1-client v0.0.0-20220302092344-a9ab5670611c/go.mod h1:qj24IKcXYK6Iy9ceXlo3Tc+vtHo9lIhSX5JddghvEPo=
-github.com/itzg/go-flagsfiller v1.18.0 h1:dSxUZcvYQg5XKJ1bhZX7rLIQcz2mzlKNVZYXrvJrBAY=
-github.com/itzg/go-flagsfiller v1.18.0/go.mod h1:Zq4PnNALfrY73hVPlg7GExLxm3lVRu90895WVe8NQVg=
+github.com/itzg/go-flagsfiller v1.19.0 h1:CiT97rDZJrRvWoiVzbx/mRM+/fn+GQ6cRMMa/x3psBs=
+github.com/itzg/go-flagsfiller v1.19.0/go.mod h1:Zq4PnNALfrY73hVPlg7GExLxm3lVRu90895WVe8NQVg=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/jpillora/backoff v1.0.0 h1:uvFg412JmmHBHw7iwprIxkPMI+sGQ4kzOWsMeHnm2EA=

server/configs.go

@@ -3,9 +3,10 @@ package server
 import "time"
 
 type WebhookConfig struct {
-	Url         string        `usage:"If set, a POST request that contains connection status notifications will be sent to this HTTP address"`
-	RequireUser bool          `default:"false" usage:"Indicates if the webhook will only be called if a user is connecting rather than just server list/ping"`
-	Timeout     time.Duration `default:"30s" usage:"Timeout for each connection status notification request"`
+	Url         string         `usage:"If set, a POST request that contains connection status notifications will be sent to this HTTP address"`
+	RequireUser bool           `default:"false" usage:"Indicates if the webhook will only be called if a user is connecting rather than just server list/ping"`
+	Timeout     time.Duration  `default:"30s" usage:"Timeout for each connection status notification request"`
+	Events      []WebhookEvent `default:"connect,disconnect" usage:"Comma delimited list of events to send to the webhook. Valid values are connect, disconnect, route-added, route-removed, default-route-set, default-route-removed"`
 }
 
 type AutoScale struct {

server/connector_test.go

@@ -132,7 +132,7 @@ func writeTestPacket(w io.Writer, packetID int32, payload func(w io.Writer)) err
 func TestConnectorMOTDFallback(t *testing.T) {
 	routes := NewRoutes(t.Context())
 	downScaler := NewDownScaler(false, 5*time.Second)
-	routes.SetDownScaler(downScaler)
+	routes.WithDownScaler(downScaler)
 
 	backendAddress := "127.0.0.1:0"
 

server/routes.go

@@ -43,6 +43,17 @@ type RoutesHandler interface {
 	DeleteMapping(serverAddress string) bool
 }
 
+type RoutesListener interface {
+	// OnRouteAdded is called when a new route is added.
+	OnRouteAdded(serverAddress string, backend string)
+	// OnDefaultRouteSet is called when a default route is set.
+	OnDefaultRouteSet(backend string)
+	// OnRouteRemoved is called when a route is removed.
+	OnRouteRemoved(serverAddress string)
+	// OnDefaultRouteRemoved is called when a default route is removed (or un-set).
+	OnDefaultRouteRemoved()
+}
+
 type IRoutes interface {
 	RoutesHandler
 
@@ -60,31 +71,22 @@ type IRoutes interface {
 	GetAsleepMOTD(serverAddress string) string
 	GetLoadingMOTD(serverAddress string) string
 	SimplifySRV(srvEnabled bool)
-	SetDownScaler(downScaler IDownScaler)
+	// BulkRegister registers a set of static mappings, attaching the scaler's waker/sleeper pair. nil-safe: a nil scaler registers without autoscaling.
+	// Reset must be called separately and previous to this if you want to clear existing mappings.
+	BulkRegister(scaler *WebhookScaler, mappings map[string]string)
+
+	WithDownScaler(downScaler IDownScaler) IRoutes
+	WithListener(listener RoutesListener) IRoutes
 }
 
 func NewRoutes(ctx context.Context) IRoutes {
 	r := &routesImpl{
 		ctx:      ctx,
 		mappings: make(map[string]mapping),
 	}
-
 	return r
 }
 
-func (r *routesImpl) SetDownScaler(downScaler IDownScaler) {
-	r.downScaler = downScaler
-}
-
-// registerStaticMappings registers each static mapping, attaching the scaler's
-// waker/sleeper pair. nil-safe: a nil scaler registers without autoscaling.
-func registerStaticMappings(routes RoutesHandler, scaler *WebhookScaler, mappings map[string]string) {
-	for k, v := range mappings {
-		waker, sleeper := scaler.routeFuncs(k, v)
-		routes.CreateMapping(k, v, "", waker, sleeper, "", "")
-	}
-}
-
 type mapping struct {
 	backend       string
 	waker         WakerFunc
@@ -96,21 +98,62 @@ type mapping struct {
 
 type routesImpl struct {
 	sync.RWMutex
-	ctx          context.Context
-	mappings     map[string]mapping
-	defaultRoute mapping
-	simplifySRV  bool
-	downScaler   IDownScaler
+	ctx             context.Context
+	mappings        map[string]mapping
+	defaultRoute    mapping
+	simplifySRV     bool
+	downScaler      IDownScaler
+	routesListeners []RoutesListener
+}
+
+// WithDownScaler sets the optional down scaler for the routes. The down scaler is used to scale down servers when they are no longer needed.
+// TODO this is a code smell because it creates a circular dependency between routes and down scaler. The down scaler needs to know about the routes to scale down servers, but the routes also need to know about the down scaler to start scaling down servers when they are no longer needed. This should be refactored in the future.
+func (r *routesImpl) WithDownScaler(downScaler IDownScaler) IRoutes {
+	r.downScaler = downScaler
+	return r
+}
+
+// WithListener adds a listener to the routes. The listener will be notified of route changes.
+// It will also be notified of existing routes when added. This ensures listeners get a consistent and complete view of routes.
+func (r *routesImpl) WithListener(listener RoutesListener) IRoutes {
+	r.Lock()
+	defer r.Unlock()
+
+	r.routesListeners = append(r.routesListeners, listener)
+	for server, backend := range r.mappings {
+		listener.OnRouteAdded(server, backend.backend)
+	}
+	if r.defaultRoute.backend != "" {
+		listener.OnDefaultRouteSet(r.defaultRoute.backend)
+	}
+	return r
 }
 
 func (r *routesImpl) Reset() {
+	r.Lock()
+	defer r.Unlock()
+
+	for serverAddress := range r.mappings {
+		for _, listener := range r.routesListeners {
+			listener.OnRouteRemoved(serverAddress)
+		}
+	}
+
 	r.mappings = make(map[string]mapping)
+
+	for _, listener := range r.routesListeners {
+		listener.OnDefaultRouteRemoved()
+	}
+
 	if r.downScaler != nil {
 		r.downScaler.Reset()
 	}
 }
 
 func (r *routesImpl) SetDefaultRoute(backend string, scalingTarget string, waker WakerFunc, sleeper SleeperFunc, asleepMOTD string, loadingMOTD string) {
+	r.Lock()
+	defer r.Unlock()
+
 	if scalingTarget == "" {
 		scalingTarget = backend
 	}
@@ -119,6 +162,10 @@ func (r *routesImpl) SetDefaultRoute(backend string, scalingTarget string, waker
 	logrus.WithFields(logrus.Fields{
 		"backend": backend,
 	}).Info("Using default route")
+
+	for _, listener := range r.routesListeners {
+		listener.OnDefaultRouteSet(backend)
+	}
 }
 
 func (r *routesImpl) GetDefaultRoute() (string, string, WakerFunc, SleeperFunc) {
@@ -245,6 +292,11 @@ func (r *routesImpl) DeleteMapping(serverAddress string) bool {
 	if m, ok := r.mappings[serverAddress]; ok {
 		r.downScaler.Cancel(m.scalingTarget)
 		delete(r.mappings, serverAddress)
+
+		for _, listener := range r.routesListeners {
+			listener.OnRouteRemoved(serverAddress)
+		}
+
 		return true
 	} else {
 		return false
@@ -267,8 +319,19 @@ func (r *routesImpl) CreateMapping(serverAddress string, backend string, scaling
 	}).Info("Created route mapping")
 	r.mappings[serverAddress] = mapping{backend: backend, scalingTarget: scalingTarget, waker: waker, sleeper: sleeper, asleepMOTD: asleepMOTD, loadingMOTD: loadingMOTD}
 
+	for _, listener := range r.routesListeners {
+		listener.OnRouteAdded(serverAddress, backend)
+	}
+
 	// Trigger auto scale down when mapping is created to ensure servers are shut down if router restarts
 	if r.downScaler != nil && scalingTarget != "" {
 		r.downScaler.Start(r.ctx, scalingTarget, r)
 	}
 }
+
+func (r *routesImpl) BulkRegister(scaler *WebhookScaler, mappings map[string]string) {
+	for k, v := range mappings {
+		waker, sleeper := scaler.routeFuncs(k, v)
+		r.CreateMapping(k, v, "", waker, sleeper, "", "")
+	}
+}

server/routes_config_loader.go

@@ -52,7 +52,7 @@ func (r *RoutesConfigLoader) Load(routesConfigFileName string) error {
 		return errors.Wrap(readErr, "Could not load the routes config file")
 	}
 
-	registerStaticMappings(r.routes, r.scaler, config.Mappings)
+	r.routes.BulkRegister(r.scaler, config.Mappings)
 	waker, sleeper := r.scaler.routeFuncs("", config.DefaultServer)
 	r.routes.SetDefaultRoute(config.DefaultServer, "", waker, sleeper, "", "")
 	return nil
@@ -71,7 +71,7 @@ func (r *RoutesConfigLoader) Reload() error {
 
 	logrus.WithField("routesConfig", r.fileName).Info("Re-loading routes config file")
 	r.routes.Reset()
-	registerStaticMappings(r.routes, r.scaler, config.Mappings)
+	r.routes.BulkRegister(r.scaler, config.Mappings)
 	waker, sleeper := r.scaler.routeFuncs("", config.DefaultServer)
 	r.routes.SetDefaultRoute(config.DefaultServer, "", waker, sleeper, "", "")