Skip to main content

yang_base/definition/
media.rs

1//! Action 请求媒体类型与受限 multipart 上传契约。
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5
6/// 默认允许的非文件表单字段数量。
7pub const DEFAULT_MULTIPART_MAX_FIELDS: u16 = 64;
8/// 默认允许的文件数量。
9pub const DEFAULT_MULTIPART_MAX_FILES: u16 = 8;
10/// 默认单文件上限:10 MiB。
11pub const DEFAULT_MULTIPART_MAX_FILE_BYTES: u64 = 10 * 1024 * 1024;
12/// 默认单个文本(非文件)表单字段上限:64 KiB。
13pub const DEFAULT_MULTIPART_MAX_TEXT_FIELD_BYTES: u64 = 64 * 1024;
14/// 默认整个 multipart 请求上限:32 MiB。
15pub const DEFAULT_MULTIPART_MAX_TOTAL_BYTES: u64 = 32 * 1024 * 1024;
16
17/// Action 接受的请求媒体类型。
18///
19/// 未知值必须降级为 JSON,不能在消费者侧擅自启用文件上传。
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
21#[serde(rename_all = "snake_case")]
22#[non_exhaustive]
23pub enum ActionMediaType {
24    /// `multipart/form-data`,必须同时提供 [`MultipartSpec`]。
25    Multipart,
26    /// `application/json`,也是未知值的安全降级。
27    #[default]
28    #[serde(other)]
29    Json,
30}
31
32/// 上传临时文件的生命周期。
33///
34/// 当前只允许请求作用域:Handler 返回后框架删除临时文件;业务若需持久化,必须在
35/// Handler 内显式复制或移动到自己的受控存储。
36#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
37#[serde(rename_all = "snake_case")]
38#[non_exhaustive]
39pub enum UploadLifecycle {
40    /// 请求结束即清理的临时文件。
41    #[default]
42    #[serde(other)]
43    RequestScoped,
44}
45
46/// `multipart/form-data` 的资源与类型限制。
47///
48/// `allowed_content_types` 只校验客户端声明的媒体类型,不能替代 Handler 对文件魔数、
49/// 内容和业务格式的验证;其中唯一允许的通配写法 `"*/*"` 表示跳过该校验(对齐 TS
50/// 导入端点只按扩展名判断文件类型的行为)。
51#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
52pub struct MultipartSpec {
53    /// 非文件表单字段数量上限。
54    pub max_fields: u16,
55    /// 文件字段数量上限。
56    pub max_files: u16,
57    /// 单文件字节上限。
58    pub max_file_bytes: u64,
59    /// 单个文本(非文件)表单字段的字节上限;不得超过 `max_total_bytes`。
60    pub max_text_field_bytes: u64,
61    /// 整个 multipart body 的字节上限。
62    pub max_total_bytes: u64,
63    /// 允许的精确 MIME 类型;`"*/*"` 表示不校验文件 part 的客户端类型;
64    /// 不允许空集合。
65    pub allowed_content_types: Vec<String>,
66    /// 临时文件生命周期。
67    pub lifecycle: UploadLifecycle,
68}
69
70impl MultipartSpec {
71    /// 使用安全默认资源上限创建上传契约。
72    pub fn new<I, S>(allowed_content_types: I) -> Self
73    where
74        I: IntoIterator<Item = S>,
75        S: Into<String>,
76    {
77        Self {
78            max_fields: DEFAULT_MULTIPART_MAX_FIELDS,
79            max_files: DEFAULT_MULTIPART_MAX_FILES,
80            max_file_bytes: DEFAULT_MULTIPART_MAX_FILE_BYTES,
81            max_text_field_bytes: DEFAULT_MULTIPART_MAX_TEXT_FIELD_BYTES,
82            max_total_bytes: DEFAULT_MULTIPART_MAX_TOTAL_BYTES,
83            allowed_content_types: allowed_content_types.into_iter().map(Into::into).collect(),
84            lifecycle: UploadLifecycle::RequestScoped,
85        }
86    }
87
88    /// 设置非文件表单字段数量上限。
89    #[must_use]
90    pub fn max_fields(mut self, max_fields: u16) -> Self {
91        self.max_fields = max_fields;
92        self
93    }
94
95    /// 设置文件字段数量上限。
96    #[must_use]
97    pub fn max_files(mut self, max_files: u16) -> Self {
98        self.max_files = max_files;
99        self
100    }
101
102    /// 设置单文件字节上限。
103    #[must_use]
104    pub fn max_file_bytes(mut self, max_file_bytes: u64) -> Self {
105        self.max_file_bytes = max_file_bytes;
106        self
107    }
108
109    /// 设置单个文本(非文件)表单字段的字节上限。
110    #[must_use]
111    pub fn max_text_field_bytes(mut self, max_text_field_bytes: u64) -> Self {
112        self.max_text_field_bytes = max_text_field_bytes;
113        self
114    }
115
116    /// 设置整个 multipart body 的字节上限。
117    #[must_use]
118    pub fn max_total_bytes(mut self, max_total_bytes: u64) -> Self {
119        self.max_total_bytes = max_total_bytes;
120        self
121    }
122}
123
124#[cfg(test)]
125mod tests {
126    use super::*;
127
128    #[test]
129    fn unknown_media_and_lifecycle_values_fail_closed() {
130        let media: ActionMediaType =
131            serde_json::from_str("\"websocket\"").expect("未知请求媒体类型应安全解析");
132        let lifecycle: UploadLifecycle =
133            serde_json::from_str("\"permanent\"").expect("未知上传生命周期应安全解析");
134
135        assert_eq!(media, ActionMediaType::Json);
136        assert_eq!(lifecycle, UploadLifecycle::RequestScoped);
137    }
138
139    #[test]
140    fn multipart_defaults_are_bounded() {
141        let spec = MultipartSpec::new(["application/pdf"]);
142        assert_eq!(spec.max_fields, DEFAULT_MULTIPART_MAX_FIELDS);
143        assert_eq!(spec.max_files, DEFAULT_MULTIPART_MAX_FILES);
144        assert_eq!(spec.max_file_bytes, DEFAULT_MULTIPART_MAX_FILE_BYTES);
145        assert_eq!(
146            spec.max_text_field_bytes,
147            DEFAULT_MULTIPART_MAX_TEXT_FIELD_BYTES
148        );
149        assert_eq!(spec.max_total_bytes, DEFAULT_MULTIPART_MAX_TOTAL_BYTES);
150        assert_eq!(spec.lifecycle, UploadLifecycle::RequestScoped);
151    }
152}