warpdrive_proxy/middleware/

sendfile.rs

//! X-Sendfile middleware
//!
//! Implements X-Sendfile/X-Accel-Redirect support for efficient file serving.
//! When the upstream application sends an X-Sendfile header, this middleware
//! intercepts it and serves the file directly from disk, bypassing application
//! processing for better performance.
//!
//! # How it works
//!
//! 1. Request phase: Add X-Sendfile-Type header to inform upstream we support it
//! 2. Response phase: Check for X-Sendfile header in upstream response
//! 3. If present: Serve file directly, remove X-Sendfile header from response
//! 4. If absent: Pass through response as-is
//!
//! # Security
//!
//! This implementation trusts the upstream application to only send safe file paths.
//! In production, consider adding path validation to prevent directory traversal.
//!
//! # Note on Pingora Limitations
//!
//! Pingora's filter system doesn't support replacing response bodies in filters.
//! This implementation marks sendfile intent in context; actual file serving
//! would need custom response body handling or a separate file server module.

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

use super::{Middleware, MiddlewareContext};

/// X-Sendfile middleware
///
/// Handles X-Sendfile headers from upstream applications to serve files
/// directly from disk instead of proxying through the application.
pub struct SendfileMiddleware {
    /// Whether sendfile support is enabled
    enabled: bool,
}

impl SendfileMiddleware {
    /// Create new sendfile middleware
    pub fn new() -> Self {
        Self { enabled: true }
    }

    /// Validate file path for security
    ///
    /// This performs basic validation to prevent directory traversal attacks.
    /// In production, you may want more strict validation based on allowed directories.
    pub(crate) fn validate_path(path: &str) -> bool {
        // Reject directory traversal attempts
        if path.starts_with("../") || path.contains("/../") {
            return false;
        }

        // Path must exist and be a file
        let path_buf = PathBuf::from(path);
        if !path_buf.exists() {
            return false;
        }

        if !path_buf.is_file() {
            return false;
        }

        true
    }

    /// Get file metadata for Content-Length header
    ///
    /// This is critical when Content-Encoding is present to ensure
    /// the client knows the actual file size being served.
    fn get_file_size(path: &str) -> Option<u64> {
        std::fs::metadata(path).ok().map(|meta| meta.len())
    }
}

impl Default for SendfileMiddleware {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl Middleware for SendfileMiddleware {
    /// Add X-Sendfile-Type header to request
    ///
    /// This informs the upstream application that we support X-Sendfile,
    /// allowing it to respond with X-Sendfile headers for static files.
    async fn request_filter(
        &self,
        session: &mut Session,
        _ctx: &mut MiddlewareContext,
    ) -> Result<()> {
        if self.enabled {
            session
                .req_header_mut()
                .insert_header("X-Sendfile-Type", "X-Sendfile")?;
            debug!("Added X-Sendfile-Type header to request");
        }

        Ok(())
    }

    /// Check for X-Sendfile header in response and handle file serving
    ///
    /// If X-Sendfile header is present:
    /// 1. Extract file path
    /// 2. Validate path for security
    /// 3. Set Content-Length from file size
    /// 4. Mark sendfile as active in context
    /// 5. Remove X-Sendfile header (internal implementation detail)
    async fn response_filter(
        &self,
        _session: &mut Session,
        upstream_response: &mut ResponseHeader,
        ctx: &mut MiddlewareContext,
    ) -> Result<()> {
        if !self.enabled {
            return Ok(());
        }

        // Check if response has X-Sendfile header and extract the path before mutating
        let sendfile_path_opt = upstream_response
            .headers
            .get("x-sendfile")
            .and_then(|v| v.to_str().ok())
            .map(|s| s.to_string());

        if let Some(file_path) = sendfile_path_opt {
            debug!("X-Sendfile header found: {}", file_path);

            // Validate file path
            if !Self::validate_path(&file_path) {
                warn!("Invalid X-Sendfile path: {}", file_path);
                return Err(Error::explain(
                    ErrorType::HTTPStatus(403),
                    "Invalid X-Sendfile path",
                ));
            }

            // Get file size for Content-Length
            if let Some(file_size) = Self::get_file_size(&file_path) {
                // Set Content-Length header
                // This is critical when Content-Encoding is present
                upstream_response.insert_header("Content-Length", file_size.to_string())?;

                debug!("Set Content-Length to {} for X-Sendfile", file_size);
            } else {
                // If we can't get file size, remove Content-Length to be safe
                upstream_response.remove_header("Content-Length");
            }

            // Load file contents into memory for downstream body replacement
            match fs::read(&file_path).await {
                Ok(contents) => {
                    let body = Bytes::from(contents);
                    ctx.sendfile.activate(file_path.clone(), body);
                }
                Err(err) => {
                    warn!("Failed to read X-Sendfile path {}: {}", file_path, err);
                    return Err(Error::explain(
                        ErrorType::HTTPStatus(500),
                        "Failed to read X-Sendfile path",
                    ));
                }
            }

            // Remove X-Sendfile header (internal implementation detail)
            upstream_response.remove_header("X-Sendfile");

            debug!("X-Sendfile configured for: {}", file_path);

            // Actual body replacement occurs in response_body_filter via MiddlewareContext
        }

        Ok(())
    }
}

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

    #[test]
    fn test_validate_path() {
        // Invalid paths (directory traversal)
        assert!(!SendfileMiddleware::validate_path("../etc/passwd"));
        assert!(!SendfileMiddleware::validate_path(
            "foo/../../../etc/passwd"
        ));

        // Non-existent file should fail validation
        assert!(!SendfileMiddleware::validate_path(
            "/nonexistent/path/to/file.txt"
        ));

        // This source file should exist and be valid
        let this_file = file!();
        assert!(SendfileMiddleware::validate_path(this_file));

        // Absolute paths are allowed when they point to files
        let abs_path = env::current_dir().unwrap().join(this_file);
        let abs_path = abs_path.to_string_lossy();
        assert!(SendfileMiddleware::validate_path(abs_path.as_ref()));
    }

    #[test]
    fn test_sendfile_middleware_creation() {
        let middleware = SendfileMiddleware::new();
        assert!(middleware.enabled);

        let middleware_default = SendfileMiddleware::default();
        assert!(middleware_default.enabled);
    }

    #[test]
    fn test_get_file_size() {
        // Test with non-existent file
        assert!(SendfileMiddleware::get_file_size("/non/existent/file.txt").is_none());

        // Test with this source file (should exist)
        let this_file = file!();
        assert!(SendfileMiddleware::get_file_size(this_file).is_some());
    }
}