Skip to main content

s3_endpoint/
middleware.rs

1//! Typed S3-aware upload middleware.
2//!
3//! Upload processors run after S3 request authentication, payload decoding, and
4//! client checksum validation, but before object bytes are committed to storage.
5//! They are intended for decoded-object workflows such as antivirus scanning or
6//! media normalization that cannot safely operate as generic HTTP body
7//! middleware.
8
9use std::{
10    collections::BTreeMap,
11    fmt,
12    future::Future,
13    path::{Path, PathBuf},
14    sync::Arc,
15};
16
17use futures_util::future::BoxFuture;
18use uuid::Uuid;
19
20use crate::{
21    error::S3Error,
22    s3::types::{BucketName, ContentLength, ObjectKey, RequestId},
23    storage::{StagedObject, StoreError},
24};
25
26/// Shared upload processor object.
27pub type SharedUploadProcessor = Arc<dyn UploadProcessor>;
28
29/// Operation that produced a staged object for processing.
30#[derive(Clone, Copy, Debug, Eq, PartialEq)]
31pub enum UploadProcessorOperation {
32    /// A single-request `PutObject` upload.
33    PutObject,
34    /// A completed multipart upload after parts have been assembled.
35    CompleteMultipartUpload,
36}
37
38/// Stable upload metadata available to processors.
39#[derive(Clone, Debug, Eq, PartialEq)]
40pub struct UploadProcessorContext {
41    /// Request ID returned to the client for this S3 request.
42    pub request_id: RequestId,
43    /// Bucket being written.
44    pub bucket: BucketName,
45    /// Object key being written.
46    pub key: ObjectKey,
47    /// S3 operation that produced the staged object.
48    pub operation: UploadProcessorOperation,
49    /// Decoded client-upload size before processors run.
50    pub original_size: ContentLength,
51    /// Optional `Content-Type` metadata supplied by the client.
52    pub content_type: Option<String>,
53    /// User metadata headers keyed by lowercase `x-amz-meta-*` names.
54    pub user_metadata: BTreeMap<String, String>,
55}
56
57/// Per-processor file paths.
58pub struct UploadProcessorRequest<'a> {
59    /// Upload metadata and target identity.
60    pub context: &'a UploadProcessorContext,
61    /// Path to the current staged object bytes.
62    pub current_path: &'a Path,
63    /// Reserved path where a processor may write replacement bytes.
64    pub replacement_path: &'a Path,
65}
66
67/// Owned convenience handle passed to closure-based upload processors.
68#[derive(Clone, Debug)]
69pub struct UploadProcessorHandle {
70    context: UploadProcessorContext,
71    current_path: PathBuf,
72    replacement_path: PathBuf,
73}
74
75impl UploadProcessorHandle {
76    fn from_request(request: UploadProcessorRequest<'_>) -> Self {
77        Self {
78            context: request.context.clone(),
79            current_path: request.current_path.to_path_buf(),
80            replacement_path: request.replacement_path.to_path_buf(),
81        }
82    }
83
84    /// Upload metadata and target identity.
85    pub fn context(&self) -> &UploadProcessorContext {
86        &self.context
87    }
88
89    /// Path to the current staged object bytes.
90    pub fn current_path(&self) -> &Path {
91        &self.current_path
92    }
93
94    /// Reserved path where replacement bytes may be written.
95    pub fn replacement_path(&self) -> &Path {
96        &self.replacement_path
97    }
98
99    /// Reads the current staged object into memory.
100    ///
101    /// This helper is intended for simple processors. Large-object processors
102    /// can stream directly from [`Self::current_path`].
103    pub async fn read_current(&self) -> Result<Vec<u8>, UploadProcessorError> {
104        tokio::fs::read(&self.current_path)
105            .await
106            .map_err(UploadProcessorError::from)
107    }
108
109    /// Writes replacement bytes to the reserved replacement path.
110    pub async fn write_replacement(
111        &self,
112        bytes: impl AsRef<[u8]>,
113    ) -> Result<(), UploadProcessorError> {
114        tokio::fs::write(&self.replacement_path, bytes)
115            .await
116            .map_err(UploadProcessorError::from)
117    }
118
119    /// Keeps the current staged bytes unchanged.
120    pub fn keep(&self) -> UploadProcessorAction {
121        UploadProcessorAction::Keep
122    }
123
124    /// Replaces current staged bytes with the file written to the replacement path.
125    pub fn replace(&self) -> UploadProcessorAction {
126        UploadProcessorAction::Replace
127    }
128
129    /// Rejects the upload with an S3 `AccessDenied` response.
130    pub fn reject(
131        &self,
132        message: impl Into<String>,
133    ) -> Result<UploadProcessorAction, UploadProcessorError> {
134        Err(UploadProcessorError::Rejected(message.into()))
135    }
136
137    /// Fails the upload with an S3 `InternalError` response.
138    pub fn fail(
139        &self,
140        message: impl Into<String>,
141    ) -> Result<UploadProcessorAction, UploadProcessorError> {
142        Err(UploadProcessorError::Failed(message.into()))
143    }
144}
145
146/// Processor decision for a staged upload.
147#[derive(Clone, Copy, Debug, Eq, PartialEq)]
148pub enum UploadProcessorAction {
149    /// Keep the current staged bytes unchanged.
150    Keep,
151    /// Replace current staged bytes with the file written to `replacement_path`.
152    Replace,
153}
154
155/// Error returned by an upload processor.
156#[derive(Debug)]
157pub enum UploadProcessorError {
158    /// The upload is intentionally rejected, for example because a scanner found
159    /// unsafe content.
160    Rejected(String),
161    /// The processor failed internally and the upload result is unknown.
162    Failed(String),
163}
164
165impl fmt::Display for UploadProcessorError {
166    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
167        match self {
168            Self::Rejected(message) | Self::Failed(message) => formatter.write_str(message),
169        }
170    }
171}
172
173impl std::error::Error for UploadProcessorError {}
174
175/// In-process processor for decoded S3 uploads.
176pub trait UploadProcessor: Send + Sync + 'static {
177    /// Inspect or replace a staged upload file.
178    fn process<'a>(
179        &'a self,
180        request: UploadProcessorRequest<'a>,
181    ) -> BoxFuture<'a, Result<UploadProcessorAction, UploadProcessorError>>;
182}
183
184/// Closure-backed upload processor adapter.
185pub struct UploadProcessorFn<F> {
186    name: String,
187    handler: F,
188}
189
190impl<F> UploadProcessorFn<F> {
191    /// Creates a closure-backed upload processor.
192    pub fn new(name: impl Into<String>, handler: F) -> Self {
193        Self {
194            name: name.into(),
195            handler,
196        }
197    }
198
199    /// Returns the diagnostic processor name.
200    pub fn name(&self) -> &str {
201        &self.name
202    }
203}
204
205impl<F, Fut> UploadProcessor for UploadProcessorFn<F>
206where
207    F: Fn(UploadProcessorHandle) -> Fut + Send + Sync + 'static,
208    Fut: Future<Output = Result<UploadProcessorAction, UploadProcessorError>> + Send + 'static,
209{
210    fn process<'a>(
211        &'a self,
212        request: UploadProcessorRequest<'a>,
213    ) -> BoxFuture<'a, Result<UploadProcessorAction, UploadProcessorError>> {
214        let handle = UploadProcessorHandle::from_request(request);
215        Box::pin((self.handler)(handle))
216    }
217}
218
219/// Runs upload processors sequentially against staged object bytes.
220///
221/// Each processor may keep the current bytes or replace them with its reserved
222/// replacement file. On rejection or failure, staged bytes are discarded.
223pub(crate) async fn process_staged_upload(
224    processors: &[SharedUploadProcessor],
225    mut staged: StagedObject,
226    context: UploadProcessorContext,
227) -> Result<StagedObject, S3Error> {
228    for processor in processors {
229        let replacement_path = staged.replacement_path(Uuid::new_v4());
230        let action = match processor
231            .process(UploadProcessorRequest {
232                context: &context,
233                current_path: staged.path(),
234                replacement_path: &replacement_path,
235            })
236            .await
237        {
238            Ok(action) => action,
239            Err(error) => {
240                remove_unused_replacement(&replacement_path).await?;
241                let _ = staged.discard().await;
242                return Err(map_processor_error(error));
243            }
244        };
245
246        match action {
247            UploadProcessorAction::Keep => remove_unused_replacement(&replacement_path).await?,
248            UploadProcessorAction::Replace => {
249                match staged.replace_with(replacement_path).await {
250                    Ok(()) => {}
251                    Err(error) => {
252                        let _ = staged.discard().await;
253                        return Err(S3Error::internal(format!(
254                            "failed to replace staged upload: {error}"
255                        )));
256                    }
257                };
258            }
259        }
260    }
261
262    Ok(staged)
263}
264
265fn map_processor_error(error: UploadProcessorError) -> S3Error {
266    match error {
267        UploadProcessorError::Rejected(message) => S3Error::access_denied(message),
268        UploadProcessorError::Failed(message) => {
269            S3Error::internal(format!("upload processor failed: {message}"))
270        }
271    }
272}
273
274async fn remove_unused_replacement(path: &Path) -> Result<(), S3Error> {
275    match tokio::fs::remove_file(path).await {
276        Ok(()) => Ok(()),
277        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
278        Err(error) => Err(S3Error::internal(format!(
279            "failed to remove unused upload processor replacement file: {error}"
280        ))),
281    }
282}
283
284impl From<StoreError> for UploadProcessorError {
285    fn from(error: StoreError) -> Self {
286        Self::Failed(error.to_string())
287    }
288}
289
290impl From<std::io::Error> for UploadProcessorError {
291    fn from(error: std::io::Error) -> Self {
292        Self::Failed(error.to_string())
293    }
294}
295
296/// Returns whether no upload processors are configured.
297pub(crate) fn processors_are_empty(processors: &[SharedUploadProcessor]) -> bool {
298    processors.is_empty()
299}