hyper_staticfile_jsutf8/
lib.rs

1#![crate_name = "hyper_staticfile_jsutf8"]
2#![deny(missing_docs)]
3
4//! Static file-serving for [Hyper 0.14](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.
17//! let static_ = hyper_staticfile_jsutf8::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 `resolve` 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//!     // Document root path.
42//!     let root = Path::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 = hyper_staticfile_jsutf8::resolve(&root, &request)
51//!         .await
52//!         .unwrap();
53//!
54//!     // Then, build a response based on the result.
55//!     // The `ResponseBuilder` is typically a short-lived, per-request instance.
56//!     let response = hyper_staticfile_jsutf8::ResponseBuilder::new()
57//!         .request(&request)
58//!         .build(result)
59//!         .unwrap();
60//! }
61//! ```
62//!
63//! The `resolve` function tries to find the file in the root, and returns a future for the
64//! `ResolveResult` enum, which determines what kind of response should be sent. The
65//! `ResponseBuilder` is then used to create a default response. It holds some settings, and can be
66//! constructed using the builder pattern.
67//!
68//! It's useful to sit between these two steps to implement custom 404 pages, for example. Your
69//! custom logic can override specific cases of `ResolveResult`, and fall back to the default
70//! behavior using `ResponseBuilder` if necessary.
71//!
72//! The `ResponseBuilder` in turn uses `FileResponseBuilder` to serve files that are found. The
73//! `FileResponseBuilder` can also be used directly if you have an existing open `tokio::fs::File`
74//! and want to serve it. It takes care of basic headers, 'not modified' responses, and streaming
75//! the file in the body.
76//!
77//! Finally, there's `FileBytesStream`, which is used by `FileResponseBuilder` to stream the file.
78//! This is a struct wrapping a `tokio::fs::File` and implementing a `futures::Stream` that
79//! produces `Bytes`s. It can be used for streaming a file in custom response.
80
81mod resolve;
82mod response_builder;
83mod service;
84
85/// Lower level utilities.
86pub mod util;
87
88pub use crate::resolve::*;
89pub use crate::response_builder::*;
90pub use crate::service::*;
91
92// For compatiblity. Removed in 0.10.
93pub use crate::util::{FileBytesStream, FileResponseBuilder};
hyper_staticfile_jsutf8/lib.rs

hyper_staticfile_jsutf8/
lib.rs
