warpdrive_proxy/middleware/

static_files.rs

//! Static file serving middleware
//!
//! Serves static files directly from disk without proxying to the upstream application.
//! This provides massive performance improvements for serving assets like JavaScript, CSS,
//! images, and other static content.
//!
//! # How it works
//!
//! 1. Request arrives (e.g., `/assets/application-abc123.js`)
//! 2. Check if path matches configured static paths (`/assets`, `/packs`, etc.)
//! 3. If match: resolve to file on disk (`./public/assets/application-abc123.js`)
//! 4. Validate path security (prevent directory traversal)
//! 5. (Future) Optional cache lookup (L1 memory, L2 Redis)
//! 6. Read file from disk (stream large files)
//! 7. If file not found and fallthrough=true: continue to upstream
//! 8. If file not found and fallthrough=false: return 404
//!
//! # Performance
//!
//! - Cache hit: <1ms (sub-millisecond from memory)
//! - Cache miss: 1-5ms (read from disk + cache)
//! - vs Rails: 100x faster (no Rails stack, no Ruby)
//!
//! # Security
//!
//! - Directory traversal prevention
//! - Hidden file blocking
//! - Symlink validation
//! - File size limits

use async_trait::async_trait;
use bytes::Bytes;
use pingora::http::ResponseHeader;
use pingora::prelude::*;
use std::path::{Path, PathBuf};
use tokio::fs;
use tracing::{debug, warn};

use super::{Middleware, MiddlewareContext, StaticResponse, StaticResponseBody};
use crate::config::Config;
#[cfg(test)]
use crate::config::DEFAULT_STATIC_INLINE_SIZE_LIMIT;

/// MIME type mapping for common file extensions
const MIME_TYPES: &[(&str, &str)] = &[
    // JavaScript
    ("js", "application/javascript"),
    ("mjs", "application/javascript"),
    // CSS
    ("css", "text/css"),
    // HTML
    ("html", "text/html"),
    ("htm", "text/html"),
    // Images
    ("jpg", "image/jpeg"),
    ("jpeg", "image/jpeg"),
    ("png", "image/png"),
    ("gif", "image/gif"),
    ("svg", "image/svg+xml"),
    ("webp", "image/webp"),
    ("ico", "image/x-icon"),
    // Fonts
    ("woff", "font/woff"),
    ("woff2", "font/woff2"),
    ("ttf", "font/ttf"),
    ("otf", "font/otf"),
    ("eot", "application/vnd.ms-fontobject"),
    // Other
    ("json", "application/json"),
    ("xml", "application/xml"),
    ("pdf", "application/pdf"),
    ("txt", "text/plain"),
    ("map", "application/json"), // Source maps
];

/// Static file serving middleware
pub struct StaticFilesMiddleware {
    /// Whether static file serving is enabled
    enabled: bool,

    /// Root directory for static files
    root: PathBuf,

    /// URL path prefixes that should be served as static files
    paths: Vec<String>,

    /// Cache-Control header value
    cache_control: String,

    /// Whether gzip serving is enabled
    gzip_enabled: bool,

    /// Index files to try for directory requests
    index_files: Vec<String>,

    /// If true, continue to backend when file not found; if false, return 404
    fallthrough: bool,

    /// Maximum file size to keep in memory (larger files are streamed)
    inline_file_size_limit: u64,
}

impl StaticFilesMiddleware {
    /// Create new static files middleware from configuration
    pub fn from_config(config: &Config) -> Self {
        Self {
            enabled: config.static_enabled,
            root: config.static_root.clone(),
            paths: config.static_paths.clone(),
            cache_control: config.static_cache_control.clone(),
            gzip_enabled: config.static_gzip_enabled,
            index_files: config.static_index_files.clone(),
            fallthrough: config.static_fallthrough,
            inline_file_size_limit: config.static_inline_size_limit,
        }
    }

    /// Check if the request path matches configured static paths
    fn matches_static_path(&self, path: &str) -> bool {
        self.paths.iter().any(|prefix| path.starts_with(prefix))
    }

    /// Resolve URL path to filesystem path
    ///
    /// Example: `/assets/app-123.js` + `./public` → `./public/assets/app-123.js`
    fn resolve_path(&self, url_path: &str) -> PathBuf {
        // Remove leading slash for joining
        let relative_path = url_path.trim_start_matches('/');
        self.root.join(relative_path)
    }

