📁 Related issues

#2119

✍️ Description

What changed

• Root folder mappings are now automatically expanded to explicit file mappings for safety.
• Non-root folder mappings preserve dynamic catch-all behavior for runtime file serving.

Why

• Enables root-level static assets (e.g., mashlib chunks) without mapping / to a folder and hijacking all Solid routes.
• Root folder mappings were previously unsafe because they would catch ALL requests, including pod resources.
• Non-root folders preserve existing behavior: new files appear automatically without server restart.

How to use

Simply map a folder to root - it will be expanded automatically:

{
  "@id": "urn:solid-server:default:StaticAssetHandler",
  "@type": "StaticAssetHandler",
  "assets": [
    {
      "@type": "StaticAssetEntry",
      "relativeUrl": "/",
      "filePath": "./node_modules/mashlib/dist/"
    },
    {
      "@type": "StaticAssetEntry",
      "relativeUrl": "/assets/",
      "filePath": "./static/"
    }
  ]
}

In this example:

• / mapping → expanded to explicit files (/mashlib.js, /841.mashlib.js, etc.)
• assets/ mapping → keeps catch-all behavior (/assets/anything.js serves from ./static/ at runtime)

Tests

• Added unit test for automatic root folder expansion.
• Added unit test verifying non-root folders keep catch-all behavior.

Notes

• Expansion is non-recursive by design (top-level files only).
• Zero breaking changes - existing configurations work unchanged.

✅ PR check list

Before this pull request can be merged, a core maintainer will check whether

• this PR is labeled with the correct semver label
  • semver.patch: Backwards compatible bug fixes.
  • semver.minor: Backwards compatible feature additions.
• the correct branch is targeted. Patch updates can target main, other changes should target the latest versions/* branch.
• the RELEASE_NOTES.md document in case of relevant feature or config changes.
• any relevant documentation was updated to reflect the changes in this PR.