feat(static): support after ordering and warn when fallthrough: false blocks REST

[dawsontoth]

Problem

The static handler registers before: 'authentication' by default (runFirst: true prior to 5.1), and the REST handler runs after: 'authentication' — so static always answers GETs first. That makes the documented history-mode SPA recipe a footgun:

static:
  files: 'dist/**'
  notFound:
    file: 'index.html'
    statusCode: 200
  fallthrough: false

This catch-all answers every unmatched GET itself — including GETs for exported REST resources — so the application's REST API silently becomes unreachable over GET (GET /MyResource/ returns index.html with a 200). All four create-harper SPA templates shipped this config; create-harper#109 removes it there and steers users toward hash routing, but Harper itself should support the history-mode pattern correctly and warn about the trap.

With this PR

One added line makes the recipe work as everyone assumed it did — the API is matched first, and the fallback only catches what's left:

rest: true

static:
  files: 'dist/**'
  # Let the REST handler match first; only unmatched URLs get the SPA fallback.
  after: 'rest'
  notFound:
    file: 'index.html'
    statusCode: 200
  fallthrough: false

GET /Dog/1          → 200 application/json   (REST resource)
GET /assets/app.js  → 200 text/javascript    (static file)
GET /app/settings   → 200 text/html          (index.html — client-side route)

History-mode routing and the REST API coexist. And anyone still running the old config now gets a startup warning in the log naming this exact fix.

Changes

• after option on static (e.g. after: 'rest'): positions the handler after the named middleware so API routes match first and only unmatched URLs receive the notFound fallback. When after is given, the default before: 'authentication' hoist is suppressed — combining them would create an ordering cycle (static < authentication < rest < static), which would fall back to registration order with a warning.
• before: false is now a documented, validated way to clear the default constraint without adding a new one (registration order applies). This previously worked only by accident of the falsy check in topoSort.
• Validation for before/after values, matching the style of the other option validations in the plugin.
• Startup warning (also re-checked on live reload of fallthrough) when fallthrough: false is used in the default pre-REST position, naming after: 'rest' as the remedy.
• config-app.schema.json: the static component is now described (files, urlPath, index, extensions, fallthrough, notFound, before, after), so editors using the schema get completion and validation.

Verification

• New unit tests: unitTests/server/static.test.js (12 tests) covering the ordering options passed to server.http, validation errors, and warning behavior — hand-rolled fake scope, plain assert, per house style.
• End-to-end against a built dist with a Vite SPA app + exported resource:
  • With after: 'rest': GET /Greeting/ → 200 application/json (the resource), GET /some/deep/link → 200 text/html (index.html fallback), GET / and built assets serve normally. History-mode routing and the REST API coexist.
  • With the old footgun config: the new warning appears in hdb.log at startup; behavior is unchanged (GET /Greeting/ still returns index.html) so nothing breaks for existing pure-static apps.
• oxlint --deny-warnings and prettier --check clean on the changed files.
• npx mocha unitTests/server/static.test.js — 12 passing. (The full test:unit:server suite fails identically on main in my local environment — pre-existing, unrelated.)

Follow-up

Docs: documentation#562 (draft) adds a Handler Ordering section to the Static Files page and corrects its SPA example to use after: 'rest'.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces 'before' and 'after' configuration options to the static file serving handler, allowing users to customize its position in the HTTP middleware chain. It also adds validation for these options, a warning when a non-fallthrough static handler might block REST API routes, and corresponding unit tests. The reviewer noted that because 'before' and 'after' are only evaluated at startup, live-reload changes to these options will be silently ignored, and suggested explicitly requesting a restart when they change.

[claude]

Reviewed; no blockers found.

[kriszyp]

Approving — nice fix for the static-shadows-REST GET footgun; after ordering resolves once at registration (no per-request cost) and the fallthrough:false warning is accurate.

One question I'm curious about: what's the use case where you'd actually reach for after here — is it for a specific static-vs-REST layout, or a general escape hatch? And given this change, is the current default ordering still the right one for the common case, or does this suggest the default should change so people don't need after in the first place?

— 🤖 KrAIs (Kris's review assistant)

[dawsontoth]

There are legitimate cases for both.

For most Harper apps, static was for purely known, static asset serving. From a known map, those requests can be served the fastest, and they help speed up site metrics. It's a cheap thing to check, should be served before authentication, and then you check your meaty resources if they want to handle things.

But with SPAs that want to use real looking URLs and query string parameters for users, a 404 fallback to a known index.html (and scripted client side route loading) is a very common approach to serving content.

The static plugin couldn't handle this situation. We opted to push people to use hash based routing, which does have advantages. But with such a simple change, we can let people do what they want. They may not have a choice over the URLs they must handle.

[kriszyp]

real looking URLs and query string parameters for users, a 404 fallback to a known index.html

Is this really the ideal way to handle mapping a set (a glob?) of URLs ("real looking") to a static file (pass throug auth, REST, 404, fallback handler)? Should we add support for URL glob -> file path for explicit and fast mapping?

[dawsontoth]

@kriszyp specifying your paths would be more performant, yes. But you're contending with a lot of people that want to do it with a 404, and have done it with 404 for a very long time.