actix_files/

named.rs

use std::{
    fs::Metadata,
    io,
    path::{Path, PathBuf},
    time::{SystemTime, UNIX_EPOCH},
};

use actix_web::{
    body::{self, BoxBody, SizedStream},
    dev::{
        self, AppService, HttpServiceFactory, ResourceDef, Service, ServiceFactory, ServiceRequest,
        ServiceResponse,
    },
    http::{
        header::{
            self, Charset, ContentDisposition, ContentEncoding, DispositionParam, DispositionType,
            ExtendedValue,
        },
        StatusCode,
    },
    Error, HttpMessage, HttpRequest, HttpResponse, Responder,
};
use bitflags::bitflags;
use derive_more::{Deref, DerefMut};
use futures_core::future::LocalBoxFuture;
use mime::Mime;

use crate::{encoding::equiv_utf8_text, range::HttpRange};

bitflags! {
    #[derive(Debug, Clone, Copy)]
    pub(crate) struct Flags: u8 {
        const ETAG =                0b0000_0001;
        const LAST_MD =             0b0000_0010;
        const CONTENT_DISPOSITION = 0b0000_0100;
        const PREFER_UTF8 =         0b0000_1000;
    }
}

impl Default for Flags {
    fn default() -> Self {
        Flags::from_bits_truncate(0b0000_1111)
    }
}

/// A file with an associated name.
///
/// `NamedFile` can be registered as services:
/// ```
/// use actix_web::App;
/// use actix_files::NamedFile;
///
/// # fn run() -> Result<(), Box<dyn std::error::Error>> {
/// let file = NamedFile::open("./static/index.html")?;
/// let app = App::new().service(file);
/// # Ok(())
/// # }
/// ```
///
/// They can also be returned from handlers:
/// ```
/// use actix_web::{Responder, get};
/// use actix_files::NamedFile;
///
/// #[get("/")]
/// async fn index() -> impl Responder {
///     NamedFile::open("./static/index.html")
/// }
/// ```
#[derive(Debug, Deref, DerefMut)]
pub struct NamedFile {
    #[deref]
    #[deref_mut]
    file: File,
    path: PathBuf,
    modified: Option<SystemTime>,
    pub(crate) md: Metadata,
    pub(crate) flags: Flags,
    pub(crate) status_code: StatusCode,
    pub(crate) content_type: Mime,
    pub(crate) content_disposition: ContentDisposition,
    pub(crate) encoding: Option<ContentEncoding>,
    pub(crate) read_mode_threshold: u64,
}

pub(crate) use std::fs::File;

use super::chunked;

pub(crate) fn get_content_type_and_disposition(
    path: &Path,
) -> Result<(mime::Mime, ContentDisposition), io::Error> {
    let filename = match path.file_name() {
        Some(name) => name.to_string_lossy(),
        None => {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "Provided path has no filename",
            ));
        }
    };

    let ct = mime_guess::from_path(path).first_or_octet_stream();

    let disposition = match ct.type_() {
        mime::IMAGE | mime::TEXT | mime::AUDIO | mime::VIDEO => DispositionType::Inline,
        mime::APPLICATION => match ct.subtype() {
            mime::JAVASCRIPT | mime::JSON => DispositionType::Inline,
            name if name == "wasm" || name == "xhtml" => DispositionType::Inline,
            _ => DispositionType::Attachment,
        },
        _ => DispositionType::Attachment,
    };

    // replace special characters in filenames which could occur on some filesystems
    let mut escaped_len = filename.len();
    for byte in filename.bytes() {
        if matches!(byte, b'\n' | b'\x0B' | b'\x0C' | b'\r') {
            escaped_len += 2;
        }
    }

    let filename_s = if escaped_len == filename.len() {
        filename.to_string()
    } else {
        let mut escaped = String::with_capacity(escaped_len);
        for ch in filename.chars() {
            match ch {
                '\n' => escaped.push_str("%0A"),   // \n line break
                '\x0B' => escaped.push_str("%0B"), // \v vertical tab
                '\x0C' => escaped.push_str("%0C"), // \f form feed
                '\r' => escaped.push_str("%0D"),   // \r carriage return
                ch => escaped.push(ch),
            }
        }
        escaped
    };

    let is_ascii = filename.is_ascii();

    let mut parameters = Vec::with_capacity(if is_ascii { 1 } else { 2 });
    parameters.push(DispositionParam::Filename(filename_s));

    if !is_ascii {
        parameters.push(DispositionParam::FilenameExt(ExtendedValue {
            charset: Charset::Ext(String::from("UTF-8")),
            language_tag: None,
            value: filename.into_owned().into_bytes(),
        }))
    }

    let cd = ContentDisposition {
        disposition,
        parameters,
    };

    Ok((ct, cd))
}

