jenkins-sdk 0.1.14

Jenkins API SDK in pure Rust with async and blocking clients, typed endpoints, pluggable middleware, and zero magic strings.
Documentation

πŸ‡ΊπŸ‡Έ English Β· πŸ‡¨πŸ‡³ δΈ­ζ–‡Β Β Β Β Β Β |Β Β Β Β Β  TableΒ ofΒ Contents ↗️

✨ Features

Feature Description
Async and Blocking Choose the I/O model at compile-time: tokio by default, enable blocking-client for sync.
Type-safe endpoints Each REST call is a zero-cost struct implementing Endpoint; responses deserialize into concrete types.
Composable middleware Ready-made CSRF-crumb fetching, retries, custom transports β€” just chain builders.
No magic strings URL build, query/form encoding, error mapping & JSON decoding handled for you.
Pure Rust, tiny deps Built on reqwest + rustls; no C bindings, minimal footprint.

πŸ–Ό 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

Category Description Method Path Status
Job Retrieve jobs information GET /api/json βœ…
Job Fetch job details GET /job/:name/api/json βœ…
Job Fetch last-build information GET /job/:name/lastBuild/api/json βœ…
Job Fetch console logs GET /job/:name/:id/consoleText βœ…
Job Fetch last-build console log GET /job/:name/lastBuild/consoleText βœ…
Job Trigger builds with parameters POST /job/:name/buildWithParameters βœ…
Job Stop ongoing builds POST /job/:name/:id/stop βœ…
Queue Retrieve build queue details GET /queue/api/json βœ…
Executor Retrieve executor statistics and status GET /computer/api/json βœ…

πŸ“₯ 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

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::{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.