feat(rust): port queue pause and unpause to native Rust (Phase 1.5)

Two queue commands in one PR — both are idempotent one-shot API
calls that share the same auth + repository resolution. Pause
exercises the new PUT method; unpause exercises the new
DELETE-with-status-check method. Together they add 5 commands to
``native`` status (3 config + scopes-send + pause + unpause = 6 of
30 commands native).

PUTs ``{"reason": "..."}`` to
``/v1/repos/<repo>/merge-queue/pause``, prints a confirmation line
with the reason and timestamp.

Safety rails match Python:

- ``--yes-i-am-sure`` skips confirmation outright.
- Interactive (TTY): prompts "Proceed? [y/N]". Anything other than
  ``y``/``yes`` aborts as a generic error.
- Non-interactive without the flag: refuses with INVALID_STATE
  (exit 7), matching Python's
  ``raise SystemExit(ExitCode.INVALID_STATE)``.

``--reason`` has a 255-char cap enforced by clap's ``value_parser``
— bad input exits 2.

DELETEs the same path. On 404 the API is telling us the queue
wasn't paused, so the command prints "Queue is not currently
paused" and exits MERGIFY_API_ERROR (matches Python). On 2xx it
prints "Queue resumed." and exits 0.

Two new methods on ``mergify_core::HttpClient``:

- ``put<B, T>(path, body) -> Result<T, CliError>`` — mirror of
  ``post``, different verb.
- ``delete_if_exists(path) -> Result<DeleteOutcome, CliError>`` —
  returns ``Deleted`` on 2xx, ``NotFound`` on 404, errors on any
  other non-success status. Lets commands like ``unpause`` give
  a friendlier 404 message without parsing error strings.

The ``resolve_token`` / ``resolve_api_url`` / ``resolve_repository``
trio is duplicated into ``mergify_queue::auth``. That's now three
copies in the tree (config simulate, ci scopes-send, queue). A
follow-up PR factors them into ``mergify_core::auth`` as soon as
a fourth command needs them.

5 new unit tests in the queue crate:

- ``parse_reason`` accepts short strings and rejects > 255 chars
- ``run`` pauses and prints the API-returned reason + timestamp
- ``run`` prints "Queue resumed" on 2xx
- ``run`` errors with MERGIFY_API_ERROR on 404 carrying the
  "not currently paused" message

End-to-end smoke tested three paths:
``queue pause --reason X -r owner/repo`` → exit 8 (missing token),
``queue unpause -r owner/repo`` → exit 8 (missing token),
``echo n | queue pause --reason X`` → exit 7 (non-TTY, no --sure).

``PORT_STATUS.toml`` flips both ``queue pause`` and ``queue
unpause`` to ``native``. Binary: 8.4 MB → 8.5 MB. 56 Rust tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Change-Id: Idba6fa38caf403fd5f4184cda462b5f7c1eb3ebf

Author: jd

Cargo.lock

@@ -63,10 +63,6 @@ status = "shimmed"
 path = ["freeze", "update"]
 status = "shimmed"
 
-[[command]]
-path = ["queue", "pause"]
-status = "shimmed"
-
 [[command]]
 path = ["queue", "show"]
 status = "shimmed"
@@ -75,10 +71,6 @@ status = "shimmed"
 path = ["queue", "status"]
 status = "shimmed"
 
-[[command]]
-path = ["queue", "unpause"]
-status = "shimmed"
-
 [[command]]
 path = ["stack", "checkout"]
 status = "shimmed"

PORT_STATUS.toml

@@ -19,6 +19,7 @@ mergify-ci = { path = "../mergify-ci" }
 mergify-config = { path = "../mergify-config" }
 mergify-core = { path = "../mergify-core" }
 mergify-py-shim = { path = "../mergify-py-shim" }
+mergify-queue = { path = "../mergify-queue" }
 tokio = { version = "1", default-features = false, features = ["macros", "rt", "time"] }
 
 [lints]

crates/mergify-cli/Cargo.toml

@@ -24,6 +24,8 @@ use mergify_config::simulate::PullRequestRef;
 use mergify_config::simulate::SimulateOptions;
 use mergify_core::OutputMode;
 use mergify_core::StdioOutput;