impl NamedFile {
    /// Creates an instance from a previously opened file.
    ///
    /// The given `path` need not exist and is only used to determine the `ContentType` and
    /// `ContentDisposition` headers.
    ///
    /// # Examples
    /// ```ignore
    /// use std::{
    ///     io::{self, Write as _},
    ///     env,
    ///     fs::File
    /// };
    /// use actix_files::NamedFile;
    ///
    /// let mut file = File::create("foo.txt")?;
    /// file.write_all(b"Hello, world!")?;
    /// let named_file = NamedFile::from_file(file, "bar.txt")?;
    /// # std::fs::remove_file("foo.txt");
    /// Ok(())
    /// ```
    pub fn from_file<P: AsRef<Path>>(file: File, path: P) -> io::Result<NamedFile> {
        let path = path.as_ref().to_path_buf();

        // Get the name of the file and use it to construct default Content-Type
        // and Content-Disposition values
        let (content_type, content_disposition) = get_content_type_and_disposition(&path)?;

        let md = file.metadata()?;

        let modified = md.modified().ok();
        let encoding = None;

        Ok(NamedFile {
            path,
            file,
            content_type,
            content_disposition,
            md,
            modified,
            encoding,
            status_code: StatusCode::OK,
            flags: Flags::default(),
            read_mode_threshold: 0,
        })
    }

    /// Attempts to open a file in read-only mode.
    ///
    /// # Examples
    /// ```
    /// use actix_files::NamedFile;
    /// let file = NamedFile::open("foo.txt");
    /// ```
    pub fn open<P: AsRef<Path>>(path: P) -> io::Result<NamedFile> {
        let file = File::open(&path)?;
        Self::from_file(file, path)
    }

    /// Returns reference to the underlying file object.
    #[inline]
    pub fn file(&self) -> &File {
        &self.file
    }

    /// Returns the filesystem path to this file.
    ///
    /// # Examples
    /// ```
    /// # use std::io;
    /// use actix_files::NamedFile;
    ///
    /// # fn path() -> io::Result<()> {
    /// let file = NamedFile::open("test.txt")?;
    /// assert_eq!(file.path().as_os_str(), "foo.txt");
    /// # Ok(())
    /// # }
    /// ```
    #[inline]
    pub fn path(&self) -> &Path {
        self.path.as_path()
    }

    /// Returns the time the file was last modified.
    ///
    /// Returns `None` only on unsupported platforms; see [`std::fs::Metadata::modified()`].
    /// Therefore, it is usually safe to unwrap this.
    #[inline]
    pub fn modified(&self) -> Option<SystemTime> {
        self.modified
    }

    /// Returns the filesystem metadata associated with this file.
    #[inline]
    pub fn metadata(&self) -> &Metadata {
        &self.md
    }

    /// Returns the `Content-Type` header that will be used when serving this file.
    #[inline]
    pub fn content_type(&self) -> &Mime {
        &self.content_type
    }

    /// Returns the `Content-Disposition` that will be used when serving this file.
    #[inline]
    pub fn content_disposition(&self) -> &ContentDisposition {
        &self.content_disposition
    }

    /// Returns the `Content-Encoding` that will be used when serving this file.
    ///
    /// A return value of `None` indicates that the content is not already using a compressed
    /// representation and may be subject to compression downstream.
    #[inline]
    pub fn content_encoding(&self) -> Option<ContentEncoding> {
        self.encoding
    }

