Skip to content

Commit 7fa4a68

Browse files
Web3NLclaude
andcommitted
docs(my-canister-frontend): clean up crate for standalone publish
- Remove unused `candid` dependency - Update Cargo.toml description to match README - Fix README Usage example to handle Result with .expect() - Extend Configuration section with header customisation docs - Remove Usage with my_canister_dashboard section - Remove dashboard/user-owned-dapp references from doc comments - Fix js_file_config test to reflect compressible behaviour (2 encodings) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent c0422cb commit 7fa4a68

5 files changed

Lines changed: 65 additions & 42 deletions

File tree

Cargo.lock

Lines changed: 0 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

packages-rs/my-canister-frontend/Cargo.toml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[package]
22
name = "my-canister-frontend"
33
version = "0.3.0"
4-
description = "Frontend asset utilities for user-owned dapps on the Internet Computer"
4+
description = "Frontend asset processing library for canisters on the Internet Computer"
55
documentation = "https://docs.rs/my-canister-frontend"
66
readme = "README.md"
77
keywords = ["internet-computer", "canister", "frontend", "assets", "dapp"]
@@ -15,7 +15,6 @@ repository = "https://github.com/Web3NL/my-canister-dapp/tree/main/packages-rs/m
1515
crate-type = ["rlib"]
1616

1717
[dependencies]
18-
candid.workspace = true
1918
ic-asset-certification.workspace = true
2019
ic-http-certification.workspace = true
2120
ic-cdk.workspace = true

packages-rs/my-canister-frontend/README.md

