hyper_staticfile/
lib.rs

1#![crate_name = "hyper_staticfile"]
2#![deny(missing_docs)]
3
4//! Static file-serving for [Hyper 1.0](https://github.com/hyperium/hyper).
5//!
6//! This library exports a high-level interface `Static` for simple file-serving, and lower-level
7//! interfaces for more control over responses.
8//!
9//! ## Basic usage
10//!
11//! The `Static` type is essentially a struct containing some settings, and a `serve` method to
12//! handle the request. It follows the builder pattern, and also implements the `hyper::Service`
13//! trait. It can be used as:
14//!
15//! ```rust
16//! // Instance of `Static` containing configuration. Can be cheaply cloned.
17//! let static_ = hyper_staticfile::Static::new("my/doc/root/");
18//!
19//! // A dummy request, but normally obtained from Hyper.
20//! let request = http::Request::get("/foo/bar.txt")
21//!     .body(())
22//!     .unwrap();
23//!
24//! // Serve the request. Returns a future for a `hyper::Response`.
25//! let response_future = static_.serve(request);
26//! ```
27//!
28//! Typically, you'd store the `Static` instance somewhere, such as in your own `hyper::Service`
29//! implementation.
30//!
31//! ## Advanced usage
32//!
33//! The `Static` type is a simple wrapper for `Resolver` and `ResponseBuilder`. You can achieve the
34//! same by doing something similar to the following:
35//!
36//! ```rust
37//! use std::path::Path;
38//!
39//! #[tokio::main]
40//! async fn main() {
41//!     // Create a resolver. This can be cheaply cloned.
42//!     let resolver = hyper_staticfile::Resolver::new("my/doc/root/");
43//!
44//!     // A dummy request, but normally obtained from Hyper.
45//!     let request = http::Request::get("/foo/bar.txt")
46//!         .body(())
47//!         .unwrap();
48//!
49//!     // First, resolve the request. Returns a future for a `ResolveResult`.
50//!     let result = resolver.resolve_request(&request).await.unwrap();
51//!
52//!     // Then, build a response based on the result.
53//!     // The `ResponseBuilder` is typically a short-lived, per-request instance.
54//!     let response = hyper_staticfile::ResponseBuilder::new()
55//!         .request(&request)
56//!         .build(result)
57//!         .unwrap();
58//! }
59//! ```
60//!
61//! The `resolve_request` method tries to find the file in the document root, and returns a future
62//! for the `ResolveResult` enum, which determines what kind of response should be sent. The
63//! `ResponseBuilder` is then used to create a default response. It holds some settings, and can be
64//! constructed using the builder pattern.
65//!
66//! It's useful to sit between these two steps to implement custom 404 pages, for example. Your
67//! custom logic can override specific cases of `ResolveResult`, and fall back to the default
68//! behavior using `ResponseBuilder` if necessary.
69
70mod body;
71mod resolve;
72mod response_builder;
73mod service;
74
75/// Lower level utilities.
76pub mod util;
77/// Types to implement a custom (virtual) filesystem to serve files from.
78pub mod vfs;
79
80pub use crate::body::Body;
81pub use crate::resolve::*;
82pub use crate::response_builder::*;
83pub use crate::service::*;
hyper_staticfile/lib.rs

hyper_staticfile/
lib.rs