    /// Set response status code.
    #[deprecated(since = "0.7.0", note = "Prefer `Responder::customize()`.")]
    pub fn set_status_code(mut self, status: StatusCode) -> Self {
        self.status_code = status;
        self
    }

    /// Sets the `Content-Type` header that will be used when serving this file. By default the
    /// `Content-Type` is inferred from the filename extension.
    #[inline]
    pub fn set_content_type(mut self, mime_type: Mime) -> Self {
        self.content_type = mime_type;
        self
    }

    /// Set the Content-Disposition for serving this file. This allows changing the
    /// `inline/attachment` disposition as well as the filename sent to the peer.
    ///
    /// By default the disposition is `inline` for `text/*`, `image/*`, `video/*` and
    /// `application/{javascript, json, wasm}` mime types, and `attachment` otherwise, and the
    /// filename is taken from the path provided in the `open` method after converting it to UTF-8
    /// (using `to_string_lossy`).
    #[inline]
    pub fn set_content_disposition(mut self, cd: ContentDisposition) -> Self {
        self.content_disposition = cd;
        self.flags.insert(Flags::CONTENT_DISPOSITION);
        self
    }

    /// Disables `Content-Disposition` header.
    ///
    /// By default, the `Content-Disposition` header is sent.
    #[inline]
    pub fn disable_content_disposition(mut self) -> Self {
        self.flags.remove(Flags::CONTENT_DISPOSITION);
        self
    }

    /// Sets content encoding for this file.
    ///
    /// This prevents the `Compress` middleware from modifying the file contents and signals to
    /// browsers/clients how to decode it. For example, if serving a compressed HTML file (e.g.,
    /// `index.html.gz`) then use `.set_content_encoding(ContentEncoding::Gzip)`.
    #[inline]
    pub fn set_content_encoding(mut self, enc: ContentEncoding) -> Self {
        self.encoding = Some(enc);
        self
    }

    /// Sets the size threshold that determines file read mode (sync/async).
    ///
    /// When a file is smaller than the threshold (bytes), the reader will use synchronous
    /// (blocking) file reads. For larger files, it switches to async reads to avoid blocking the
    /// main thread.
    ///
    /// Tweaking this value according to your expected usage may lead to significant performance
    /// gains (or losses in other handlers, if `size` is too high).
    ///
    /// Default is 0, meaning all files are read asynchronously.
    pub fn read_mode_threshold(mut self, size: u64) -> Self {
        self.read_mode_threshold = size;
        self
    }

    /// Specifies whether to return `ETag` header in response.
    ///
    /// Default is true.
    #[inline]
    pub fn use_etag(mut self, value: bool) -> Self {
        self.flags.set(Flags::ETAG, value);
        self
    }

    /// Specifies whether to return `Last-Modified` header in response.
    ///
    /// Default is true.
    #[inline]
    pub fn use_last_modified(mut self, value: bool) -> Self {
        self.flags.set(Flags::LAST_MD, value);
        self
    }

    /// Specifies whether text responses should signal a UTF-8 encoding.
    ///
    /// Default is false (but will default to true in a future version).
    #[inline]
    pub fn prefer_utf8(mut self, value: bool) -> Self {
        self.flags.set(Flags::PREFER_UTF8, value);
        self
    }

    /// Creates a strong ETag from the file's metadata.
    ///
    /// Returns `None` if the platform does not provide the file's modification time. (See
    /// [`File::modified()`] docs for more.)
    ///
    /// [`File::modified()`]: https://doc.rust-lang.org/std/fs/struct.Metadata.html#method.modified
    pub(crate) fn etag(&self) -> Option<header::EntityTag> {
        let mtime = self.modified?;

        Some({
            let ino = {
                #[cfg(unix)]
                {
                    use std::os::unix::fs::MetadataExt as _;

                    self.md.ino()
                }

                #[cfg(windows)]
                {
                    // MetadataExt::file_index is not yet stable.
                    winapi_util::file::information(&self.file).map_or(0, |info| info.file_index())
                }

                #[cfg(not(any(unix, windows)))]
                {
                    0
                }
            };

            // Don't panic for pre-epoch modification times. Encode the timestamp as seconds and
            // sub-second nanoseconds relative to the UNIX epoch, allowing negative values.
            let (secs, nanos) = match mtime.duration_since(UNIX_EPOCH) {
                Ok(dur) => (dur.as_secs() as i64, dur.subsec_nanos()),
                Err(err) => {
                    let dur = err.duration();

                    // For timestamps before the epoch, represent the time as a negative seconds
                    // offset with positive nanoseconds (like POSIX timespec).
                    if dur.subsec_nanos() == 0 {
                        (-(dur.as_secs() as i64), 0)
                    } else {
                        (
                            -(dur.as_secs() as i64) - 1,
                            1_000_000_000 - dur.subsec_nanos(),
                        )
                    }
                }
            };

            header::EntityTag::new_strong(format!(
                "{:x}:{:x}:{:x}:{:x}",
                ino,
                self.md.len(),
                secs as u64,
                nanos
            ))
        })
    }

