feat: Configurable fallback behavior for the asset canister (custom 404 support)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 204
- Forks
- 98
- PR merge metrics
- No merged PRs in 30d
Description
Problem
The asset canister serves /index.html with status 200 for all unmatched routes. This is correct for SPAs but wrong for static sites, docs sites, and multi-page apps where unmatched routes should return 404. It also hurts SEO — search engines index non-existent pages as real content.
The fallback file and status code are hardcoded:
FALLBACK_FILE = "/index.html"inic-certified-assets/src/asset_certification/types/http.rs- Always served with status 200
There is no custom 404.html support despite it being standard on other hosting platforms (Netlify, Vercel, GitHub Pages, Cloudflare Pages).
Proposal
Make the fallback configurable via .ic-assets.json5:
// SPA (current default — no change needed)
{ "fallback": { "file": "/index.html", "status_code": 200 } }
// Static site with custom 404
{ "fallback": { "file": "/404.html", "status_code": 404 } }
// No fallback (strict mode)
{ "fallback": false }
Default remains { file: "/index.html", status_code: 200 } for full backward compatibility.
Implementation notes
Areas to change:
- Config parsing (
ic-asset): extend.ic-assets.json5schema with top-levelfallbackproperty - State machine (
ic-certified-assets/src/state_machine/mod.rs): replace hardcodedFALLBACK_FILEwith configurable value and status code - Certification (
ic-certified-assets/src/asset_certification/mod.rs): the certification tree and witness generation must be updated to certify the configured fallback file and status code (currently hardcoded for 200 + index.html) - Stable storage: persist fallback config across upgrades
The certification changes are the most involved — the Merkle proof must cover the actual status code and body being returned for unmatched paths.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the fallback definition in ic-certified-assets/src/asset_certification/types/http.rs, then read config parsing in ic-asset, the state machine in ic-certified-assets/src/state_machine/mod.rs, and certification in ic-certified-assets/src/asset_certification/mod.rs. Trace how stable storage persists upgrades. Done means .ic-assets.json5 supports the proposed fallback modes, unmatched routes return the configured file and status, and certification covers the returned body and status.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100