feat: send X-Tower-Idempotency-Key on deploy

crates/tower-cmd/src/deploy.rs

@@ -1,13 +1,20 @@
+use chrono::{DateTime, Duration, Utc};
 use clap::{Arg, ArgMatches, Command};
 use config::{Config, Towerfile};
 use std::convert::From;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 
 use crate::{output, util};
 use tower_api::apis::configuration::Configuration;
 use tower_package::{Package, PackageSpec};
 use tower_telemetry::debug;
 
+/// How far in the past a returned version's `created_at` must be before we treat
+/// it as a reuse (rather than a fresh insert) for the stdout hint. A fresh
+/// deploy stamps `created_at` at request time, so anything older than this was
+/// created by an earlier deploy that shared the same idempotency key.
+const REUSE_AGE_THRESHOLD: Duration = Duration::seconds(60);
+
 pub fn deploy_cmd() -> Command {
     Command::new("deploy")
         .arg(
@@ -38,6 +45,22 @@ pub fn deploy_cmd() -> Command {
                 .action(clap::ArgAction::SetTrue)
                 .conflicts_with("environment"),
         )
+        .arg(
+            Arg::new("idempotency-key")
+                .long("idempotency-key")
+                .help(
+                    "Reuse the existing version deployed with this key instead of creating a new one. \
+                     Defaults to the current git commit SHA when the working tree is clean.",
+                )
+                .conflicts_with("no-idempotency-key"),
+        )
+        .arg(
+            Arg::new("no-idempotency-key")
+                .long("no-idempotency-key")
+                .help("Never send an idempotency key, even on a clean git tree")
+                .action(clap::ArgAction::SetTrue)
+                .conflicts_with("idempotency-key"),
+        )
         .about("Deploy your latest code to Tower")
 }
 
@@ -59,9 +82,29 @@ pub enum DeployTarget {
     All,
 }
 
+/// Resolves the idempotency key to send with the deploy, in precedence order:
+///
+/// 1. `--no-idempotency-key` → never send a key.
+/// 2. `--idempotency-key <value>` → send that exact value.
+/// 3. Otherwise auto-detect the git `HEAD` SHA, but only when the working tree
+///    is clean (a dirty tree gets no key, so every deploy creates a new version).
+fn resolve_idempotency_key(args: &ArgMatches, dir: &Path) -> Option<String> {
+    if args.get_flag("no-idempotency-key") {
+        debug!("--no-idempotency-key set; suppressing idempotency key");
+        return None;
+    }
+
+    if let Some(key) = args.get_one::<String>("idempotency-key") {
+        return Some(key.clone());
+    }
+
+    util::git::clean_head_sha(dir)
+}
+
 pub async fn do_deploy(config: Config, args: &ArgMatches) {
     let dir = resolve_path(args);
     let create_app = args.get_flag("create");
+    let idempotency_key = resolve_idempotency_key(args, &dir);
 
     let target = if args.get_flag("all") {
         DeployTarget::All
@@ -71,7 +114,7 @@ pub async fn do_deploy(config: Config, args: &ArgMatches) {
         DeployTarget::Environment("default".to_string())
     };
 
-    if let Err(err) = deploy_from_dir(config, dir, create_app, target).await {
+    if let Err(err) = deploy_from_dir(config, dir, create_app, target, idempotency_key).await {
         match err {
             crate::Error::ApiDeployError { source } => {
                 output::tower_error_and_die(source, "Deploying app failed")
@@ -100,6 +143,7 @@ pub async fn deploy_from_dir(
     dir: PathBuf,
     create_app: bool,
     target: DeployTarget,
+    idempotency_key: Option<String>,
 ) -> Result<(), crate::Error> {
     debug!("Building package from directory: {:?}", dir);
 
@@ -135,14 +179,15 @@ pub async fn deploy_from_dir(
     };
 
     spinner.success();
-    do_deploy_package(api_config, package, &towerfile, target).await
+    do_deploy_package(api_config, package, &towerfile, target, idempotency_key).await
 }
 
 async fn do_deploy_package(
     api_config: Configuration,
     package: Package,
     towerfile: &Towerfile,
     target: DeployTarget,
+    idempotency_key: Option<String>,
 ) -> Result<(), crate::Error> {
     let (environment, all_environments) = match &target {
         DeployTarget::All => (None, true),
@@ -155,6 +200,7 @@ async fn do_deploy_package(
         package,
         environment,
         all_environments,
+        idempotency_key.as_deref(),
     )
     .await;
 
@@ -172,22 +218,71 @@ async fn do_deploy_package(
                 ),
             };
             output::success(&line);
+
+            // Only emit the informational hint in normal mode; in JSON mode a
+            // bare line would corrupt the structured output.
+            if output::get_output_mode().is_normal() {
+                if let Some(hint) = reuse_hint(&version, idempotency_key.as_deref()) {
+                    output::muted(&hint);
+                }
+            }
+
             Ok(())
         }
         Err(err) => Err(crate::Error::ApiDeployError { source: err }),
     }
 }
 
+/// Builds the "reused an existing version" hint, or `None` when the deploy
+/// created a fresh version.
+///
+/// We treat the returned version as a reuse when (a) we sent an idempotency key,
+/// (b) the server echoed it back on the version, and (c) the version's
+/// `created_at` is meaningfully older than now — i.e. it predates this deploy.
+fn reuse_hint(version: &tower_api::models::AppVersion, sent_key: Option<&str>) -> Option<String> {
+    let sent_key = sent_key?;
+
+    if version.idempotency_key.as_deref() != Some(sent_key) {
+        return None;
+    }
+
+    let created_at = DateTime::parse_from_rfc3339(&version.created_at)
+        .ok()?
+        .with_timezone(&Utc);
+
+    if Utc::now().signed_duration_since(created_at) < REUSE_AGE_THRESHOLD {
+        return None;
+    }
+
+    Some(format!(
+        "No changes since commit {} (deployed on {})",
+        sent_key,
+        util::dates::format(created_at),
+    ))
+}
+
 #[cfg(test)]
 mod tests {
-    use super::deploy_cmd;
+    use super::*;
+    use tower_api::models::AppVersion;
 
     fn parse(args: &[&str]) -> Result<clap::ArgMatches, clap::Error> {
         let mut full = vec!["deploy"];
         full.extend_from_slice(args);
         deploy_cmd().try_get_matches_from(full)
     }
 
+    fn version_with(idempotency_key: Option<&str>, created_at: &str) -> AppVersion {
+        AppVersion {
+            created_at: created_at.to_string(),
+            parameters: vec![],
+            towerfile: String::new(),
+            version: "v3".to_string(),
+            idempotency_key: idempotency_key.map(|s| s.to_string()),
+            content_checksum: None,
+        }
+    }
+
     #[test]
     fn no_args_uses_defaults() {
         let m = parse(&[]).unwrap();
@@ -276,4 +371,75 @@ mod tests {
         let err = parse(&["--help"]).unwrap_err();
         assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
     }
+
+    #[test]
+    fn idempotency_key_flag() {
+        let m = parse(&["--idempotency-key", "abc123"]).unwrap();
+        assert_eq!(
+            m.get_one::<String>("idempotency-key").map(|s| s.as_str()),
+            Some("abc123")
+        );
+    }
+
+    #[test]
+    fn no_idempotency_key_flag() {
+        let m = parse(&["--no-idempotency-key"]).unwrap();
+        assert!(m.get_flag("no-idempotency-key"));
+    }
+
+    #[test]
+    fn idempotency_key_and_no_idempotency_key_conflict() {
+        let err = parse(&["--idempotency-key", "abc", "--no-idempotency-key"]).unwrap_err();
+        assert_eq!(err.kind(), clap::error::ErrorKind::ArgumentConflict);
+    }
+
+    #[test]
+    fn resolve_key_prefers_explicit_flag() {
+        let m = parse(&["--idempotency-key", "explicit"]).unwrap();
+        // A non-existent path guarantees git auto-detection can't interfere.
+        let key = resolve_idempotency_key(&m, Path::new("/nonexistent/path"));
+        assert_eq!(key.as_deref(), Some("explicit"));
+    }
+
+    #[test]
+    fn resolve_key_opt_out_wins_over_git() {
+        let m = parse(&["--no-idempotency-key"]).unwrap();
+        // Even pointed at the (clean-or-dirty) repo we're in, opt-out yields None.
+        let key = resolve_idempotency_key(&m, Path::new("."));
+        assert_eq!(key, None);
+    }
+
+    #[test]
+    fn resolve_key_none_outside_git() {
+        let m = parse(&[]).unwrap();
+        let key = resolve_idempotency_key(&m, Path::new("/nonexistent/path"));
+        assert_eq!(key, None);
+    }
+
+    #[test]
+    fn reuse_hint_none_without_sent_key() {
+        let version = version_with(Some("abc"), "2020-01-01T00:00:00Z");
+        assert_eq!(reuse_hint(&version, None), None);
+    }
+
+    #[test]
+    fn reuse_hint_none_when_key_mismatch() {
+        let version = version_with(Some("other"), "2020-01-01T00:00:00Z");
+        assert_eq!(reuse_hint(&version, Some("abc")), None);
+    }
+
+    #[test]
+    fn reuse_hint_none_for_freshly_created_version() {
+        // created_at "now" → not a reuse, no hint.
+        let now = Utc::now().to_rfc3339();
+        let version = version_with(Some("abc"), &now);
+        assert_eq!(reuse_hint(&version, Some("abc")), None);
+    }
+
+    #[test]
+    fn reuse_hint_present_for_old_matching_version() {
+        let version = version_with(Some("abc123"), "2020-01-01T00:00:00Z");
+        let hint = reuse_hint(&version, Some("abc123")).expect("expected a reuse hint");
+        assert!(hint.contains("No changes since commit abc123"));
+    }
 }

crates/tower-cmd/src/mcp.rs

@@ -812,7 +812,20 @@ impl TowerService {
         let env = request.environment.unwrap_or_else(|| "default".to_string());
         let deploy_target = deploy::DeployTarget::Environment(env);
 
-        match deploy::deploy_from_dir(self.config.clone(), working_dir, true, deploy_target).await {
+        // Auto-detect the idempotency key from git (clean tree HEAD) just like
+        // the CLI deploy command does, so repeated deploys of unchanged source
+        // collapse to a single AppVersion server-side.
+        let idempotency_key = crate::util::git::clean_head_sha(&working_dir);
+
+        match deploy::deploy_from_dir(
+            self.config.clone(),
+            working_dir,
+            true,
+            deploy_target,
+            idempotency_key,
+        )
+        .await
+        {
             Ok(_) => Self::text_success("Deploy completed successfully".to_string()),
             Err(e) => Self::error_result("Deploy failed", e),
         }

crates/tower-cmd/src/output.rs

@@ -110,6 +110,19 @@ pub fn success(msg: &str) {
     success_with_data(msg, None::<serde_json::Value>);
 }
 
+pub fn muted(msg: &str) {
+    if get_output_mode().is_json() {
+        let response = serde_json::json!({
+            "result": "muted",
+            "message": msg
+        });
+        json(&response);
+    } else {
+        let line = msg.dimmed();
+        write(&line);
+    }
+}
+
 pub fn success_with_data<T: Serialize>(msg: &str, data: Option<T>) {
     if get_output_mode().is_json() {
         let mut response = serde_json::json!({

crates/tower-cmd/src/util/deploy.rs

@@ -19,6 +19,7 @@ pub async fn upload_file_with_progress(
     endpoint_url: String,
     file_path: PathBuf,
     content_type: &str,
+    idempotency_key: Option<&str>,
     progress_cb: Box<dyn Fn(u64, u64) + Send + Sync>,
 ) -> Result<DeployAppResponse, Error<DeployAppError>> {
     let package_hash = match compute_sha256_file(&file_path).await {
@@ -57,6 +58,13 @@ pub async fn upload_file_with_progress(
         .header("Content-Encoding", "gzip")
         .body(Body::wrap_stream(progress_stream));
 
+    // When supplied, ask the server to reuse an existing AppVersion that was
+    // deployed with the same key (e.g. a git commit SHA) instead of creating a
+    // new one.
+    if let Some(key) = idempotency_key {
+        req = req.header("X-Tower-Idempotency-Key", key);
+    }
+
     // Add authorization if available. Mirrors the generated tower-api client: prefer a
     // bearer token (interactive session), otherwise fall back to the API key header set
     // when TOWER_API_KEY is configured.
@@ -107,6 +115,7 @@ pub async fn deploy_app_package(
     package: Package,
     environment: Option<&str>,
     all_environments: bool,
+    idempotency_key: Option<&str>,
 ) -> Result<DeployAppResponse, Error<DeployAppError>> {
     let progress_bar = Arc::new(Mutex::new(output::progress_bar("Deploying to Tower...")));
 
@@ -150,6 +159,7 @@ pub async fn deploy_app_package(
         url,
         package_path,
         "application/tar",
+        idempotency_key,
         progress_callback,
     )
     .await?;