    pub(crate) fn last_modified(&self) -> Option<header::HttpDate> {
        let mtime = self.modified?;

        // avoid panic in `httpdate` crate when formatting as an HTTP date
        // see: https://github.com/actix/actix-web/issues/2748
        //
        // httpdate supports dates in range [1970, 9999); see:
        // https://github.com/seanmonstar/httpdate/blob/v1.0.3/src/date.rs
        let dur = mtime.duration_since(UNIX_EPOCH).ok()?;
        if dur.as_secs() >= 253_402_300_800 {
            return None;
        }

        Some(mtime.into())
    }

    /// Creates an `HttpResponse` with file as a streaming body.
    pub fn into_response(self, req: &HttpRequest) -> HttpResponse<BoxBody> {
        if self.status_code != StatusCode::OK {
            let mut res = HttpResponse::build(self.status_code);

            let ct = if self.flags.contains(Flags::PREFER_UTF8) {
                equiv_utf8_text(self.content_type.clone())
            } else {
                self.content_type
            };

            res.insert_header((header::CONTENT_TYPE, ct.to_string()));

            if self.flags.contains(Flags::CONTENT_DISPOSITION) {
                res.insert_header((
                    header::CONTENT_DISPOSITION,
                    self.content_disposition.to_string(),
                ));
            }

            if let Some(current_encoding) = self.encoding {
                res.insert_header((header::CONTENT_ENCODING, current_encoding.as_str()));
            }

            let reader =
                chunked::new_chunked_read(self.md.len(), 0, self.file, self.read_mode_threshold);

            return res.streaming(reader);
        }

        let etag = if self.flags.contains(Flags::ETAG) {
            self.etag()
        } else {
            None
        };

        let last_modified = if self.flags.contains(Flags::LAST_MD) {
            self.last_modified()
        } else {
            None
        };

        // check preconditions
        let precondition_failed = if !any_match(etag.as_ref(), req) {
            true
        } else if let (Some(ref m), Some(header::IfUnmodifiedSince(ref since))) =
            (last_modified, req.get_header())
        {
            let t1: SystemTime = (*m).into();
            let t2: SystemTime = (*since).into();

            match (t1.duration_since(UNIX_EPOCH), t2.duration_since(UNIX_EPOCH)) {
                (Ok(t1), Ok(t2)) => t1.as_secs() > t2.as_secs(),
                _ => false,
            }
        } else {
            false
        };

        // check last modified
        let not_modified = if !none_match(etag.as_ref(), req) {
            true
        } else if req.headers().contains_key(header::IF_NONE_MATCH) {
            false
        } else if let (Some(ref m), Some(header::IfModifiedSince(ref since))) =
            (last_modified, req.get_header())
        {
            let t1: SystemTime = (*m).into();
            let t2: SystemTime = (*since).into();

            match (t1.duration_since(UNIX_EPOCH), t2.duration_since(UNIX_EPOCH)) {
                (Ok(t1), Ok(t2)) => t1.as_secs() <= t2.as_secs(),
                _ => false,
            }
        } else {
            false
        };

        let mut res = HttpResponse::build(self.status_code);

        let ct = if self.flags.contains(Flags::PREFER_UTF8) {
            equiv_utf8_text(self.content_type.clone())
        } else {
            self.content_type
        };

        res.insert_header((header::CONTENT_TYPE, ct.to_string()));

        if self.flags.contains(Flags::CONTENT_DISPOSITION) {
            res.insert_header((
                header::CONTENT_DISPOSITION,
                self.content_disposition.to_string(),
            ));
        }

        if let Some(current_encoding) = self.encoding {
            res.insert_header((header::CONTENT_ENCODING, current_encoding.as_str()));
        }

        if let Some(lm) = last_modified {
            res.insert_header((header::LAST_MODIFIED, lm.to_string()));
        }

        if let Some(etag) = &etag {
            res.insert_header((header::ETAG, etag.to_string()));
        }

        res.insert_header((header::ACCEPT_RANGES, "bytes"));

        let mut length = self.md.len();
        let mut offset = 0;
        let mut ranged_req = false;

        // check for range header
        if let Some(ranges) = req
            .headers()
            .get(header::RANGE)
            .filter(|_| if_range_matches(etag.as_ref(), last_modified, req))
        {
            if let Ok(ranges_header) = ranges.to_str() {
                if let Some(range) = HttpRange::parse(ranges_header, length)
                    .ok()
                    .and_then(|ranges| ranges.first().copied())
                {
                    ranged_req = true;
                    length = range.length;
                    offset = range.start;

                    res.insert_header((
                        header::CONTENT_RANGE,
                        format!("bytes {}-{}/{}", offset, offset + length - 1, self.md.len()),
                    ));
                } else {
                    res.insert_header((header::CONTENT_RANGE, format!("bytes */{}", length)));
                    return res.status(StatusCode::RANGE_NOT_SATISFIABLE).finish();
                };
            } else {
                return res.status(StatusCode::BAD_REQUEST).finish();
            };
        };

        if precondition_failed {
            return res.status(StatusCode::PRECONDITION_FAILED).finish();
        } else if not_modified {
            return res
                .status(StatusCode::NOT_MODIFIED)
                .body(body::None::new())
                .map_into_boxed_body();
        }

        let reader = chunked::new_chunked_read(length, offset, self.file, self.read_mode_threshold);

        if ranged_req {
            res.status(StatusCode::PARTIAL_CONTENT);
        }

        res.body(SizedStream::new(length, reader))
    }
}

