dfinity / dfinity/sdk

feat: Configurable fallback behavior for the asset canister (custom 404 support)

Open
#4,497 1 comment 0 reactions 0 assignees View on GitHub

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" in ic-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:

  1. Config parsing (ic-asset): extend .ic-assets.json5 schema with top-level fallback property
  2. State machine (ic-certified-assets/src/state_machine/mod.rs): replace hardcoded FALLBACK_FILE with configurable value and status code
  3. 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)
  4. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.