fastly: Add surrogate-key purging (#14228)

Author: Turbo87

crates/crates_io_fastly/examples/purge.rs

@@ -1,20 +1,35 @@
 use std::str::FromStr;
 
-use clap::Parser;
+use clap::{ArgGroup, Parser};
 use crates_io_fastly::Fastly;
 use secrecy::SecretString;
 
 /// Arguments accepted by the purge example.
 #[derive(Debug, Parser)]
-#[command(about = "Purge cached content using the crates.io Fastly client")]
+#[command(
+    about = "Purge cached content using the crates.io Fastly client",
+    group(
+        ArgGroup::new("operation")
+            .required(true)
+            .args(["url", "service_id"])
+    )
+)]
 struct Options {
     /// Fastly API token used to authenticate the purge request.
     #[arg(long, env = "FASTLY_API_TOKEN", hide_env_values = true)]
     api_token: SecretString,
 
     /// URL to purge, without the scheme.
     #[arg(long, value_name = "DOMAIN/PATH")]
-    url: PurgeUrl,
+    url: Option<PurgeUrl>,
+
+    /// Fastly service containing the objects associated with the key.
+    #[arg(long, value_name = "ID", requires = "key")]
+    service_id: Option<String>,
+
+    /// Surrogate key to purge.
+    #[arg(value_name = "KEY", requires = "service_id")]
+    key: Option<String>,
 }
 
 /// Domain and path extracted from a URL argument.
@@ -53,12 +68,17 @@ async fn main() -> Result<(), crates_io_fastly::Error> {
     let options = Options::parse();
     let fastly = Fastly::new(options.api_token);
 
-    fastly.purge(&options.url.domain, &options.url.path).await
+    match (options.url, options.service_id, options.key) {
+        (Some(url), None, None) => fastly.purge(&url.domain, &url.path).await,
+        (None, Some(service_id), Some(key)) => fastly.purge_surrogate_key(&service_id, &key).await,
+        _ => unreachable!("clap validates exactly one complete purge operation"),
+    }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use clap::error::ErrorKind;
 
     #[test]
     fn rejects_url_with_http_scheme() {
@@ -86,10 +106,60 @@ mod tests {
 
         assert_eq!(
             options.url,
-            PurgeUrl {
+            Some(PurgeUrl {
                 domain: "static.crates.io".into(),
                 path: "crates/serde/serde-1.0.0.crate".into(),
-            }
+            })
         );
+        assert_eq!(options.service_id, None);
+        assert_eq!(options.key, None);
+    }
+
+    #[test]
+    fn parses_surrogate_key_purge() {
+        let options = Options::try_parse_from([
+            "purge",
+            "--api-token",
+            "test-token",
+            "--service-id",
+            "static-service-id",
+            "release:serde@1.0.0+metadata",
+        ])
+        .unwrap();
+
+        assert_eq!(options.url, None);
+        assert_eq!(options.service_id.as_deref(), Some("static-service-id"));
+        assert_eq!(options.key.as_deref(), Some("release:serde@1.0.0+metadata"));
+    }
+
+    #[test]
+    fn rejects_service_id_without_key() {
+        let error = Options::try_parse_from([
+            "purge",
+            "--api-token",
+            "test-token",
+            "--service-id",
+            "static-service-id",
+        ])
+        .unwrap_err();
+
+        assert_eq!(error.kind(), ErrorKind::MissingRequiredArgument);
+    }
+
+    #[test]
+    fn rejects_multiple_operations() {
+        let error = Options::try_parse_from([
+            "purge",
+            "--api-token",
+            "test-token",
+            "--url",
+            "static.crates.io/crates/serde/serde-1.0.0.crate",
+            "--service-id",
+            "static-service-id",
+            "crate:serde",
+        ])
+        .unwrap_err();
+
+        assert_eq!(error.kind(), ErrorKind::ArgumentConflict);
     }
 }

crates/crates_io_fastly/src/lib.rs

@@ -73,6 +73,18 @@ impl Fastly {
         Ok(())
     }
 
+    /// Invalidates all objects associated with a surrogate key on a Fastly service.
+    ///
+    /// The key uses Fastly's native representation without CloudFront's leading `#` marker.
+    ///
+    /// More information on Fastly's APIs for cache invalidations can be found here:
+    /// <https://developer.fastly.com/reference/api/purging/>
+    #[instrument(skip(self))]
+    pub async fn purge_surrogate_key(&self, service_id: &str, key: &str) -> Result<(), Error> {
+        let url = format!("{}/service/{service_id}/purge/{key}", self.api_base_url);
+        self.send_purge_request(url).await
+    }
+
     /// Invalidates a path on Fastly
     ///
     /// This method takes a domain and path and invalidates the cached content
@@ -89,7 +101,11 @@ impl Fastly {
 
         let path = path.trim_start_matches('/');
         let url = format!("{}/purge/{domain}/{path}", self.api_base_url);
+        self.send_purge_request(url).await
+    }
 
+    /// Sends an authenticated purge request to Fastly.
+    async fn send_purge_request(&self, url: String) -> Result<(), Error> {
         trace!(?url);
 
         debug!("sending invalidation request to Fastly");
@@ -205,6 +221,27 @@ mod tests {
             .unwrap();
     }
 
+    #[tokio::test]
+    async fn purges_surrogate_key() {
+        let mut server = mock_server().await;
+        let _mock = server
+            .mock(
+                "POST",
+                "/service/static-service-id/purge/release:serde@1.0.0+metadata",
+            )
+            .match_header("fastly-key", TEST_TOKEN)
+            .with_status(200)
+            .expect(1)
+            .create_async()
+            .await;
+
+        let client = client_with_server(&server);
+        client
+            .purge_surrogate_key("static-service-id", "release:serde@1.0.0+metadata")
+            .await
+            .unwrap();
+    }
+
     #[tokio::test]
     async fn rejects_wildcards() {
         let server = mock_server().await;