/// Returns true if `req` has no `If-Match` header or one which matches `etag`.
fn any_match(etag: Option<&header::EntityTag>, req: &HttpRequest) -> bool {
    match req.get_header::<header::IfMatch>() {
        None | Some(header::IfMatch::Any) => true,

        Some(header::IfMatch::Items(ref items)) => {
            if let Some(some_etag) = etag {
                for item in items {
                    if item.strong_eq(some_etag) {
                        return true;
                    }
                }
            }

            false
        }
    }
}

/// Returns true if `req` has no `If-Range` header or one whose validator matches the file.
fn if_range_matches(
    etag: Option<&header::EntityTag>,
    last_modified: Option<header::HttpDate>,
    req: &HttpRequest,
) -> bool {
    if !req.headers().contains_key(header::IF_RANGE) {
        return true;
    }

    match req.get_header::<header::IfRange>() {
        Some(header::IfRange::EntityTag(ref tag)) => etag.is_some_and(|etag| etag.strong_eq(tag)),
        Some(header::IfRange::Date(date)) => last_modified.is_some_and(|m| {
            let t1: SystemTime = m.into();
            let t2: SystemTime = date.into();

            match (t1.duration_since(UNIX_EPOCH), t2.duration_since(UNIX_EPOCH)) {
                (Ok(t1), Ok(t2)) => t1.as_secs() == t2.as_secs(),
                _ => false,
            }
        }),
        None => false,
    }
}

/// Returns true if `req` doesn't have an `If-None-Match` header matching `req`.
fn none_match(etag: Option<&header::EntityTag>, req: &HttpRequest) -> bool {
    match req.get_header::<header::IfNoneMatch>() {
        Some(header::IfNoneMatch::Any) => false,

        Some(header::IfNoneMatch::Items(ref items)) => {
            if let Some(some_etag) = etag {
                for item in items {
                    if item.weak_eq(some_etag) {
                        return false;
                    }
                }
            }

            true
        }

        None => true,
    }
}

