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>"] --> Endpoint["Typed&nbsp;Endpoint<br/>structs"]
  end

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

%% ── Flows ─────────────────────────────
  CLI --> Builder
  Endpoint --> 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,Endpoint 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
# jenkins-sdk = { version = "0.1", default-features = false, features = ["blocking-client"] }

⚡Quick Start

Async Example

use jenkins_sdk::{JenkinsAsync};
use jenkins_sdk::core::{QueueLength, JobsInfo, ExecutorsInfoEndpoint};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), jenkins_sdk::core::JenkinsError> {
    // Build a client with some sugar ‑‑>
    let j = JenkinsAsync::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.request(&QueueLength).await?;
    println!("queue items = {}", q["items"].as_array().map_or(0, |a| a.len()));

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

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

    Ok(())
}

Sync Example

// Compile with `default-features = false, features = ["blocking-client"]`.
use jenkins_sdk::{JenkinsBlocking};
use jenkins_sdk::core::QueueLength;
use std::time::Duration;

fn main() -> Result<(), jenkins_sdk::core::JenkinsError> {
    let j = JenkinsBlocking::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.request(&QueueLength)?;
    println!("queue items = {}", q["items"].as_array().unwrap().len());
    Ok(())
}

📜 Changelog

See CHANGELOG.md for release notes.

📃 License

This project is licensed under the MIT License.