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).

## ``queue pause``

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.

## ``queue unpause``

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.

## HttpClient additions

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.

## Shared auth helpers

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.

## Tests

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,6 +71,20 @@ struct CiScopesSendOpts {
     file_deprecated: Option<PathBuf>,
 }
 
+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>,
+}
+
 /// Try to recognize the invocation as a native command.
 ///
 /// Returns ``None`` when the argv doesn't look like a native
@@ -84,7 +102,9 @@ fn detect_native(argv: &[String]) -> Option<NativeCommand> {
         let has_config_sub = argv.iter().any(|a| a == "validate" || a == "simulate");
         let has_ci = argv.iter().any(|a| a == "ci");
         let has_ci_sub = argv.iter().any(|a| a == "scopes-send");
-        (has_config && has_config_sub) || (has_ci && has_ci_sub)
+        let has_queue = argv.iter().any(|a| a == "queue");
+        let has_queue_sub = argv.iter().any(|a| a == "pause" || a == "unpause");
+        (has_config && has_config_sub) || (has_ci && has_ci_sub) || (has_queue && has_queue_sub)
     };
 
     let parsed = match CliRoot::try_parse_from(
@@ -141,6 +161,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,
+        })),
     }
 }
 
@@ -191,6 +237,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
+            }
         }
     });
 
@@ -218,6 +288,8 @@ enum Subcommands {
     Config(ConfigArgs),
     /// Mergify CI-related commands.
     Ci(CiArgs),
+    /// Manage the Mergify merge queue.
+    Queue(QueueArgs),
 }
 
 #[derive(clap::Args)]
@@ -313,3 +385,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