+use mergify_queue::pause::PauseOptions;
+use mergify_queue::unpause::UnpauseOptions;
 
 fn main() -> ExitCode {
     let argv: Vec<String> = env::args().skip(1).collect();
@@ -47,6 +49,8 @@ enum NativeCommand {
     ConfigValidate { config_file: Option<PathBuf> },
     ConfigSimulate(ConfigSimulateOpts),
     CiScopesSend(CiScopesSendOpts),
+    QueuePause(QueuePauseOpts),
+    QueueUnpause(QueueUnpauseOpts),
 }
 
 struct ConfigSimulateOpts {
@@ -67,36 +71,50 @@ struct CiScopesSendOpts {
     file_deprecated: Option<PathBuf>,
 }
 
-/// Try to recognize the invocation as a native command.
-///
-/// Returns ``None`` when the argv doesn't look like a native
-/// command — callers fall back to the Python shim, which produces
-/// the same error messages as before the port started. When the
-/// argv obviously targets a native command (contains ``config``
-/// and ``validate``/``simulate``) but clap can't parse it — e.g.
-/// the user gave a bad flag or an invalid URL — this function
-/// prints clap's formatted error to stderr and exits the process
-/// with clap's exit code (2), matching the Python CLI's behavior
-/// for argument errors.
+struct QueuePauseOpts {
+    repository: Option<String>,
+    token: Option<String>,
+    api_url: Option<String>,
+    reason: String,
+    yes_i_am_sure: bool,
+}
+
+struct QueueUnpauseOpts {
+    repository: Option<String>,
+    token: Option<String>,
+    api_url: Option<String>,
+}
+
 /// Heuristic: does argv look like the user intended a native
-/// subcommand (`config validate`, `config simulate`, `ci
-/// scopes-send`)?
+/// subcommand?
 ///
 /// Used as a fallback when clap rejects the input — if the user
-/// clearly meant a native command, surface clap's error rather than
-/// silently dispatching to the Python shim. We look for two
+/// clearly meant a native command, surface clap's error rather
+/// than silently dispatching to the Python shim. We look for two
 /// *consecutive* tokens forming a `(group, subcommand)` pair so a
 /// flag value like `--repository config` doesn't accidentally
 /// classify the invocation as native.
 fn looks_native(argv: &[String]) -> bool {
     argv.windows(2).any(|pair| {
         matches!(
             (pair[0].as_str(), pair[1].as_str()),
-            ("config", "validate" | "simulate") | ("ci", "scopes-send"),
+            ("config", "validate" | "simulate")
+                | ("ci", "scopes-send")
+                | ("queue", "pause" | "unpause"),
         )
     })
 }
 
+/// Try to recognize the invocation as a native command.
+///
+/// Returns ``None`` when the argv doesn't look like a native
+/// command — callers fall back to the Python shim, which produces
+/// the same error messages as before the port started. When the
+/// argv obviously targets a native command (per [`looks_native`])
+/// but clap can't parse it — e.g. the user gave a bad flag or an
+/// invalid URL — this function prints clap's formatted error to
+/// stderr and exits the process with clap's exit code (2),
+/// matching the Python CLI's behavior for argument errors.
 fn detect_native(argv: &[String]) -> Option<NativeCommand> {
     let looks_native = looks_native(argv);
 
@@ -154,6 +172,32 @@ fn detect_native(argv: &[String]) -> Option<NativeCommand> {
             scopes_file,
             file_deprecated,
         })),
+        Subcommands::Queue(QueueArgs {
+            repository,
+            token,
+            api_url,
+            command:
+                QueueSubcommand::Pause(PauseCliArgs {
+                    reason,
+                    yes_i_am_sure,
+                }),
+        }) => Some(NativeCommand::QueuePause(QueuePauseOpts {
+            repository,
+            token,
+            api_url,
+            reason,
+            yes_i_am_sure,
+        })),
+        Subcommands::Queue(QueueArgs {
+            repository,
+            token,
+            api_url,
+            command: QueueSubcommand::Unpause,
+        }) => Some(NativeCommand::QueueUnpause(QueueUnpauseOpts {
+            repository,
+            token,
+            api_url,
+        })),
     }
 }
 
