pub struct ServeDir<F = DefaultServeDirFallback> { /* private fields */ }
Available on crate feature fs only.
Expand description

Service that serves files from a given directory and all its sub directories.

The Content-Type will be guessed from the file extension.

An empty response with status 404 Not Found will be returned if:

  • The file doesn’t exist
  • Any segment of the path contains ..
  • Any segment of the path contains a backslash
  • On unix, any segment of the path referenced as directory is actually an existing file (/file.html/something)
  • We don’t have necessary permissions to read the file

Example

use tower_http::services::ServeDir;

// This will serve files in the "assets" directory and
// its subdirectories
let service = ServeDir::new("assets");

Implementations§

source§

impl ServeDir<DefaultServeDirFallback>

source

pub fn new<P>(path: P) -> Self
where P: AsRef<Path>,

Create a new ServeDir.

source§

impl<F> ServeDir<F>

source

pub fn append_index_html_on_directories(self, append: bool) -> Self

If the requested path is a directory append index.html.

This is useful for static sites.

Defaults to true.

source

pub fn with_buf_chunk_size(self, chunk_size: usize) -> Self

Set a specific read buffer chunk size.

The default capacity is 64kb.

source

pub fn precompressed_gzip(self) -> Self

Informs the service that it should also look for a precompressed gzip version of any file in the directory.

Assuming the dir directory is being served and dir/foo.txt is requested, a client with an Accept-Encoding header that allows the gzip encoding will receive the file dir/foo.txt.gz instead of dir/foo.txt. If the precompressed file is not available, or the client doesn’t support it, the uncompressed version will be served instead. Both the precompressed version and the uncompressed version are expected to be present in the directory. Different precompressed variants can be combined.

source

pub fn precompressed_br(self) -> Self

Informs the service that it should also look for a precompressed brotli version of any file in the directory.

Assuming the dir directory is being served and dir/foo.txt is requested, a client with an Accept-Encoding header that allows the brotli encoding will receive the file dir/foo.txt.br instead of dir/foo.txt. If the precompressed file is not available, or the client doesn’t support it, the uncompressed version will be served instead. Both the precompressed version and the uncompressed version are expected to be present in the directory. Different precompressed variants can be combined.

source

pub fn precompressed_deflate(self) -> Self

Informs the service that it should also look for a precompressed deflate version of any file in the directory.

Assuming the dir directory is being served and dir/foo.txt is requested, a client with an Accept-Encoding header that allows the deflate encoding will receive the file dir/foo.txt.zz instead of dir/foo.txt. If the precompressed file is not available, or the client doesn’t support it, the uncompressed version will be served instead. Both the precompressed version and the uncompressed version are expected to be present in the directory. Different precompressed variants can be combined.

source

pub fn precompressed_zstd(self) -> Self

Informs the service that it should also look for a precompressed zstd version of any file in the directory.

Assuming the dir directory is being served and dir/foo.txt is requested, a client with an Accept-Encoding header that allows the zstd encoding will receive the file dir/foo.txt.zst instead of dir/foo.txt. If the precompressed file is not available, or the client doesn’t support it, the uncompressed version will be served instead. Both the precompressed version and the uncompressed version are expected to be present in the directory. Different precompressed variants can be combined.

source

pub fn fallback<F2>(self, new_fallback: F2) -> ServeDir<F2>

Set the fallback service.

This service will be called if there is no file at the path of the request.

The status code returned by the fallback will not be altered. Use ServeDir::not_found_service to set a fallback and always respond with 404 Not Found.

Example

This can be used to respond with a different file:

use tower_http::services::{ServeDir, ServeFile};

let service = ServeDir::new("assets")
    // respond with `not_found.html` for missing files
    .fallback(ServeFile::new("assets/not_found.html"));
source

pub fn not_found_service<F2>(self, new_fallback: F2) -> ServeDir<SetStatus<F2>>

Set the fallback service and override the fallback’s status code to 404 Not Found.

