ServeDir 与 ServeFile

axum = "=0.8.9"
tower-http = { version = "=0.7.1", features = ["fs"] }
tower = { version = "=0.5.3", features = ["util"] }
http-body-util = "0.1"
tokio = { version = "=1.54.1", features = ["macros", "rt-multi-thread"] }

pub struct ServeDir<F = DefaultServeDirFallback, B = TokioBackend> {
    base: PathBuf,
    redirect_path_prefix: String,
    buf_chunk_size: usize,
    ignore_multi_range_requests: bool,
    precompressed_variants: Option<PrecompressedVariants>,
    // This is used to specialize implementation for
    // single files
    variant: ServeVariant,
    fallback: Option<F>,
    call_fallback_on_method_not_allowed: bool,
    backend: B,
}

                let path = requested_path.trim_start_matches('/');

                let path_decoded = percent_decode(path.as_ref()).decode_utf8().ok()?;
                let path_decoded = Path::new(&*path_decoded);

                let mut path_to_file = base_path.to_path_buf();
                for component in path_decoded.components() {
                    match component {
                        Component::Normal(comp) => {
                            // protect against paths like `/foo/c:/bar/baz` (#204)
                            if Path::new(&comp)
                                .components()
                                .all(|c| matches!(c, Component::Normal(_)))
                            {
                                // ... Windows 上还要拒绝 CON、COM1 这类保留名
                                path_to_file.push(comp)
                            } else {
                                return None;
                            }
                        }
                        Component::CurDir => {}
                        Component::Prefix(_) | Component::RootDir | Component::ParentDir => {
                            return None;
                        }
                    }
                }
                Some(path_to_file)

use axum::{body::Body, http::Request};
use http_body_util::BodyExt;
use std::fs;
use tower::ServiceExt;
use tower_http::services::ServeDir;

async fn show<S>(svc: S, method: &str, uri: &str)
where
  S: tower::Service<Request<Body>, Error = std::convert::Infallible>,
  S::Response: axum::response::IntoResponse,
{
  let req = Request::builder().method(method).uri(uri).body(Body::empty()).unwrap();
  let res = axum::response::IntoResponse::into_response(svc.oneshot(req).await.unwrap());
  let status = res.status();
  let loc = res.headers().get("location").map(|v| format!(" location={}", v.to_str().unwrap())).unwrap_or_default();
  let allow = res.headers().get("allow").map(|v| format!(" allow={}", v.to_str().unwrap())).unwrap_or_default();
  let body = res.into_body().collect().await.unwrap().to_bytes();
  println!("{method:<4} {uri:<28} {status}{loc}{allow} body={:?}", String::from_utf8_lossy(&body));
}

#[tokio::main]
async fn main() {
  let _ = fs::remove_dir_all("tmp/paths");
  fs::create_dir_all("tmp/paths/site/docs").unwrap();
  fs::write("tmp/paths/secret.txt", "SECRET").unwrap();
  fs::write("tmp/paths/site/a.txt", "A").unwrap();
  fs::write("tmp/paths/site/docs/index.html", "DOCS").unwrap();
  fs::write("tmp/paths/site/x\\y.txt", "BACKSLASH").unwrap();

  let dir = ServeDir::new("tmp/paths/site");
  for uri in [
    "/a.txt",
    "/../secret.txt",
    "/%2e%2e/secret.txt",
    "/docs/..%2f..%2fsecret.txt",
    "/..%5csecret.txt",
    "/x%5cy.txt",
    "//a.txt",
    "/c:/a.txt",
    "/a.txt%00",
    "/%ff",
    "/a.txt/",
    "/docs",
    "/docs?v=1",
    "/docs/",
  ] {
    show(dir.clone(), "GET", uri).await;
  }
  show(dir.clone(), "POST", "/a.txt").await;

  println!("-- redirect_to_trailing_slash(false)");
  show(dir.clone().redirect_to_trailing_slash(false), "GET", "/docs").await;
  println!("-- append_index_html_on_directories(false)");
  show(dir.clone().append_index_html_on_directories(false), "GET", "/docs/").await;
}

