From 78577d55e84f72d1be22190864b7912646de7e55 Mon Sep 17 00:00:00 2001 From: Angel Hudgins Date: Wed, 19 Mar 2025 15:37:07 +0100 Subject: [PATCH] docs: create README.md and crate docs in lib.rs --- README.md | 90 +++++++++++++++++++++++++++++++++++++++- static-serve/README.md | 84 +++++++++++++++++++++++++++++++++++++ static-serve/clippy.toml | 1 + static-serve/src/lib.rs | 4 +- 4 files changed, 176 insertions(+), 3 deletions(-) create mode 100644 static-serve/README.md create mode 100644 static-serve/clippy.toml diff --git a/README.md b/README.md index 3a7be6d..4a6ee04 100644 --- a/README.md +++ b/README.md @@ -1 +1,89 @@ -# static-serve +# Static Serve + +A Rust library for compressing and embedding static assets in a web server using [Axum](https://github.com/tokio-rs/axum). This crate provides efficient asset embedding with optional compression (`gzip` and `zstd`) and conditional requests support. + +## Features + +- **Embed static assets** at compile-time for efficient serving + +- **Automatic compression** with `gzip` and `zstd` + +- **ETag support** for conditional requests and caching + +- **Seamless Axum integration** with request extraction for encoding and caching headers + +## Installation + +Add the following to your `Cargo.toml`: + +```toml +[dependencies] +static-serve = "0.1" +axum = "0.8" +``` + +## Usage + +### Embedding Static Assets + +Use the `embed_assets!` macro to create a `static_router()` function in scope which will include your static files, embedding them into your binary: + +```rust +use static_serve::embed_assets; + +embed_assets!("assets", compress = true); +let router = static_router(); +``` + +This will: + +- Include all files from the `assets` directory +- Compress them using `gzip` and `zstd` (if beneficial) +- Generate a `static_router()` function to serve these assets + +### Conditional Requests & Caching + +The crate automatically handles: +- `Accept-Encoding` header to serve compressed versions if available +- `If-None-Match` header for ETag validation, returning `304 Not Modified` if unchanged + +### Required parameter + +- `path_to_dir` - a valid Rust identifier or `&str` of the path to the static files to be included + +### Optional parameters + +- `compress = false` - compress static files with zstd and gzip, true or false (defaults to false) + +- `ignore_dirs = [my_ignore_dir, other_ignore_dir]` - a bracketed list of valid Rust identifiers or `&str`s of the paths/subdirectories inside the target directory, which should be ignored and not included. (If this parameter is missing, no subdirectories will be ignored) + +## Example + +```rust + +use axum::{Router, Server}; +use static_serve::embed_assets; + +embed_assets!("public", compress = true); + +#[tokio::main] +async fn main() { + let router = static_router(); + Server::bind(&"0.0.0.0:3000".parse().unwrap()) + .serve(router.into_make_service()) + .await + .unwrap(); +} +``` + +## License + +Licensed under either of +- Apache License, Version 2.0, (LICENSE-APACHE or [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)) +- MIT license (LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/static-serve/README.md b/static-serve/README.md new file mode 100644 index 0000000..895961a --- /dev/null +++ b/static-serve/README.md @@ -0,0 +1,84 @@ +# Static Serve + +A Rust library for compressing and embedding static assets in a web server using [Axum](https://github.com/tokio-rs/axum). This crate provides efficient asset embedding with optional compression (`gzip` and `zstd`) and conditional requests support. + +## Features + +- **Embed static assets** at compile-time for efficient serving +- **Automatic compression** with `gzip` and `zstd` +- **ETag support** for conditional requests and caching +- **Seamless Axum integration** with request extraction for encoding and caching headers + +## Installation + +Add the following to your `Cargo.toml`: + +```toml +[dependencies] +static-serve = "0.1" +axum = "0.8" +``` + +## Usage + +### Embedding Static Assets + +Use the `embed_assets!` macro to create a `static_router()` function in scope which will include your static files, embedding them into your binary: + +```rust,ignore +use static_serve::embed_assets; + +embed_assets!("assets", compress = true); +let router = static_router(); +``` + +This will: + +- Include all files from the `assets` directory +- Compress them using `gzip` and `zstd` (if beneficial) +- Generate a `static_router()` function to serve these assets + +### Conditional Requests & Caching + +The crate automatically handles: +- `Accept-Encoding` header to serve compressed versions if available +- `If-None-Match` header for ETag validation, returning `304 Not Modified` if unchanged + +### Required parameter + +- `path_to_dir` - a valid Rust identifier or `&str` of the path to the static files to be included + +### Optional parameters + +- `compress = false` - compress static files with zstd and gzip, true or false (defaults to false) +- `ignore_dirs = [my_ignore_dir, other_ignore_dir]` - a bracketed list of valid Rust identifiers or `&str`s of the paths/subdirectories inside the target directory, which should be ignored and not included. (If this parameter is missing, no subdirectories will be ignored) + +## Example + +```rust,ignore +use axum::{Router, Server}; +use static_serve::embed_assets; + +embed_assets!("public", compress = true); + +#[tokio::main] +async fn main() { + let router = static_router(); + Server::bind(&"0.0.0.0:3000".parse().unwrap()) + .serve(router.into_make_service()) + .await + .unwrap(); +} +``` + +## License + +Licensed under either of +- Apache License, Version 2.0, (LICENSE-APACHE or [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)) +- MIT license (LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/static-serve/clippy.toml b/static-serve/clippy.toml new file mode 100644 index 0000000..4c37da1 --- /dev/null +++ b/static-serve/clippy.toml @@ -0,0 +1 @@ +doc-valid-idents = ["ETag", ".."] diff --git a/static-serve/src/lib.rs b/static-serve/src/lib.rs index 092a24d..6caacfd 100644 --- a/static-serve/src/lib.rs +++ b/static-serve/src/lib.rs @@ -1,5 +1,5 @@ -//! Crate for compressing and embedding static assets -//! in a web server +#![doc = include_str!("../README.md")] + use std::convert::Infallible; use axum::{