use crate::error::BaseError;
use schemars::gen::SchemaGenerator;
use schemars::schema::{InstanceType, Schema, SchemaObject, SingleOrVec};
use schemars::JsonSchema;
use serde::Deserialize;
use std::fmt;
use std::path::{Path, PathBuf};
#[derive(Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UploadedFile {
field_name: String,
original_filename: String,
content_type: String,
size: u64,
path: PathBuf,
#[serde(default)]
temp_root: Option<PathBuf>,
}
impl UploadedFile {
pub fn field_name(&self) -> &str {
&self.field_name
}
pub fn original_filename(&self) -> &str {
&self.original_filename
}
pub fn content_type(&self) -> &str {
&self.content_type
}
pub const fn size(&self) -> u64 {
self.size
}
pub fn path(&self) -> &Path {
&self.path
}
pub async fn copy_to(&self, destination: impl AsRef<Path>) -> Result<u64, BaseError> {
let temp_root = self.temp_root.as_ref().ok_or_else(|| {
BaseError::PermissionDenied(
"上传文件缺少受信临时根(疑似不可信反序列化实例),拒绝复制".to_string(),
)
})?;
let root = temp_root.canonicalize().map_err(|error| {
BaseError::PermissionDenied(format!("受信临时根校验失败,拒绝复制: {error}"))
})?;
let source = self.path.canonicalize().map_err(|error| {
BaseError::PermissionDenied(format!("上传临时文件校验失败,拒绝复制: {error}"))
})?;
if !source.starts_with(&root) {
return Err(BaseError::PermissionDenied(
"上传文件路径越出受信临时根,拒绝复制".to_string(),
));
}
tokio::fs::copy(&source, destination)
.await
.map_err(BaseError::from)
}
}
impl fmt::Debug for UploadedFile {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("UploadedFile")
.field("field_name", &self.field_name)
.field("original_filename", &self.original_filename)
.field("content_type", &self.content_type)
.field("size", &self.size)
.field("path", &"[REQUEST_SCOPED_TEMP_FILE]")
.field("trusted", &self.temp_root.is_some())
.finish()
}
}
impl JsonSchema for UploadedFile {
fn schema_name() -> String {
"UploadedFile".to_string()
}
fn json_schema(_generator: &mut SchemaGenerator) -> Schema {
Schema::Object(SchemaObject {
instance_type: Some(SingleOrVec::Single(Box::new(InstanceType::String))),
format: Some("binary".to_string()),
..SchemaObject::default()
})
}
}
#[cfg(test)]
mod tests {
use super::*;
fn unique_test_dir(tag: &str) -> PathBuf {
let nanos = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|duration| duration.as_nanos())
.unwrap_or(0);
let dir = std::env::temp_dir().join(format!(
"yang_upload_test_{tag}_{}_{nanos}",
std::process::id()
));
std::fs::create_dir_all(&dir).expect("测试临时目录应创建成功");
dir
}
#[test]
fn uploaded_file_projects_as_openapi_binary_input() {
let schema = schemars::schema_for!(UploadedFile);
let value = serde_json::to_value(schema).expect("UploadedFile schema 应可序列化");
assert_eq!(value["type"], "string");
assert_eq!(value["format"], "binary");
assert!(value.get("path").is_none(), "临时路径不得进入输入契约");
}
#[tokio::test]
async fn copy_to_rejects_deserialized_instance_without_trusted_temp_root() {
let victim = std::env::current_exe().expect("当前可执行文件路径应可获取");
let forged: UploadedFile = serde_json::from_value(serde_json::json!({
"field_name": "file",
"original_filename": "payload.bin",
"content_type": "application/octet-stream",
"size": 1,
"path": victim,
}))
.expect("伪造实例应可反序列化");
let dir = unique_test_dir("untrusted");
let destination = dir.join("stolen.bin");
let error = forged
.copy_to(&destination)
.await
.expect_err("无受信临时根的实例必须拒绝复制");
assert!(
matches!(error, BaseError::PermissionDenied(_)),
"无受信临时根应返回 PermissionDenied: {error}"
);
assert!(!destination.exists(), "拒绝复制不得产生目标文件");
let _ = std::fs::remove_dir_all(&dir);
}
#[tokio::test]
async fn copy_to_rejects_path_escaping_trusted_temp_root() {
let root = unique_test_dir("root");
let outside = unique_test_dir("outside");
let secret = outside.join("secret.txt");
std::fs::write(&secret, b"top-secret").expect("越界文件应写入成功");
let file = UploadedFile {
field_name: "file".to_string(),
original_filename: "secret.txt".to_string(),
content_type: "text/plain".to_string(),
size: 10,
path: secret,
temp_root: Some(root.clone()),
};
let destination = root.join("copy.txt");
let error = file
.copy_to(&destination)
.await
.expect_err("越出受信临时根的路径必须拒绝");
assert!(
matches!(error, BaseError::PermissionDenied(_)),
"越界路径应返回 PermissionDenied: {error}"
);
assert!(!destination.exists(), "拒绝复制不得产生目标文件");
let _ = std::fs::remove_dir_all(&root);
let _ = std::fs::remove_dir_all(&outside);
}
#[tokio::test]
async fn copy_to_copies_file_inside_trusted_temp_root() {
let root = unique_test_dir("trusted");
let source = root.join("yang-upload-1");
std::fs::write(&source, b"hello").expect("源文件应写入成功");
let file = UploadedFile {
field_name: "file".to_string(),
original_filename: "upload.bin".to_string(),
content_type: "application/octet-stream".to_string(),
size: 5,
path: source,
temp_root: Some(root.clone()),
};
let destination = root.join("saved.bin");
let copied = file
.copy_to(&destination)
.await
.expect("受信临时根内的文件应复制成功");
assert_eq!(copied, 5);
assert_eq!(
std::fs::read(&destination).expect("目标文件应可读"),
b"hello"
);
let _ = std::fs::remove_dir_all(&root);
}
#[test]
fn transport_injected_temp_root_deserializes_into_trusted_instance() {
let trusted: UploadedFile = serde_json::from_value(serde_json::json!({
"field_name": "file",
"original_filename": "a.txt",
"content_type": "text/plain",
"size": 3,
"path": "/tmp/scope/yang-upload-1",
"temp_root": "/tmp/scope",
}))
.expect("transport 注入的 temp_root 应可反序列化");
assert_eq!(
trusted.temp_root.as_deref(),
Some(Path::new("/tmp/scope")),
"transport 注入的临时根必须保留"
);
let forged: UploadedFile = serde_json::from_value(serde_json::json!({
"field_name": "file",
"original_filename": "a.txt",
"content_type": "text/plain",
"size": 3,
"path": "/etc/passwd",
}))
.expect("缺省 temp_root 应可反序列化");
assert!(
forged.temp_root.is_none(),
"客户端 JSON 反序列化的实例不得获得受信临时根"
);
}
}