@@ -204,6 +248,30 @@ fn run_native(cmd: NativeCommand) -> ExitCode {
                 )
                 .await
             }
+            NativeCommand::QueuePause(opts) => {
+                mergify_queue::pause::run(
+                    PauseOptions {
+                        repository: opts.repository.as_deref(),
+                        token: opts.token.as_deref(),
+                        api_url: opts.api_url.as_deref(),
+                        reason: &opts.reason,
+                        yes_i_am_sure: opts.yes_i_am_sure,
+                    },
+                    &mut output,
+                )
+                .await
+            }
+            NativeCommand::QueueUnpause(opts) => {
+                mergify_queue::unpause::run(
+                    UnpauseOptions {
+                        repository: opts.repository.as_deref(),
+                        token: opts.token.as_deref(),
+                        api_url: opts.api_url.as_deref(),
+                    },
+                    &mut output,
+                )
+                .await
+            }
         }
     });
 
@@ -231,6 +299,8 @@ enum Subcommands {
     Config(ConfigArgs),
     /// Mergify CI-related commands.
     Ci(CiArgs),
+    /// Manage the Mergify merge queue.
+    Queue(QueueArgs),
 }
 
 #[derive(clap::Args)]
@@ -326,3 +396,44 @@ struct ScopesSendCliArgs {
     #[arg(long = "file", short = 'f', hide = true)]
     file_deprecated: Option<PathBuf>,
 }
+
+#[derive(clap::Args)]
+struct QueueArgs {
+    /// Mergify or GitHub token. Falls back to ``MERGIFY_TOKEN`` and
+    /// then ``GITHUB_TOKEN`` env vars.
+    #[arg(long, short = 't', global = true)]
+    token: Option<String>,
+
+    /// Mergify API URL. Falls back to ``MERGIFY_API_URL`` env var,
+    /// then to the default.
+    #[arg(long = "api-url", short = 'u', global = true)]
+    api_url: Option<String>,
+
+    /// Repository full name (owner/repo). Falls back to
+    /// ``GITHUB_REPOSITORY`` env var.
+    #[arg(long, short = 'r', global = true)]
+    repository: Option<String>,
+
+    #[command(subcommand)]
+    command: QueueSubcommand,
+}
+
+#[derive(Subcommand)]
+enum QueueSubcommand {
+    /// Pause the merge queue for the repository.
+    Pause(PauseCliArgs),
+    /// Unpause the merge queue for the repository.
+    Unpause,
+}
+
+#[derive(clap::Args)]
+struct PauseCliArgs {
+    /// Reason for pausing the queue (max 255 characters).
+    #[arg(long, value_parser = mergify_queue::pause::parse_reason)]
+    reason: String,
+
+    /// Skip the confirmation prompt. Required in non-interactive
+    /// sessions.
+    #[arg(long = "yes-i-am-sure", default_value_t = false)]
+    yes_i_am_sure: bool,
+}

crates/mergify-cli/src/main.rs

@@ -40,6 +40,15 @@ pub enum ApiFlavor {
     Mergify,
 }
 
+/// Outcome of [`Client::delete_if_exists`].
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum DeleteOutcome {
+    /// 2xx: the resource was deleted.
+    Deleted,
+    /// 404: the resource didn't exist (or was already gone).
+    NotFound,
+}
+
 /// Retry policy for transient failures. Only 5xx responses and
 /// connect/timeout errors are retried; 4xx responses are never
 /// retried — those are caller errors and retrying would hide bugs.
@@ -128,6 +137,29 @@ impl Client {
         self.execute(self.inner.post(url).json(body)).await
     }
 