GET  /a.txt                       200 OK body="A"
GET  /../secret.txt               404 Not Found body=""
GET  /%2e%2e/secret.txt           404 Not Found body=""
GET  /docs/..%2f..%2fsecret.txt   404 Not Found body=""
GET  /..%5csecret.txt             404 Not Found body=""
GET  /x%5cy.txt                   200 OK body="BACKSLASH"
GET  //a.txt                      200 OK body="A"
GET  /c:/a.txt                    404 Not Found body=""
GET  /a.txt%00                    404 Not Found body=""
GET  /%ff                         404 Not Found body=""
GET  /a.txt/                      404 Not Found body=""
GET  /docs                        307 Temporary Redirect location=/docs/ body=""
GET  /docs?v=1                    307 Temporary Redirect location=/docs/?v=1 body=""
GET  /docs/                       200 OK body="DOCS"
POST /a.txt                       405 Method Not Allowed allow=GET,HEAD body=""
-- redirect_to_trailing_slash(false)
GET  /docs                        200 OK body="DOCS"
-- append_index_html_on_directories(false)
GET  /docs/                       404 Not Found body=""

    let is_directory = is_dir(path_to_file, backend).await?;

    if uri_path.ends_with('/') && uri_path != "/" && is_directory != Some(true) {
        return Ok(Some(OpenFileOutput::FileNotFound));
    }

    // If the path has no extension and doesn't exist as a file, try appending .html
    if html_as_default_extension && is_directory.is_none() && path_to_file.extension().is_none() {
        path_to_file.set_extension("html");
        return Ok(None);
    }

    if is_directory != Some(true) {
        return Ok(None);
    }

    if !append_index_html_on_directories {
        return Ok(Some(OpenFileOutput::FileNotFound));
    }

    if uri_path.ends_with('/') || !redirect_to_trailing_slash {
        path_to_file.push("index.html");
        Ok(None)
    } else {
        let uri = match append_slash_on_path(uri.clone(), redirect_path_prefix) {
            Ok(uri) => uri,
            Err(err) => return Ok(Some(err)),
        };
        let location = HeaderValue::from_str(&uri.to_string()).unwrap();
        Ok(Some(OpenFileOutput::Redirect { location }))
    }

    let (file, encoding) = loop {
        // Get the preferred encoding among the negotiated ones.
        let encoding = preferred_encoding(&mut path, &negotiated_encoding);
        match (backend.open(path.clone()).await, encoding) {
            (Ok(file), maybe_encoding) => break (file, maybe_encoding),
            (Err(err), Some(encoding))
                if err.kind() == io::ErrorKind::NotFound && encoding != Encoding::Identity =>
            {
                // Remove the extension corresponding to a precompressed file (.gz, .br, .zz)
                // to reset the path before the next iteration.
                path.set_extension(OsStr::new(""));
                // Remove the encoding from the negotiated_encodings since the file doesn't exist
                negotiated_encoding
                    .retain(|(negotiated_encoding, _)| *negotiated_encoding != encoding);
            }
            (Err(err), _) => return Err(err),
        }
    };

use axum::{body::Body, http::Request};
use http_body_util::BodyExt;
use std::fs;
use tower::ServiceExt;
use tower_http::services::ServeDir;

async fn show(dir: &ServeDir, uri: &str, accept: Option<&str>) {
  let mut req = Request::get(uri);
  if let Some(a) = accept {
    req = req.header("accept-encoding", a);
  }
  let res = dir.clone().oneshot(req.body(Body::empty()).unwrap()).await.unwrap();
  let h = |name: &str| res.headers().get(name).map(|v| v.to_str().unwrap().to_owned()).unwrap_or("-".into());
  let line = format!(
    "{:<8} {:<26} {} enc={} vary={} len={}",
    uri,
    format!("{accept:?}"),
    res.status().as_u16(),
    h("content-encoding"),
    h("vary"),
    h("content-length"),
  );
  let body = res.into_body().collect().await.unwrap().to_bytes();
  println!("{line} body={:?}", String::from_utf8_lossy(&body));
}

#[tokio::main]
async fn main() {
  let _ = fs::remove_dir_all("tmp/enc");
  fs::create_dir_all("tmp/enc").unwrap();
  // fake "compressed" files: the content only shows which file was picked
  fs::write("tmp/enc/app.js", "plain").unwrap();
  fs::write("tmp/enc/app.js.gz", "gz").unwrap();
  fs::write("tmp/enc/app.js.br", "br").unwrap();
  fs::write("tmp/enc/only.js", "plain").unwrap();
  fs::write("tmp/enc/only.js.gz", "gz").unwrap();

  let dir = ServeDir::new("tmp/enc").precompressed_gzip().precompressed_br();
  for accept in [
    None,
    Some("gzip"),
    Some("gzip, br"),
    Some("br;q=0.5, gzip"),
    Some("br;q=0"),
    Some("zstd"),
    Some("*"),
    Some("gzip;q=0.5000"),
  ] {
    show(&dir, "/app.js", accept).await;
  }
  show(&dir, "/only.js", Some("br, gzip")).await;
  println!("-- no precompressed_* configured");
  show(&ServeDir::new("tmp/enc"), "/app.js", Some("gzip, br")).await;
}

