Implement Caddy static responses config

Author: mars

buildpacks/static-web-server/README.md

@@ -306,6 +306,75 @@ For example, a request to `example.com/support` will be tried in the document ro
 2. the path with HTML extension, `support.html`
 3. the path as a directory, `support/`
 
+#### Caddy: Static Responses
+
+*Default: none*
+
+Define preset HTTP responses. Supports the common HTTP redirect use-case, or any custom status, headers, and body response.
+
+```toml
+[[com.heroku.static-web-server.caddy_server_opts.static_responses]]
+# match the Host header indicated in request
+host_matcher = "hostname.example.com"
+# match the whole request path, supports `*` wildcards
+path_matcher = "/resources/*"
+# respond with HTTP status (default: 200)
+status = 200
+# repond with body content (default: none)
+body = "I could be anything."
+# set one or more response headers (default: none)
+[com.heroku.static-web-server.caddy_server_opts.static_responses.headers]
+"X-My-Header" = "Yells at cloud"
+```
+
+`host_matcher` and `path_matcher` are both optional. At least one of them should be set for each static response. Static responses are processed in the order defined. When a static response is matched, its response is terminal. No further processing will occur for the request.
+
+[Caddy placeholders](https://caddyserver.com/docs/conventions#placeholders) can be used for per-request dynamic values. The [HTTP placeholders](https://caddyserver.com/docs/json/apps/http/#docs) are useful with this feature:
+
+- `{http.request.host}`
+- `{http.request.uri}`
+- `{http.request.uri.path}`
+- `{http.request.uri.path.dir}`
+- `{http.request.uri.path.file}`
+- `{http.request.uri.query}`
+
+For example, permanently redirect to a different path with status `301` and a `Location` header, using the requested filename in the new path:
+
+```toml
+[[com.heroku.static-web-server.caddy_server_opts.static_responses]]
+path_matcher = "/blog/*"
+status = 301
+[com.heroku.static-web-server.caddy_server_opts.static_responses.headers]
+"Location" = "/feed/{http.request.uri.path.file}"
+```
+
+Another example, permanently redirect any request for a specific host to a new server, passing through the original URI (path and querystring) and an additional custom header:
+
+```toml
+[[com.heroku.static-web-server.caddy_server_opts.static_responses]]
+host_matcher = "original.example.com"
+status = 301
+[com.heroku.static-web-server.caddy_server_opts.static_responses.headers]
+"Location" = "https://new.example.com{http.request.uri}"
+"X-Redirected-From" = "original.example.com"
+```
+
+Multiple static responses may be set using additional TOML tables:
+
+```toml
+[[com.heroku.static-web-server.caddy_server_opts.static_responses]]
+path_matcher = "/news/*"
+status = 301
+[com.heroku.static-web-server.caddy_server_opts.static_responses.headers]
+"Location" = "/media/{http.request.uri.path.file}"
+
+[[com.heroku.static-web-server.caddy_server_opts.static_responses]]
+path_matcher = "/support/*"
+status = 301
+[com.heroku.static-web-server.caddy_server_opts.static_responses.headers]
+"Location" = "/help/{http.request.uri.path.file}"
+```
+
 #### Caddy: Basic Authorization
 
 *Default: not enabled*

buildpacks/static-web-server/src/caddy_config.rs

@@ -1,25 +1,27 @@
 use crate::heroku_web_server_config::{
-    ErrorsConfig, Header, HerokuWebServerConfig, DEFAULT_DOC_INDEX, DEFAULT_DOC_ROOT,
+    ErrorsConfig, HerokuWebServerConfig, PathMatchedHeader, DEFAULT_DOC_INDEX, DEFAULT_DOC_ROOT,
 };
 use crate::o11y::*;
 use indexmap::IndexMap;
+use serde::Serialize;
 use serde_json::json;
 use std::collections::HashMap;
 
 /// Transforms the given [`HerokuWebServerConfig`] into an equivalent Caddy JSON configuration.
 /// Keeping this as a single function, because many lines are just the JSON itself being assembled.
 #[allow(clippy::too_many_lines)]
-pub(crate) fn caddy_json_config(config: HerokuWebServerConfig) -> serde_json::Value {
+pub(crate) fn caddy_json_config(config: &HerokuWebServerConfig) -> serde_json::Value {
     let mut routes = vec![];
 
     // Header routes come first so headers will be added to any response down the chain.
-    if let Some(headers) = config.headers {
+    if let Some(ref headers) = config.headers {
         tracing::info!({ CONFIG_RESPONSE_HEADERS_ENABLED } = true, "config");
-        routes.extend(generate_response_headers_routes(&headers));
+        routes.extend(generate_response_headers_routes(headers));
     }
 
     let doc_root = config
         .root
+        .clone()
         .map_or(String::from(DEFAULT_DOC_ROOT), |path_buf| {
             String::from(path_buf.to_string_lossy())
         });
@@ -63,6 +65,8 @@ pub(crate) fn caddy_json_config(config: HerokuWebServerConfig) -> serde_json::Va
         }));
     }
 