+    /// PUT `body` as JSON to `path` and deserialize the JSON
+    /// response as `T`.
+    pub async fn put<B: Serialize + ?Sized, T: DeserializeOwned>(
+        &self,
+        path: &str,
+        body: &B,
+    ) -> Result<T, CliError> {
+        let url = self.join(path)?;
+        self.execute(self.inner.put(url).json(body)).await
+    }
+
+    /// DELETE `path`, returning whether the resource existed.
+    ///
+    /// Returns `Ok(DeleteOutcome::Deleted)` on 2xx responses and
+    /// `Ok(DeleteOutcome::NotFound)` on 404 — useful for idempotent
+    /// "turn this thing off if it's on" operations where 404 means
+    /// "nothing to do". 4xx-other and 5xx map to the normal API
+    /// errors.
+    pub async fn delete_if_exists(&self, path: &str) -> Result<DeleteOutcome, CliError> {
+        let url = self.join(path)?;
+        self.execute_status(self.inner.delete(url)).await
+    }
+
     fn join(&self, path: &str) -> Result<Url, CliError> {
         // `Url::join` accepts absolute URLs and protocol-relative
         // paths (`//host/...`), which would let a caller-supplied
@@ -143,6 +175,58 @@ impl Client {
             .map_err(|e| self.api_error(format!("invalid path {path:?}: {e}")))
     }
 
+    /// Execute a request that cares only about the HTTP status.
+    ///
+    /// Used by [`Self::delete_if_exists`] — the response body (if
+    /// any) is discarded.
+    async fn execute_status(
+        &self,
+        builder: reqwest::RequestBuilder,
+    ) -> Result<DeleteOutcome, CliError> {
+        let mut backoff = self.retry.initial_backoff;
+        let mut last_message = String::from("HTTP request failed without response");
+
+        for attempt in 0..self.retry.max_attempts {
+            let Some(cloned) = builder.try_clone() else {
+                return Err(self.api_error(
+                    "request body is not cloneable (streaming?) — cannot retry".into(),
+                ));
+            };
+            let req = match &self.token {
+                Some(token) => cloned.bearer_auth(token),
+                None => cloned,
+            };
+
+            match req.send().await {
+                Ok(resp) => {
+                    let status = resp.status();
+                    if status.is_success() {
+                        return Ok(DeleteOutcome::Deleted);
+                    }
+                    if status == StatusCode::NOT_FOUND {
+                        return Ok(DeleteOutcome::NotFound);
+                    }
+                    last_message = error_message(status, resp).await;
+                    if status.is_server_error() && attempt + 1 < self.retry.max_attempts {
+                        tokio::time::sleep(backoff).await;
+                        backoff *= 2;
+                        continue;
+                    }
+                    return Err(self.api_error(last_message));
+                }
+                Err(e) if is_transient(&e) && attempt + 1 < self.retry.max_attempts => {
+                    last_message = format!("network error: {e}");
+                    tokio::time::sleep(backoff).await;
+                    backoff *= 2;
+                }
+                Err(e) => {
+                    return Err(self.api_error(format!("request failed: {e}")));
+                }
+            }
+        }
+        Err(self.api_error(last_message))
+    }
+
     async fn execute<T: DeserializeOwned>(
         &self,
         builder: reqwest::RequestBuilder,

crates/mergify-core/src/http.rs

@@ -22,7 +22,7 @@ pub mod output;
 
 pub use error::CliError;
 pub use exit_code::ExitCode;
-pub use http::{ApiFlavor, Client as HttpClient, RetryPolicy};
+pub use http::{ApiFlavor, Client as HttpClient, DeleteOutcome, RetryPolicy};
 pub use output::{Output, OutputMode, StdioOutput};
 
 /// Compile-time version string taken from the crate package metadata

crates/mergify-core/src/lib.rs

@@ -0,0 +1,24 @@
+[package]
+name = "mergify-queue"
+version = "0.0.0"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+description = "Native implementation of `mergify queue` subcommands."
+publish = false
+
+[dependencies]
+mergify-core = { path = "../mergify-core" }
+serde = { version = "1.0", features = ["derive"] }
+url = "2"
+
+[dev-dependencies]
+serde_json = "1.0"
+temp-env = { version = "0.3", features = ["async_closure"] }
+tokio = { version = "1", default-features = false, features = ["macros", "rt", "time"] }
+wiremock = "0.6"
+
+[lints]
+workspace = true