This service will be called if there is no file at the path of the request.

Example

This can be used to respond with a different file:

use tower_http::services::{ServeDir, ServeFile};

let service = ServeDir::new("assets")
    // respond with `404 Not Found` and the contents of `not_found.html` for missing files
    .not_found_service(ServeFile::new("assets/not_found.html"));

Setups like this are often found in single page applications.

source

pub fn call_fallback_on_method_not_allowed(self, call_fallback: bool) -> Self

Customize whether or not to call the fallback for requests that aren’t GET or HEAD.

Defaults to not calling the fallback and instead returning 405 Method Not Allowed.

source

pub fn try_call<ReqBody, FResBody>( &mut self, req: Request<ReqBody> ) -> ResponseFuture<ReqBody, F>
where F: Service<Request<ReqBody>, Response = Response<FResBody>, Error = Infallible> + Clone, F::Future: Send + 'static, FResBody: Body<Data = Bytes> + Send + 'static, FResBody::Error: Into<Box<dyn Error + Send + Sync>>,

Call the service and get a future that contains any std::io::Error that might have happened.

By default <ServeDir as Service<_>>::call will handle IO errors and convert them into responses. It does that by converting std::io::ErrorKind::NotFound and std::io::ErrorKind::PermissionDenied to 404 Not Found and any other error to 500 Internal Server Error. The error will also be logged with tracing.

If you want to manually control how the error response is generated you can make a new service that wraps a ServeDir and calls try_call instead of call.

Example
use tower_http::services::ServeDir;
use std::{io, convert::Infallible};
use http::{Request, Response, StatusCode};
use http_body::Body as _;
use http_body_util::{Full, BodyExt, combinators::UnsyncBoxBody};
use bytes::Bytes;
use tower::{service_fn, ServiceExt, BoxError};

async fn serve_dir(
    request: Request<Full<Bytes>>
) -> Result<Response<UnsyncBoxBody<Bytes, BoxError>>, Infallible> {
    let mut service = ServeDir::new("assets");

    // You only need to worry about backpressure, and thus call `ServiceExt::ready`, if
    // your adding a fallback to `ServeDir` that cares about backpressure.
    //
    // Its shown here for demonstration but you can do `service.try_call(request)`
    // otherwise
    let ready_service = match ServiceExt::<Request<Full<Bytes>>>::ready(&mut service).await {
        Ok(ready_service) => ready_service,
        Err(infallible) => match infallible {},
    };

    match ready_service.try_call(request).await {
        Ok(response) => {
            Ok(response.map(|body| body.map_err(Into::into).boxed_unsync()))
        }
        Err(err) => {
            let body = Full::from("Something went wrong...")
                .map_err(Into::into)
                .boxed_unsync();
            let response = Response::builder()
                .status(StatusCode::INTERNAL_SERVER_ERROR)
                .body(body)
                .unwrap();
            Ok(response)
        }
    }
}

Trait Implementations§

source§

impl<F: Clone> Clone for ServeDir<F>

source§

fn clone(&self) -> ServeDir<F>

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<F: Debug> Debug for ServeDir<F>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<ReqBody, F, FResBody> Service<Request<ReqBody>> for ServeDir<F>
where F: Service<Request<ReqBody>, Response = Response<FResBody>, Error = Infallible> + Clone, F::Future: Send + 'static, FResBody: Body<Data = Bytes> + Send + 'static, FResBody::Error: Into<Box<dyn Error + Send + Sync>>,

§

type Response = Response<ResponseBody>

Responses given by the service.
§

type Error = Infallible

Errors produced by the service.
§

type Future = InfallibleResponseFuture<ReqBody, F>

The future response value.
source§

fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests. Read more
source§

fn call(&mut self, req: Request<ReqBody>) -> Self::Future

Process the request and return the response asynchronously. Read more

Auto Trait Implementations§

§

