linger-openai-sdk 0.1.1

use crate::error::LingerError;
use crate::transport::{BodyStream, HttpRequest};
use crate::RequestId;
use bytes::Bytes;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::BTreeMap;

/// EN: Request body descriptor for `POST /v1/files`.
/// 中文：`POST /v1/files` 的请求体描述。
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct CreateFileRequest {
    /// EN: File content and filename metadata.
    /// 中文：文件内容和文件名元数据。
    pub file: FileUpload,
    /// EN: OpenAI file purpose, such as `fine-tune`, `assistants`, or `batch`.
    /// 中文：OpenAI 文件用途，例如 `fine-tune`、`assistants` 或 `batch`。
    pub purpose: String,
    /// EN: Optional expiration policy for supported purposes.
    /// 中文：受支持用途的可选过期策略。
    pub expires_after: Option<FileExpirationPolicy>,
}

impl CreateFileRequest {
    /// EN: Starts building a file upload request.
    /// 中文：开始构建文件上传请求。
    pub fn builder() -> CreateFileRequestBuilder {
        CreateFileRequestBuilder::default()
    }

    pub(crate) fn apply_multipart_body(&self, request: &mut HttpRequest) {
        let boundary = multipart_boundary(&self.file.content);
        request.insert_header(
            "content-type",
            format!("multipart/form-data; boundary={boundary}"),
        );
        request.set_body_stream(self.multipart_stream(boundary));
    }

    fn multipart_stream(
        &self,
        boundary: String,
    ) -> impl futures_core::Stream<Item = Result<Bytes, LingerError>> {
        let mut chunks = Vec::new();
        push_text_field(&mut chunks, &boundary, "purpose", &self.purpose);
        if let Some(expires_after) = &self.expires_after {
            push_text_field(
                &mut chunks,
                &boundary,
                "expires_after[anchor]",
                &expires_after.anchor,
            );
            push_text_field(
                &mut chunks,
                &boundary,
                "expires_after[seconds]",
                &expires_after.seconds.to_string(),
            );
        }
        chunks.push(Ok(Bytes::from(format!(
            "--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"{}\"\r\nContent-Type: {}\r\n\r\n",
            escape_multipart_param(&self.file.filename),
            self.file.content_type
        ))));
        chunks.push(Ok(self.file.content.clone()));
        chunks.push(Ok(Bytes::from(format!("\r\n--{boundary}--\r\n"))));
        futures_util::stream::iter(chunks)
    }
}

/// EN: Builder for file upload requests.
/// 中文：文件上传请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateFileRequestBuilder {
    file: Option<FileUpload>,
    purpose: Option<String>,
    expires_after: Option<FileExpirationPolicy>,
}

impl CreateFileRequestBuilder {
    /// EN: Sets the file to upload.
    /// 中文：设置要上传的文件。
    pub fn file(mut self, file: FileUpload) -> Self {
        self.file = Some(file);
        self
    }

    /// EN: Sets the file purpose.
    /// 中文：设置文件用途。
    pub fn purpose(mut self, purpose: impl Into<String>) -> Self {
        self.purpose = Some(purpose.into());
        self
    }

    /// EN: Sets the optional expiration policy.
    /// 中文：设置可选的过期策略。
    pub fn expires_after(mut self, expires_after: FileExpirationPolicy) -> Self {
        self.expires_after = Some(expires_after);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateFileRequest, LingerError> {
        let file = self
            .file
            .ok_or_else(|| LingerError::invalid_config("file is required"))?;
        let purpose = self
            .purpose
            .filter(|value| !value.trim().is_empty())
            .ok_or_else(|| LingerError::invalid_config("purpose is required"))?;
        if let Some(expires_after) = &self.expires_after {
            expires_after.validate()?;
        }
        Ok(CreateFileRequest {
            file,
            purpose,
            expires_after: self.expires_after,
        })
    }
}

/// EN: Uploadable file bytes and multipart metadata.
/// 中文：可上传文件字节及 multipart 元数据。
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct FileUpload {
    /// EN: Filename sent in the multipart part.
    /// 中文：multipart 分段中发送的文件名。
    pub filename: String,
    /// EN: Content type sent for the file part.
    /// 中文：文件分段发送的内容类型。
    pub content_type: String,
    content: Bytes,
}

impl FileUpload {
    /// EN: Creates an upload from already available bytes without copying them.
    /// 中文：通过已可用字节创建上传对象，不复制这些字节。
    pub fn from_bytes(
        filename: impl Into<String>,
        content: impl Into<Bytes>,
    ) -> Result<Self, LingerError> {
        let filename = filename.into();
        validate_header_param("filename", &filename)?;
        Ok(Self {
            filename,
            content_type: "application/octet-stream".to_string(),
            content: content.into(),
        })
    }

