# einherjar/spa-server

[![version](https://img.shields.io/badge/version-v1.7.1-5C4EE5?style=flat-square)](https://code.nochebuena.dev/einherjar/spa-server)
[![license](https://img.shields.io/badge/license-AGPL--3.0-22863A?style=flat-square)](LICENSE)
[![go](https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat-square&logo=go&logoColor=white)](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.1
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.1
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.*