    /// Validate file path for security
    ///
    /// Prevents:
    /// - Directory traversal (`../`)
    /// - Symlinks outside root (optional)
    /// - Hidden files (`.` prefix)
    fn validate_path(&self, file_path: &Path) -> bool {
        // Reject symlinks to avoid exposing files outside the static root
        if let Ok(metadata) = std::fs::symlink_metadata(file_path) {
            if metadata.file_type().is_symlink() {
                warn!("Symlink access blocked: {:?}", file_path);
                return false;
            }
        }

        // Convert to absolute path for validation
        let file_path = match file_path.canonicalize() {
            Ok(p) => p,
            Err(_) => return false, // File doesn't exist or can't be accessed
        };

        let root = match self.root.canonicalize() {
            Ok(p) => p,
            Err(_) => {
                warn!("Static root directory doesn't exist: {:?}", self.root);
                return false;
            }
        };

        // Ensure file is within root directory
        if !file_path.starts_with(&root) {
            warn!("Path traversal attempt blocked: {:?}", file_path);
            return false;
        }

        // Check if it's a file (not a directory)
        if !file_path.is_file() {
            return false;
        }

        // Block hidden files (.htaccess, .env, etc.)
        if let Some(filename) = file_path.file_name() {
            if filename.to_string_lossy().starts_with('.') {
                warn!("Hidden file access blocked: {:?}", file_path);
                return false;
            }
        }

        true
    }

    /// Detect MIME type from file extension
    fn detect_content_type(path: &Path) -> &'static str {
        if let Some(ext) = path.extension() {
            let ext_str = ext.to_string_lossy().to_lowercase();
            for (extension, mime_type) in MIME_TYPES {
                if ext_str == *extension {
                    return mime_type;
                }
            }
        }

        // Default to octet-stream for unknown types
        "application/octet-stream"
    }

    /// Generate ETag from file metadata
    ///
    /// Format: "{size}-{mtime_nanos}"
    /// Example: "12345-1609459200000000000"
    fn generate_etag(metadata: &std::fs::Metadata) -> Option<String> {
        let size = metadata.len();
        let mtime = metadata.modified().ok()?;
        let mtime_nanos = mtime.duration_since(std::time::UNIX_EPOCH).ok()?.as_nanos();

        Some(format!("\"{}-{}\"", size, mtime_nanos))
    }

    /// Try to serve gzipped version of file if available
    ///
    /// Checks for `{file}.gz` and serves if:
    /// 1. Gzip enabled
    /// 2. Client accepts gzip (Accept-Encoding: gzip)
    /// 3. `.gz` file exists
    fn try_gzip_path(&self, path: &Path) -> Option<PathBuf> {
        if !self.gzip_enabled {
            return None;
        }

        let mut gz_path = path.to_path_buf();
        let mut filename = gz_path.file_name()?.to_os_string();
        filename.push(".gz");
        gz_path.set_file_name(filename);

        if gz_path.exists() && gz_path.is_file() {
            Some(gz_path)
        } else {
            None
        }
    }

    /// Serve index file for directory requests
    ///
    /// If request is for `/assets/` try `/assets/index.html`, `/assets/index.htm`, etc.
    async fn try_index_file(&self, dir_path: &Path) -> Option<PathBuf> {
        for index_file in &self.index_files {
            let index_path = dir_path.join(index_file);
            if index_path.exists() && index_path.is_file() {
                return Some(index_path);
            }
        }
        None
    }
}