    /// EN: Sets the file part content type.
    /// 中文：设置文件分段的内容类型。
    pub fn content_type(mut self, content_type: impl Into<String>) -> Result<Self, LingerError> {
        let content_type = content_type.into();
        validate_header_value("content_type", &content_type)?;
        self.content_type = content_type;
        Ok(self)
    }

    /// EN: Returns the file bytes as a cheap `Bytes` clone.
    /// 中文：以廉价 `Bytes` 克隆返回文件字节。
    pub fn bytes(&self) -> Bytes {
        self.content.clone()
    }
}

/// EN: File expiration policy sent as multipart fields.
/// 中文：作为 multipart 字段发送的文件过期策略。
#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct FileExpirationPolicy {
    /// EN: Expiration anchor, for example `created_at`.
    /// 中文：过期锚点，例如 `created_at`。
    pub anchor: String,
    /// EN: Expiration offset in seconds.
    /// 中文：过期偏移秒数。
    pub seconds: u64,
}

impl FileExpirationPolicy {
    /// EN: Creates an expiration policy.
    /// 中文：创建过期策略。
    pub fn new(anchor: impl Into<String>, seconds: u64) -> Self {
        Self {
            anchor: anchor.into(),
            seconds,
        }
    }

    pub(crate) fn validate_for_uploads(&self) -> Result<(), LingerError> {
        if self.anchor != "created_at" {
            return Err(LingerError::invalid_config(
                "expires_after.anchor must be created_at",
            ));
        }
        if !(3_600..=2_592_000).contains(&self.seconds) {
            return Err(LingerError::invalid_config(
                "expires_after.seconds must be between 3600 and 2592000",
            ));
        }
        Ok(())
    }

    fn validate(&self) -> Result<(), LingerError> {
        self.validate_for_uploads()
    }
}

/// EN: File object returned by the Files API.
/// 中文：Files API 返回的文件对象。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct FileObject {
    /// EN: File id.
    /// 中文：文件 ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: File size in bytes.
    /// 中文：文件大小，单位为字节。
    pub bytes: u64,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Unix timestamp for expiration, when returned.
    /// 中文：过期时间的 Unix 时间戳，如响应中存在。
    #[serde(default)]
    pub expires_at: Option<u64>,
    /// EN: Original filename.
    /// 中文：原始文件名。
    pub filename: String,
    /// EN: File purpose.
    /// 中文：文件用途。
    pub purpose: String,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl FileObject {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Paginated file list returned by the Files API.
/// 中文：Files API 返回的分页文件列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct FilesPage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Files on this page.
    /// 中文：本页文件。
    #[serde(default)]
    pub data: Vec<FileObject>,
    /// EN: First file id on this page.
    /// 中文：本页第一个文件 ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last file id on this page.
    /// 中文：本页最后一个文件 ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more files are available.
    /// 中文：是否还有更多文件。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl FilesPage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Deletion result returned by the Files API.
/// 中文：Files API 返回的删除结果。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct FileDeletion {
    /// EN: Deleted file id.
    /// 中文：已删除的文件 ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Whether the file was deleted.
    /// 中文：文件是否已删除。
    pub deleted: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl FileDeletion {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Incremental file content response.
/// 中文：增量文件内容响应。
pub struct FileContent {
    request_id: Option<RequestId>,
    body: BodyStream,
}

impl FileContent {
    pub(crate) fn new(request_id: Option<RequestId>, body: BodyStream) -> Self {
        Self { request_id, body }
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }

    /// EN: Consumes this response and returns the incremental content stream.
    /// 中文：消耗此响应并返回增量内容流。
    pub fn into_stream(self) -> BodyStream {
        self.body
    }
}

fn push_text_field(
    chunks: &mut Vec<Result<Bytes, LingerError>>,
    boundary: &str,
    name: &str,
    value: &str,
) {
    chunks.push(Ok(Bytes::from(format!(
        "--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"\r\n\r\n{value}\r\n"
    ))));
}

fn multipart_boundary(content: &Bytes) -> String {
    for counter in 0.. {
        let boundary = format!("linger-openai-sdk-boundary-{counter}");
        if !contains_bytes(content, boundary.as_bytes()) {
            return boundary;
        }
    }
    unreachable!("unbounded boundary counter")
}

fn contains_bytes(haystack: &[u8], needle: &[u8]) -> bool {
    if needle.is_empty() {
        return true;
    }
    haystack
        .windows(needle.len())
        .any(|window| window == needle)
}

fn validate_header_param(name: &str, value: &str) -> Result<(), LingerError> {
    if value.trim().is_empty() {
        return Err(LingerError::invalid_config(format!("{name} is required")));
    }
    validate_header_value(name, value)
}

fn validate_header_value(name: &str, value: &str) -> Result<(), LingerError> {
    if value.contains('\r') || value.contains('\n') {
        return Err(LingerError::invalid_config(format!(
            "{name} must not contain CR or LF"
        )));
    }
    Ok(())
}

fn escape_multipart_param(value: &str) -> String {
    value.replace('\\', "\\\\").replace('"', "\\\"")
}