Lines changed: 58 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
[![Build Status](https://github.com/Web3NL/my-canister-dapp/workflows/Release/badge.svg)](https://github.com/Web3NL/my-canister-dapp/actions)
66
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
77

8-
Frontend asset processing library for user-owned dapps on the Internet Computer.
8+
Frontend asset processing library for canisters on the Internet Computer.
99

1010
## Usage
1111

@@ -21,7 +21,7 @@ static ASSETS: Dir = include_dir!("$CARGO_MANIFEST_DIR/../dapp-frontend/dist");
2121
2222
#[init]
2323
fn init() {
24-
setup_frontend(&ASSETS);
24+
setup_frontend(&ASSETS).expect("Failed to setup frontend");
2525
}
2626
2727
#[query]
@@ -37,16 +37,18 @@ fn http_request(req: HttpRequest) -> HttpResponse {
3737
- Automatic MIME type detection using `mime_guess`
3838
- `index.html` auto-configured as fallback for `/`
3939
- Certification using [`ic-asset-certification`](https://docs.rs/ic-asset-certification)
40-
- **Security headers**: 8 default security/privacy headers on all responses (HSTS, X-Frame-Options, Referrer-Policy, etc.)
41-
- **Asset validation**: File type allowlist, 2 MB size limit, path traversal protection, duplicate detection
40+
- **Security headers**: 6 default security/privacy headers on all responses (X-Frame-Options, Referrer-Policy, Permissions-Policy, etc.)
41+
- **Asset validation**: File type allowlist, 2 MiB − 16 KiB size limit, path traversal protection, duplicate detection
4242
- **Gzip compression**: Automatic gzip for text-based assets (HTML, JS, CSS, JSON, SVG)
43-
- **Configurable**: Use `FrontendConfig` to allow additional file types or adjust size limits
43+
- **Configurable**: Use `FrontendConfig` to allow additional file types, suppress default headers, or add custom headers
4444
- Exposes `with_asset_router` and `with_asset_router_mut` for access to the asset router, see example below.
4545
- Exposes `asset_router_configs` if you want to implement your own asset router, see [this example](https://github.com/Web3NL/my-canister-dapp/blob/e8fdc0ac81f7bdc702418c05130ace3f9f5399fb/examples/my-hello-world/src/backend/src/lib.rs).
4646

4747
## Configuration
4848

49-
To allow additional file types or customize settings:
49+
`FrontendConfig` controls which file types are accepted and what HTTP headers are sent with every response. All fields have sensible defaults — only set what you need, and use `..Default::default()` to fill in the rest.
50+
51+
### Allow additional file types
5052

5153
```rust,ignore
5254
use ic_cdk::init;
@@ -65,37 +67,61 @@ fn init() {
6567
}
6668
```
6769

68-
## Usage with [`my_canister_dashboard`](https://crates.io/crates/my-canister-dashboard)
70+
### Default security headers
71+
72+
Every response includes these headers out of the box:
73+
74+
| Header | Value |
75+
|---|---|
76+
| `X-Content-Type-Options` | `nosniff` |
77+
| `X-Frame-Options` | `DENY` |
78+
| `Referrer-Policy` | `no-referrer` |
79+
| `Permissions-Policy` | `accelerometer=(), camera=(), geolocation=(), microphone=(), payment=(), usb=()` |
80+
| `Cross-Origin-Opener-Policy` | `same-origin-allow-popups` |
81+
| `Cross-Origin-Resource-Policy` | `same-origin` |
82+
83+
`Strict-Transport-Security` is intentionally omitted — ICP gateways enforce HTTPS at the infrastructure level, making it redundant on `.icp0.io`/`.ic0.app` domains. `X-XSS-Protection` is also omitted as it is a legacy header for old IE/Chrome versions. Both can be added via `extra_headers` if needed.
84+
85+
### Suppress a default header
86+
87+
Use `excluded_headers` with a `StandardHeader` variant to remove a specific default:
6988

7089
```rust,ignore
71-
use ic_cdk::{init, query};
72-
use ic_http_certification::{HttpRequest, HttpResponse};
73-
use include_dir::{include_dir, Dir};
74-
use my_canister_dashboard::setup_dashboard_assets;
75-
use my_canister_frontend::setup_frontend;
76-
use my_canister_frontend::asset_router::with_asset_router_mut;
90+
use my_canister_frontend::{setup_frontend_with_config, FrontendConfig, StandardHeader};
7791
78-
static ASSETS: Dir = include_dir!("$CARGO_MANIFEST_DIR/../dapp-frontend/dist");
92+
let config = FrontendConfig {
93+
excluded_headers: vec![StandardHeader::XFrameOptions],
94+
..Default::default()
95+
};
96+
```
7997

80-
#[init]
81-
fn init() {
82-
setup_frontend(&ASSETS);
83-
84-
// Setup dashboard in internal asset router
85-
with_asset_router_mut(|router| {
86-
setup_dashboard_assets(
87-
router,
88-
Some(vec![
89-
"https://mycanister.app".to_string(),
90-
]),
91-
);
92-
});
93-
}
98+
### Add or override headers
9499

95-
#[query]
96-
fn http_request(req: HttpRequest) -> HttpResponse {
97-
my_canister_frontend::http_request(req)
98-
}
100+
Use `extra_headers` to append headers to every response. If the name matches a default header (case-insensitive), the default is replaced rather than duplicated:
101+
102+
```rust,ignore
103+
use my_canister_frontend::{setup_frontend_with_config, FrontendConfig};
104+
105+
let config = FrontendConfig {
106+
// Replaces the default X-Frame-Options: DENY
107+
extra_headers: vec![
108+
("X-Frame-Options".to_string(), "SAMEORIGIN".to_string()),
109+
("Content-Security-Policy".to_string(), "default-src 'self'".to_string()),
110+
],
111+
..Default::default()
112+
};
113+
```
114+
115+
To add HSTS on a custom domain:
116+
117+
```rust,ignore
118+
let config = FrontendConfig {
119+
extra_headers: vec![(
120+
"Strict-Transport-Security".to_string(),
121+
"max-age=31536000; includeSubDomains".to_string(),
122+
)],
123+
..Default::default()
124+
};
99125
```
100126

101127
## License

packages-rs/my-canister-frontend/src/asset_router.rs

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -549,7 +549,7 @@ mod tests {
549549

550550
#[test]
551551
fn js_file_config() {
552-
let config = create_asset_config("/app.js", false, &FrontendConfig::default());
552+
let config = create_asset_config("/app.js", true, &FrontendConfig::default());
553553

554554
match config {
555555
AssetConfig::File {
@@ -569,8 +569,9 @@ mod tests {
569569
);
570570
assert!(fallback_for.is_empty());
571571
assert!(aliased_by.is_empty());
572-
assert_eq!(encodings.len(), 1);
572+
assert_eq!(encodings.len(), 2);
573573
assert!(matches!(encodings[0].0, AssetEncoding::Identity));
574+
assert!(matches!(encodings[1].0, AssetEncoding::Gzip));
574575
}
575576
_ => panic!("Expected AssetConfig::File"),
576577
}

packages-rs/my-canister-frontend/src/lib.rs

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ use ic_http_certification::{HttpRequest, HttpResponse, StatusCode};
99
use include_dir::Dir;
1010
use std::borrow::Cow;
1111

12-
/// Initialize and certify your user-owned dapp frontend assets.
12+
/// Initialize and certify frontend assets.
1313
///
1414
/// Embeds files from an [`include_dir`](https://docs.rs/include_dir/latest/include_dir/) `Dir` into the internal
1515
/// [`AssetRouter`](https://docs.rs/ic-asset-certification/latest/ic_asset_certification/struct.AssetRouter.html)
@@ -38,7 +38,7 @@ pub fn setup_frontend(assets_dir: &Dir<'static>) -> Result<(), String> {
3838
setup_frontend_with_config(assets_dir, &FrontendConfig::default())
3939
}
4040

41-
/// Initialize and certify your user-owned dapp frontend assets with custom configuration.
41+
/// Initialize and certify frontend assets with custom configuration.
4242
///
4343
/// Like [`setup_frontend`], but allows specifying additional allowed file
4444
/// extensions and other options via [`FrontendConfig`].
@@ -67,9 +67,7 @@ pub fn setup_frontend_with_config(
6767
})
6868
}
6969

70-
/// Serve certified frontend assets.
71-
/// Any other additional assets you may have added to the asset router,
72-
/// like for example dashboard assets, will also be served.
70+
/// Serve certified assets from the internal asset router.
7371
///
7472
/// # Example
7573
/// ```rust,no_run

0 commit comments

Comments
 (0)