feat: expose PathBufWrap utility for public access

actix-files/CHANGES.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- `PathBufWrap` & `UriSegmentError` made public.
 - Minimum supported Rust version (MSRV) is now 1.75.
 
 ## 0.6.6

actix-files/src/error.rs

@@ -21,6 +21,7 @@ impl ResponseError for FilesError {
     }
 }
 
+/// Error which can occur with parsing/validating a request-uri path
 #[derive(Debug, PartialEq, Eq, Display)]
 #[non_exhaustive]
 pub enum UriSegmentError {

actix-files/src/lib.rs

@@ -37,13 +37,12 @@ mod range;
 mod service;
 
 pub use self::{
-    chunked::ChunkedReadFile, directory::Directory, files::Files, named::NamedFile,
-    range::HttpRange, service::FilesService,
+    chunked::ChunkedReadFile, directory::Directory, error::UriSegmentError, files::Files,
+    named::NamedFile, path_buf::PathBufWrap, range::HttpRange, service::FilesService,
 };
 use self::{
     directory::{directory_listing, DirectoryRenderer},
     error::FilesError,
-    path_buf::PathBufWrap,
 };
 
 type HttpService = BoxService<ServiceRequest, ServiceResponse, Error>;

actix-files/src/path_buf.rs

@@ -8,8 +8,11 @@ use actix_web::{dev::Payload, FromRequest, HttpRequest};
 
 use crate::error::UriSegmentError;
 
+/// Secure Path Traversal Guard
+///
+/// This struct parses a request-uri [`PathBuf`](std::path::PathBuf)
 #[derive(Debug, PartialEq, Eq)]
-pub(crate) struct PathBufWrap(PathBuf);
+pub struct PathBufWrap(PathBuf);
 
 impl FromStr for PathBufWrap {
     type Err = UriSegmentError;
@@ -20,6 +23,15 @@ impl FromStr for PathBufWrap {
 }
 
 impl PathBufWrap {
+    /// Parse a safe path from a supplied [`HttpRequest`](actix_web::HttpRequest),
+    /// given the choice of allowing hiddden files to be considered valid segments.
+    ///
+    /// Path traversal is guarded by this method.
+    #[inline]
+    pub fn parse_req(req: &HttpRequest, hidden_files: bool) -> Result<Self, UriSegmentError> {
+        Self::parse_path(req.match_info().unprocessed(), hidden_files)
+    }
+
     /// Parse a path, giving the choice of allowing hidden files to be considered valid segments.
     ///
     /// Path traversal is guarded by this method.