Skip to content

armgit / kokon

Public Imported from GitHub
0

Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.

44.6 KB
Raw Blame
//! Inference adapter for stable-diffusion.cpp's native async API (`/sdcpp/v1/*`).
//!
//! This is the only module that knows the sd-server wire format. Schemas were verified
//! against examples/server (api.md, routes_sdcpp.cpp, async_jobs.h) at commit 3f8527a:
//!   GET  /sdcpp/v1/capabilities
//!   POST /sdcpp/v1/img_gen            -> 202 {id, kind, status, created, poll_url}
//!   GET  /sdcpp/v1/jobs/{id}          -> {status: queued|generating|completed|failed|cancelled, ...}
//!   POST /sdcpp/v1/jobs/{id}/cancel   -> 200, or 409 while generating (not interruptible)
//!   POST /sdcpp/v1/upscale            -> 200 {images, upscaler, scale, width, height} (sync ESRGAN)
//!   POST /sdcpp/v1/text_gen           -> SSE delta/done/error (Kokon's engine: prompt enhancer)
//!
//! Request objects are merged field by field over the server's launch defaults
//! (`SDGenerationParams::from_json_str`), so omitted fields keep the CLI values.

use std::time::Duration;

use base64::Engine;
use serde::{Deserialize, Serialize};

use crate::error::{AppError, ErrorCode};

// ---------------------------------------------------------------------------------------
// Request
// ---------------------------------------------------------------------------------------

#[derive(Debug, Clone, Default, Serialize, PartialEq)]
pub struct Guidance {
    pub txt_cfg: f32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub img_cfg: Option<f32>,
}

#[derive(Debug, Clone, Default, Serialize, PartialEq)]
pub struct SampleParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sample_method: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub scheduler: Option<String>,
    pub sample_steps: u32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub flow_shift: Option<f32>,
    /// Exact noise schedule, used verbatim (steps = len - 1, no shift).
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub custom_sigmas: Vec<f32>,
    pub guidance: Guidance,
}

#[derive(Debug, Clone, Default, Serialize, PartialEq)]
pub struct VaeTilingParams {
    pub enabled: bool,
    /// Image pixels; 0 = backend default (256).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tile_size_w: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tile_size_h: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub target_overlap: Option<f32>,
}

/// Second pass of `img_gen` (`hires`): the first result is upscaled to the target size
/// (`upscaler` = built-in filter or an ESRGAN model stem from `--hires-upscalers-dir`)
/// and re-sampled with `denoising_strength`. Reference latents and the inpaint mask are
/// carried into the second pass (src/pipeline/image.cpp, commit 3f8527a).
#[derive(Debug, Clone, Default, Serialize, PartialEq)]
pub struct HiresParams {
    pub enabled: bool,
    pub upscaler: String,
    pub target_width: u32,
    pub target_height: u32,
    /// Effective refine steps (the server scales the schedule by the denoise strength).
    pub steps: u32,
    pub denoising_strength: f32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub upscale_tile_size: Option<u32>,
}

/// Body of `POST /sdcpp/v1/img_gen`. Images are base64 PNG strings.
#[derive(Debug, Clone, Default, Serialize, PartialEq)]
pub struct ImgGenRequest {
    pub prompt: String,
    pub negative_prompt: String,
    pub width: u32,
    pub height: u32,
    pub seed: i64,
    pub batch_count: u32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub strength: Option<f32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub init_image: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mask_image: Option<String>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub ref_images: Vec<String>,
    /// Our images already arrive at exact working geometry, so input transforms are
    /// disabled (`mode=none`) to guarantee no crop/stretch happens server-side.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub image_preprocess: Vec<String>,
    /// e.g. "resize_before_vae=false": for Qwen-Image 2.1 the server otherwise resizes every
    /// reference to the output's area before encoding (pipeline/image.cpp), smaller ones too.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ref_image_args: Option<String>,
    pub sample_params: SampleParams,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub vae_tiling_params: Option<VaeTilingParams>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hires: Option<HiresParams>,
    /// e.g. "easycache"; applies to both passes. Omitted = server default.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cache_mode: Option<String>,
    /// e.g. "threshold=0.2".
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cache_option: Option<String>,
    /// LoRAs, by path relative to the server's `--lora-model-dir`.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub lora: Vec<LoraParam>,
    pub output_format: String,
    /// We write our own metadata after post-processing.
    pub embed_image_metadata: bool,
}

#[derive(Debug, Clone, Serialize, PartialEq)]
pub struct LoraParam {
    pub path: String,
    pub multiplier: f32,
}

pub fn b64(bytes: &[u8]) -> String {
    base64::engine::general_purpose::STANDARD.encode(bytes)
}

pub fn b64_decode(s: &str) -> Result<Vec<u8>, AppError> {
    let s = s.split_once(";base64,").map(|(_, d)| d).unwrap_or(s);
    base64::engine::general_purpose::STANDARD
        .decode(s.trim())
        .map_err(|e| AppError::new(ErrorCode::GenerationFailed, "The inference server returned an unreadable image.").detail(e.to_string()))
}

// ---------------------------------------------------------------------------------------
// Responses
// ---------------------------------------------------------------------------------------

#[derive(Debug, Clone, Deserialize, Serialize, Default)]
pub struct CapModel {
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub stem: String,
    #[serde(default)]
    pub path: String,
}

#[derive(Debug, Clone, Deserialize, Serialize, Default)]
pub struct CapLimits {
    #[serde(default)]
    pub min_width: u32,
    #[serde(default)]
    pub max_width: u32,
    #[serde(default)]
    pub min_height: u32,
    #[serde(default)]
    pub max_height: u32,
    #[serde(default)]
    pub max_batch_count: u32,
    #[serde(default)]
    pub max_queue_size: u32,
}