/app.js  None                       200 enc=- vary=accept-encoding len=5 body="plain"
/app.js  Some("gzip")               200 enc=gzip vary=accept-encoding len=2 body="gz"
/app.js  Some("gzip, br")           200 enc=br vary=accept-encoding len=2 body="br"
/app.js  Some("br;q=0.5, gzip")     200 enc=gzip vary=accept-encoding len=2 body="gz"
/app.js  Some("br;q=0")             200 enc=- vary=accept-encoding len=5 body="plain"
/app.js  Some("zstd")               200 enc=- vary=accept-encoding len=5 body="plain"
/app.js  Some("*")                  200 enc=- vary=accept-encoding len=5 body="plain"
/app.js  Some("gzip;q=0.5000")      200 enc=- vary=accept-encoding len=5 body="plain"
/only.js Some("br, gzip")           200 enc=gzip vary=accept-encoding len=2 body="gz"
-- no precompressed_* configured
/app.js  Some("gzip, br")           200 enc=- vary=- len=5 body="plain"

    let header_value = maybe_range_ref?;
    let parsed = match http_range_header::parse_range_header(header_value) {
        Ok(parsed) => parsed,
        Err(_) => return Some(Err(RangeError::Unsatisfiable)),
    };

    if parsed.ranges.len() > 1 {
        // ServeDir/ServeFile do not support multipart responses. Optionally ignore
        // the Range header before validate() runs semantic and overlap checks.
        return if ignore_multi_range_requests {
            None
        } else {
            Some(Err(RangeError::MultipleRangesNotSupported))
        };
    }

    Some(
        parsed
            .validate(file_size)
            .map_err(|_| RangeError::Unsatisfiable)
            .and_then(|mut ranges| ranges.pop().ok_or(RangeError::Unsatisfiable)),
    )

        let value = format!(
            "\"{:x}.{:08x}-{:x}\"",
            duration.as_secs(),
            duration.subsec_nanos(),
            size
        );

    /// Precedence order:
    /// 1. If-Match (strong comparison) → 412 on failure
    /// 2. If-Unmodified-Since (only if If-Match absent) → 412 on failure
    /// 3. If-None-Match (weak comparison) → 304 on failure (for GET/HEAD)
    /// 4. If-Modified-Since (only if If-None-Match absent) → 304 on failure

use axum::{body::Body, http::Request};
use http_body_util::BodyExt;
use std::{
  fs,
  time::{Duration, SystemTime},
};
use tower::ServiceExt;
use tower_http::services::ServeDir;

async fn show(dir: &ServeDir, method: &str, headers: &[(&str, &str)]) {
  let mut req = Request::builder().method(method).uri("/digits.txt");
  for (k, v) in headers {
    req = req.header(*k, *v);
  }
  let res = dir.clone().oneshot(req.body(Body::empty()).unwrap()).await.unwrap();
  let h = |name: &str| res.headers().get(name).map(|v| v.to_str().unwrap().to_owned()).unwrap_or("-".into());
  let line = format!(
    "{method:<4} {:<34} {} range={} len={} type={}",
    format!("{headers:?}").trim_start_matches('[').trim_end_matches(']').to_owned(),
    res.status().as_u16(),
    h("content-range"),
    h("content-length"),
    h("content-type"),
  );
  let body = res.into_body().collect().await.unwrap().to_bytes();
  let text = String::from_utf8_lossy(&body);
  if text.len() > 40 {
    println!("{line} body={} bytes", text.len());
  } else {
    println!("{line} body={text:?}");
  }
}

