docs: expand proxy protocol docs (#6620)

1 files changed, 35 insertions, 3 deletions

diff --git a/modules/caddyhttp/proxyprotocol/listenerwrapper.go b/modules/caddyhttp/proxyprotocol/listenerwrapper.go
index f5f2099ce..f1d170c38 100644
--- a/modules/caddyhttp/proxyprotocol/listenerwrapper.go
+++ b/modules/caddyhttp/proxyprotocol/listenerwrapper.go
@@ -25,7 +25,12 @@ import (
 )
 
 // ListenerWrapper provides PROXY protocol support to Caddy by implementing
-// the caddy.ListenerWrapper interface. It must be loaded before the `tls` listener.
+// the caddy.ListenerWrapper interface. If a connection is received via Unix
+// socket, it's trusted. Otherwise, it's checked against the Allow/Deny lists,
+// then it's handled by the FallbackPolicy.
+//
+// It must be loaded before the `tls` listener because the PROXY protocol
+// encapsulates the TLS data.
 //
 // Credit goes to https://github.com/mastercactapus/caddy2-proxyprotocol for having
 // initially implemented this as a plugin.
@@ -45,8 +50,35 @@ type ListenerWrapper struct {
 	Deny []string `json:"deny,omitempty"`
 	deny []netip.Prefix
 
-	// Accepted values are: ignore, use, reject, require, skip
-	// default: ignore
+	// FallbackPolicy specifies the policy to use if the downstream
+	// IP address is not in the Allow list nor is in the Deny list.
+	//
+	// NOTE: The generated docs which describe the value of this
+	// field is wrong because of how this type unmarshals JSON in a
+	// custom way. The field expects a string, not a number.
+	//
+	// Accepted values are: IGNORE, USE, REJECT, REQUIRE, SKIP
+	//
+	// - IGNORE: address from PROXY header, but accept connection
+	//
+	// - USE: address from PROXY header
+	//
+	// - REJECT: connection when PROXY header is sent
+	//   Note: even though the first read on the connection returns an error if
+	//   a PROXY header is present, subsequent reads do not. It is the task of
+	//   the code using the connection to handle that case properly.
+	//
+	// - REQUIRE: connection to send PROXY header, reject if not present
+	//   Note: even though the first read on the connection returns an error if
+	//   a PROXY header is not present, subsequent reads do not. It is the task
+	//   of the code using the connection to handle that case properly.
+	//
+	// - SKIP: accepts a connection without requiring the PROXY header.
+	//   Note: an example usage can be found in the SkipProxyHeaderForCIDR
+	//   function.
+	//
+	// Default: IGNORE
+	//
 	// Policy definitions are here: https://pkg.go.dev/github.com/pires/[email protected]#Policy
 	FallbackPolicy Policy `json:"fallback_policy,omitempty"`