1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
//! web-static-pack is the "loader" (2nd stage) part of the
//! [web-static-pack](https://github.com/peku33/web-static-pack)
//! project. See project page for a general idea how two parts cooperate.
//!
//! Once a `pack` is created with build script / CI / build.rs using
//! [web-static-pack-packer](https://crates.io/crates/web-static-pack-packer)
//! it will usually be included in your target application with
//! <https://docs.rs/include_bytes_aligned/latest/include_bytes_aligned/>.
//! Then it will be loaded with a [loader::load], utilizing zero-copy
//! deserialization (so file contents will be sent from executable contents
//! directly). The pack is then possibly wrapped with [responder::Responder]
//! http service and used with a web server like hyper.
//!
//! The main part of this crate is [responder::Responder]. Its
//! [responder::Responder::respond_flatten] method makes a [http] service - a
//! function taking [http::Request] parts (method, path, headers) and returning
//! [http::Response].
//!
//! To make a [responder::Responder], a [common::pack::Pack] is needed. It can
//! be obtained by [loader::load] function by passing (possibly included in
//! binary) contents of a `pack` created with the packer.
//!
//! # Examples
//!
//! ## Creating and calling responder
//! ```ignore
//! use anyhow::Error;
//! use include_bytes_aligned::include_bytes_aligned;
//! use http::{HeaderMap, Method, StatusCode};
//! use web_static_pack::{loader::load, responder::Responder};
//!
//! // assume we have a vcard-personal-portfolio.pack available from packer examples
//! static PACK_ARCHIVED_SERIALIZED: &[u8] =
//! include_bytes_aligned!(16, "vcard-personal-portfolio.pack");
//!
//! fn main() -> Result<(), Error> {
//! // load (map / cast) [common::pack::PackArchived] from included bytes
//! let pack_archived = unsafe { load(PACK_ARCHIVED_SERIALIZED).unwrap() };
//!
//! // create a responder from `pack`
//! let responder = Responder::new(pack_archived);
//!
//! // do some checks on the responder
//! assert_eq!(
//! responder.respond_flatten(
//! &Method::GET,
//! "/present",
//! &HeaderMap::default(),
//! ).status(),
//! StatusCode::OK
//! );
//!
//! Ok(())
//! }
//! ```
//!
//! ## Adapting to hyper service
//! This example is based on
//! <https://hyper.rs/guides/1/server/graceful-shutdown/>
//! which is a bit complicated.
//!
//! You can run full working example from
//! `tests/examples/vcard_personal_portfolio_server.rs`
//!
//! ```ignore
//! use anyhow::Error;
//! use web_static_pack::responder::Responder;
//! use std::{
//! convert::Infallible,
//! mem::transmute,
//! };
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<(), Error> {
//! // lets assume we have a `responder: Responder` object available from previous example
//! // hyper requires service to be static
//! // we use graceful, no connections will outlive server function
//! let responder = unsafe {
//! transmute::<
//! &Responder<'_, _>,
//! &Responder<'static, _>,
//! >(&responder)
//! };
//!
//! // make hyper service
//! let service_fn = service_fn(|request| async {
//! // you can probably filter your /api requests here
//! let (parts, _body) = request.into_parts();
//!
//! let response = responder.respond_flatten(
//! &parts.method,
//! parts.uri.path(),
//! &parts.headers
//! );
//!
//! Ok::<_, Infallible>(response)
//! });
//!
//! // use service_fn like in hyper example
//! Ok(())
//! }
//! ```
pub use web_static_pack_common as common;