caddyhttp: New experimental handler for intercepting responses (#6232)

* feat: add generic response interceptors

* fix: cs

* rename intercept

* add some docs

* @francislavoie review (first round)

* Update modules/caddyhttp/intercept/intercept.go

Co-authored-by: Francis Lavoie <[email protected]>

* shorthands: ir to resp

* mark exported symbols as experimental

---------

Co-authored-by: Francis Lavoie <[email protected]>

2 files changed, 264 insertions, 0 deletions

diff --git a/caddytest/integration/caddyfile_adapt/intercept_response.caddyfiletest b/caddytest/integration/caddyfile_adapt/intercept_response.caddyfiletest
new file mode 100644
index 000000000..c92b76fe5
--- /dev/null
+++ b/caddytest/integration/caddyfile_adapt/intercept_response.caddyfiletest
@@ -0,0 +1,230 @@
+localhost
+
+respond "To intercept"
+
+intercept {
+	@500 status 500
+	replace_status @500 400
+
+	@all status 2xx 3xx 4xx 5xx
+	replace_status @all {http.error.status_code}
+
+	replace_status {http.error.status_code}
+
+	@accel header X-Accel-Redirect *
+	handle_response @accel {
+		respond "Header X-Accel-Redirect!"
+	}
+
+	@another {
+		header X-Another *
+	}
+	handle_response @another {
+		respond "Header X-Another!"
+	}
+
+	@401 status 401
+	handle_response @401 {
+		respond "Status 401!"
+	}
+
+	handle_response {
+		respond "Any! This should be last in the JSON!"
+	}
+
+	@403 {
+		status 403
+	}
+	handle_response @403 {
+		respond "Status 403!"
+	}
+
+	@multi {
+		status 401 403
+		status 404
+		header Foo *
+		header Bar *
+	}
+	handle_response @multi {
+		respond "Headers Foo, Bar AND statuses 401, 403 and 404!"
+	}
+}
+----------
+{
+	"apps": {
+		"http": {
+			"servers": {
+				"srv0": {
+					"listen": [
+						":443"
+					],
+					"routes": [
+						{
+							"match": [
+								{
+									"host": [
+										"localhost"
+									]
+								}
+							],
+							"handle": [
+								{
+									"handler": "subroute",
+									"routes": [
+										{
+											"handle": [
+												{
+													"handle_response": [
+														{
+															"match": {
+																"status_code": [
+																	500
+																]
+															},
+															"status_code": 400
+														},
+														{
+															"match": {
+																"status_code": [
+																	2,
+																	3,
+																	4,
+																	5
+																]
+															},
+															"status_code": "{http.error.status_code}"
+														},
+														{
+															"match": {
+																"headers": {
+																	"X-Accel-Redirect": [
+																		"*"
+																	]
+																}
+															},
+															"routes": [
+																{
+																	"handle": [
+																		{
+																			"body": "Header X-Accel-Redirect!",
+																			"handler": "static_response"
+																		}
+																	]
+																}
+															]
+														},
+														{
+															"match": {
+																"headers": {
+																	"X-Another": [
+																		"*"
+																	]
+																}
+															},
+															"routes": [
+																{
+																	"handle": [
+																		{
+																			"body": "Header X-Another!",
+																			"handler": "static_response"
+																		}
+																	]
+																}
+															]
+														},
+														{
+															"match": {
+																"status_code": [
+																	401
+																]
+															},
+															"routes": [
+																{
+																	"handle": [
+																		{
+																			"body": "Status 401!",
+																			"handler": "static_response"
+																		}
+																	]
+																}
+															]
+														},
+														{
+															"match": {
+																"status_code": [
+																	403
+																]
+															},
+															"routes": [
+																{
+																	"handle": [
+																		{
+																			"body": "Status 403!",
+																			"handler": "static_response"
+																		}
+																	]
+																}
+															]
+														},
+														{
+															"match": {
+																"headers": {
+																	"Bar": [
+																		"*"
+																	],
+																	"Foo": [
+																		"*"
+																	]
+																},
+																"status_code": [
+																	401,
+																	403,
+																	404
+																]
+															},
+															"routes": [
+																{
+																	"handle": [
+																		{
+																			"body": "Headers Foo, Bar AND statuses 401, 403 and 404!",
+																			"handler": "static_response"
+																		}
+																	]
+																}
+															]
+														},
+														{
+															"status_code": "{http.error.status_code}"
+														},
+														{
+															"routes": [
+																{
+																	"handle": [
+																		{
+																			"body": "Any! This should be last in the JSON!",
+																			"handler": "static_response"
+																		}
+																	]
+																}
+															]
+														}
+													],
+													"handler": "intercept"
+												},
+												{
+													"body": "To intercept",
+													"handler": "static_response"
+												}
+											]
+										}
+									]
+								}
+							],
+							"terminal": true
+						}
+					]
+				}
+			}
+		}
+	}
+}
diff --git a/caddytest/integration/intercept_test.go b/caddytest/integration/intercept_test.go
new file mode 100644
index 000000000..81db6a7d6
--- /dev/null
+++ b/caddytest/integration/intercept_test.go
@@ -0,0 +1,34 @@
+package integration
+
+import (
+	"testing"
+
+	"github.com/caddyserver/caddy/v2/caddytest"
+)
+
+func TestIntercept(t *testing.T) {
+	tester := caddytest.NewTester(t)
+	tester.InitServer(`{
+			skip_install_trust
+			admin localhost:2999
+			http_port     9080
+			https_port    9443
+			grace_period  1ns
+		}
+	
+		localhost:9080 {
+			respond /intercept "I'm a teapot" 408
+			respond /no-intercept "I'm not a teapot"
+
+			intercept {
+				@teapot status 408
+				handle_response @teapot {
+					respond /intercept "I'm a combined coffee/tea pot that is temporarily out of coffee" 503
+				}
+			}	
+		}
+		`, "caddyfile")
+
+	tester.AssertGetResponse("http://localhost:9080/intercept", 503, "I'm a combined coffee/tea pot that is temporarily out of coffee")
+	tester.AssertGetResponse("http://localhost:9080/no-intercept", 200, "I'm not a teapot")
+}