#[async_trait]
impl Middleware for StaticFilesMiddleware {
    /// Check if request matches static path and serve file
    ///
    /// This runs BEFORE proxying to upstream, allowing us to intercept
    /// static file requests and serve them directly.
    async fn request_filter(
        &self,
        session: &mut Session,
        ctx: &mut MiddlewareContext,
    ) -> Result<()> {
        if !self.enabled {
            return Ok(());
        }

        let req_path = session.req_header().uri.path();

        // Check if path matches configured static paths
        if !self.matches_static_path(req_path) {
            return Ok(());
        }

        debug!("Static file request: {}", req_path);

        // Resolve to filesystem path
        let mut file_path = self.resolve_path(req_path);

        // If path ends with `/`, try index files
        if req_path.ends_with('/') {
            if let Some(index_path) = self.try_index_file(&file_path).await {
                file_path = index_path;
            }
        }

        // Validate path security
        if !self.validate_path(&file_path) {
            if self.fallthrough {
                // File doesn't exist or invalid - continue to upstream
                debug!("Static file not found, falling through: {:?}", file_path);
                return Ok(());
            } else {
                // Return 404
                debug!("Static file not found, returning 404: {:?}", file_path);
                return Err(Error::explain(ErrorType::HTTPStatus(404), "File not found"));
            }
        }

        // Check for gzipped version if client accepts gzip
        let accept_encoding = session
            .req_header()
            .headers
            .get("accept-encoding")
            .and_then(|v| v.to_str().ok())
            .unwrap_or("");

        let (serve_path, is_gzipped) = if accept_encoding.contains("gzip") {
            if let Some(gz_path) = self.try_gzip_path(&file_path) {
                if self.validate_path(&gz_path) {
                    debug!("Serving gzipped version: {:?}", gz_path);
                    (gz_path, true)
                } else {
                    (file_path, false)
                }
            } else {
                (file_path, false)
            }
        } else {
            (file_path, false)
        };

        // Retrieve metadata once (size, mtime, etc.)
        let metadata = match fs::metadata(&serve_path).await {
            Ok(meta) => meta,
            Err(err) => {
                warn!("Failed to stat static file {:?}: {}", serve_path, err);
                if self.fallthrough {
                    return Ok(());
                } else {
                    return Err(Error::explain(ErrorType::HTTPStatus(404), "File not found"));
                }
            }
        };

        let file_len = metadata.len();

        // Generate ETag from metadata
        let etag = Self::generate_etag(&metadata);

        // Check If-None-Match for 304 Not Modified
        if let Some(ref etag_value) = etag {
            if let Some(if_none_match) = session
                .req_header()
                .headers
                .get("if-none-match")
                .and_then(|v| v.to_str().ok())
            {
                if if_none_match == etag_value {
                    debug!("ETag match, returning 304 Not Modified");

                    // Create 304 response
                    let mut resp = ResponseHeader::build(304, None)?;
                    resp.insert_header("ETag", etag_value)?;
                    resp.insert_header("Cache-Control", &self.cache_control)?;

                    ctx.static_response = Some(StaticResponse {
                        header: resp,
                        body: StaticResponseBody::InMemory(Bytes::new()),
                    });
                    return Ok(());
                }
            }
        }

        // Build response headers
        let mut resp = ResponseHeader::build(200, None)?;

        let content_type = Self::detect_content_type(&serve_path);
        resp.insert_header("Content-Type", content_type)?;
        resp.insert_header("Content-Length", file_len.to_string())?;
        resp.insert_header("Cache-Control", &self.cache_control)?;

        if let Some(etag_value) = etag {
            resp.insert_header("ETag", &etag_value)?;
        }

        if is_gzipped {
            resp.insert_header("Content-Encoding", "gzip")?;
            // Remove .gz from Content-Type determination
            let original_path = serve_path.with_extension("");
            let original_content_type = Self::detect_content_type(&original_path);
            resp.insert_header("Content-Type", original_content_type)?;
        }

        let body = if file_len <= self.inline_file_size_limit {
            match fs::read(&serve_path).await {
                Ok(data) => StaticResponseBody::InMemory(Bytes::from(data)),
                Err(err) => {
                    warn!("Failed to read static file {:?}: {}", serve_path, err);
                    if self.fallthrough {
                        return Ok(());
                    } else {
                        return Err(Error::explain(
                            ErrorType::HTTPStatus(500),
                            "Failed to read file",
                        ));
                    }
                }
            }
        } else {
            StaticResponseBody::Stream(serve_path.clone())
        };

        debug!(
            "Serving static file: {:?} ({} bytes, {})",
            serve_path, file_len, content_type
        );

        // Store response in context to short-circuit proxy
        ctx.static_response = Some(StaticResponse { header: resp, body });

        Ok(())
    }
}

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

    #[test]
    fn test_mime_type_detection() {
        assert_eq!(
            StaticFilesMiddleware::detect_content_type(Path::new("app.js")),
            "application/javascript"
        );
        assert_eq!(
            StaticFilesMiddleware::detect_content_type(Path::new("style.css")),
            "text/css"
        );
        assert_eq!(
            StaticFilesMiddleware::detect_content_type(Path::new("image.png")),
            "image/png"
        );
        assert_eq!(
            StaticFilesMiddleware::detect_content_type(Path::new("unknown.xyz")),
            "application/octet-stream"
        );
    }

    #[test]
    fn test_path_matching() {
        let middleware = StaticFilesMiddleware {
            enabled: true,
            root: PathBuf::from("./public"),
            paths: vec!["/assets".to_string(), "/packs".to_string()],
            cache_control: "public, max-age=31536000".to_string(),
            gzip_enabled: true,
            index_files: vec!["index.html".to_string()],
            fallthrough: true,
            inline_file_size_limit: DEFAULT_STATIC_INLINE_SIZE_LIMIT,
        };

        assert!(middleware.matches_static_path("/assets/app.js"));
        assert!(middleware.matches_static_path("/packs/application.css"));
        assert!(!middleware.matches_static_path("/api/users"));
    }

    #[test]
    fn test_path_resolution() {
        let middleware = StaticFilesMiddleware {
            enabled: true,
            root: PathBuf::from("./public"),
            paths: vec!["/assets".to_string()],
            cache_control: String::new(),
            gzip_enabled: false,
            index_files: vec![],
            fallthrough: true,
            inline_file_size_limit: DEFAULT_STATIC_INLINE_SIZE_LIMIT,
        };

        let resolved = middleware.resolve_path("/assets/app.js");
        assert_eq!(resolved, PathBuf::from("./public/assets/app.js"));
    }
}