Static files and SPA#

There are three ways to serve. Every one of them is a handler separate from routing proper (requirement F-W-20).

Content is read from the classpath. You can serve it while it stays inside the jar, and during development it is read from build/resources/main. The behaviour is the same either way (requirement F-W-18).

Static files#

install(() -> AssetHandler.mount("/assets", "test-assets"));

The second argument is a directory on the classpath, not a filesystem path. With AssetHandler.mount("/assets", "assets"), src/main/resources/assets/app.css comes out at /assets/app.css.

Two routes are registered: GET and HEAD on /assets/*.

[!WARNING] /assets itself (no trailing path) is not served. Only /assets/* is registered. SPA and MPA also register the bare prefix, so they differ here.

routes() hands those routes back, so you can attach attributes to them.

AssetController assets = AssetHandler.mount("/assets", "assets");
for (Route route : assets.routes()) {
	route.attribute(NO_AUTH, true);
}
install(() -> assets);

routes() works the same way for SpaHandler.mount(...) and MpaHandler.mount(...). The count differs, though — SPA and MPA also register the bare prefix, so there are four (GET and HEAD on both /app and /app/*).

Caching#

The default for dynamic responses is no-store (requirement F-X-07). Static serving is the only thing that overrides it.

assets {
	max_age            = 0        # ordinary files
	immutable_max_age  = 31536000 # for files with a content hash in the name (one year)
	etag               = true
	if_modified_since  = true
}

Conditional GET#

• ETag is a weak ETag (md5 of path, modification time and size)
• Last-Modified is URLConnection's modification time
• If-None-Match is checked first; If-Modified-Since only when it is absent
• On a match, a 304 without reading the body

What is not there#

SPA#

install(() -> SpaHandler.mount("/app", "test-spa"));

When a request hits /app/..., this is how it looks.

1. If a real file exists, return that (same headers as AssetHandler)
2. Otherwise walk up from that path looking for index.html
3. Finally, the index.html directly under the base
4. If that is missing too, 404

It coexists with ordinary routes. Declare /api/items and the SPA will not swallow it. The tree's precedence (fixed segment > path parameter > wildcard) applies unchanged.

Rewriting index.html per path#

Use this when you want to swap out <title> or <meta> for crawlers or OGP.

install(() -> SpaHandler.mount("/app", "test-spa", spa -> spa
	.route("/app/items/{id}", (context, html) ->
		html.replace("<!--title-->", "<title>item " + context.request().bodyPath().getString("id") + "</title>"))
));

Paths are written the same way as real routes ({id}, a trailing /*). Matching is done by the same route tree the real routes use (requirement D-75).

MPA#

install(() -> MpaHandler.mount("/docs", "test-mpa"));

With an extension it returns the file; without one, <path>/index.html. /docs/guide → docs/guide/index.html.

Defaults on the safe side#

Every path is inspected before anything is served. Anything dangerous gets a 404 (so we do not reveal what exists).

Rejected: NUL characters, backslashes, empty segments (//), and . and .. segments.

When you edit during development#

jimbleRun watches .html / .js / .css. Save and the resources are rebuilt, and the next request serves them (Hot reload).