# einherjar/spa-server

[![version](https://img.shields.io/badge/version-v1.0.0-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 any path that does not resolve to a file on disk — the standard SPA routing contract.

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.0.0
COPY dist/ /srv/www/
```

That is the complete Dockerfile for a production SPA container.

---

## 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 matching file | `index.html` served (SPA router handles it) |
| `/` — directory | `index.html` served (directory listing is disabled) |

---

## 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.*