Skip to content

Commit 6bd0d0e

Browse files
docs: update README.md for cache-bust headers feature
1 parent c8e8d53 commit 6bd0d0e

File tree

1 file changed

+11
-4
lines changed

1 file changed

+11
-4
lines changed

README.md

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,14 +31,15 @@ Use the `embed_assets!` macro to create a `static_router()` function in scope wh
3131
```rust
3232
use static_serve::embed_assets;
3333

34-
embed_assets!("assets", compress = true);
34+
embed_assets!("assets", compress = true, cache_busted_paths = ["immutable"]);
3535
let router = static_router();
3636
```
3737

3838
This will:
3939

4040
- Include all files from the `assets` directory
4141
- Compress them using `gzip` and `zstd` (if beneficial)
42+
- For only files in `assets/immutable`, add a `Cache-Control` header with `public, max-age=31536000, immutable` (since these are marked as cache-busted paths)
4243
- Generate a `static_router()` function to serve these assets
4344

4445
#### Required parameter
@@ -49,10 +50,12 @@ This will:
4950

5051
- `compress = false` - compress static files with zstd and gzip, true or false (defaults to false)
5152

52-
- `ignore_dirs = [my_ignore_dir, other_ignore_dir]` - a bracketed list of `&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)
53+
- `ignore_dirs = ["my_ignore_dir", "other_ignore_dir"]` - a bracketed list of `&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)
5354

5455
- `strip_html_ext = false` - strips the `.html` or `.htm` from all HTML files included. If the filename is `index.html` or `index.htm`, the `index` part will also be removed, leaving just the root (defaults to false)
5556

57+
- `cache_busted_paths = ["my_immutables_dir", "my_immutable_file"]` - a bracketed list of `&str`s of the subdirectories and/or single files which should gain the `Cache-Control` header with `public, max-age=31536000, immutable` for cache-busted paths. If this parameter is missing, the default is that no embedded files will have the `Cache-Control` header. Note: the files in `cache_busted_paths` need to already be compatible with cache-busting by having hashes in their file paths (for example). All `static-serve` does is set the appropriate header.
58+
5659
### Embedding a single static asset file
5760

5861
Use the `embed_asset!` macro to return a function you can use as a GET handler, which will include your static file, embedded into your binary:
@@ -61,7 +64,7 @@ Use the `embed_asset!` macro to return a function you can use as a GET handler,
6164
use static_serve::embed_assets;
6265

6366
let router: Router<()> = Router::new();
64-
let handler = embed_asset!("assets/my_file.png", compress = true);
67+
let handler = embed_asset!("assets/my_file.png", compress = true, cache_bust = true);
6568
let router = router.route("/my_file.png", handler);
6669

6770
```
@@ -70,15 +73,17 @@ This will:
7073

7174
- Include the file `my_file.png` from the `assets` directory
7275
- Compress it using `gzip` and `zstd` (if beneficial)
76+
- Add a `Cache-Control` header with the value `public, max-age=31536000, immutable` for cache-busted paths. Note: the file in `embed_asset!` needs to already be compatible with cache-busting by having a hash in its file path (for example). All `static-serve` does is set the appropriate header.
7377
- Generate a `MethodRouter` "handler" you can add as a route on your router to serve the file
7478

7579
#### Required parameter
7680

7781
- `path_to_file` - a valid `&str` string literal of the path to the static file to be included
7882

79-
#### Optional parameter
83+
#### Optional parameters
8084

8185
- `compress = false` - compress a static file with zstd and gzip, true or false (defaults to false)
86+
- `cache_bust = false` - add a `Cache-Control` header with the value `public, max-age=31536000, immutable` for a cache-busted asset (defaults to false)
8287

8388
## Conditional Requests & Caching
8489

@@ -87,6 +92,8 @@ The crate automatically handles:
8792
- `Accept-Encoding` header to serve compressed versions if available
8893
- `If-None-Match` header for ETag validation, returning `304 Not Modified` if unchanged
8994

95+
- With the optional cache-bust headers feature, each embedded file in the `cache_busted_paths` array (or single file in the case of `embed_asset!` with `cache_bust = true`) will be returned with a `Cache-Control` header with the value `public, max-age=31536000, immutable`. Note: the files involved need to already be compatible with cache-busting by having hashes in their file paths (for example). All `static-serve` does is set the appropriate header.
96+
9097
## Example
9198

9299
```rust

0 commit comments

Comments
 (0)