cetai 0.1.1

Typed prompt! expressions and #[ai] functions for natural-language tasks over DeepSeek.
Documentation
//! 可替换的 HTTP 传输层抽象。
//!
//! 核心编排(状态分类、重试预算、修复对话)只依赖本模块定义的
//! [`Transport`] trait,不直接依赖 reqwest / tokio。默认 feature
//! `reqwest-transport` 提供基于 reqwest + tokio 的实现;bevy、wasm
//! 等场景可以提供自己的实现并通过 `AiConfig::transport` 注入。

use std::future::Future;
use std::pin::Pin;
use std::time::Duration;

/// 拥有所有权的装箱 Future 别名,等价于 futures crate 的 `BoxFuture`
/// (std 未提供该别名),避免引入 futures 依赖。
pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;

/// 一次 HTTP 传输请求,全部数据拥有所有权,可以送入 `'static` Future。
pub struct TransportRequest {
    /// 完整的请求 URL。
    pub url: String,
    /// Bearer 认证令牌。传输层不得把它写入日志或错误摘要。
    pub bearer_token: String,
    /// 请求体字节;HTTP 重试时逐字节复用同一份内容。
    pub body: Vec<u8>,
    /// 本次物理 HTTP 尝试的整体超时。
    pub timeout: Duration,
}

/// 一次 HTTP 传输响应。
pub struct TransportResponse {
    /// HTTP 状态码。
    pub status: u16,
    /// 服务端 `Retry-After` 头,仅接受秒数形式。
    pub retry_after: Option<Duration>,
    /// `x-request-id` 请求 ID(如服务端提供)。
    pub request_id: Option<String>,
    /// 响应体字节。
    pub body: Vec<u8>,
}

/// 传输层错误。
pub struct TransportError {
    /// 是否为可安全重试的瞬时错误(连接失败、单次超时等)。
    pub retryable: bool,
    /// 简短的脱敏错误摘要,不含 URL、key 或完整请求内容。
    pub summary: String,
}

/// 可替换的 HTTP 传输层。
///
/// 实现必须是 `Send + Sync` 并在多次调用间共享(通过 `Arc` 注入
/// `AiConfig`)。返回的 Future 为 `'static`,不借用 `self`,因此实现
/// 需要在内部持有共享客户端等状态(例如静态实例或 `Arc`)。
pub trait Transport: Send + Sync {
    /// 传输层名称,用于 `AiConfig` 的调试输出。
    fn name(&self) -> &'static str;

    /// 发送一次 HTTP POST 请求并返回完整响应。
    fn send(
        &self,
        request: TransportRequest,
    ) -> BoxFuture<'static, Result<TransportResponse, TransportError>>;

    /// 等待指定时长;核心编排在重试退避时调用它,而不是直接依赖某个
    /// 异步运行时的计时器。
    fn sleep(&self, duration: Duration) -> BoxFuture<'static, ()>;
}