Skip to content

Commit

Permalink
Include README in lib.rs
Browse files Browse the repository at this point in the history
  • Loading branch information
@marlonbaeten
marlonbaeten committed Feb 15, 2024
1 parent beff059 commit d8fc9f8
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 141 deletions.
36 changes: 18 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ memory-serve is designed to work with [axum](https://github.com/tokio-rs/axum)

Provide a relative path to the directory containing your static assets
to the `load_assets!` macro. This macro creates a data structure intended to
be consumed by `MemoryServe::new`. Calling `MemoryServe::into_router()` on
be consumed by `[MemoryServe::new]`. Calling `[MemoryServe::into_router()]` on
the resulting instance produces a axum
[Router](https://docs.rs/axum/latest/axum/routing/struct.Router.html) that
can either be merged in another `Router` or used directly in a server by
Expand Down Expand Up @@ -69,16 +69,16 @@ async fn main() {
An instance of the `MemoryServe` struct can be configured by calling
the following configuration methods:

| method | Default value | Description |
|----------------------|-------------------------|-------------------------------------------------------|
| `index_file` | `Some("/index.html")` | Which file to serve on the route "/" |
| `fallback` | `None` | Which file to serve if no routed matched the request |
| `fallback_status` | `StatusCode::NOT_FOUND` | The HTTP status code to routes that did not match |
| `enable_gzip` | `true` | Allow to serve gzip encoded files |
| `enable_brotli` | `true` | Allow to serve brotli encoded files |
| `html_cache_control` | `CacheConrol::Short` | Cache control header to serve on HTML files |
| `cache_control` | `CacheConrol::Medium` | Cache control header to serve on other files |
| `add_alias` | `[]` | Create a route / file alias |
| method | Default value | Description |
|--------|---------------|-------------|
| `[MemoryServe::index_file]` | `Some("/index.html")` | Which file to serve on the route "/"
| `[MemoryServe::fallback]` | `None` | Which file to serve if no routed matched the request
| `[MemoryServe::fallback_status]` | `StatusCode::NOT_FOUND` | The HTTP status code to routes that did not match
| `[MemoryServe::enable_gzip]` | `true` | Allow to serve gzip encoded files
| `[MemoryServe::enable_brotli]` | `true` | Allow to serve brotli encoded files
| `[MemoryServe::html_cache_control]` | `CacheConrol::Short` | Cache control header to serve on HTML files
| `[MemoryServe::cache_control]` | `CacheConrol::Medium` | Cache control header to serve on other files
| `[MemoryServe::add_alias]` | `[]` | Create a route / file alias

See `Cache control` for the cache control options.

Expand Down Expand Up @@ -115,10 +115,10 @@ Example output:

There are 5 different values to choose from for the cache-control settings:

| Option | Description | Value |
|-----------------------|--------------------------------------------------------------------------------------------|------------------------------------------------|
| CacheControl::Long | clients can keep assets that have cache busting for a year | `max-age=31536000, immutable` |
| CacheControl::Medium | assets without cache busting are revalidated after a day and can be kept for a week | `max-age=604800, stale-while-revalidate=86400` |
| CacheControl::Short | cache kept for max 5 minutes, only at the client (not in a proxy) | `max-age:300, private` |
| CacheControl::NoCache | do not cache if freshness is really vital | `no-cache` |
| CacheControl::Custom | Custom value | *user defined* |
| Option | Description | Value |
|--------|-------------|-------|
| `[CacheControl::Long]` | clients can keep assets that have cache busting for a year | `max-age=31536000, immutable`
| `[CacheControl::Medium]` | assets without cache busting are revalidated after a day and can be kept for a week | `max-age=604800, stale-while-revalidate=86400`
| `[CacheControl::Short]` | cache kept for max 5 minutes, only at the client (not in a proxy) | `max-age:300, private`
| `[CacheControl::NoCache]` | do not cache if freshness is really vital | `no-cache`
| `[CacheControl::Custom]` | Custom value | *user defined*
124 changes: 1 addition & 123 deletions memory-serve/src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,126 +1,4 @@
//! [memory-serve] enables fast static file serving for axum web applications,
//! by keeping all assets in memory.
//!
//! It loads static web assets like HTML, stylesheets, images and
//! scripts into the rust binary at compile time and exposes them as an
//! [axum](https://github.com/tokio-rs/axum) Router. It automatically adds cache
//! headers and handles file compression.
//!
//! During development (debug builds) files are served dynamically,
//! they are read and compressed at request time.
//!
//! Text-based files like HTML or javascript
//! are compressed using [brotli](https://en.wikipedia.org/wiki/Brotli)
//! at compile time and decompressed at startup, to minimize the binary size.
//!
//! All files are served with an
//! [etag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
//! header and
//! [If-None-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match)
//! requests are handled accordingly.
//!
//! Text based files are served as-is or with gzip or brotli compression
//! based on the abilities and preferences of the client.
//!
//! Routing can be configured in a flexible manner, for instance to accommodate
//! an SPA.
//!
//! # Compatibility
//!
//! memory-serve is designed to work with [axum](https://github.com/tokio-rs/axum)
//!
//! # Usage
//!
//! Provide a relative path to the directory containing your static assets
//! to the `load_assets!` macro. This macro creates a data structure intended to
//! be consumed by [MemoryServe::new]. Calling [MemoryServe::into_router()] on
//! the resulting instance produces a axum
//! [Router](https://docs.rs/axum/latest/axum/routing/struct.Router.html) that
//! can either be merged in another `Router` or used directly in a server by
//! calling `Router::into_make_service()`.
//!
//! # Example
//!
//! ```no_run
//! use axum::{response::Html, routing::get, Router};
//! use memory_serve::{load_assets, MemoryServe};
//! use std::net::SocketAddr;
//!
//! #[tokio::main]
//! async fn main() {
//! let memory_router = MemoryServe::new(load_assets!("../static"))
//! .index_file(Some("/index.html"))
//! .into_router();
//!
//! // possible other routes an be added at this point, like API routes
//! let app = Router::new()
//! .merge(memory_router);
//!
//! let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
//! let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
//! axum::serve(listener, app).await.unwrap();
//! }
//! ```
//!
//! # Configuration options
//!
//! An instance of the `MemoryServe` struct can be configured by calling
//! the following configuration methods:
//!
//! | method | Default value | Description |
//! |-----------------------------------|-------------------------|-------------------------------------------------------|
//! | [MemoryServe::index_file] | `Some("/index.html")` | Which file to serve on the route "/" |
//! | [MemoryServe::fallback] | `None` | Which file to serve if no routed matched the request |
//! | [MemoryServe::fallback_status] | `StatusCode::NOT_FOUND` | The HTTP status code to routes that did not match |
//! | [MemoryServe::enable_gzip] | `true` | Allow to serve gzip encoded files |
//! | [MemoryServe::enable_brotli] | `true` | Allow to serve brotli encoded files |
//! | [MemoryServe::html_cache_control] | `CacheConrol::Short` | Cache control header to serve on HTML files |
//! | [MemoryServe::cache_control] | `CacheConrol::Medium` | Cache control header to serve on other files |
//! | [MemoryServe::add_alias] | `[]` | Create a route / file alias |
//!
//! See [Cache control](index.html#cache-control) for the cache control options.
//!
//! # Logging
//!
//! During compilation, problems that occur with the inclusion or compression
//! of assets are logged to stdout, for instance:
//!
//! ```txt,no_run
//! WARN skipping file "static/empty.txt": file empty
//! ```
//!
//! When running the resulting executable, all registered routes and asset
//! sizes are logged using the [tracing](https://github.com/tokio-rs/tracing)
//! crate. To print or log them, use `tracing-subscriber`.
//! Example output:
//!
//! ```txt,no_run
//! INFO memory_serve: serving /assets/icon.jpg 1366 bytes
//! INFO memory_serve: serving /assets/index.css 1552 bytes
//! INFO memory_serve: serving /assets/index.css (brotli compressed) 509 bytes
//! INFO memory_serve: serving /assets/index.css (gzip compressed) 624 bytes
//! INFO memory_serve: serving /assets/index.js 20 bytes
//! INFO memory_serve: serving /assets/stars.svg 2255 bytes
//! INFO memory_serve: serving /assets/stars.svg (brotli compressed) 907 bytes
//! INFO memory_serve: serving /assets/stars.svg (gzip compressed) 1048 bytes
//! INFO memory_serve: serving /index.html 437 bytes
//! INFO memory_serve: serving /index.html (brotli compressed) 178 bytes
//! INFO memory_serve: serving /index.html (gzip compressed) 274 bytes
//! INFO memory_serve: serving /index.html as index on /
//! ```
//!
//! # Cache control
//!
//! There are 5 different values to choose from for the cache-control settings:
//!
//! | Option | Description | Value |
//! |-------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------|
//! | [CacheControl::Long] | clients can keep assets that have cache busting for a year | `max-age=31536000, immutable` |
//! | [CacheControl::Medium] | assets without cache busting are revalidated after a day and can be kept for a week | `max-age=604800, stale-while-revalidate=86400` |
//! | [CacheControl::Short] | cache kept for max 5 minutes, only at the client (not in a proxy) | `max-age:300, private` |
//! | [CacheControl::NoCache] | do not cache if freshness is really vital | `no-cache` |
//! | [CacheControl::Custom] | Custom value | *user defined* |

#![doc = include_str!("../README.md")]
use axum::{
http::{HeaderMap, StatusCode},
routing::get,
Expand Down

0 comments on commit d8fc9f8

Please sign in to comment.