Add connection webhook notifications (#392)

Also 

* Added decode of LoginStart message
* Add metrics backend constants
* Updated usage section
* Documented MaxFrameLength

Author: itzg

README.md

@@ -43,7 +43,7 @@ Routes Minecraft client connections to backend servers based upon the requested
   -mapping value
     	Comma or newline delimited or repeated mappings of externalHostname=host:port (env MAPPING)
   -metrics-backend string
-    	Backend to use for metrics exposure/publishing: discard,expvar,influxdb (env METRICS_BACKEND) (default "discard")
+    	Backend to use for metrics exposure/publishing: discard,expvar,influxdb,prometheus (env METRICS_BACKEND) (default "discard")
   -metrics-backend-config-influxdb-addr string
     	 (env METRICS_BACKEND_CONFIG_INFLUXDB_ADDR)
   -metrics-backend-config-influxdb-database string
@@ -74,9 +74,12 @@ Routes Minecraft client connections to backend servers based upon the requested
     	Send PROXY protocol to backend servers (env USE_PROXY_PROTOCOL)
   -version
     	Output version and exit (env VERSION)
+  -webhook-require-user
+    	Indicates if the webhook will only be called if a user is connecting rather than just server list/ping (env WEBHOOK_REQUIRE_USER)
+  -webhook-url string
+    	If set, a POST request that contains connection status notifications will be sent to this HTTP address (env WEBHOOK_URL)
 ```
 
-
 ## Docker Multi-Architecture Image
 
 The [multi-architecture image published at Docker Hub](https://hub.docker.com/repository/docker/itzg/mc-router) supports amd64, arm64, and arm32v6 (i.e. RaspberryPi).
@@ -353,6 +356,99 @@ From those logs, locate the `ngrokUrl` parameter from the "Listening" info log m
 
 In the Minecraft client, the server address will be the part after the "tcp://" prefix, such as `8.tcp.ngrok.io:99999`.
 
+## Webhook Support
+
+Refer to [the usage section above](#usage) for `-webhook-*` argument descriptions.
+
+### Sample connect event payloads
+
+The following are sample payloads for the `connect` webhook events.
+
+#### Successful player backend connection
+
+```json
+{
+  "event": "connect",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00",
+  "status": "success",
+  "client": {
+    "host": "127.0.0.1",
+    "port": 56860
+  },
+  "server": "localhost",
+  "player": {
+    "name": "itzg",
+    "uuid": "5cddfd26-fc86-4981-b52e-c42bb10bfdef"
+  },
+  "backend": "localhost:25566"
+}
+```
+
+**NOTE** `client` refers to the machine where the Minecraft client is connecting from and is conveyed separately from the `player` starting a session. As seen below, the player information may not always be present, such as when the client is pinging the server list.
+
+#### Successful server ping backend connection
+
+**NOTE** the absence of `player` in this payload since the Minecraft client does not send player information in the server ping request.
+
+```json
+{
+  "event": "connect",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00",
+  "status": "success",
+  "client": {
+    "host": "127.0.0.1",
+    "port": 56396
+  },
+  "server": "localhost",
+  "backend": "localhost:25566"
+}
+```
+
+#### Missing backend
+
+In this the status is `"missing-backend"` since the requested server `invalid.example.com` does not have a configured/discovered backend entry.
+
+```json
+{
+  "event": "connect",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00",
+  "status": "missing-backend",
+  "client": {
+    "host": "127.0.0.1",
+    "port": 56891
+  },
+  "server": "invalid.example.com",
+  "player": {
+    "name": "itzg",
+    "uuid": "5cddfd26-fc86-4981-b52e-c42bb10bfdef"
+  },
+  "error": "No backend found"
+}
+```
+
+#### Failed backend connection
+
+In this case the `status` is `"failed-backend-connection"` indicating that a backend server was located but a connection could not be established from mc-router.
+
+```json
+{
+  "event": "connect",
+  "timestamp": "2025-04-20T22:26:30.2568775-05:00",
+  "status": "failed-backend-connection",
+  "client": {
+    "host": "127.0.0.1",
+    "port": 56905
+  },
+  "server": "localhost",
+  "player": {
+    "name": "itzg",
+    "uuid": "5cddfd26-fc86-4981-b52e-c42bb10bfdef"
+  },
+  "backend": "localhost:25566",
+  "error": "dial tcp [::1]:25566: connectex: No connection could be made because the target machine actively refused it."
+}
+```
+
 ## Development
 
 ### Building locally with Docker

cmd/mc-router/main.go

@@ -28,6 +28,11 @@ type MetricsBackendConfig struct {
 	}
 }
 
+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"`
+}
+
 type Config struct {
 	Port                  int               `default:"25565" usage:"The [port] bound to listen for Minecraft client connections"`
 	Default               string            `usage:"host:port of a default Minecraft server to use when mapping not found"`
@@ -57,6 +62,8 @@ type Config struct {
 	ClientsToDeny  []string `usage:"Zero or more client IP addresses or CIDRs to deny. Ignored if any configured to allow"`
 
 	SimplifySRV bool `default:"false" usage:"Simplify fully qualified SRV records for mapping"`
+
+	Webhook WebhookConfig `usage:"Webhook configuration"`
 }
 
 var (
@@ -135,12 +142,23 @@ func main() {
 		trustedIpNets = append(trustedIpNets, ipNet)
 	}
 
+	connector := server.NewConnector(metricsBuilder.BuildConnectorMetrics(), config.UseProxyProtocol, config.ReceiveProxyProtocol, trustedIpNets)
+
 	clientFilter, err := server.NewClientFilter(config.ClientsToAllow, config.ClientsToDeny)
 	if err != nil {
 		logrus.WithError(err).Fatal("Unable to create client filter")
 	}
+	connector.SetClientFilter(clientFilter)
+
+	if config.Webhook.Url != "" {
+		logrus.
+			WithField("url", config.Webhook.Url).
+			WithField("require-user", config.Webhook.RequireUser).
+			Info("Using webhook for connection status notifications")
+		connector.SetConnectionNotifier(
+			server.NewWebhookNotifier(config.Webhook.Url, config.Webhook.RequireUser))
+	}
 
-	connector := server.NewConnector(metricsBuilder.BuildConnectorMetrics(), config.UseProxyProtocol, config.ReceiveProxyProtocol, trustedIpNets, clientFilter)
 	if config.NgrokToken != "" {
 		connector.UseNgrok(config.NgrokToken)
 	}

cmd/mc-router/metrics.go

@@ -24,14 +24,26 @@ type MetricsBuilder interface {
 	Start(ctx context.Context) error
 }
 
+const (
+	MetricsBackendExpvar     = "expvar"
+	MetricsBackendPrometheus = "prometheus"
+	MetricsBackendInfluxDB   = "influxdb"
+	MetricsBackendDiscard    = "discard"
+)
+
+// NewMetricsBuilder creates a new MetricsBuilder based on the specified backend.
+// If the backend is not recognized, a discard builder is returned.
+// config can be nil if the backend is not influxdb.
 func NewMetricsBuilder(backend string, config *MetricsBackendConfig) MetricsBuilder {
 	switch strings.ToLower(backend) {
-	case "expvar":
+	case MetricsBackendExpvar:
 		return &expvarMetricsBuilder{}
-	case "prometheus":
+	case MetricsBackendPrometheus:
 		return &prometheusMetricsBuilder{}
-	case "influxdb":
+	case MetricsBackendInfluxDB:
 		return &influxMetricsBuilder{config: config}
+	case MetricsBackendDiscard:
+		return &discardMetricsBuilder{}
 	default:
 		return &discardMetricsBuilder{}
 	}

mcproto/decode.go

@@ -0,0 +1,67 @@
+package mcproto
+
+import (
+	"bytes"
+	"github.com/pkg/errors"
+)
+
+const invalidPacketDataBytesMsg = "data should be byte slice from Packet.Data"
+
+// DecodeHandshake takes the Packet.Data bytes and decodes a Handshake message from it
+func DecodeHandshake(data interface{}) (*Handshake, error) {
+
+	dataBytes, ok := data.([]byte)
+	if !ok {
+		return nil, errors.New(invalidPacketDataBytesMsg)
+	}
+
+	handshake := &Handshake{}
+	buffer := bytes.NewBuffer(dataBytes)
+	var err error
+
+	handshake.ProtocolVersion, err = ReadVarInt(buffer)
+	if err != nil {
+		return nil, err
+	}
+
+	handshake.ServerAddress, err = ReadString(buffer)
+	if err != nil {
+		return nil, err
+	}
+
+	handshake.ServerPort, err = ReadUnsignedShort(buffer)
+	if err != nil {
+		return nil, err
+	}
+
+	nextState, err := ReadVarInt(buffer)
+	if err != nil {
+		return nil, err
+	}
+	handshake.NextState = State(nextState)
+	return handshake, nil
+}
+
+// DecodeLoginStart takes the Packet.Data bytes and decodes a LoginStart message from it
+func DecodeLoginStart(data interface{}) (*LoginStart, error) {
+	dataBytes, ok := data.([]byte)
+	if !ok {
+		return nil, errors.New(invalidPacketDataBytesMsg)
+	}
+
+	loginStart := &LoginStart{}
+	buffer := bytes.NewBuffer(dataBytes)
+	var err error
+
+	loginStart.Name, err = ReadString(buffer)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to read username")
+	}
+
+	loginStart.PlayerUuid, err = ReadUuid(buffer)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to read player uuid")
+	}
+
+	return loginStart, nil
+}

mcproto/handshake-login-start.hex

@@ -0,0 +1,2 @@
+10008206096c6f63616c686f737463dd02
+16000469747a675cddfd26fc864981b52ec42bb10bfdef

mcproto/handshake-status.hex

@@ -0,0 +1,2 @@
+10008206096c6f63616c686f737463dd01
+0100

mcproto/read.go

@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"bytes"
 	"encoding/binary"
+	"github.com/google/uuid"
 	"io"
 	"net"
 	"strings"
@@ -15,22 +16,27 @@ import (
 	"golang.org/x/text/transform"
 )
 
-func ReadPacket(reader io.Reader, addr net.Addr, state State) (*Packet, error) {
+// MaxFrameLength is declared at https://minecraft.wiki/w/Java_Edition_protocol#Packet_format
+// to be 2^21 - 1
+const MaxFrameLength = 2097151
+
+// ReadPacket reads a packet from the given reader based on the provided connection state.
+// Returns a pointer to the Packet and an error if reading fails.
+// Handles legacy server list ping packet when in the handshaking state.
+// The provided addr is used for logging purposes.
+func ReadPacket(reader *bufio.Reader, addr net.Addr, state State) (*Packet, error) {
 	logrus.
 		WithField("client", addr).
 		Debug("Reading packet")
 
 	if state == StateHandshaking {
-		bufReader := bufio.NewReader(reader)
-		data, err := bufReader.Peek(1)
+		data, err := reader.Peek(1)
 		if err != nil {
 			return nil, err
 		}
 
 		if data[0] == PacketIdLegacyServerListPing {
-			return ReadLegacyServerListPing(bufReader, addr)
-		} else {
-			reader = bufReader
+			return ReadLegacyServerListPing(reader, addr)
 		}
 	}
 
@@ -161,8 +167,7 @@ func ReadFrame(reader io.Reader, addr net.Addr) (*Frame, error) {
 		return nil, err
 	}
 
-	// Limit frame length to 2^21 - 1
-	if frame.Length > 2097151 {
+	if frame.Length > MaxFrameLength {
 		return nil, errors.Errorf("frame length %d too large", frame.Length)
 	}
 
@@ -280,36 +285,11 @@ func ReadUnsignedInt(reader io.Reader) (uint32, error) {
 	return value, nil
 }
 
-func ReadHandshake(data interface{}) (*Handshake, error) {
-
-	dataBytes, ok := data.([]byte)
-	if !ok {
-		return nil, errors.New("data is not expected byte slice")
-	}
-
-	handshake := &Handshake{}
-	buffer := bytes.NewBuffer(dataBytes)
-	var err error
-
-	handshake.ProtocolVersion, err = ReadVarInt(buffer)
-	if err != nil {
-		return nil, err
-	}
-
-	handshake.ServerAddress, err = ReadString(buffer)
+func ReadUuid(reader io.Reader) (uuid.UUID, error) {
+	uuidBytes := make([]byte, 16)
+	_, err := io.ReadFull(reader, uuidBytes)
 	if err != nil {
-		return nil, err
-	}
-
-	handshake.ServerPort, err = ReadUnsignedShort(buffer)
-	if err != nil {
-		return nil, err
-	}
-
-	nextState, err := ReadVarInt(buffer)
-	if err != nil {
-		return nil, err
+		return uuid.UUID{}, err
 	}
-	handshake.NextState = nextState
-	return handshake, nil
+	return uuid.FromBytes(uuidBytes)
 }