impl Responder for NamedFile {
    type Body = BoxBody;

    fn respond_to(self, req: &HttpRequest) -> HttpResponse<Self::Body> {
        self.into_response(req)
    }
}

impl ServiceFactory<ServiceRequest> for NamedFile {
    type Response = ServiceResponse;
    type Error = Error;
    type Config = ();
    type Service = NamedFileService;
    type InitError = ();
    type Future = LocalBoxFuture<'static, Result<Self::Service, Self::InitError>>;

    fn new_service(&self, _: ()) -> Self::Future {
        let service = NamedFileService {
            path: self.path.clone(),
        };

        Box::pin(async move { Ok(service) })
    }
}

#[doc(hidden)]
#[derive(Debug)]
pub struct NamedFileService {
    path: PathBuf,
}

impl Service<ServiceRequest> for NamedFileService {
    type Response = ServiceResponse;
    type Error = Error;
    type Future = LocalBoxFuture<'static, Result<Self::Response, Self::Error>>;

    dev::always_ready!();

    fn call(&self, req: ServiceRequest) -> Self::Future {
        let (req, _) = req.into_parts();

        let path = self.path.clone();
        Box::pin(async move {
            let file = NamedFile::open(path)?;
            let res = file.into_response(&req);
            Ok(ServiceResponse::new(req, res))
        })
    }
}

impl HttpServiceFactory for NamedFile {
    fn register(self, config: &mut AppService) {
        config.register_service(
            ResourceDef::root_prefix(self.path.to_string_lossy().as_ref()),
            None,
            self,
            None,
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn audio_files_use_inline_content_disposition() {
        let (_ct, cd) = get_content_type_and_disposition(Path::new("sound.mp3")).unwrap();
        assert_eq!(cd.disposition, DispositionType::Inline);
    }

    #[test]
    fn special_chars_are_escaped_in_content_disposition_filename() {
        let (_ct, cd) =
            get_content_type_and_disposition(Path::new("test\n\x0B\x0C\rnewline.text")).unwrap();

        assert_eq!(
            cd.to_string(),
            "inline; filename=\"test%0A%0B%0C%0Dnewline.text\"",
        );
    }

    #[cfg(any(unix, windows))]
    #[actix_web::test]
    async fn if_none_match_does_not_match_a_different_file_with_same_size_and_mtime() {
        use std::fs;

        use actix_web::{body::to_bytes, test::TestRequest};
        use filetime::{set_file_mtime, FileTime};

        let dir = tempfile::tempdir().unwrap();
        let first_path = dir.path().join("first.txt");
        let second_path = dir.path().join("second.txt");

        fs::write(&first_path, b"first").unwrap();
        fs::write(&second_path, b"other").unwrap();

        let mtime = FileTime::from_unix_time(1_600_000_000, 0);

        set_file_mtime(&first_path, mtime).unwrap();
        set_file_mtime(&second_path, mtime).unwrap();

        let first_md = fs::metadata(&first_path).unwrap();
        let second_md = fs::metadata(&second_path).unwrap();

        assert_eq!(first_md.len(), second_md.len());
        assert_eq!(first_md.modified().unwrap(), second_md.modified().unwrap());

        let req = TestRequest::default().to_http_request();
        let first = NamedFile::from_file(File::open(&first_path).unwrap(), "file.txt").unwrap();
        let res = first.into_response(&req);
        let etag = res.headers().get(header::ETAG).unwrap().clone();

        let req = TestRequest::default()
            .insert_header((header::IF_NONE_MATCH, etag.clone()))
            .to_http_request();
        let second = NamedFile::from_file(File::open(&second_path).unwrap(), "file.txt").unwrap();
        let res = second.into_response(&req);

        assert_eq!(res.status(), StatusCode::OK);
        assert_ne!(res.headers().get(header::ETAG).unwrap(), &etag);
        assert_eq!(
            to_bytes(res.into_body()).await.unwrap(),
            b"other".as_slice()
        );
    }
}