+    generate_static_response_handlers(config, &mut static_file_handlers);
+
     static_file_handlers.push(json!(
     {
         "handler": "encode",
@@ -191,10 +195,67 @@ pub(crate) fn caddy_json_config(config: HerokuWebServerConfig) -> serde_json::Va
     })
 }
 
-fn generate_response_headers_routes(headers: &Vec<Header>) -> Vec<serde_json::Value> {
+fn generate_static_response_handlers(
+    config: &HerokuWebServerConfig,
+    static_file_handlers: &mut Vec<serde_json::Value>,
+) {
+    if let Some(static_responses) = config
+        .caddy_server_opts
+        .as_ref()
+        .and_then(|v| v.static_responses.clone())
+    {
+        tracing::info!(
+            { CONFIG_CADDY_SERVER_OPTS_STATIC_RESPONSES } = true,
+            "config"
+        );
+        for static_response in static_responses {
+            let mut match_array = vec![];
+
+            if let Some(host_matcher) = static_response.host_matcher {
+                let mut host_match = serde_json::Map::new();
+                host_match.insert("host".to_string(), json!(vec![host_matcher]));
+                match_array.push(serde_json::Value::Object(host_match));
+            }
+            if let Some(path_matcher) = static_response.path_matcher {
+                let mut path_match = serde_json::Map::new();
+                path_match.insert("path".to_string(), json!(vec![path_matcher]));
+                match_array.push(serde_json::Value::Object(path_match));
+            }
+
+            let headers = static_response.headers.map(|headers_vec| {
+                headers_vec
+                    .into_iter()
+                    .map(|header| (header.key, vec![header.value]))
+                    .collect::<HashMap<_, _>>()
+            });
+
+            let static_response_handler = StaticResponseHandler {
+                handler: "static_response".to_string(),
+                status_code: static_response.status.unwrap_or(200),
+                headers,
+                body: static_response.body,
+            };
+            let static_response_handler_json = serde_json::to_value(static_response_handler)
+                .expect("StaticResponseHandler should serialize to JSON");
+
+            static_file_handlers.push(json!(
+            {
+                "handler": "subroute",
+                "routes": [{
+                    "match": match_array,
+                    "handle": [static_response_handler_json],
+                    "terminal": true
+                }],
+
+            }));
+        }
+    }
+}
+
+fn generate_response_headers_routes(headers: &Vec<PathMatchedHeader>) -> Vec<serde_json::Value> {
     // Group headers with the same matcher while preserving the order of the matchers
     // by "when-first-seen".
-    let mut groups = IndexMap::<String, Vec<&Header>>::new();
+    let mut groups = IndexMap::<String, Vec<&PathMatchedHeader>>::new();
     for header in headers {
         if let Some(headers) = groups.get_mut(&header.path_matcher) {
             headers.push(header);
@@ -284,27 +345,37 @@ const DEFAULT_404_HTML: &str = r#"
     </html>
 "#;
 
+#[derive(Serialize)]
+struct StaticResponseHandler {
+    handler: String,
+    status_code: u16,
+    headers: Option<HashMap<String, Vec<String>>>,
+    body: Option<String>,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::heroku_web_server_config::{ErrorConfig, ErrorsConfig};
+    use crate::heroku_web_server_config::{
+        CaddyServerOpts, CaddyStaticResponseConfig, ErrorConfig, ErrorsConfig, Header,
+    };
     use std::path::PathBuf;
 
     #[test]
     fn generates_matched_response_headers_routes() {
         let heroku_config = HerokuWebServerConfig {
             headers: Some(vec![
-                Header {
+                PathMatchedHeader {
                     path_matcher: String::from("*"),
                     key: String::from("X-Foo"),
                     value: String::from("Bar"),
                 },
-                Header {
+                PathMatchedHeader {
                     path_matcher: String::from("*.html"),
                     key: String::from("X-Baz"),
                     value: String::from("Buz"),
                 },
-                Header {
+                PathMatchedHeader {
                     path_matcher: String::from("*"),
                     key: String::from("X-Zuu"),
                     value: String::from("Zem"),
@@ -327,7 +398,7 @@ mod tests {
     #[test]
     fn generates_global_response_headers_routes() {
         let heroku_config = HerokuWebServerConfig {
-            headers: Some(vec![Header {
+            headers: Some(vec![PathMatchedHeader {
                 path_matcher: String::from("*"),
                 key: String::from("X-Foo"),
                 value: String::from("Bar"),
@@ -390,4 +461,113 @@ mod tests {
             json!({"handle":[{"handler":"rewrite","uri":"index.html"},{"handler":"file_server","index_names":["index.html"],"pass_thru":false,"root":"tests/fixtures/client_side_routing/public","status_code":"200"}]})
         );
     }
+
+    #[test]
+    fn generates_static_response_handlers() {
+        let heroku_config = HerokuWebServerConfig {
+            caddy_server_opts: Some(CaddyServerOpts {
+                static_responses: Some(vec![
+                    CaddyStaticResponseConfig {
+                        host_matcher: Some("original.example.com".to_string()),
+                        path_matcher: None,
+                        status: Some(301),
+                        headers: Some(vec![
+                            Header {
+                                key: "Location".to_string(),
+                                value: "https://new.example.com{http.request.uri}".to_string(),
+                            },
+                            Header {
+                                key: "X-Redirected-From".to_string(),
+                                value: "original.example.com".to_string(),
+                            },
+                        ]),
+                        body: None,
+                    },
+                    CaddyStaticResponseConfig {
+                        host_matcher: Some("original.example.com".to_string()),
+                        path_matcher: Some("/blog/*".to_string()),
+                        status: Some(301),
+                        headers: Some(vec![Header {
+                            key: "Location".to_string(),
+                            value:
+                                "https://{http.request.host}/new-blog/{http.request.uri.path.file}"
+                                    .to_string(),
+                        }]),
+                        body: None,
+                    },
+                    CaddyStaticResponseConfig {
+                        host_matcher: None,
+                        path_matcher: Some("/api/*".to_string()),
+                        status: Some(500),
+                        headers: Some(vec![Header {
+                            key: "Content-Type".to_string(),
+                            value: "application/json".to_string(),
+                        }]),
+                        body: Some(r#"{"error":"Service not available"}"#.to_string()),
+                    },
+                ]),
+                ..CaddyServerOpts::default()
+            }),
+            ..HerokuWebServerConfig::default()
+        };
+
+        let mut handlers = vec![];
+        generate_static_response_handlers(&heroku_config, &mut handlers);
+
+        assert_eq!(handlers.len(), 3);
+
+        assert_eq!(
+            handlers[0],
+            json!({
+                "handler": "subroute",
+                "routes": [{
+                    "match": [{"host": ["original.example.com"]}],
+                    "handle": [{
+                        "handler": "static_response",
+                        "status_code": 301,
+                        "headers": {
+                            "Location": ["https://new.example.com{http.request.uri}"],
+                            "X-Redirected-From": ["original.example.com"]
+                        },
+                        "body": null
+                    }],
+                    "terminal": true
+                }]
+            })
+        );
+
+        assert_eq!(
+            handlers[1],
+            json!({
+                "handler": "subroute",
+                "routes": [{
+                    "match": [{"host": ["original.example.com"]}, {"path": ["/blog/*"]}],
+                    "handle": [{
+                        "handler": "static_response",
+                        "status_code": 301,
+                        "headers": {"Location": ["https://{http.request.host}/new-blog/{http.request.uri.path.file}"]},
+                        "body": null
+                    }],
+                    "terminal": true
+                }]
+            })
+        );
+
+        assert_eq!(
+            handlers[2],
+            json!({
+                "handler": "subroute",
+                "routes": [{
+                    "match": [{"path": ["/api/*"]}],
+                    "handle": [{
+                        "handler": "static_response",
+                        "status_code": 500,
+                        "headers": {"Content-Type": ["application/json"]},
+                        "body": r#"{"error":"Service not available"}"#
+                    }],
+                    "terminal": true
+                }]
+            })
+        );
+    }
 }

buildpacks/static-web-server/src/config_web_server.rs

@@ -56,7 +56,7 @@ pub(crate) fn config_web_server(
     );
 
     // Transform web server config to Caddy native JSON config
-    let caddy_config_json = serde_json::to_string(&caddy_json_config(heroku_config))
+    let caddy_config_json = serde_json::to_string(&caddy_json_config(&heroku_config))
         .map_err(StaticWebServerBuildpackError::Json)?;
 
     let config_path = configuration_layer.path().join("caddy.json");