Rene Nochebuena
b73b9ee022
- Cache-Control per file: no-cache for index.html + service workers, immutable 1y for content-hashed assets, 1h for the rest (Vite/CRA/Angular). Closes the stale-release trap at the HTTP layer that the v1.6.0 image fix closed at the container layer. - SPA fallback scoped to navigation: a missing asset (path w/ extension) or a non-HTML Accept now returns 404 instead of index.html (no more HTML-as-JS 'Unexpected token <'). - X-Content-Type-Options: nosniff on every response. - Image runs as a non-root 'spa' user. - README: caching table, fallback contract, and the Angular dist/<project>/browser/ note.
125 lines
4.6 KiB
Markdown
125 lines
4.6 KiB
Markdown
# einherjar/spa-server
|
|
|
|
[](https://code.nochebuena.dev/einherjar/spa-server)
|
|
[](LICENSE)
|
|
[](https://go.dev)
|
|
|
|
> A shield wall holds because every warrior knows their position. The SPA asks only for the wall — not for every soldier's name.
|
|
|
|
`code.nochebuena.dev/einherjar/spa-server` is a container-first HTTP server for single-page applications and progressive web apps. It serves static assets directly and falls back to `index.html` for navigation routes that do not resolve to a file — the standard SPA routing contract — while a missing asset returns `404` rather than the HTML shell.
|
|
|
|
The module ships as a ready-to-use Docker base image. Deploying a SPA to a container requires a single `COPY` instruction. No nginx, no custom configuration, no index.html redirect logic to maintain.
|
|
|
|
---
|
|
|
|
## Container usage
|
|
|
|
```dockerfile
|
|
FROM code.nochebuena.dev/einherjar/spa-server:v1.7.0
|
|
COPY dist/ /srv/www/
|
|
```
|
|
|
|
That is the complete Dockerfile for a production SPA container. It runs as an
|
|
unprivileged user and serves `/srv/www` on port 8080.
|
|
|
|
`COPY dist/ /srv/www/` is correct for **Vite** and **CRA**, which emit `index.html`
|
|
at the root of `dist/`. **Angular**'s application builder instead emits
|
|
`dist/<project>/browser/` (with `index.html` inside `browser/`, next to
|
|
`3rdpartylicenses.txt`), so copy that subdirectory — otherwise no `index.html` lands
|
|
at the root and every request falls through to a 404:
|
|
|
|
```dockerfile
|
|
FROM code.nochebuena.dev/einherjar/spa-server:v1.7.0
|
|
COPY dist/my-app/browser/ /srv/www/
|
|
```
|
|
|
|
---
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `EINHERJAR_SPA_PORT` | `8080` | TCP port the server listens on |
|
|
| `EINHERJAR_SPA_STATIC_DIR` | `/srv/www` | Path to the directory containing `index.html` and assets |
|
|
| `EINHERJAR_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARN`, `ERROR` |
|
|
|
|
---
|
|
|
|
## Health endpoint
|
|
|
|
`GET /health` returns `200 OK` with a JSON body consistent with all Einherjar health responses:
|
|
|
|
```json
|
|
{"status":"UP","components":{}}
|
|
```
|
|
|
|
`503 Service Unavailable` is never returned — if the process is alive, it is healthy. Wire `/health` directly to your container liveness and readiness probes.
|
|
|
|
---
|
|
|
|
## Routing behaviour
|
|
|
|
| Request | Result |
|
|
|---|---|
|
|
| `/app.js` — file exists | Served directly with correct `Content-Type` |
|
|
| `/assets/logo.png` — file exists | Served directly |
|
|
| `/dashboard` — no file, `Accept: text/html` | `index.html` served (SPA router handles it) |
|
|
| `/` — directory | `index.html` served (directory listing is disabled) |
|
|
| `/main.js` — **no file, has an extension** | **`404`** — a missing asset is not masked as HTML |
|
|
| `/api/x` — no file, `Accept: application/json` | **`404`** — a non-HTML client is not handed `index.html` |
|
|
|
|
The fallback to `index.html` is deliberately scoped to **navigation** requests (no
|
|
file extension, and `Accept` includes `text/html` or `*/*`). A request for a missing
|
|
asset returns `404` instead of `index.html`, so a broken deploy fails at the first
|
|
request rather than delivering the SPA shell as JavaScript (`Unexpected token '<'`).
|
|
|
|
---
|
|
|
|
## Caching
|
|
|
|
`Cache-Control` is set per file, correct for Vite, CRA and Angular alike:
|
|
|
|
| File | `Cache-Control` |
|
|
|---|---|
|
|
| `index.html` | `no-cache` — revalidated every load, so a new deploy is never masked |
|
|
| Service workers (`ngsw.json`, `ngsw-worker.js`, `sw.js`, `service-worker.js`, `safety-worker.js`, `workbox-*.js`) | `no-cache` — a client is never pinned to a superseded release |
|
|
| Content-hashed assets (`main.4f8a2b1c.js`, `index-DkJf3x9a.js`, …) | `public, max-age=31536000, immutable` |
|
|
| Everything else (`favicon.ico`, `icons/`, verbatim assets) | `public, max-age=3600` |
|
|
|
|
A hashed filename is detected by a trailing hash-like token (≥8 alphanumerics
|
|
including a digit) before the extension — a heuristic whose only failure mode is a
|
|
missed year-long cache, never staleness.
|
|
|
|
Every response also carries `X-Content-Type-Options: nosniff`.
|
|
|
|
---
|
|
|
|
## Dependency graph
|
|
|
|
```
|
|
contracts (zero dependencies)
|
|
↑
|
|
core
|
|
↑
|
|
spa-server (contracts, core, stdlib only)
|
|
```
|
|
|
|
No external dependencies beyond the Go standard library.
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
cd spa-server/
|
|
go build ./...
|
|
go vet ./...
|
|
go test ./...
|
|
gofmt -l .
|
|
```
|
|
|
|
---
|
|
|
|
> *A shield wall holds because every warrior knows their position.*
|
|
> *The SPA asks only for the wall — not for every soldier's name.*
|