ollama-client 0.1.0

//! Async client, request builders, and client builder.

use std::time::Duration;

use futures_core::Stream;
use url::Url;

use crate::error::{OllamaError, Result};
use crate::streaming::ndjson_stream;
use crate::types::chat::{ChatRequest, ChatResponse, ChatStreamChunk};
use crate::types::common::{Message, Options, Tool};
use crate::types::embed::{EmbedInput, EmbedRequest, EmbedResponse};
use crate::types::generate::{GenerateRequest, GenerateResponse, GenerateStreamChunk};
use crate::types::models::*;

/// Default Ollama server address (standard local install).
const DEFAULT_BASE_URL: &str = "http://localhost:11434";
/// Total request timeout — generous to accommodate slow model loads.
const DEFAULT_TIMEOUT_SECS: u64 = 120;
/// TCP connect timeout — fail fast if the server is unreachable.
const DEFAULT_CONNECT_TIMEOUT_SECS: u64 = 30;
/// Cap on remote error body to prevent log flooding or memory abuse.
const MAX_ERROR_MESSAGE_LEN: usize = 1024;

/// Async Ollama API client.
#[derive(Debug)]
pub struct OllamaClient {
    http: reqwest::Client,
    base_url: Url,
}

impl OllamaClient {
    /// Creates a new client connecting to `http://localhost:11434`.
    ///
    /// # Panics
    ///
    /// Panics if the HTTP client cannot be built (should not happen in practice).
    /// Use [`OllamaClient::builder()`] for a fallible alternative.
    pub fn new() -> Self {
        Self::try_new().expect("failed to create OllamaClient")
    }

    /// Fallible constructor connecting to `http://localhost:11434`.
    pub fn try_new() -> Result<Self> {
        Self::try_with_base_url(DEFAULT_BASE_URL)
    }

    /// Creates a new client with a custom base URL.
    ///
    /// # Panics
    ///
    /// Panics if `base_url` is not a valid HTTP/HTTPS URL.
    /// Use [`OllamaClient::try_with_base_url()`] for a fallible alternative.
    pub fn with_base_url(base_url: impl Into<String>) -> Self {
        Self::try_with_base_url(base_url).expect("invalid base URL")
    }

    /// Fallible constructor with a custom base URL.
    ///
    /// Only `http` and `https` schemes are accepted.
    pub fn try_with_base_url(base_url: impl Into<String>) -> Result<Self> {
        let base_url = parse_base_url(base_url.into())?;
        let http = reqwest::Client::builder()
            .timeout(Duration::from_secs(DEFAULT_TIMEOUT_SECS))
            .connect_timeout(Duration::from_secs(DEFAULT_CONNECT_TIMEOUT_SECS))
            .build()
            .map_err(OllamaError::Http)?;
        Ok(Self { http, base_url })
    }

    /// Creates a client from an existing `reqwest::Client` and base URL.
    ///
    /// # Panics
    ///
    /// Panics if `base_url` is not a valid HTTP/HTTPS URL.
    /// Use [`OllamaClient::try_from_reqwest()`] for a fallible alternative.
    pub fn from_reqwest(client: reqwest::Client, base_url: impl Into<String>) -> Self {
        Self::try_from_reqwest(client, base_url).expect("invalid base URL")
    }

    /// Fallible constructor from an existing `reqwest::Client`.
    ///
    /// Use this to inject a custom HTTP client for testing. Point `base_url`
    /// at a mock server (e.g., `wiremock` or `mockito`) to test without a
    /// real Ollama instance:
    ///
    /// ```no_run
    /// # fn example() -> ollama_client::Result<()> {
    /// let client = ollama_client::OllamaClient::try_from_reqwest(
    ///     reqwest::Client::new(),
    ///     "http://127.0.0.1:8080",
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn try_from_reqwest(client: reqwest::Client, base_url: impl Into<String>) -> Result<Self> {
        let base_url = parse_base_url(base_url.into())?;
        Ok(Self {
            http: client,
            base_url,
        })
    }

    /// Returns a builder for configuring timeouts and base URL.
    pub fn builder() -> OllamaClientBuilder {
        OllamaClientBuilder::default()
    }

    pub(crate) fn url(&self, path: &str) -> String {
        // Safe: base_url is validated at construction, path is a known literal.
        let mut url = self.base_url.clone();
        url.set_path(path);
        url.to_string()
    }

