vtx_sdk/
http.rs

1use crate::bindings::vtx::api::{
2    stream_io,
3    types::{HttpRequest, HttpResponse},
4};
5use crate::error::VtxError;
6
7/// 标准化请求与响应类型别名（与 WIT 接口对齐）
8pub type Request = HttpRequest;
9pub type Response = HttpResponse;
10
11/// HTTP 响应构造器（适用于插件运行时）
12///
13/// 提供以下构造能力：
14/// - 成功响应（JSON）
15/// - 错误响应（自动映射状态码与结构体）
16/// - 文件流响应（基于宿主 UUID 打开文件）
17/// - 状态码响应（纯状态码，无 body）
18///
19pub struct ResponseBuilder;
20
21impl ResponseBuilder {
22    /// 构造 JSON 响应（200 OK）
23    ///
24    /// ⚠️ 若序列化失败，返回 `[]` 作为兜底内容，**不表示逻辑成功**。
25    pub fn json<T: serde::Serialize>(data: &T) -> Response {
26        let json_bytes = serde_json::to_vec(data).unwrap_or_else(|_| b"[]".to_vec());
27
28        // 使用宿主提供的内存缓冲区封装 JSON 数据
29        let buffer = stream_io::create_memory_buffer(&json_bytes);
30        HttpResponse {
31            status: 200,
32            body: Some(buffer),
33        }
34    }
35
36    /// 构造错误响应（根据错误类型自动映射 HTTP 状态码）
37    ///
38    /// - `AuthDenied(code)` → `code`（401 / 403）
39    /// - `NotFound(_)` → 404
40    /// - `PermissionDenied(_)` → 403
41    /// - `SerializationError(_)` → 400
42    /// - `DatabaseError(_)`, `Internal(_)` → 500
43    ///
44    /// 返回结构：
45    /// ```json
46    /// {
47    ///   "success": false,
48    ///   "error": true,
49    ///   "code": 403,
50    ///   "type": "PermissionDenied",
51    ///   "message": "You are not allowed to access this resource"
52    /// }
53    /// ```
54    pub fn error(err: VtxError) -> Response {
55        let (status, message) = match &err {
56            VtxError::AuthDenied(code) => (*code, format!("Authentication failed: {}", err)),
57            VtxError::NotFound(msg) => (404, msg.clone()),
58            VtxError::PermissionDenied(msg) => (403, msg.clone()),
59            VtxError::SerializationError(msg) => (400, format!("Bad Request: {}", msg)),
60            VtxError::DatabaseError(msg) => (500, format!("Database Error: {}", msg)),
61            VtxError::Internal(msg) => (500, format!("Internal Error: {}", msg)),
62        };
63
64        let error_body = serde_json::json!({
65            "success": false,                  // 统一布尔失败标识
66            "error": true,                     // 标识为错误响应
67            "code": status,                    // 映射的 HTTP 状态码
68            "type": format!("{:?}", err),      // 错误类型（调试使用）
69            "message": message                 // 错误消息（用户可见）
70        });
71
72        let mut resp = Self::json(&error_body);
73        resp.status = status;
74        resp
75    }
76
77    /// 构造文件流响应（通过宿主接口按 UUID 打开）
78    ///
79    /// - 成功：200 + 文件内容流
80    /// - 失败：返回 404 JSON 错误响应
81    pub fn file(uuid: &str) -> Response {
82        match stream_io::open_file(uuid) {
83            Ok(buffer) => HttpResponse {
84                status: 200,
85                body: Some(buffer),
86            },
87            Err(e) => Self::error(VtxError::NotFound(format!("File UUID not found: {}", e))),
88        }
89    }
90
91    /// 构造纯状态码响应（无 body）
92    ///
93    /// 用于如：204 No Content、403 Forbidden 等响应场景
94    pub fn status(code: u16) -> Response {
95        HttpResponse {
96            status: code,
97            body: None,
98        }
99    }
100
101    /// 构造标准 404 Not Found 响应（无正文）
102    pub fn not_found() -> Response {
103        Self::status(404)
104    }
105}
vtx_sdk/http.rs

vtx_sdk/
http.rs