impl<F> RefUnwindSafe for ServeDir<F>
where F: RefUnwindSafe,

§

impl<F> Send for ServeDir<F>
where F: Send,

§

impl<F> Sync for ServeDir<F>
where F: Sync,

§

impl<F> Unpin for ServeDir<F>
where F: Unpin,

§

impl<F> UnwindSafe for ServeDir<F>
where F: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> PolicyExt for T
where T: ?Sized,

source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Available on crate feature follow-redirect only.
Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Available on crate feature follow-redirect only.
Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
source§

impl<T, Request> ServiceExt<Request> for T
where T: Service<Request> + ?Sized,

source§

fn ready(&mut self) -> Ready<'_, Self, Request>
where Self: Sized,

Yields a mutable reference to the service when it is ready to accept a request.
source§

fn ready_and(&mut self) -> Ready<'_, Self, Request>
where Self: Sized,

👎Deprecated since 0.4.6: please use the ServiceExt::ready method instead
Yields a mutable reference to the service when it is ready to accept a request.
source§

fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
where Self: Sized,

Yields the service when it is ready to accept a request.
source§

fn oneshot(self, req: Request) -> Oneshot<Self, Request>
where Self: Sized,

Consume this Service, calling with the providing request once it is ready.
source§

fn call_all<S>(self, reqs: S) -> CallAll<Self, S>
where Self: Sized, Self::Error: Into<Box<dyn Error + Sync + Send>>, S: Stream<Item = Request>,

Process all requests from the given Stream, and produce a Stream of their responses. Read more
source§

fn and_then<F>(self, f: F) -> AndThen<Self, F>
where Self: Sized, F: Clone,

Executes a new future after this service’s future resolves. This does not alter the behaviour of the poll_ready method. Read more
source§

fn map_response<F, Response>(self, f: F) -> MapResponse<Self, F>
where Self: Sized, F: FnOnce(Self::Response) -> Response + Clone,

Maps this service’s response value to a different value. This does not alter the behaviour of the poll_ready method. Read more
source§

fn map_err<F, Error>(self, f: F) -> MapErr<Self, F>
where Self: Sized, F: FnOnce(Self::Error) -> Error + Clone,

Maps this service’s error value to a different value. This does not alter the behaviour of the poll_ready method. Read more
source§

fn map_result<F, Response, Error>(self, f: F) -> MapResult<Self, F>
where Self: Sized, Error: From<Self::Error>, F: FnOnce(Result<Self::Response, Self::Error>) -> Result<Response, Error> + Clone,

Maps this service’s result type (Result<Self::Response, Self::Error>) to a different value, regardless of whether the future succeeds or fails. Read more
source§

fn map_request<F, NewRequest>(self, f: F) -> MapRequest<Self, F>
where Self: Sized, F: FnMut(NewRequest) -> Request,

Composes a function in front of the service. Read more
source§

fn then<F, Response, Error, Fut>(self, f: F) -> Then<Self, F>
where Self: Sized, Error: From<Self::Error>, F: FnOnce(Result<Self::Response, Self::Error>) -> Fut + Clone, Fut: Future<Output = Result<Response, Error>>,

Composes an asynchronous function after this service. Read more
source§

fn map_future<F, Fut, Response, Error>(self, f: F) -> MapFuture<Self, F>
where Self: Sized, F: FnMut(Self::Future) -> Fut, Error: From<Self::Error>, Fut: Future<Output = Result<Response, Error>>,

Composes a function that transforms futures produced by the service. Read more
source§

fn boxed(self) -> BoxService<Request, Self::Response, Self::Error>
where Self: Sized + Send + 'static, Self::Future: Send + 'static,

Convert the service into a Service + Send trait object. Read more
source§

fn boxed_clone(self) -> BoxCloneService<Request, Self::Response, Self::Error>
where Self: Clone + Sized + Send + 'static, Self::Future: Send + 'static,

Convert the service into a Service + Clone + Send trait object. Read more
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more