    pub(crate) fn http(&self) -> &reqwest::Client {
        &self.http
    }

    // ── Chat ──

    /// Start building a chat completion request.
    pub fn chat(&self) -> ChatRequestBuilder<'_> {
        ChatRequestBuilder {
            client: self,
            model: String::new(),
            messages: Vec::new(),
            format: None,
            tools: None,
            think: None,
            options: None,
            keep_alive: None,
        }
    }

    // ── Generate ──

    /// Start building a text generation request.
    pub fn generate(&self) -> GenerateRequestBuilder<'_> {
        GenerateRequestBuilder {
            client: self,
            model: String::new(),
            prompt: None,
            suffix: None,
            images: None,
            format: None,
            system: None,
            think: None,
            raw: None,
            keep_alive: None,
            options: None,
            context: None,
        }
    }

    // ── Embed ──

    /// Start building an embeddings request.
    pub fn embed(&self) -> EmbedRequestBuilder<'_> {
        EmbedRequestBuilder {
            client: self,
            model: String::new(),
            input: EmbedInput::Single(String::new()),
            truncate: None,
            dimensions: None,
            keep_alive: None,
            options: None,
        }
    }

    // ── Model management ──

    /// List locally available models.
    pub async fn list_models(&self) -> Result<ListModelsResponse> {
        let response = self.http.get(self.url("/api/tags")).send().await?;
        let response = check_api_error(response).await?;
        Ok(response.json().await?)
    }

    /// Start building a show model info request.
    pub fn show_model(&self) -> ShowModelRequestBuilder<'_> {
        ShowModelRequestBuilder {
            client: self,
            model: String::new(),
            verbose: None,
        }
    }

    /// Copy a model.
    pub async fn copy_model(
        &self,
        source: impl Into<String>,
        destination: impl Into<String>,
    ) -> Result<()> {
        let request = CopyModelRequest {
            source: source.into(),
            destination: destination.into(),
        };
        let response = self
            .http
            .post(self.url("/api/copy"))
            .json(&request)
            .send()
            .await?;
        check_api_error(response).await?;
        Ok(())
    }

    /// Delete a model.
    pub async fn delete_model(&self, model: impl Into<String>) -> Result<()> {
        let request = DeleteModelRequest {
            model: model.into(),
        };
        let response = self
            .http
            .delete(self.url("/api/delete"))
            .json(&request)
            .send()
            .await?;
        check_api_error(response).await?;
        Ok(())
    }

    /// Start building a pull model request.
    pub fn pull_model(&self) -> PullModelRequestBuilder<'_> {
        PullModelRequestBuilder {
            client: self,
            model: String::new(),
            insecure: None,
        }
    }

    /// Start building a push model request.
    pub fn push_model(&self) -> PushModelRequestBuilder<'_> {
        PushModelRequestBuilder {
            client: self,
            model: String::new(),
            insecure: None,
        }
    }

    /// Start building a create model request.
    pub fn create_model(&self) -> CreateModelRequestBuilder<'_> {
        CreateModelRequestBuilder {
            client: self,
            model: String::new(),
            from: None,
            system: None,
            template: None,
            parameters: None,
            quantize: None,
            license: None,
            messages: None,
        }
    }

    /// List currently running/loaded models.
    pub async fn list_running(&self) -> Result<ListRunningResponse> {
        let response = self.http.get(self.url("/api/ps")).send().await?;
        let response = check_api_error(response).await?;
        Ok(response.json().await?)
    }

    // ── Blobs ──

    /// Check if a blob exists.
    ///
    /// Returns `Ok(true)` if the blob exists (HTTP 200), `Ok(false)` if not found (HTTP 404),
    /// and `Err(...)` for any other error.
    pub async fn check_blob(&self, digest: &str) -> Result<bool> {
        validate_digest(digest)?;
        let response = self
            .http
            .head(self.url(&format!("/api/blobs/{digest}")))
            .send()
            .await?;
        match response.status().as_u16() {
            200 => Ok(true),
            404 => Ok(false),
            _ => {
                check_api_error(response).await?;
                Ok(false)
            }
        }
    }

    /// Upload a blob with the given digest.
    ///
    /// **Note:** The entire blob is loaded into memory as `Vec<u8>`. For very large blobs,
    /// consider splitting them or using a lower-level HTTP client with streaming upload.
    pub async fn upload_blob(&self, digest: &str, data: Vec<u8>) -> Result<()> {
        validate_digest(digest)?;
        let response = self
            .http
            .post(self.url(&format!("/api/blobs/{digest}")))
            .body(data)
            .send()
            .await?;
        check_api_error(response).await?;
        Ok(())
    }

    // ── Version ──

    /// Get the Ollama server version.
    pub async fn version(&self) -> Result<VersionResponse> {
        let response = self.http.get(self.url("/api/version")).send().await?;
        let response = check_api_error(response).await?;
        Ok(response.json().await?)
    }
}

