jenkins-sdk-rust

📦 Jenkins API SDK in pure Rust — async and blocking clients, typed endpoints, pluggable middleware & zero magic strings.

✨ Features

🖼 Architecture

flowchart LR
%% ── Your App ──────────────────────────
  subgraph A["Your App"]
    direction TB
    CLI["Binary / Service"]
  end

%% ── SDK Core ──────────────────────────
  subgraph S["jenkins-sdk-rust"]
    direction LR
    Builder["Client&nbsp;Builder"] --> Client["Jenkins<br/>Async&nbsp;/&nbsp;Blocking"] --> Middleware["Middleware<br/><sub>retry • crumbs • custom</sub>"] --> Service["Core&nbsp;Services<br/><sub>jobs • queue • system • ...</sub>"]
  end

%% ── External ──────────────────────────
  subgraph J["Jenkins&nbsp;Master"]
    direction TB
    API["REST&nbsp;API"]
  end

%% ── Flows ─────────────────────────────
  CLI --> Builder
  Service --> API
%% ── Styling ───────────────────────────
  classDef app fill:#e3f2fd,stroke:#1976d2,stroke-width:1px;
  classDef sdk fill:#e8f5e9,stroke:#388e3c,stroke-width:1px;
  classDef server fill:#fff8e1,stroke:#f57f17,stroke-width:1px;
  class CLI app;
  class Builder,Client,Middleware,Service sdk;
  class API server;

🚀 Supported API Matrix

📥 Installation

# quickest
cargo add jenkins-sdk

# Cargo.toml — async client (default)
[dependencies]
jenkins-sdk = "0.1"

# blocking client (choose one TLS backend)
# jenkins-sdk = { version = "0.1", default-features = false, features = ["blocking", "rustls"] }
# jenkins-sdk = { version = "0.1", default-features = false, features = ["blocking", "native-tls"] }

⚡Quick Start

Base URL can include a sub-path (e.g. https://example.com/jenkins); a trailing / is optional, the SDK normalises it for you.

Async Example

use jenkins_sdk::Client;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), jenkins_sdk::Error> {
  // Build a client with some sugar ‑‑>
  let j = Client::builder("https://jenkins.example.com")?
    .auth_basic("user", "apitoken")
    .no_system_proxy()
    .with_retry(3, Duration::from_millis(300))
    .with_crumb(Duration::from_secs(1800))
    .build()?;

  // Queue length
  let q: serde_json::Value = j.queue().list(None).await?;
  println!("queue items = {}", q["items"].as_array().map_or(0, |a| a.len()));

  // Executor stats (typed deserialisation)
  let mut ex = j.computers().executors_info().await?;
  ex = ex.calc_idle();
  println!("idle executors = {}", ex.idle_executors);

  // Raw job list
  let jobs: serde_json::Value = j.jobs().list().await?;
  println!("first job = {}", jobs["jobs"][0]["name"]);

  Ok(())
}

Blocking Example

// Compile with `default-features = false, features = ["blocking", "rustls"]`
// or `default-features = false, features = ["blocking", "native-tls"]`.
use jenkins_sdk::BlockingClient;
use std::time::Duration;

fn main() -> Result<(), jenkins_sdk::Error> {
  let j = BlockingClient::builder("https://jenkins.example.com")?
    .auth_basic("user", "apitoken")
    .timeout(Duration::from_secs(15))
    .with_retry(2, Duration::from_millis(250))
    .build()?;

  let q: serde_json::Value = j.queue().list(None)?;
  println!("queue items = {}", q["items"].as_array().unwrap().len());
  Ok(())
}

Any Endpoint (Unstable Raw Request)

Enable the unstable-raw feature and use raw::Request + execute() when an API endpoint isn't modeled yet:

use jenkins_sdk::Client;
use jenkins_sdk::raw::Request;

# async fn demo(client: Client) -> Result<(), jenkins_sdk::Error> {
  let resp = client
    .execute(&Request::get(["api", "json"]).query_pair("tree", "jobs[name]"))
    .await?;
  let root: serde_json::Value = resp.json()?;
  println!("{root:?}");
  # Ok(())
  #
}

Note: when using the blocking client inside a Tokio runtime, call it via tokio::task::spawn_blocking or a dedicated thread pool.

📜 Changelog

See CHANGELOG.md for release notes.

📃 License

This project is licensed under the MIT License.