#[derive(Debug, Clone, Deserialize, Serialize, Default, PartialEq)]
pub struct CapUpscaler {
    #[serde(default)]
    pub name: String,
    /// True for a model-backed upscaler (false for built-in filters).
    #[serde(default)]
    pub model: bool,
    /// Usable with `POST /sdcpp/v1/upscale` (RGB ESRGAN models).
    #[serde(default)]
    pub image_upscale: bool,
}

#[derive(Debug, Clone, Deserialize, Serialize, Default)]
pub struct Capabilities {
    #[serde(default)]
    pub model: CapModel,
    #[serde(default)]
    pub supported_modes: Vec<String>,
    #[serde(default)]
    pub samplers: Vec<String>,
    #[serde(default)]
    pub schedulers: Vec<String>,
    #[serde(default)]
    pub output_formats: Vec<String>,
    #[serde(default)]
    pub limits: CapLimits,
    #[serde(default)]
    pub features_by_mode: serde_json::Value,
    #[serde(default)]
    pub defaults_by_mode: serde_json::Value,
    #[serde(default)]
    pub upscalers: Vec<CapUpscaler>,
    /// Whether any RGB ESRGAN model is available for `/sdcpp/v1/upscale`.
    #[serde(default)]
    pub upscale: bool,
    /// Whether `/sdcpp/v1/text_gen` works with the loaded model (Kokon's engine builds only).
    #[serde(default)]
    pub text_generation: bool,
    /// The server's own name when it is not sd-server: `kokon-engine-mac` (Kokon's Mac engine).
    #[serde(default)]
    pub engine: String,
}

impl Capabilities {
    pub fn img_feature(&self, name: &str) -> bool {
        self.features_by_mode.get("img_gen").and_then(|f| f.get(name)).and_then(|v| v.as_bool()).unwrap_or(false)
    }
    pub fn supports_img_gen(&self) -> bool {
        self.supported_modes.iter().any(|m| m == "img_gen")
    }
    /// The server is Kokon's Mac engine (`engine-mac/`), not sd-server.
    pub fn is_mac_engine(&self) -> bool {
        self.engine == crate::config::MAC_ENGINE_EXE
    }
    /// What in `req` Kokon's Mac engine cannot do yet, in the user's words; None when it can, and always for
    /// sd-server. It edits with reference images when it has the vision projector (`ref_images` in its features), and
    /// takes an init image and a mask (brushed edits, extending an image) from the build that advertises them.
    pub fn mac_engine_unsupported(&self, req: &ImgGenRequest) -> Option<&'static str> {
        if !self.is_mac_engine() {
            None
        } else if (req.init_image.is_some() && !self.img_feature("init_image"))
            || (req.mask_image.is_some() && !self.img_feature("mask_image"))
        {
            Some("edits of a brushed area or extending images")
        } else if !req.ref_images.is_empty() && !self.img_feature("ref_images") {
            Some("edits")
        } else if req.hires.as_ref().is_some_and(|h| h.enabled) {
            Some("second passes")
        } else {
            None
        }
    }
    /// True when `name` is a model-backed upscaler the server can load (hires and,
    /// if `image` is set, the standalone upscale endpoint).
    pub fn has_upscaler(&self, name: &str, image: bool) -> bool {
        self.upscalers.iter().any(|u| u.model && u.name == name && (!image || u.image_upscale))
    }
    /// True when the loaded diffusion model is the file we expect (path compare is
    /// case/slash-insensitive, since Windows paths come back with forward slashes).
    pub fn model_matches(&self, expected: &std::path::Path) -> bool {
        let norm = |s: &str| s.replace('\\', "/").to_ascii_lowercase();
        let want = norm(&expected.to_string_lossy());
        let got = norm(&self.model.path);
        if !got.is_empty() {
            return got == want || want.ends_with(&got) || got.ends_with(&want);
        }
        let file = expected.file_name().map(|f| f.to_string_lossy().to_ascii_lowercase()).unwrap_or_default();
        self.model.name.to_ascii_lowercase() == file
    }
}