#[tokio::main]
async fn main() {
  let _ = fs::remove_dir_all("tmp/range");
  fs::create_dir_all("tmp/range").unwrap();
  let digits: String = (0..100).map(|i| char::from(b'0' + (i % 10) as u8)).collect();
  fs::write("tmp/range/digits.txt", &digits).unwrap();
  // pin mtime so ETag / Last-Modified are the same on every run
  let mtime = SystemTime::UNIX_EPOCH + Duration::new(1_767_225_600, 123_456_789);
  fs::File::options().write(true).open("tmp/range/digits.txt").unwrap().set_modified(mtime).unwrap();

  let dir = ServeDir::new("tmp/range");
  let res = dir.clone().oneshot(Request::get("/digits.txt").body(Body::empty()).unwrap()).await.unwrap();
  let etag = res.headers()["etag"].to_str().unwrap().to_owned();
  let last_modified = res.headers()["last-modified"].to_str().unwrap().to_owned();
  println!("etag={etag} last-modified={last_modified} accept-ranges={:?}", res.headers()["accept-ranges"]);

  println!("-- Range");
  for range in ["bytes=0-9", "bytes=95-", "bytes=-3", "bytes=90-200", "bytes=100-", "bytes=0-1,5-6", "bytes=abc"] {
    show(&dir, "GET", &[("range", range)]).await;
  }
  show(&dir, "HEAD", &[("range", "bytes=0-9")]).await;
  println!("-- ignore_multi_range_requests(true)");
  let lenient = dir.clone().ignore_multi_range_requests(true);
  show(&lenient, "GET", &[("range", "bytes=0-1,5-6")]).await;
  show(&lenient, "GET", &[("range", "bytes=5-1,200-300")]).await;
  show(&lenient, "GET", &[("range", "bytes=200-")]).await;

  println!("-- conditional");
  show(&dir, "GET", &[("if-none-match", etag.as_str())]).await;
  show(&dir, "GET", &[("if-none-match", "\"other\"")]).await;
  show(&dir, "GET", &[("if-modified-since", last_modified.as_str())]).await;
  show(&dir, "GET", &[("if-modified-since", "Wed, 31 Dec 2025 23:59:59 GMT")]).await;
  show(&dir, "GET", &[("if-none-match", "\"other\""), ("if-modified-since", last_modified.as_str())]).await;
  show(&dir, "GET", &[("if-match", "\"other\"")]).await;
  show(&dir, "GET", &[("if-unmodified-since", "Wed, 31 Dec 2025 23:59:59 GMT")]).await;
}

etag="6955b900.075bcd15-64" last-modified=Thu, 01 Jan 2026 00:00:00 GMT accept-ranges="bytes"
-- Range
GET  ("range", "bytes=0-9")             206 range=bytes 0-9/100 len=10 type=text/plain body="0123456789"
GET  ("range", "bytes=95-")             206 range=bytes 95-99/100 len=5 type=text/plain body="56789"
GET  ("range", "bytes=-3")              206 range=bytes 97-99/100 len=3 type=text/plain body="789"
GET  ("range", "bytes=90-200")          206 range=bytes 90-99/100 len=10 type=text/plain body="0123456789"
GET  ("range", "bytes=100-")            416 range=bytes */100 len=- type=- body=""
GET  ("range", "bytes=0-1,5-6")         416 range=bytes */100 len=- type=- body="Cannot serve multipart range requests"
GET  ("range", "bytes=abc")             416 range=bytes */100 len=- type=- body=""
HEAD ("range", "bytes=0-9")             206 range=bytes 0-9/100 len=10 type=text/plain body=""
-- ignore_multi_range_requests(true)
GET  ("range", "bytes=0-1,5-6")         200 range=- len=100 type=text/plain body=100 bytes
GET  ("range", "bytes=5-1,200-300")     200 range=- len=100 type=text/plain body=100 bytes
GET  ("range", "bytes=200-")            416 range=bytes */100 len=- type=- body=""
-- conditional
GET  ("if-none-match", "\"6955b900.075bcd15-64\"") 304 range=- len=- type=- body=""
GET  ("if-none-match", "\"other\"")     200 range=- len=100 type=text/plain body=100 bytes
GET  ("if-modified-since", "Thu, 01 Jan 2026 00:00:00 GMT") 304 range=- len=- type=- body=""
GET  ("if-modified-since", "Wed, 31 Dec 2025 23:59:59 GMT") 200 range=- len=100 type=text/plain body=100 bytes
GET  ("if-none-match", "\"other\""), ("if-modified-since", "Thu, 01 Jan 2026 00:00:00 GMT") 200 range=- len=100 type=text/plain body=100 bytes
GET  ("if-match", "\"other\"")          412 range=- len=- type=- body=""
GET  ("if-unmodified-since", "Wed, 31 Dec 2025 23:59:59 GMT") 412 range=- len=- type=- body=""

use axum::{body::Body, http::Request};
use http_body_util::BodyExt;
use tower::ServiceExt;
use tower_http::services::ServeDir;

#[tokio::main]
async fn main() {
  std::fs::create_dir_all("tmp/chunks").unwrap();
  std::fs::write("tmp/chunks/big.bin", vec![b'x'; 200_000]).unwrap();
  for (name, dir) in [
    ("default", ServeDir::new("tmp/chunks")),
    ("16 KiB", ServeDir::new("tmp/chunks").with_buf_chunk_size(16 * 1024)),
  ] {
    let req = Request::get("/big.bin").body(Body::empty()).unwrap();
    let mut body = dir.oneshot(req).await.unwrap().into_body();
    let mut sizes = Vec::new();
    while let Some(frame) = body.frame().await {
      sizes.push(frame.unwrap().into_data().unwrap().len());
    }
    println!("{name:<8} frames={} sizes={:?}", sizes.len(), sizes);
  }
}

