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/// 内容和业务格式的验证。
50#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
51pub struct MultipartSpec {
52    /// 非文件表单字段数量上限。
53    pub max_fields: u16,
54    /// 文件字段数量上限。
55    pub max_files: u16,
56    /// 单文件字节上限。
57    pub max_file_bytes: u64,
58    /// 单个文本(非文件)表单字段的字节上限;不得超过 `max_total_bytes`。
59    pub max_text_field_bytes: u64,
60    /// 整个 multipart body 的字节上限。
61    pub max_total_bytes: u64,
62    /// 允许的精确 MIME 类型;不允许空集合或通配符。
63    pub allowed_content_types: Vec<String>,
64    /// 临时文件生命周期。
65    pub lifecycle: UploadLifecycle,
66}
67
68impl MultipartSpec {
69    /// 使用安全默认资源上限创建上传契约。
70    pub fn new<I, S>(allowed_content_types: I) -> Self
71    where
72        I: IntoIterator<Item = S>,
73        S: Into<String>,
74    {
75        Self {
76            max_fields: DEFAULT_MULTIPART_MAX_FIELDS,
77            max_files: DEFAULT_MULTIPART_MAX_FILES,
78            max_file_bytes: DEFAULT_MULTIPART_MAX_FILE_BYTES,
79            max_text_field_bytes: DEFAULT_MULTIPART_MAX_TEXT_FIELD_BYTES,
80            max_total_bytes: DEFAULT_MULTIPART_MAX_TOTAL_BYTES,
81            allowed_content_types: allowed_content_types.into_iter().map(Into::into).collect(),
82            lifecycle: UploadLifecycle::RequestScoped,
83        }
84    }
85
86    /// 设置非文件表单字段数量上限。
87    #[must_use]
88    pub fn max_fields(mut self, max_fields: u16) -> Self {
89        self.max_fields = max_fields;
90        self
91    }
92
93    /// 设置文件字段数量上限。
94    #[must_use]
95    pub fn max_files(mut self, max_files: u16) -> Self {
96        self.max_files = max_files;
97        self
98    }
99
100    /// 设置单文件字节上限。
101    #[must_use]
102    pub fn max_file_bytes(mut self, max_file_bytes: u64) -> Self {
103        self.max_file_bytes = max_file_bytes;
104        self
105    }
106
107    /// 设置单个文本(非文件)表单字段的字节上限。
108    #[must_use]
109    pub fn max_text_field_bytes(mut self, max_text_field_bytes: u64) -> Self {
110        self.max_text_field_bytes = max_text_field_bytes;
111        self
112    }
113
114    /// 设置整个 multipart body 的字节上限。
115    #[must_use]
116    pub fn max_total_bytes(mut self, max_total_bytes: u64) -> Self {
117        self.max_total_bytes = max_total_bytes;
118        self
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125
126    #[test]
127    fn unknown_media_and_lifecycle_values_fail_closed() {
128        let media: ActionMediaType =
129            serde_json::from_str("\"websocket\"").expect("未知请求媒体类型应安全解析");
130        let lifecycle: UploadLifecycle =
131            serde_json::from_str("\"permanent\"").expect("未知上传生命周期应安全解析");
132
133        assert_eq!(media, ActionMediaType::Json);
134        assert_eq!(lifecycle, UploadLifecycle::RequestScoped);
135    }
136
137    #[test]
138    fn multipart_defaults_are_bounded() {
139        let spec = MultipartSpec::new(["application/pdf"]);
140        assert_eq!(spec.max_fields, DEFAULT_MULTIPART_MAX_FIELDS);
141        assert_eq!(spec.max_files, DEFAULT_MULTIPART_MAX_FILES);
142        assert_eq!(spec.max_file_bytes, DEFAULT_MULTIPART_MAX_FILE_BYTES);
143        assert_eq!(
144            spec.max_text_field_bytes,
145            DEFAULT_MULTIPART_MAX_TEXT_FIELD_BYTES
146        );
147        assert_eq!(spec.max_total_bytes, DEFAULT_MULTIPART_MAX_TOTAL_BYTES);
148        assert_eq!(spec.lifecycle, UploadLifecycle::RequestScoped);
149    }
150}