impl Default for OllamaClient {
    fn default() -> Self {
        Self::new()
    }
}

// ────────────────────────────────────────────────────────────────
// Builders
// ────────────────────────────────────────────────────────────────

// ── Chat builder ──

/// Builder for a chat completion request.
#[must_use]
#[derive(Debug)]
pub struct ChatRequestBuilder<'a> {
    client: &'a OllamaClient,
    model: String,
    messages: Vec<Message>,
    format: Option<serde_json::Value>,
    tools: Option<Vec<Tool>>,
    think: Option<serde_json::Value>,
    options: Option<Options>,
    keep_alive: Option<String>,
}

impl<'a> ChatRequestBuilder<'a> {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = model.into();
        self
    }

    pub fn messages(mut self, messages: Vec<Message>) -> Self {
        self.messages = messages;
        self
    }

    pub fn format(mut self, format: serde_json::Value) -> Self {
        self.format = Some(format);
        self
    }

    pub fn tools(mut self, tools: Vec<Tool>) -> Self {
        self.tools = Some(tools);
        self
    }

    pub fn think(mut self, think: bool) -> Self {
        self.think = Some(serde_json::Value::Bool(think));
        self
    }

    pub fn options(mut self, options: Options) -> Self {
        self.options = Some(options);
        self
    }

    pub fn temperature(mut self, temp: f64) -> Self {
        self.options
            .get_or_insert_with(Options::default)
            .temperature = Some(temp);
        self
    }

    pub fn top_k(mut self, top_k: u32) -> Self {
        self.options.get_or_insert_with(Options::default).top_k = Some(top_k);
        self
    }

    pub fn top_p(mut self, top_p: f64) -> Self {
        self.options.get_or_insert_with(Options::default).top_p = Some(top_p);
        self
    }

    pub fn num_ctx(mut self, num_ctx: u32) -> Self {
        self.options.get_or_insert_with(Options::default).num_ctx = Some(num_ctx);
        self
    }

    pub fn keep_alive(mut self, keep_alive: impl Into<String>) -> Self {
        self.keep_alive = Some(keep_alive.into());
        self
    }

    fn build_request(&self, stream: bool) -> ChatRequest {
        ChatRequest {
            model: self.model.clone(),
            messages: self.messages.clone(),
            stream: Some(stream),
            format: self.format.clone(),
            tools: self.tools.clone(),
            think: self.think.clone(),
            options: self.options.clone(),
            keep_alive: self.keep_alive.clone(),
        }
    }

    /// Send and wait for the complete response.
    ///
    /// # Errors
    ///
    /// Returns [`OllamaError::Http`] on network failure,
    /// [`OllamaError::Api`] if Ollama returns an error status,
    /// or [`OllamaError::Json`] if the response cannot be parsed.
    pub async fn send(self) -> Result<ChatResponse> {
        let request = self.build_request(false);
        let response = self
            .client
            .http()
            .post(self.client.url("/api/chat"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        let body = response.text().await?;
        Ok(serde_json::from_str(&body)?)
    }

    /// Send and return a stream of chunks.
    ///
    /// # Errors
    ///
    /// Returns [`OllamaError::Http`] on network failure or
    /// [`OllamaError::Api`] if Ollama returns an error status.
    /// Individual stream items may yield [`OllamaError::Json`]
    /// or [`OllamaError::LineTooLarge`].
    pub async fn send_stream(self) -> Result<impl Stream<Item = Result<ChatStreamChunk>>> {
        let request = self.build_request(true);
        let response = self
            .client
            .http()
            .post(self.client.url("/api/chat"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        Ok(ndjson_stream(response))
    }
}

// ── Generate builder ──

/// Builder for a text generation request.
#[must_use]
#[derive(Debug)]
pub struct GenerateRequestBuilder<'a> {
    client: &'a OllamaClient,
    model: String,
    prompt: Option<String>,
    suffix: Option<String>,
    images: Option<Vec<String>>,
    format: Option<serde_json::Value>,
    system: Option<String>,
    think: Option<serde_json::Value>,
    raw: Option<bool>,
    keep_alive: Option<String>,
    options: Option<Options>,
    context: Option<Vec<i64>>,
}

impl<'a> GenerateRequestBuilder<'a> {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = model.into();
        self
    }

    pub fn prompt(mut self, prompt: impl Into<String>) -> Self {
        self.prompt = Some(prompt.into());
        self
    }

    pub fn suffix(mut self, suffix: impl Into<String>) -> Self {
        self.suffix = Some(suffix.into());
        self
    }

    pub fn images(mut self, images: Vec<String>) -> Self {
        self.images = Some(images);
        self
    }

    pub fn format(mut self, format: serde_json::Value) -> Self {
        self.format = Some(format);
        self
    }

    pub fn system(mut self, system: impl Into<String>) -> Self {
        self.system = Some(system.into());
        self
    }

    pub fn think(mut self, think: bool) -> Self {
        self.think = Some(serde_json::Value::Bool(think));
        self
    }

    pub fn raw(mut self, raw: bool) -> Self {
        self.raw = Some(raw);
        self
    }

    pub fn keep_alive(mut self, keep_alive: impl Into<String>) -> Self {
        self.keep_alive = Some(keep_alive.into());
        self
    }

    pub fn options(mut self, options: Options) -> Self {
        self.options = Some(options);
        self
    }

    pub fn temperature(mut self, temp: f64) -> Self {
        self.options
            .get_or_insert_with(Options::default)
            .temperature = Some(temp);
        self
    }

    pub fn context(mut self, context: Vec<i64>) -> Self {
        self.context = Some(context);
        self
    }

    fn build_request(&self, stream: bool) -> GenerateRequest {
        GenerateRequest {
            model: self.model.clone(),
            prompt: self.prompt.clone(),
            suffix: self.suffix.clone(),
            images: self.images.clone(),
            format: self.format.clone(),
            system: self.system.clone(),
            stream: Some(stream),
            think: self.think.clone(),
            raw: self.raw,
            keep_alive: self.keep_alive.clone(),
            options: self.options.clone(),
            context: self.context.clone(),
        }
    }

    /// Send and wait for the complete response.
    pub async fn send(self) -> Result<GenerateResponse> {
        let request = self.build_request(false);
        let response = self
            .client
            .http()
            .post(self.client.url("/api/generate"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        let body = response.text().await?;
        Ok(serde_json::from_str(&body)?)
    }

    /// Send and return a stream of chunks.
    pub async fn send_stream(self) -> Result<impl Stream<Item = Result<GenerateStreamChunk>>> {
        let request = self.build_request(true);
        let response = self
            .client
            .http()
            .post(self.client.url("/api/generate"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        Ok(ndjson_stream(response))
    }
}

// ── Embed builder ──

/// Builder for an embeddings request.
#[must_use]
#[derive(Debug)]
pub struct EmbedRequestBuilder<'a> {
    client: &'a OllamaClient,
    model: String,
    input: EmbedInput,
    truncate: Option<bool>,
    dimensions: Option<u32>,
    keep_alive: Option<String>,
    options: Option<Options>,
}

impl<'a> EmbedRequestBuilder<'a> {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = model.into();
        self
    }

    pub fn input(mut self, input: impl Into<EmbedInput>) -> Self {
        self.input = input.into();
        self
    }

    pub fn truncate(mut self, truncate: bool) -> Self {
        self.truncate = Some(truncate);
        self
    }

    pub fn dimensions(mut self, dimensions: u32) -> Self {
        self.dimensions = Some(dimensions);
        self
    }

    pub fn keep_alive(mut self, keep_alive: impl Into<String>) -> Self {
        self.keep_alive = Some(keep_alive.into());
        self
    }

    pub fn options(mut self, options: Options) -> Self {
        self.options = Some(options);
        self
    }

    /// Send and wait for the embeddings response.
    pub async fn send(self) -> Result<EmbedResponse> {
        let request = EmbedRequest {
            model: self.model,
            input: self.input,
            truncate: self.truncate,
            dimensions: self.dimensions,
            keep_alive: self.keep_alive,
            options: self.options,
        };
        let response = self
            .client
            .http()
            .post(self.client.url("/api/embed"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        let body = response.text().await?;
        Ok(serde_json::from_str(&body)?)
    }
}

// ── Show model builder ──

/// Builder for a show-model request.
#[must_use]
#[derive(Debug)]
pub struct ShowModelRequestBuilder<'a> {
    client: &'a OllamaClient,
    model: String,
    verbose: Option<bool>,
}

impl<'a> ShowModelRequestBuilder<'a> {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = model.into();
        self
    }

    pub fn verbose(mut self, verbose: bool) -> Self {
        self.verbose = Some(verbose);
        self
    }

    /// Send the request.
    pub async fn send(self) -> Result<ShowModelResponse> {
        let request = ShowModelRequest {
            model: self.model,
            verbose: self.verbose,
        };
        let response = self
            .client
            .http()
            .post(self.client.url("/api/show"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        let body = response.text().await?;
        Ok(serde_json::from_str(&body)?)
    }
}

// ── Pull model builder ──

/// Builder for a pull-model request.
#[must_use]
#[derive(Debug)]
pub struct PullModelRequestBuilder<'a> {
    client: &'a OllamaClient,
    model: String,
    insecure: Option<bool>,
}

impl<'a> PullModelRequestBuilder<'a> {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = model.into();
        self
    }

    /// Enable insecure mode (skip TLS certificate verification on the Ollama server side).
    ///
    /// **Warning:** This disables TLS certificate verification for registry operations.
    /// Use only in local development or testing environments, never in production.
    pub fn insecure(mut self, insecure: bool) -> Self {
        self.insecure = Some(insecure);
        self
    }

    /// Send and wait for the final status (non-streaming).
    pub async fn send(self) -> Result<PullModelStatus> {
        let request = PullModelRequest {
            model: self.model,
            insecure: self.insecure,
            stream: Some(false),
        };
        let response = self
            .client
            .http()
            .post(self.client.url("/api/pull"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        let body = response.text().await?;
        Ok(serde_json::from_str(&body)?)
    }

    /// Send and return a stream of status updates.
    pub async fn send_stream(self) -> Result<impl Stream<Item = Result<PullModelStatus>>> {
        let request = PullModelRequest {
            model: self.model,
            insecure: self.insecure,
            stream: Some(true),
        };
        let response = self
            .client
            .http()
            .post(self.client.url("/api/pull"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        Ok(ndjson_stream(response))
    }
}

// ── Push model builder ──

/// Builder for a push-model request.
#[must_use]
#[derive(Debug)]
pub struct PushModelRequestBuilder<'a> {
    client: &'a OllamaClient,
    model: String,
    insecure: Option<bool>,
}

impl<'a> PushModelRequestBuilder<'a> {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = model.into();
        self
    }

    /// Enable insecure mode (skip TLS certificate verification on the Ollama server side).
    ///
    /// **Warning:** This disables TLS certificate verification for registry operations.
    /// Use only in local development or testing environments, never in production.
    pub fn insecure(mut self, insecure: bool) -> Self {
        self.insecure = Some(insecure);
        self
    }

    /// Send and wait for the final status (non-streaming).
    pub async fn send(self) -> Result<PushModelStatus> {
        let request = PushModelRequest {
            model: self.model,
            insecure: self.insecure,
            stream: Some(false),
        };
        let response = self
            .client
            .http()
            .post(self.client.url("/api/push"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        let body = response.text().await?;
        Ok(serde_json::from_str(&body)?)
    }

    /// Send and return a stream of status updates.
    pub async fn send_stream(self) -> Result<impl Stream<Item = Result<PushModelStatus>>> {
        let request = PushModelRequest {
            model: self.model,
            insecure: self.insecure,
            stream: Some(true),
        };
        let response = self
            .client
            .http()
            .post(self.client.url("/api/push"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        Ok(ndjson_stream(response))
    }
}

// ── Create model builder ──

/// Builder for a create-model request.
#[must_use]
#[derive(Debug)]
pub struct CreateModelRequestBuilder<'a> {
    client: &'a OllamaClient,
    model: String,
    from: Option<String>,
    system: Option<String>,
    template: Option<String>,
    parameters: Option<serde_json::Value>,
    quantize: Option<String>,
    license: Option<serde_json::Value>,
    messages: Option<Vec<Message>>,
}

impl<'a> CreateModelRequestBuilder<'a> {
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = model.into();
        self
    }

    pub fn from_model(mut self, from: impl Into<String>) -> Self {
        self.from = Some(from.into());
        self
    }

    pub fn system(mut self, system: impl Into<String>) -> Self {
        self.system = Some(system.into());
        self
    }

    pub fn template(mut self, template: impl Into<String>) -> Self {
        self.template = Some(template.into());
        self
    }

    pub fn parameters(mut self, parameters: serde_json::Value) -> Self {
        self.parameters = Some(parameters);
        self
    }

    pub fn quantize(mut self, quantize: impl Into<String>) -> Self {
        self.quantize = Some(quantize.into());
        self
    }

    pub fn license(mut self, license: serde_json::Value) -> Self {
        self.license = Some(license);
        self
    }

    pub fn messages(mut self, messages: Vec<Message>) -> Self {
        self.messages = Some(messages);
        self
    }

    /// Send and wait for the final status (non-streaming).
    pub async fn send(self) -> Result<CreateModelStatus> {
        let request = self.build_request(false);
        let response = self
            .client
            .http()
            .post(self.client.url("/api/create"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        let body = response.text().await?;
        Ok(serde_json::from_str(&body)?)
    }

    /// Send and return a stream of status updates.
    pub async fn send_stream(self) -> Result<impl Stream<Item = Result<CreateModelStatus>>> {
        let request = self.build_request(true);
        let response = self
            .client
            .http()
            .post(self.client.url("/api/create"))
            .json(&request)
            .send()
            .await?;
        let response = check_api_error(response).await?;
        Ok(ndjson_stream(response))
    }

    fn build_request(&self, stream: bool) -> CreateModelRequest {
        CreateModelRequest {
            model: self.model.clone(),
            from: self.from.clone(),
            system: self.system.clone(),
            template: self.template.clone(),
            parameters: self.parameters.clone(),
            quantize: self.quantize.clone(),
            license: self.license.clone(),
            messages: self.messages.clone(),
            stream: Some(stream),
        }
    }
}

// ────────────────────────────────────────────────────────────────
// Helpers
// ────────────────────────────────────────────────────────────────

/// Check for HTTP error responses and convert them to `OllamaError::Api`.
///
/// Error messages from the remote server are truncated to [`MAX_ERROR_MESSAGE_LEN`] bytes
/// and control characters (except `\n`) are stripped.
pub(crate) async fn check_api_error(response: reqwest::Response) -> Result<reqwest::Response> {
    let status = response.status();
    if status.is_client_error() || status.is_server_error() {
        let raw = response
            .text()
            .await
            .unwrap_or_else(|_| "unknown error".to_string());
        let message = sanitize_error_message(&raw);
        return Err(OllamaError::Api {
            status: status.as_u16(),
            message,
        });
    }
    Ok(response)
}

/// Truncate and sanitize a remote error message.
fn sanitize_error_message(raw: &str) -> String {
    let truncated = if raw.len() > MAX_ERROR_MESSAGE_LEN {
        // Truncate at a char boundary.
        let mut end = MAX_ERROR_MESSAGE_LEN;
        while !raw.is_char_boundary(end) && end > 0 {
            end -= 1;
        }
        format!("{}...(truncated)", &raw[..end])
    } else {
        raw.to_string()
    };
    // Strip control chars except newline.
    truncated
        .chars()
        .filter(|c| !c.is_control() || *c == '\n')
        .collect()
}

/// Parse and validate a base URL. Only `http` and `https` schemes are accepted.
fn parse_base_url(raw: String) -> Result<Url> {
    let trimmed = raw.trim_end_matches('/');
    let url =
        Url::parse(trimmed).map_err(|e| OllamaError::InvalidBaseUrl(format!("{trimmed}: {e}")))?;
    match url.scheme() {
        "http" | "https" => Ok(url),
        scheme => Err(OllamaError::InvalidBaseUrl(format!(
            "unsupported scheme '{scheme}', expected 'http' or 'https'"
        ))),
    }
}

/// Validate a blob digest string.
///
/// Expected format: `<algorithm>:<hex>` (e.g., `sha256:abc123...`).
/// Rejects slashes, backslashes, query separators, fragments, and control characters.
fn validate_digest(digest: &str) -> Result<()> {
    if digest.is_empty() {
        return Err(OllamaError::InvalidDigest("digest is empty".into()));
    }
    if !digest.contains(':') {
        return Err(OllamaError::InvalidDigest(format!(
            "expected '<algorithm>:<hex>' format, got '{digest}'"
        )));
    }
    let bad_chars = ['/', '\\', '?', '#'];
    if digest
        .chars()
        .any(|c| bad_chars.contains(&c) || c.is_control())
    {
        return Err(OllamaError::InvalidDigest(format!(
            "digest contains invalid characters: '{digest}'"
        )));
    }
    Ok(())
}

// ────────────────────────────────────────────────────────────────
// Client builder
// ────────────────────────────────────────────────────────────────

/// Configurable builder for [`OllamaClient`].
#[derive(Debug)]
pub struct OllamaClientBuilder {
    base_url: String,
    timeout: Duration,
    connect_timeout: Duration,
}

impl Default for OllamaClientBuilder {
    fn default() -> Self {
        Self {
            base_url: DEFAULT_BASE_URL.to_string(),
            timeout: Duration::from_secs(DEFAULT_TIMEOUT_SECS),
            connect_timeout: Duration::from_secs(DEFAULT_CONNECT_TIMEOUT_SECS),
        }
    }
}

impl OllamaClientBuilder {
    /// Set the base URL (default: `http://localhost:11434`).
    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
        self.base_url = base_url.into();
        self
    }

    /// Set the total request timeout (default: 120s).
    ///
    /// For long-running streaming requests (chat, generate, pull, push, create),
    /// consider setting a longer timeout or disabling it with `Duration::ZERO`.
    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    /// Set the connection timeout (default: 30s).
    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
        self.connect_timeout = timeout;
        self
    }

    /// Build the client.
    pub fn build(self) -> Result<OllamaClient> {
        let base_url = parse_base_url(self.base_url)?;
        let mut builder = reqwest::Client::builder().connect_timeout(self.connect_timeout);
        if self.timeout != Duration::ZERO {
            builder = builder.timeout(self.timeout);
        }
        let http = builder.build().map_err(OllamaError::Http)?;
        Ok(OllamaClient { http, base_url })
    }
}

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

    #[test]
    fn parse_base_url_valid_http() {
        assert!(parse_base_url("http://localhost:11434".into()).is_ok());
    }

    #[test]
    fn parse_base_url_valid_https() {
        assert!(parse_base_url("https://ollama.example.com".into()).is_ok());
    }

    #[test]
    fn parse_base_url_rejects_ftp() {
        assert!(parse_base_url("ftp://evil.com".into()).is_err());
    }

    #[test]
    fn parse_base_url_rejects_garbage() {
        assert!(parse_base_url("not a url".into()).is_err());
    }

    #[test]
    fn validate_digest_valid() {
        assert!(validate_digest("sha256:abcdef0123456789").is_ok());
    }

    #[test]
    fn validate_digest_empty() {
        assert!(validate_digest("").is_err());
    }

    #[test]
    fn validate_digest_no_colon() {
        assert!(validate_digest("sha256abcdef").is_err());
    }

    #[test]
    fn validate_digest_with_slash() {
        assert!(validate_digest("sha256:abc/def").is_err());
    }

    #[test]
    fn validate_digest_with_query() {
        assert!(validate_digest("sha256:abc?x=1").is_err());
    }

    #[test]
    fn sanitize_error_truncation() {
        let long = "a".repeat(2000);
        let result = sanitize_error_message(&long);
        assert!(result.len() < 2000);
        assert!(result.ends_with("...(truncated)"));
    }

    #[test]
    fn sanitize_error_strips_control_chars() {
        let msg = "error\x00with\x01control\nchars";
        let result = sanitize_error_message(msg);
        assert_eq!(result, "errorwithcontrol\nchars");
    }

    #[test]
    fn builder_default() {
        let client = OllamaClient::builder().build();
        assert!(client.is_ok());
    }

    #[test]
    fn builder_custom_timeout() {
        let client = OllamaClient::builder()
            .timeout(Duration::from_secs(300))
            .connect_timeout(Duration::from_secs(10))
            .build();
        assert!(client.is_ok());
    }

    #[test]
    fn builder_invalid_url() {
        let client = OllamaClient::builder().base_url("ftp://bad").build();
        assert!(client.is_err());
    }
}