default  frames=4 sizes=[65536, 65536, 65536, 3392]
16 KiB   frames=13 sizes=[16384, 16384, 16384, 16384, 16384, 16384, 16384, 16384, 16384, 16384, 16384, 16384, 3392]

                let response = result.unwrap_or_else(|err| {
                    let status = if should_return_not_found(&err) {
                        StatusCode::NOT_FOUND
                    } else {
                        #[cfg(feature = "tracing")]
                        tracing::error!(error = %err, "Failed to read file");

                        StatusCode::INTERNAL_SERVER_ERROR
                    };
                    // ... 空 body
                });

                    Err(err) => {
                        if super::should_return_not_found(&err) {
                            if let Some((mut fallback, request)) = fallback_and_request.take() {
                                call_fallback(&mut fallback, request)
                            } else {
                                break Poll::Ready(Err(err));
                            }
                        } else {
                            break Poll::Ready(Err(err));
                        }
                    }

use axum::{body::Body, http::Request};
use http_body_util::BodyExt;
use std::{fs, os::unix::fs::PermissionsExt};
use tower::ServiceExt;
use tower_http::services::{ServeDir, ServeFile};

fn req(uri: &str) -> Request<Body> {
  Request::get(uri).body(Body::empty()).unwrap()
}

#[tokio::main]
async fn main() {
  // undo the previous run's chmod so the directory can be removed
  let _ = fs::set_permissions("tmp/try/site/locked", fs::Permissions::from_mode(0o755));
  let _ = fs::remove_dir_all("tmp/try");
  fs::create_dir_all("tmp/try/site/locked").unwrap();
  fs::write("tmp/try/site/a.txt", "A").unwrap();
  fs::write("tmp/try/site/locked/f.txt", "F").unwrap();
  fs::write("tmp/try/site/nope.txt", "N").unwrap();
  fs::write("tmp/try/404.html", "custom 404").unwrap();
  fs::set_permissions("tmp/try/site/nope.txt", fs::Permissions::from_mode(0o000)).unwrap();
  fs::set_permissions("tmp/try/site/locked", fs::Permissions::from_mode(0o000)).unwrap();

  let uris = ["/a.txt", "/missing.txt", "/../a.txt", "/..%5ca.txt", "/a.txt/x", "/nope.txt", "/locked/f.txt"];
  println!("{:<16} {:<44} {}", "uri", "try_call", "call");
  for uri in uris {
    let mut dir = ServeDir::new("tmp/try/site");
    let tried = match dir.try_call(req(uri)).await {
      Ok(res) => format!("Ok({})", res.status()),
      Err(err) => format!("Err({:?}, os={:?})", err.kind(), err.raw_os_error()),
    };
    let called = ServeDir::new("tmp/try/site").oneshot(req(uri)).await.unwrap().status();
    println!("{uri:<16} {tried:<44} {called}");
  }

  println!("-- with not_found_service");
  for uri in ["/missing.txt", "/../a.txt", "/locked/f.txt"] {
    let mut dir = ServeDir::new("tmp/try/site").not_found_service(ServeFile::new("tmp/try/404.html"));
    match dir.try_call(req(uri)).await {
      Ok(res) => {
        let status = res.status();
        let body = res.into_body().collect().await.unwrap().to_bytes();
        println!("{uri:<16} Ok({status}) {:?}", String::from_utf8_lossy(&body));
      }
      Err(err) => println!("{uri:<16} Err({:?})", err.kind()),
    }
  }
}

uri              try_call                                     call
/a.txt           Ok(200 OK)                                   200 OK
/missing.txt     Err(NotFound, os=Some(2))                    404 Not Found
/../a.txt        Ok(404 Not Found)                            404 Not Found
/..%5ca.txt      Err(NotFound, os=Some(2))                    404 Not Found
/a.txt/x         Err(NotADirectory, os=Some(20))              404 Not Found
/nope.txt        Err(PermissionDenied, os=Some(13))           404 Not Found
/locked/f.txt    Err(PermissionDenied, os=Some(13))           404 Not Found
-- with not_found_service
/missing.txt     Ok(404 Not Found) "custom 404"
/../a.txt        Ok(404 Not Found) "custom 404"
/locked/f.txt    Ok(404 Not Found) "custom 404"

307 Temporary Redirect location=Some("/docs/")