#[derive(Debug, Clone, Deserialize)]
pub struct JobAccepted {
    pub id: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum BackendJobStatus {
    Queued,
    Generating,
    Completed,
    Failed,
    Cancelled,
    #[serde(other)]
    Unknown,
}

#[derive(Debug, Clone, Deserialize, Default)]
pub struct JobError {
    #[serde(default)]
    pub code: String,
    #[serde(default)]
    pub message: String,
}

#[derive(Debug, Clone, Deserialize)]
pub struct JobImage {
    #[serde(default)]
    pub index: u32,
    pub b64_json: String,
}

#[derive(Debug, Clone, Deserialize, Default)]
pub struct JobResult {
    #[serde(default)]
    pub images: Vec<JobImage>,
    #[serde(default)]
    pub output_format: String,
}

#[derive(Debug, Clone, Deserialize)]
pub struct BackendJob {
    pub id: String,
    pub status: BackendJobStatus,
    #[serde(default)]
    pub queue_position: u32,
    #[serde(default)]
    pub result: Option<JobResult>,
    #[serde(default)]
    pub error: Option<JobError>,
}

/// Body of `POST /sdcpp/v1/upscale`.
#[derive(Debug, Clone, Serialize, PartialEq)]
pub struct UpscaleRequest {
    pub image: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub upscaler: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tile_size: Option<u32>,
    pub output_format: String,
}

#[derive(Debug, Clone, Deserialize)]
pub struct UpscaleResponse {
    #[serde(default)]
    pub images: Vec<JobImage>,
    #[serde(default)]
    pub upscaler: String,
    #[serde(default)]
    pub scale: u32,
    #[serde(default)]
    pub width: u32,
    #[serde(default)]
    pub height: u32,
}

/// Sampling of `POST /sdcpp/v1/text_gen` (`temperature` 0 = greedy).
#[derive(Debug, Clone, Copy, Serialize, PartialEq)]
pub struct TextSampling {
    pub temperature: f32,
    pub top_p: f32,
    pub top_k: u32,
    pub presence_penalty: f32,
    /// Negative = the server picks one.
    pub seed: i64,
}

/// Body of `POST /sdcpp/v1/text_gen`: one chat turn for the LLM the model uses as its text
/// encoder.
#[derive(Debug, Clone, Serialize, PartialEq)]
pub struct TextGenRequest {
    pub prompt: String,
    /// Always sent; "" means no system turn (the server has no built-in prompt).
    pub system_prompt: String,
    /// Base64 images shown before the prompt (`<image1>`, `<image2>`, ... when several).
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub images: Vec<String>,
    pub max_tokens: u32,
    pub sampling: TextSampling,
    pub stream: bool,
}

#[derive(Debug, Clone, Deserialize, Default, PartialEq)]
pub struct TextUsage {
    #[serde(default)]
    pub prompt_tokens: u32,
    #[serde(default)]
    pub completion_tokens: u32,
}

/// The `done` event of `text_gen` (the whole reply with `stream: false`).
#[derive(Debug, Clone, Deserialize, Default)]
pub struct TextGenDone {
    #[serde(default)]
    pub text: String,
    /// "stop", "length" or "cancelled".
    #[serde(default)]
    pub finish_reason: String,
    #[serde(default)]
    pub seed: i64,
    #[serde(default)]
    pub usage: TextUsage,
    /// Seconds: prepare_s, image_s, prefill_s, decode_s.
    #[serde(default)]
    pub timings: serde_json::Value,
}

/// Splits a `text/event-stream` body into (event, data) pairs. Bytes are buffered until the
/// blank line that ends an event, so a chunk may end inside a line or a UTF-8 character.
/// Comment lines (": waiting for the model") are skipped.
#[derive(Default)]
pub struct SseParser {
    buf: Vec<u8>,
}

impl SseParser {
    pub fn push(&mut self, chunk: &[u8]) -> Vec<(String, String)> {
        self.buf.extend(chunk.iter().filter(|&&b| b != b'\r'));
        let mut events = Vec::new();
        while let Some(end) = self.buf.windows(2).position(|w| w == b"\n\n") {
            let block: Vec<u8> = self.buf.drain(..end + 2).collect();
            let text = String::from_utf8_lossy(&block[..end]);
            let (mut event, mut data) = (String::new(), Vec::new());
            for line in text.lines() {
                if let Some(v) = line.strip_prefix("event:") {
                    event = v.trim().to_string();
                } else if let Some(v) = line.strip_prefix("data:") {
                    data.push(v.strip_prefix(' ').unwrap_or(v));
                }
            }
            if !data.is_empty() || !event.is_empty() {
                events.push((if event.is_empty() { "message".into() } else { event }, data.join("\n")));
            }
        }
        events
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CancelOutcome {
    Cancelled,
    /// The backend cannot interrupt a job that is already generating.
    NotInterruptible,
    AlreadyFinished,
    NotFound,
}

// ---------------------------------------------------------------------------------------
// Client
// ---------------------------------------------------------------------------------------

#[derive(Clone)]
pub struct SdcppClient {
    base: String,
    http: reqwest::Client,
}

fn unavailable(e: impl std::fmt::Display) -> AppError {
    AppError::new(ErrorCode::ServerUnavailable, "The inference server is not reachable.").detail(e.to_string())
}

impl SdcppClient {
    pub fn new(port: u16) -> Self {
        let http = reqwest::Client::builder()
            .no_proxy()
            .connect_timeout(Duration::from_secs(3))
            .build()
            .expect("http client");
        Self { base: format!("http://127.0.0.1:{port}"), http }
    }

    pub fn base_url(&self) -> &str {
        &self.base
    }

    pub async fn capabilities(&self, timeout: Duration) -> Result<Capabilities, AppError> {
        let r = self.http.get(format!("{}/sdcpp/v1/capabilities", self.base)).timeout(timeout).send().await.map_err(unavailable)?;
        if !r.status().is_success() {
            return Err(AppError::new(ErrorCode::ServerUnavailable, "The inference server did not report its capabilities.")
                .detail(format!("HTTP {}", r.status())));
        }
        r.json::<Capabilities>().await.map_err(|e| {
            AppError::new(ErrorCode::Unsupported, "The program on the inference port does not look like stable-diffusion.cpp.").detail(e.to_string())
        })
    }

    pub async fn submit(&self, req: &ImgGenRequest) -> Result<JobAccepted, AppError> {
        let body = serde_json::to_vec(req).map_err(AppError::internal)?;
        let r = self
            .http
            .post(format!("{}/sdcpp/v1/img_gen", self.base))
            .header("Content-Type", "application/json")
            .body(body)
            .timeout(Duration::from_secs(120))
            .send()
            .await
            .map_err(unavailable)?;
        let status = r.status().as_u16();
        let text = r.text().await.unwrap_or_default();
        match status {
            200 | 202 => serde_json::from_str(&text)
                .map_err(|e| AppError::new(ErrorCode::Unsupported, "Unexpected reply from the inference server.").detail(format!("{e}: {text}"))),
            429 => Err(AppError::new(ErrorCode::QueueFull, "The inference server queue is full.").detail(text)),
            400 => Err(AppError::new(ErrorCode::MalformedRequest, "The inference server rejected the request.").detail(text)),
            _ => Err(AppError::new(ErrorCode::GenerationFailed, "The inference server returned an error.").detail(format!("HTTP {status}: {text}"))),
        }
    }

    /// Synchronous ESRGAN pass. It waits for the server's generation lock, so the
    /// timeout covers a job that might still be finishing.
    pub async fn upscale(&self, req: &UpscaleRequest) -> Result<UpscaleResponse, AppError> {
        let body = serde_json::to_vec(req).map_err(AppError::internal)?;
        let r = self
            .http
            .post(format!("{}/sdcpp/v1/upscale", self.base))
            .header("Content-Type", "application/json")
            .body(body)
            .timeout(Duration::from_secs(600))
            .send()
            .await
            .map_err(unavailable)?;
        let status = r.status().as_u16();
        let text = r.text().await.unwrap_or_default();
        let server_error = || serde_json::from_str::<serde_json::Value>(&text).ok().and_then(|v| v["error"].as_str().map(str::to_owned)).unwrap_or_else(|| text.clone());
        match status {
            200 => {
                let resp: UpscaleResponse = serde_json::from_str(&text)
                    .map_err(|e| AppError::new(ErrorCode::Unsupported, "Unexpected reply from the upscaler.").detail(format!("{e}: {}", &text[..text.len().min(300)])))?;
                if resp.images.is_empty() {
                    return Err(AppError::new(ErrorCode::GenerationFailed, "The upscaler returned no image."));
                }
                Ok(resp)
            }
            404 => Err(AppError::new(ErrorCode::Unsupported, "This sd-server build has no upscale endpoint.").detail(text)),
            400 => Err(AppError::new(ErrorCode::MalformedRequest, "The upscaler rejected the image.").detail(server_error())),
            _ => Err(AppError::new(ErrorCode::GenerationFailed, "The upscaler failed.").detail(format!("HTTP {status}: {}", server_error()))),
        }
    }

    /// Streams `POST /sdcpp/v1/text_gen`: `on_delta` gets each piece of text as it is written.
    /// `cancelled` is checked a few times a second; returning true drops the connection, which
    /// stops the generation on the server. `idle` limits the wait for the next chunk (the
    /// server first waits for a running generation, then reads the images).
    pub async fn text_gen(&self, req: &TextGenRequest, idle: Duration, mut on_delta: impl FnMut(&str), cancelled: impl Fn() -> bool) -> Result<TextGenDone, AppError> {
        use futures_util::StreamExt;
        let cancel_err = || AppError::new(ErrorCode::Cancelled, "Cancelled.");
        let failed = |detail: String| AppError::new(ErrorCode::GenerationFailed, "The prompt enhancer failed.").detail(detail);
        let body = serde_json::to_vec(&TextGenRequest { stream: true, ..req.clone() }).map_err(AppError::internal)?;
        let r = self
            .http
            .post(format!("{}/sdcpp/v1/text_gen", self.base))
            .header("Content-Type", "application/json")
            .header("Accept", "text/event-stream")
            .body(body)
            .send()
            .await
            .map_err(unavailable)?;
        let status = r.status().as_u16();
        if status != 200 {
            let text = r.text().await.unwrap_or_default();
            let msg = serde_json::from_str::<serde_json::Value>(&text).ok().and_then(|v| v["error"].as_str().map(str::to_owned)).unwrap_or(text);
            return Err(match status {
                404 => AppError::new(ErrorCode::Unsupported, "This inference engine cannot write prompts.").detail(msg),
                400 => AppError::new(ErrorCode::MalformedRequest, "The inference server rejected the prompt request.").detail(msg),
                _ => failed(format!("HTTP {status}: {msg}")),
            });
        }
        let mut stream = r.bytes_stream();
        let mut parser = SseParser::default();
        let mut last_chunk = std::time::Instant::now();
        loop {
            let chunk = tokio::select! {
                c = stream.next() => c,
                _ = tokio::time::sleep(Duration::from_millis(200)) => {
                    if cancelled() {
                        return Err(cancel_err());
                    }
                    if last_chunk.elapsed() > idle {
                        return Err(failed(format!("no answer for {} s", idle.as_secs())));
                    }
                    continue;
                }
            };
            let bytes = match chunk {
                Some(Ok(b)) => b,
                Some(Err(e)) => return Err(failed(format!("connection broke: {e}"))),
                None => return Err(failed("the stream ended without an answer".into())),
            };
            last_chunk = std::time::Instant::now();
            for (event, data) in parser.push(&bytes) {
                let json = serde_json::from_str::<serde_json::Value>(&data).ok();
                match event.as_str() {
                    "delta" => {
                        if let Some(t) = json.as_ref().and_then(|v| v["text"].as_str()) {
                            on_delta(t);
                        }
                    }
                    "done" => {
                        return serde_json::from_str(&data)
                            .map_err(|e| AppError::new(ErrorCode::Unsupported, "Unexpected reply from the prompt enhancer.").detail(format!("{e}: {data}")));
                    }
                    "error" => return Err(failed(json.as_ref().and_then(|v| v["error"].as_str().map(str::to_owned)).unwrap_or(data))),
                    _ => {}
                }
            }
            if cancelled() {
                return Err(cancel_err());
            }
        }
    }

    pub async fn job(&self, id: &str) -> Result<BackendJob, AppError> {
        let r = self
            .http
            .get(format!("{}/sdcpp/v1/jobs/{}", self.base, id))
            .timeout(Duration::from_secs(60))
            .send()
            .await
            .map_err(unavailable)?;
        match r.status().as_u16() {
            200 => r.json().await.map_err(|e| AppError::new(ErrorCode::Unsupported, "Unexpected job status format.").detail(e.to_string())),
            404 | 410 => Err(AppError::new(ErrorCode::NotFound, "The inference job is no longer known to the server.")),
            s => Err(AppError::new(ErrorCode::GenerationFailed, "Could not read job status.").detail(format!("HTTP {s}"))),
        }
    }

    pub async fn cancel(&self, id: &str) -> Result<CancelOutcome, AppError> {
        let r = self
            .http
            .post(format!("{}/sdcpp/v1/jobs/{}/cancel", self.base, id))
            .timeout(Duration::from_secs(10))
            .send()
            .await
            .map_err(unavailable)?;
        let status = r.status().as_u16();
        Ok(match status {
            200 => {
                let job: Option<BackendJob> = r.json().await.ok();
                match job.map(|j| j.status) {
                    Some(BackendJobStatus::Cancelled) | None => CancelOutcome::Cancelled,
                    _ => CancelOutcome::AlreadyFinished,
                }
            }
            409 => CancelOutcome::NotInterruptible,
            404 | 410 => CancelOutcome::NotFound,
            _ => CancelOutcome::NotInterruptible,
        })
    }
}

/// Parses `stable-diffusion.cpp version X, commit abc123` from `--help` output.
pub fn parse_version_banner(text: &str) -> Option<String> {
    let line = text.lines().find(|l| l.contains("stable-diffusion.cpp version"))?;
    Some(line.trim().trim_start_matches("stable-diffusion.cpp").trim().to_string())
}

/// A one-shot HTTP server on 127.0.0.1 for tests: answers the first request with `status`
/// and `chunks` (sent `gap` apart, then the connection closes) and hands back the request body.
#[cfg(test)]
pub(crate) async fn fake_server(status: u16, content_type: &'static str, chunks: Vec<String>, gap: Duration) -> (u16, tokio::sync::oneshot::Receiver<String>) {
    use tokio::io::{AsyncReadExt, AsyncWriteExt};
    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
    let port = listener.local_addr().unwrap().port();
    let (tx, rx) = tokio::sync::oneshot::channel();
    tokio::spawn(async move {
        let (mut sock, _) = listener.accept().await.unwrap();
        let mut req = Vec::new();
        let mut buf = [0u8; 8192];
        // Headers, then Content-Length bytes of body.
        let body = loop {
            let n = sock.read(&mut buf).await.unwrap();
            req.extend_from_slice(&buf[..n]);
            let text = String::from_utf8_lossy(&req).to_string();
            if let Some(end) = text.find("\r\n\r\n") {
                let len = text.lines().find_map(|l| l.to_ascii_lowercase().strip_prefix("content-length:").map(|v| v.trim().parse::<usize>().unwrap())).unwrap_or(0);
                if req.len() >= end + 4 + len {
                    break String::from_utf8_lossy(&req[end + 4..end + 4 + len]).to_string();
                }
            }
        };
        let _ = tx.send(body);
        let head = format!("HTTP/1.1 {status} X\r\nContent-Type: {content_type}\r\nConnection: close\r\n\r\n");
        if sock.write_all(head.as_bytes()).await.is_err() {
            return;
        }
        for c in chunks {
            tokio::time::sleep(gap).await;
            if sock.write_all(c.as_bytes()).await.is_err() {
                return; // the client hung up (cancel)
            }
        }
    });
    (port, rx)
}

/// SSE chunks of a `text_gen` that writes `pieces` and ends with `done`.
#[cfg(test)]
pub(crate) fn sse_answer(pieces: &[&str], finish: &str) -> Vec<String> {
    let mut v = vec![": waiting for the model\n\n".to_string()];
    for p in pieces {
        v.push(format!("event: delta\ndata: {}\n\n", serde_json::json!({ "text": p })));
    }
    let done = serde_json::json!({ "text": pieces.concat(), "finish_reason": finish, "seed": 7, "usage": { "prompt_tokens": 60, "completion_tokens": pieces.len() } });
    v.push(format!("event: done\ndata: {done}\n\n"));
    v
}

#[cfg(test)]
mod tests {
    use super::*;

    fn text_req() -> TextGenRequest {
        TextGenRequest {
            prompt: "un gatto".into(),
            system_prompt: "sys".into(),
            images: vec![],
            max_tokens: 64,
            sampling: TextSampling { temperature: 0.7, top_p: 0.8, top_k: 20, presence_penalty: 1.5, seed: 7 },
            stream: false,
        }
    }

    #[tokio::test]
    async fn text_gen_streams_deltas_and_returns_done() {
        let (port, body) = fake_server(200, "text/event-stream", sse_answer(&["A tabby", " cat on", " a sill."], "stop"), Duration::from_millis(5)).await;
        let mut seen = Vec::new();
        let done = SdcppClient::new(port).text_gen(&text_req(), Duration::from_secs(10), |d| seen.push(d.to_string()), || false).await.unwrap();
        assert_eq!(seen, ["A tabby", " cat on", " a sill."]);
        assert_eq!((done.text.as_str(), done.finish_reason.as_str(), done.seed, done.usage.completion_tokens), ("A tabby cat on a sill.", "stop", 7, 3));
        let sent: serde_json::Value = serde_json::from_str(&body.await.unwrap()).unwrap();
        assert_eq!(sent["stream"], true, "always streamed");
        assert_eq!((sent["prompt"].as_str(), sent["system_prompt"].as_str()), (Some("un gatto"), Some("sys")));
    }

    #[tokio::test]
    async fn text_gen_errors_and_cancel() {
        // A failure after the stream started.
        let chunks = vec!["event: delta\ndata: {\"text\":\"A\"}\n\n".into(), "event: error\ndata: {\"error\":\"out of memory\"}\n\n".into()];
        let (port, _) = fake_server(200, "text/event-stream", chunks, Duration::from_millis(1)).await;
        let e = SdcppClient::new(port).text_gen(&text_req(), Duration::from_secs(10), |_| {}, || false).await.unwrap_err();
        assert_eq!(e.code, ErrorCode::GenerationFailed);
        assert_eq!(e.detail.as_deref(), Some("out of memory"));
        // An engine without the endpoint, and a model without text generation.
        let (port, _) = fake_server(404, "text/plain", vec!["Not Found".into()], Duration::ZERO).await;
        assert_eq!(SdcppClient::new(port).text_gen(&text_req(), Duration::from_secs(10), |_| {}, || false).await.unwrap_err().code, ErrorCode::Unsupported);
        let (port, _) = fake_server(400, "application/json", vec!["{\"error\":\"model has no text generation\"}".into()], Duration::ZERO).await;
        let e = SdcppClient::new(port).text_gen(&text_req(), Duration::from_secs(10), |_| {}, || false).await.unwrap_err();
        assert_eq!((e.code, e.detail.as_deref()), (ErrorCode::MalformedRequest, Some("model has no text generation")));
        // The stream ends without `done`.
        let (port, _) = fake_server(200, "text/event-stream", vec!["event: delta\ndata: {\"text\":\"A\"}\n\n".into()], Duration::ZERO).await;
        assert_eq!(SdcppClient::new(port).text_gen(&text_req(), Duration::from_secs(10), |_| {}, || false).await.unwrap_err().code, ErrorCode::GenerationFailed);
        // Cancel while the server is silent (waiting for the model).
        let (port, _) = fake_server(200, "text/event-stream", sse_answer(&["late"], "stop"), Duration::from_secs(30)).await;
        let t = std::time::Instant::now();
        let cancel_at = t + Duration::from_millis(300);
        let e = SdcppClient::new(port).text_gen(&text_req(), Duration::from_secs(60), |_| {}, || std::time::Instant::now() > cancel_at).await.unwrap_err();
        assert_eq!(e.code, ErrorCode::Cancelled);
        assert!(t.elapsed() < Duration::from_secs(3), "{:?}", t.elapsed());
        // No answer within `idle`.
        let (port, _) = fake_server(200, "text/event-stream", sse_answer(&["late"], "stop"), Duration::from_secs(30)).await;
        let e = SdcppClient::new(port).text_gen(&text_req(), Duration::from_millis(400), |_| {}, || false).await.unwrap_err();
        assert!(e.code == ErrorCode::GenerationFailed && e.detail.unwrap().contains("no answer"));
    }

    #[test]
    fn request_serialization_matches_native_schema() {
        let req = ImgGenRequest {
            prompt: "change the red car to a black Porsche".into(),
            negative_prompt: String::new(),
            width: 1920,
            height: 1088,
            seed: 42,
            batch_count: 1,
            strength: None,
            init_image: None,
            mask_image: None,
            ref_images: vec!["AAA".into(), "BBB".into()],
            image_preprocess: vec!["target=ref,mode=none".into()],
            ref_image_args: None,
            sample_params: SampleParams {
                sample_method: Some("euler".into()),
                scheduler: None,
                sample_steps: 30,
                flow_shift: None,
                custom_sigmas: Vec::new(),
                guidance: Guidance { txt_cfg: 6.0, img_cfg: None },
            },
            vae_tiling_params: None,
            hires: None,
            cache_mode: None,
            cache_option: None,
            lora: Vec::new(),
            output_format: "png".into(),
            embed_image_metadata: false,
        };
        let v: serde_json::Value = serde_json::to_value(&req).unwrap();
        assert_eq!(v["width"], 1920);
        assert_eq!(v["height"], 1088);
        assert_eq!(v["sample_params"]["sample_method"], "euler");
        assert_eq!(v["sample_params"]["sample_steps"], 30);
        assert_eq!(v["sample_params"]["guidance"]["txt_cfg"], 6.0);
        assert!(v["sample_params"].get("scheduler").is_none(), "omitted -> backend default");
        assert!(v["sample_params"]["guidance"].get("img_cfg").is_none());
        assert_eq!(v["ref_images"][0], "AAA");
        assert_eq!(v["ref_images"][1], "BBB", "reference order preserved");
        assert!(v.get("init_image").is_none());
        assert!(v.get("mask_image").is_none());
        assert!(v.get("strength").is_none());
        assert!(v.get("vae_tiling_params").is_none());
        assert_eq!(v["embed_image_metadata"], false);
        assert_eq!(v["image_preprocess"][0], "target=ref,mode=none");
        assert!(v.get("hires").is_none() && v.get("cache_mode").is_none() && v.get("cache_option").is_none(), "server defaults apply");
        assert!(v["sample_params"].get("custom_sigmas").is_none(), "default schedule");
        // Turbo: exact schedule.
        let turbo = ImgGenRequest { sample_params: SampleParams { custom_sigmas: vec![1.0, 0.5, 0.0], ..req.sample_params.clone() }, ..req };
        let v = serde_json::to_value(&turbo).unwrap();
        assert_eq!(v["sample_params"]["custom_sigmas"][1], 0.5);
    }

    #[test]
    fn hires_cache_and_tiling_serialization() {
        let req = ImgGenRequest {
            prompt: "a cabin".into(),
            width: 1376,
            height: 768,
            hires: Some(HiresParams {
                enabled: true,
                upscaler: "RealESRGAN_x4plus".into(),
                target_width: 2048,
                target_height: 1152,
                steps: 6,
                denoising_strength: 0.35,
                upscale_tile_size: None,
            }),
            cache_mode: Some("easycache".into()),
            cache_option: Some("threshold=0.2".into()),
            vae_tiling_params: Some(VaeTilingParams { enabled: false, ..Default::default() }),
            ..Default::default()
        };
        let v = serde_json::to_value(&req).unwrap();
        assert_eq!(v["hires"]["enabled"], true);
        assert_eq!(v["hires"]["upscaler"], "RealESRGAN_x4plus");
        assert_eq!((v["hires"]["target_width"].as_u64(), v["hires"]["target_height"].as_u64()), (Some(2048), Some(1152)));
        assert_eq!(v["hires"]["steps"], 6);
        assert!((v["hires"]["denoising_strength"].as_f64().unwrap() - 0.35).abs() < 1e-6);
        assert!(v["hires"].get("upscale_tile_size").is_none());
        assert!(v["hires"].get("scale").is_none(), "target size wins over scale");
        assert_eq!(v["cache_mode"], "easycache");
        assert_eq!(v["cache_option"], "threshold=0.2");
        // Only `enabled` is sent, so the server keeps its configured tile size.
        assert_eq!(v["vae_tiling_params"], serde_json::json!({"enabled": false}));
    }

    #[test]
    fn upscale_request_and_response() {
        let r = UpscaleRequest { image: "AAA".into(), upscaler: Some("RealESRGAN_x4plus".into()), tile_size: None, output_format: "png".into() };
        assert_eq!(serde_json::to_value(&r).unwrap(), serde_json::json!({"image": "AAA", "upscaler": "RealESRGAN_x4plus", "output_format": "png"}));
        let resp: UpscaleResponse = serde_json::from_str(
            r#"{"images":[{"index":0,"b64_json":"iVBOR"}],"upscaler":"RealESRGAN_x4plus","scale":4,"repeats":1,"width":5504,"height":3072,"output_format":"png"}"#,
        )
        .unwrap();
        assert_eq!((resp.scale, resp.width, resp.height), (4, 5504, 3072));
        assert_eq!(resp.images[0].b64_json, "iVBOR");
    }

    #[test]
    fn job_status_parsing() {
        let done = r#"{"completed":1791295347,"created":1791295301,"error":null,"id":"job_1","kind":"img_gen","queue_position":0,
            "result":{"images":[{"b64_json":"iVBORw0K","index":0}],"output_format":"png"},"started":1791295302,"status":"completed"}"#;
        let j: BackendJob = serde_json::from_str(done).unwrap();
        assert_eq!(j.status, BackendJobStatus::Completed);
        assert_eq!(j.result.unwrap().images[0].b64_json, "iVBORw0K");
        let failed = r#"{"id":"job_2","status":"failed","error":{"code":"generation_failed","message":"generate_image returned empty results"}}"#;
        let j: BackendJob = serde_json::from_str(failed).unwrap();
        assert_eq!(j.status, BackendJobStatus::Failed);
        assert_eq!(j.error.unwrap().code, "generation_failed");
        let weird: BackendJob = serde_json::from_str(r#"{"id":"x","status":"paused"}"#).unwrap();
        assert_eq!(weird.status, BackendJobStatus::Unknown);
    }

    #[test]
    fn capabilities_parsing_and_model_match() {
        let caps: Capabilities = serde_json::from_str(r#"{"model":{"name":"qwen-image-2.1-UC-Q4_K_M.gguf","path":"C:/AI/sdcpp/models/qwen21/qwen-image-2.1-UC-Q4_K_M.gguf","stem":"x"},
            "supported_modes":["img_gen"],"features_by_mode":{"img_gen":{"cancel_generating":false,"ref_images":true}},
            "limits":{"max_width":4096,"max_height":4096,"min_width":64,"min_height":64,"max_batch_count":8,"max_queue_size":64}}"#).unwrap();
        assert!(caps.supports_img_gen());
        assert!(caps.img_feature("ref_images"));
        assert!(!caps.img_feature("cancel_generating"));
        assert!(caps.model_matches(std::path::Path::new(r"C:\AI\sdcpp\models\qwen21\qwen-image-2.1-UC-Q4_K_M.gguf")));
        assert!(!caps.model_matches(std::path::Path::new(r"C:\AI\sdcpp\models\other.gguf")));
        assert_eq!(caps.limits.max_width, 4096);
        assert!(!caps.upscale && caps.upscalers.is_empty(), "older servers: no upscaler fields");
        assert!(!caps.text_generation, "official engines: no text endpoint");
        let caps: Capabilities = serde_json::from_str(r#"{"text_generation":true}"#).unwrap();
        assert!(caps.text_generation);

        let caps: Capabilities = serde_json::from_str(
            r#"{"upscale":true,"upscalers":[{"name":"Lanczos","model":false,"image_upscale":false},
                {"name":"RealESRGAN_x4plus","model":true,"image_upscale":true},{"name":"ltx_latent","model":true,"image_upscale":false}]}"#,
        )
        .unwrap();
        assert!(caps.upscale);
        assert!(caps.has_upscaler("RealESRGAN_x4plus", true));
        assert!(caps.has_upscaler("ltx_latent", false) && !caps.has_upscaler("ltx_latent", true));
        assert!(!caps.has_upscaler("Lanczos", false), "built-in filters are not models");
    }

    #[test]
    fn text_gen_request_matches_api() {
        let r = TextGenRequest {
            prompt: "un gatto".into(),
            system_prompt: String::new(),
            images: vec![],
            max_tokens: 512,
            sampling: TextSampling { temperature: 0.7, top_p: 0.8, top_k: 20, presence_penalty: 1.5, seed: 42 },
            stream: true,
        };
        let v = serde_json::to_value(&r).unwrap();
        assert_eq!(v["system_prompt"], "", "always sent: the server has no built-in prompt");
        assert!(v.get("images").is_none());
        assert_eq!((v["max_tokens"].as_u64(), v["sampling"]["top_k"].as_u64(), v["sampling"]["seed"].as_i64()), (Some(512), Some(20), Some(42)));
        assert!((v["sampling"]["presence_penalty"].as_f64().unwrap() - 1.5).abs() < 1e-6);
        let v = serde_json::to_value(TextGenRequest { images: vec!["AAA".into()], ..r }).unwrap();
        assert_eq!(v["images"][0], "AAA");
    }

    #[test]
    fn mac_engine_capabilities() {
        // As `kokon-engine-mac serve` answers (EngineServer.capabilities).
        let caps: Capabilities = serde_json::from_str(r#"{"engine":"kokon-engine-mac","model":{"name":"q.gguf","path":"/m/q.gguf","stem":"q"},
            "supported_modes":["img_gen"],"features_by_mode":{"img_gen":{"ref_images":false,"lora":false,"cancel_generating":true}},
            "upscale":false,"upscalers":[],"text_generation":false}"#).unwrap();
        assert!(caps.is_mac_engine() && caps.supports_img_gen());
        assert!(caps.img_feature("cancel_generating") && !caps.img_feature("lora") && !caps.img_feature("ref_images"));
        assert!(caps.model_matches(std::path::Path::new("/m/q.gguf")));
        let t2i = ImgGenRequest { prompt: "a fox".into(), width: 1024, height: 1024, ..Default::default() };
        assert_eq!(caps.mac_engine_unsupported(&t2i), None);
        let edit = ImgGenRequest { ref_images: vec!["png".into()], ..t2i.clone() };
        assert_eq!(caps.mac_engine_unsupported(&edit), Some("edits"), "no vision projector");
        let inpaint = ImgGenRequest { mask_image: Some("png".into()), ..t2i.clone() };
        assert_eq!(caps.mac_engine_unsupported(&inpaint), Some("edits of a brushed area or extending images"));
        // Started with --llm_vision: edits with references run; a mask only on a build that advertises it.
        let vision: Capabilities = serde_json::from_str(r#"{"engine":"kokon-engine-mac","supported_modes":["img_gen"],
            "features_by_mode":{"img_gen":{"ref_images":true}}}"#).unwrap();
        assert_eq!(vision.mac_engine_unsupported(&edit), None);
        assert!(vision.mac_engine_unsupported(&inpaint).is_some());
        let masks: Capabilities = serde_json::from_str(r#"{"engine":"kokon-engine-mac","supported_modes":["img_gen"],
            "features_by_mode":{"img_gen":{"ref_images":true,"init_image":true,"mask_image":true}}}"#).unwrap();
        let brushed = ImgGenRequest { init_image: Some("png".into()), ref_images: vec!["png".into()], ..inpaint.clone() };
        assert_eq!(masks.mac_engine_unsupported(&brushed), None);
        let init_only: Capabilities = serde_json::from_str(r#"{"engine":"kokon-engine-mac","supported_modes":["img_gen"],
            "features_by_mode":{"img_gen":{"ref_images":true,"init_image":true}}}"#).unwrap();
        assert!(init_only.mac_engine_unsupported(&brushed).is_some(), "a mask the engine does not advertise");
        let hires = ImgGenRequest { hires: Some(HiresParams { enabled: true, ..Default::default() }), ..t2i.clone() };
        assert_eq!(caps.mac_engine_unsupported(&hires), Some("second passes"));
        // sd-server: no engine field, nothing refused here.
        let sdcpp: Capabilities = serde_json::from_str(r#"{"supported_modes":["img_gen"]}"#).unwrap();
        assert!(!sdcpp.is_mac_engine());
        assert_eq!(sdcpp.mac_engine_unsupported(&edit), None);
    }

    #[test]
    fn sse_parser_splits_events_across_chunks() {
        // The documented stream, cut at awkward places: inside a line, inside "é", in "\r\n".
        let body = ": waiting for the model\r\n\r\nevent: delta\r\ndata: {\"text\":\"A caf\u{e9}\"}\r\n\r\nevent: delta\ndata: {\"text\":\" at night\"}\n\nevent: done\ndata: {\"text\":\"A caf\u{e9} at night\",\"finish_reason\":\"stop\",\"seed\":7,\"usage\":{\"prompt_tokens\":96,\"completion_tokens\":4},\"timings\":{\"decode_s\":0.1}}\n\n";
        let bytes = body.as_bytes();
        let e_acute = body.find('\u{e9}').unwrap();
        let cuts = [5, 24, 30, e_acute + 1, e_acute + 2, 90, bytes.len()];
        let mut p = SseParser::default();
        let mut events = Vec::new();
        let mut start = 0;
        for &c in &cuts {
            events.extend(p.push(&bytes[start..c]));
            start = c;
        }
        assert_eq!(events.len(), 3, "{events:?}");
        assert_eq!(events[0], ("delta".to_string(), "{\"text\":\"A caf\u{e9}\"}".to_string()));
        assert_eq!(events[1].0, "delta");
        let done: TextGenDone = serde_json::from_str(&events[2].1).unwrap();
        assert_eq!((done.text.as_str(), done.finish_reason.as_str(), done.seed), ("A caf\u{e9} at night", "stop", 7));
        assert_eq!(done.usage, TextUsage { prompt_tokens: 96, completion_tokens: 4 });
        // An event without an `event:` line, and the error event.
        assert_eq!(p.push(b"data: x\n\nevent: error\ndata: {\"error\":\"boom\"}\n\n"), vec![("message".into(), "x".into()), ("error".into(), "{\"error\":\"boom\"}".into())]);
        assert!(p.push(b"event: delta\ndata: {\"te").is_empty(), "incomplete event waits");
    }

    #[test]
    fn base64_roundtrip_and_data_urls() {
        let data = vec![0u8, 1, 2, 250];
        assert_eq!(b64_decode(&b64(&data)).unwrap(), data);
        assert_eq!(b64_decode(&format!("data:image/png;base64,{}", b64(&data))).unwrap(), data);
        assert!(b64_decode("!!!").is_err());
    }

    #[test]
    fn version_banner() {
        assert_eq!(parse_version_banner("stable-diffusion.cpp version unknown, commit 3f8527a\nUsage: ...").unwrap(), "version unknown, commit 3f8527a");
        assert!(parse_version_banner("nothing").is_none());
    }
}