61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# boardwalk
|
|
|
|
HTTP handler that serves the embedded admin SPA build under a configurable path prefix.
|
|
|
|
`import "git.golem15.com/golem15/summercms/modules/boardwalk"`
|
|
|
|
## Overview
|
|
|
|
`boardwalk` embeds the compiled admin SPA (`dist/`, produced by `npm --prefix admin run build`) into the binary and serves it. The build is path-agnostic: `index.html` carries a placeholder token that the handler replaces once, at construction, with the prefix the admin is mounted under, so one build works at any backend URI. [cabana](../cabana/README.md) mounts it when it activates the admin routes. It stands in for the server-rendered backend layouts of WinterCMS, which the Go port replaces with a single-page app.
|
|
|
|
## Features
|
|
|
|
- Serves the embedded build under any prefix, rewriting relative asset URLs and the admin base meta in `index.html` for that prefix (`boardwalk.RewriteIndex`).
|
|
- Fails at boot when `index.html` lacks the `boardwalk.BaseToken` placeholder, which catches a stale or hand-edited build.
|
|
- Falls back to `index.html` for client-side routes and directories; missing files with an extension get a plain 404.
|
|
- Hands every request whose path under the prefix is `api` or starts with `api/` to a caller-supplied handler, so admin API misses stay JSON instead of returning the SPA.
|
|
- Long-lived immutable caching for hashed files under `assets/`, `no-cache` for other files and `no-store` for `index.html`.
|
|
- Security headers on every response: a restrictive Content-Security-Policy, frame denial, `nosniff`, a same-origin referrer policy and `noindex, nofollow`.
|
|
- Explicit content types for scripts, styles, fonts, SVG and JSON, with a MIME lookup fallback.
|
|
|
|
## Usage
|
|
|
|
```go
|
|
notFoundAPI := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
|
w.Header().Set("Content-Type", "application/json")
|
|
w.WriteHeader(http.StatusNotFound)
|
|
_, _ = w.Write([]byte(`{"error":"not found"}`))
|
|
})
|
|
|
|
spa, err := boardwalk.Handler("/backend", notFoundAPI)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
mux.Handle("/backend/", spa)
|
|
```
|
|
|
|
## API reference
|
|
|
|
| Identifier | Description |
|
|
|------------|-------------|
|
|
| `boardwalk.Handler` | Builds the SPA handler for a prefix; the second argument answers unmatched `api/` paths. |
|
|
| `boardwalk.Dist` | Returns the embedded build as an `fs.FS` rooted at `dist/`. |
|
|
| `boardwalk.RewriteIndex` | Rewrites raw `index.html` bytes for a prefix; errors when the placeholder token is missing. |
|
|
| `boardwalk.BaseToken` | The placeholder in `dist/index.html` that is replaced by the prefix. |
|
|
|
|
## Dependencies
|
|
|
|
- SummerCMS modules: none.
|
|
- Third-party: none.
|
|
- Standard library: `bytes`, `embed`, `errors`, `fmt`, `html`, `io/fs`, `mime`, `net/http`, `path`, `strings`, `time`.
|
|
|
|
The embedded `dist/` tree is generated from the `admin/` Vite project, whose build writes to `modules/boardwalk/dist`.
|
|
|
|
## Testing
|
|
|
|
```sh
|
|
go test ./modules/boardwalk/...
|
|
```
|
|
|
|
The tests run the handler through `net/http/httptest` against the embedded build and in-memory file systems; they need no external services.
|