diff --git a/axum-extra/src/lib.rs b/axum-extra/src/lib.rs index e14c5a16fc..e672d7adf0 100644 --- a/axum-extra/src/lib.rs +++ b/axum-extra/src/lib.rs @@ -26,7 +26,7 @@ //! `tracing` | Log rejections from built-in extractors | Yes //! `typed-routing` | Enables the [`TypedPath`](crate::routing::TypedPath) routing utilities | No //! `typed-header` | Enables the [`TypedHeader`] extractor and response | No -//! `FileStream` | Enables the [`FileStream`](crate::response::FileStream) response | No +//! `file-stream` | Enables the [`FileStream`](crate::response::FileStream) response | No //! //! [`axum`]: https://crates.io/crates/axum diff --git a/axum-extra/src/response/file_stream.rs b/axum-extra/src/response/file_stream.rs index 03271410c5..380ff72203 100644 --- a/axum-extra/src/response/file_stream.rs +++ b/axum-extra/src/response/file_stream.rs @@ -22,23 +22,27 @@ use tokio_util::io::ReaderStream; /// ``` /// use axum::{ /// http::StatusCode, -/// response::{Response, IntoResponse}, +/// response::{IntoResponse, Response}, +/// routing::get, /// Router, -/// routing::get /// }; /// use axum_extra::response::file_stream::FileStream; /// use tokio::fs::File; /// use tokio_util::io::ReaderStream; /// /// async fn file_stream() -> Result { -/// let stream=ReaderStream::new(File::open("test.txt").await.map_err(|e| (StatusCode::NOT_FOUND, format!("File not found: {e}")))?); -/// let file_stream_resp = FileStream::new(stream) -/// .file_name("test.txt"); -// +/// let stream = ReaderStream::new( +/// File::open("test.txt") +/// .await +/// .map_err(|e| (StatusCode::NOT_FOUND, format!("File not found: {e}")))?, +/// ); +/// let file_stream_resp = FileStream::new(stream).file_name("test.txt"); +/// /// Ok(file_stream_resp.into_response()) /// } -/// let app = Router::new().route("/FileStreamDownload", get(file_stream)); -/// # let _: Router = app; +/// +/// let app = Router::new().route("/file-stream", get(file_stream)); +/// let _: Router = app; /// ``` #[derive(Debug)] pub struct FileStream { @@ -56,7 +60,7 @@ where S::Ok: Into, S::Error: Into, { - /// Create a file stream. + /// Create a new [`FileStream`] pub fn new(stream: S) -> Self { Self { stream, @@ -65,14 +69,14 @@ where } } - /// Create a file stream from a file path. + /// Create a [`FileStream`] from a file path. /// /// # Examples /// /// ``` /// use axum::{ /// http::StatusCode, - /// response::{Response, IntoResponse}, + /// response::IntoResponse, /// Router, /// routing::get /// }; @@ -80,34 +84,30 @@ where /// use tokio::fs::File; /// use tokio_util::io::ReaderStream; /// - /// async fn file_stream() -> Response { + /// async fn file_stream() -> impl IntoResponse { /// FileStream::>::from_path("test.txt") /// .await /// .map_err(|e| (StatusCode::NOT_FOUND, format!("File not found: {e}"))) - /// .into_response() /// } - /// let app = Router::new().route("/FileStreamDownload", get(file_stream)); - /// # let _: Router = app; + /// + /// let app = Router::new().route("/file-stream", get(file_stream)); + /// let _: Router = app; /// ``` pub async fn from_path(path: impl AsRef) -> io::Result>> { - // open file let file = File::open(&path).await?; let mut content_size = None; let mut file_name = None; - // get file metadata length if let Ok(metadata) = file.metadata().await { content_size = Some(metadata.len()); } - // get file name if let Some(file_name_os) = path.as_ref().file_name() { if let Some(file_name_str) = file_name_os.to_str() { file_name = Some(file_name_str.to_owned()); } } - // return FileStream Ok(FileStream { stream: ReaderStream::new(file), file_name, @@ -115,7 +115,9 @@ where }) } - /// Set the file name of the file. + /// Set the file name of the [`FileStream`]. + /// + /// This adds the attachment `Content-Disposition` header with the given `file_name`. pub fn file_name(mut self, file_name: impl Into) -> Self { self.file_name = Some(file_name.into()); self @@ -136,25 +138,35 @@ where /// ``` /// use axum::{ /// http::StatusCode, - /// response::{Response, IntoResponse}, + /// response::IntoResponse, + /// routing::get, /// Router, - /// routing::get /// }; /// use axum_extra::response::file_stream::FileStream; /// use tokio::fs::File; - /// use tokio_util::io::ReaderStream; /// use tokio::io::AsyncSeekExt; + /// use tokio_util::io::ReaderStream; + /// + /// async fn range_response() -> Result { + /// let mut file = File::open("test.txt") + /// .await + /// .map_err(|e| (StatusCode::NOT_FOUND, format!("File not found: {e}")))?; + /// let mut file_size = file + /// .metadata() + /// .await + /// .map_err(|e| (StatusCode::NOT_FOUND, format!("Get file size: {e}")))? + /// .len(); + /// + /// file.seek(std::io::SeekFrom::Start(10)) + /// .await + /// .map_err(|e| (StatusCode::NOT_FOUND, format!("File seek error: {e}")))?; + /// let stream = ReaderStream::new(file); /// - /// async fn range_response() -> Result { - /// let mut file=File::open("test.txt").await.map_err(|e| (StatusCode::NOT_FOUND, format!("File not found: {e}")))?; - /// let mut file_size=file.metadata().await.map_err(|e| (StatusCode::NOT_FOUND, format!("Get file size: {e}")))?.len(); - /// file.seek(std::io::SeekFrom::Start(10)).await.map_err(|e| (StatusCode::NOT_FOUND, format!("File seek error: {e}")))?; - /// let stream=ReaderStream::new(file); - /// - /// Ok(FileStream::new(stream).into_range_response(10, file_size-1, file_size)) + /// Ok(FileStream::new(stream).into_range_response(10, file_size - 1, file_size)) /// } - /// let app = Router::new().route("/FileStreamRange", get(range_response)); - /// # let _: Router = app; + /// + /// let app = Router::new().route("/file-stream", get(range_response)); + /// let _: Router = app; /// ``` pub fn into_range_response(self, start: u64, end: u64, total_size: u64) -> Response { let mut resp = Response::builder().header(header::CONTENT_TYPE, "application/octet-stream"); @@ -169,7 +181,7 @@ where .unwrap_or_else(|e| { ( StatusCode::INTERNAL_SERVER_ERROR, - format!("build FileStream responsec error: {e}"), + format!("build FileStream response error: {e}"), ) .into_response() }) @@ -180,15 +192,20 @@ where /// # Arguments /// /// * `file_path` - The path of the file to be streamed - /// * `start` - The start position of the range, if start > file size or start > end return Range Not Satisfiable - /// * `end` - The end position of the range if end == 0 end = file size - 1 + /// * `start` - The start position of the range + /// * `end` - The end position of the range + /// + /// # Note + /// + /// * If `end` is 0, then it is used as `file_size - 1` + /// * If `start` > `file_size` or `start` > `end`, then `Range Not Satisfiable` is returned /// /// # Examples /// /// ``` /// use axum::{ /// http::StatusCode, - /// response::{Response, IntoResponse}, + /// response::IntoResponse, /// Router, /// routing::get /// }; @@ -198,27 +215,24 @@ where /// use tokio_util::io::ReaderStream; /// use tokio::io::AsyncSeekExt; /// - /// async fn range_stream() -> Response { + /// async fn range_stream() -> impl IntoResponse { /// let range_start = 0; /// let range_end = 1024; /// /// FileStream::>::try_range_response("CHANGELOG.md", range_start, range_end).await - /// .map_err(|e| (StatusCode::NOT_FOUND, format!("File not found: {e}"))) - /// .into_response() - /// + /// .map_err(|e| (StatusCode::NOT_FOUND, format!("File not found: {e}"))) /// } - /// let app = Router::new().route("/FileStreamRange", get(range_stream)); - /// # let _: Router = app; + /// + /// let app = Router::new().route("/file-stream", get(range_stream)); + /// let _: Router = app; /// ``` pub async fn try_range_response( file_path: impl AsRef, start: u64, mut end: u64, ) -> io::Result { - // open file let mut file = File::open(file_path).await?; - // get file metadata let metadata = file.metadata().await?; let total_size = metadata.len(); @@ -226,7 +240,6 @@ where end = total_size - 1; } - // range check if start > total_size { return Ok((StatusCode::RANGE_NOT_SATISFIABLE, "Range Not Satisfiable").into_response()); } @@ -237,7 +250,6 @@ where return Ok((StatusCode::RANGE_NOT_SATISFIABLE, "Range Not Satisfiable").into_response()); } - // get file stream and seek to start to return range response file.seek(std::io::SeekFrom::Start(start)).await?; let stream = ReaderStream::new(file.take(end - start + 1)); @@ -246,7 +258,6 @@ where } } -/// default response is application/octet-stream and attachment mode; impl IntoResponse for FileStream where S: TryStream + Send + 'static,