initial: zero-trust markdown tutorials site
Single-binary Go service that renders markdown pages from a runtime volume mount. Targeted at public, no-auth, no-WAF deployment behind a TLS ingress; security posture is defense-in-depth at every layer: - goldmark with no WithUnsafe — raw HTML in author markdown is stripped - CSP without 'unsafe-inline', plus HSTS, COOP, CORP, Permissions-Policy - static handler rejects non-GET/HEAD, directory listings, dotfiles, traversal - content loader rejects symlinks that escape the content root, dotfiles, and .md files larger than 1 MiB - per-page template trees (cloned from layout) so define-blocks don't collide between home/category/page - SIGHUP triggers atomic library swap — live edits on volume, no rebuild Locale layout content/<locale>/<category>/<slug>.md. Categories without _index.md still appear on the home page with a humanized name. Search is a ~70-line vanilla JS scan over /search.json?lang=<locale>; swap for a real indexer if the corpus ever balloons. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,344 @@
|
||||
// Package server is the HTTP layer: route mux, page handlers, search index endpoint.
|
||||
//
|
||||
// Routing:
|
||||
//
|
||||
// GET / → redirect to /<defaultLocale>/
|
||||
// GET /<locale>/ → home (lists categories)
|
||||
// GET /<locale>/<category>/ → category landing (lists pages)
|
||||
// GET /<locale>/<category>/<slug> → render single page
|
||||
// GET /search.json → ?lang=<locale> returns search index for client-side FlexSearch
|
||||
// GET /static/... → bundled CSS / htmx.min.js
|
||||
// GET /healthz → liveness
|
||||
package server
|
||||
|
||||
import (
|
||||
"context"
|
||||
"embed"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"html/template"
|
||||
"io/fs"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"strings"
|
||||
"sync/atomic"
|
||||
"time"
|
||||
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/content"
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/render"
|
||||
)
|
||||
|
||||
//go:embed all:templates
|
||||
var templatesFS embed.FS
|
||||
|
||||
//go:embed all:static
|
||||
var staticFS embed.FS
|
||||
|
||||
// Server holds the swappable library + per-page template trees + default locale.
|
||||
// SwapLibrary is used by SIGHUP-driven reload in main.go.
|
||||
//
|
||||
// Templates are parsed as one base tree (layout.html) plus a clone per page
|
||||
// template so that `{{define "title"}}` / `{{define "content"}}` blocks from
|
||||
// home/category/page don't overwrite each other. Rendering invokes the
|
||||
// "layout" template name from the page-specific tree.
|
||||
type Server struct {
|
||||
lib atomic.Pointer[content.Library]
|
||||
tmpls map[string]*template.Template
|
||||
defLocale string
|
||||
}
|
||||
|
||||
// New constructs a Server with the given library + default locale.
|
||||
func New(lib *content.Library, defaultLocale string) *Server {
|
||||
s := &Server{defLocale: defaultLocale, tmpls: make(map[string]*template.Template)}
|
||||
s.lib.Store(lib)
|
||||
|
||||
sub, err := fs.Sub(templatesFS, "templates")
|
||||
if err != nil {
|
||||
panic(fmt.Errorf("subFS templates: %w", err))
|
||||
}
|
||||
base := template.Must(template.New("base").Funcs(funcMap()).ParseFS(sub, "layout.html"))
|
||||
for _, name := range []string{"home.html", "category.html", "page.html"} {
|
||||
t := template.Must(base.Clone())
|
||||
template.Must(t.ParseFS(sub, name))
|
||||
s.tmpls[name] = t
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// SwapLibrary replaces the active library atomically (used by SIGHUP reload).
|
||||
func (s *Server) SwapLibrary(lib *content.Library) { s.lib.Store(lib) }
|
||||
|
||||
func (s *Server) currentLib() *content.Library { return s.lib.Load() }
|
||||
|
||||
// Run starts the HTTP server and blocks until ctx is cancelled.
|
||||
func (s *Server) Run(ctx context.Context, addr string) error {
|
||||
mux := http.NewServeMux()
|
||||
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
|
||||
w.WriteHeader(http.StatusNoContent)
|
||||
})
|
||||
mux.HandleFunc("GET /search.json", s.handleSearch)
|
||||
mux.HandleFunc("GET /{$}", s.handleRoot)
|
||||
mux.HandleFunc("GET /{locale}/{$}", s.handleHome)
|
||||
mux.HandleFunc("GET /{locale}/{category}/{$}", s.handleCategory)
|
||||
mux.HandleFunc("GET /{locale}/{category}/{slug}", s.handlePage)
|
||||
|
||||
// /static/* is served BEFORE the mux to avoid pattern conflicts between
|
||||
// `/static/` and `/{locale}/{$}` (Go 1.22's mux can't pick a winner —
|
||||
// they overlap at exactly "/static/"). Wrapping order: securityHeaders
|
||||
// → staticFirst → mux.
|
||||
staticSub, err := fs.Sub(staticFS, "static")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
staticFileHandler := http.StripPrefix("/static/", http.FileServerFS(staticSub))
|
||||
staticHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
// Zero-trust posture: only GET/HEAD, no directory listings, no dotfiles.
|
||||
if r.Method != http.MethodGet && r.Method != http.MethodHead {
|
||||
w.Header().Set("Allow", "GET, HEAD")
|
||||
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
path := r.URL.Path
|
||||
if strings.HasSuffix(path, "/") || strings.Contains(path, "/.") {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Cache-Control", "public, max-age=3600")
|
||||
staticFileHandler.ServeHTTP(w, r)
|
||||
})
|
||||
|
||||
root := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if strings.HasPrefix(r.URL.Path, "/static/") {
|
||||
staticHandler.ServeHTTP(w, r)
|
||||
return
|
||||
}
|
||||
mux.ServeHTTP(w, r)
|
||||
})
|
||||
|
||||
srv := &http.Server{
|
||||
Addr: addr,
|
||||
Handler: securityHeaders(root),
|
||||
ReadHeaderTimeout: 10 * time.Second,
|
||||
ReadTimeout: 30 * time.Second,
|
||||
WriteTimeout: 60 * time.Second,
|
||||
IdleTimeout: 120 * time.Second,
|
||||
}
|
||||
|
||||
errCh := make(chan error, 1)
|
||||
go func() {
|
||||
slog.Info("listening", "addr", addr, "default_locale", s.defLocale)
|
||||
err := srv.ListenAndServe()
|
||||
if !errors.Is(err, http.ErrServerClosed) {
|
||||
errCh <- err
|
||||
return
|
||||
}
|
||||
errCh <- nil
|
||||
}()
|
||||
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
_ = srv.Shutdown(shutdownCtx)
|
||||
return <-errCh
|
||||
case err := <-errCh:
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
// --- Handlers ---
|
||||
|
||||
func (s *Server) handleRoot(w http.ResponseWriter, r *http.Request) {
|
||||
http.Redirect(w, r, "/"+s.defLocale+"/", http.StatusFound)
|
||||
}
|
||||
|
||||
func (s *Server) handleHome(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
lib := s.currentLib()
|
||||
if !lib.HasLocale(locale) {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
s.render(w, "home.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Categories": lib.Categories(locale),
|
||||
"Path": []crumb{},
|
||||
})
|
||||
}
|
||||
|
||||
func (s *Server) handleCategory(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
categoryName := r.PathValue("category")
|
||||
lib := s.currentLib()
|
||||
if !lib.HasLocale(locale) {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
var cat *content.Category
|
||||
for _, c := range lib.Categories(locale) {
|
||||
c := c
|
||||
if c.Name == categoryName {
|
||||
cat = &c
|
||||
break
|
||||
}
|
||||
}
|
||||
if cat == nil {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
|
||||
var indexHTML template.HTML
|
||||
if cat.Index != nil {
|
||||
out, err := render.Markdown(cat.Index.Source)
|
||||
if err == nil {
|
||||
indexHTML = template.HTML(out)
|
||||
}
|
||||
}
|
||||
s.render(w, "category.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Category": cat,
|
||||
"IndexHTML": indexHTML,
|
||||
"Path": []crumb{
|
||||
{Label: titleFor(cat), URL: "/" + locale + "/" + cat.Name + "/"},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
func (s *Server) handlePage(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
category := r.PathValue("category")
|
||||
slug := r.PathValue("slug")
|
||||
lib := s.currentLib()
|
||||
page := lib.Page(locale, category, slug)
|
||||
if page == nil {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
html, err := render.Markdown(page.Source)
|
||||
if err != nil {
|
||||
http.Error(w, "render error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
s.render(w, "page.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Page": page,
|
||||
"BodyHTML": template.HTML(html),
|
||||
"Path": []crumb{
|
||||
{Label: humanize(category), URL: "/" + locale + "/" + category + "/"},
|
||||
{Label: page.Title, URL: ""},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// handleSearch returns a flat JSON array of {path, title, summary, body} for FlexSearch
|
||||
// to index in the browser. Body is plain markdown source — small enough for the page set.
|
||||
func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request) {
|
||||
lang := r.URL.Query().Get("lang")
|
||||
if lang == "" {
|
||||
lang = s.defLocale
|
||||
}
|
||||
lib := s.currentLib()
|
||||
type entry struct {
|
||||
Path string `json:"path"`
|
||||
Title string `json:"title"`
|
||||
Summary string `json:"summary,omitempty"`
|
||||
Body string `json:"body"`
|
||||
}
|
||||
var out []entry
|
||||
for _, p := range lib.AllPages() {
|
||||
if p.Locale != lang || p.Slug == "_index" {
|
||||
continue
|
||||
}
|
||||
out = append(out, entry{
|
||||
Path: "/" + p.Path,
|
||||
Title: p.Title,
|
||||
Summary: p.Summary,
|
||||
Body: string(p.Source),
|
||||
})
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||
w.Header().Set("Cache-Control", "public, max-age=300")
|
||||
_ = json.NewEncoder(w).Encode(out)
|
||||
}
|
||||
|
||||
// --- Helpers ---
|
||||
|
||||
type crumb struct {
|
||||
Label string
|
||||
URL string // empty for the active leaf
|
||||
}
|
||||
|
||||
func (s *Server) render(w http.ResponseWriter, name string, data map[string]any) {
|
||||
t, ok := s.tmpls[name]
|
||||
if !ok {
|
||||
slog.Error("template not found", "name", name)
|
||||
http.Error(w, "template error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
if err := t.ExecuteTemplate(w, "layout", data); err != nil {
|
||||
slog.Error("template render", "name", name, "err", err)
|
||||
}
|
||||
}
|
||||
|
||||
func titleFor(c *content.Category) string {
|
||||
if c.Index != nil {
|
||||
return c.Index.Title
|
||||
}
|
||||
return humanize(c.Name)
|
||||
}
|
||||
|
||||
func humanize(s string) string {
|
||||
s = strings.ReplaceAll(s, "-", " ")
|
||||
s = strings.ReplaceAll(s, "_", " ")
|
||||
if s == "" {
|
||||
return ""
|
||||
}
|
||||
return strings.ToUpper(s[:1]) + s[1:]
|
||||
}
|
||||
|
||||
func funcMap() template.FuncMap {
|
||||
return template.FuncMap{
|
||||
"humanize": humanize,
|
||||
}
|
||||
}
|
||||
|
||||
// securityHeaders adds the hardening headers expected for a public, no-auth,
|
||||
// internet-facing service. The intent is zero-trust: every visitor is anonymous
|
||||
// and untrusted, and the only data we serve is rendered markdown plus the static
|
||||
// CSS/JS bundle in /static/. Headers are tuned for that surface specifically.
|
||||
//
|
||||
// - CSP is tight: 'self' for default/script/style/connect; images from data: + https:.
|
||||
// 'unsafe-inline' is deliberately absent — templates have no inline styles or
|
||||
// scripts, and goldmark output (with WithUnsafe disabled) contains neither.
|
||||
// - HSTS is set assuming TLS termination upstream (k8s ingress).
|
||||
// - COOP/CORP isolate the document from cross-origin actors.
|
||||
// - Permissions-Policy disables every browser capability we don't use.
|
||||
func securityHeaders(next http.Handler) http.Handler {
|
||||
const csp = "default-src 'self'; " +
|
||||
"img-src 'self' data: https:; " +
|
||||
"style-src 'self'; " +
|
||||
"script-src 'self'; " +
|
||||
"connect-src 'self'; " +
|
||||
"object-src 'none'; " +
|
||||
"base-uri 'self'; " +
|
||||
"form-action 'self'; " +
|
||||
"frame-ancestors 'none'"
|
||||
const permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
h := w.Header()
|
||||
h.Set("X-Content-Type-Options", "nosniff")
|
||||
h.Set("X-Frame-Options", "DENY")
|
||||
h.Set("Referrer-Policy", "no-referrer")
|
||||
h.Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
|
||||
h.Set("Cross-Origin-Opener-Policy", "same-origin")
|
||||
h.Set("Cross-Origin-Resource-Policy", "same-origin")
|
||||
h.Set("Content-Security-Policy", csp)
|
||||
h.Set("Permissions-Policy", permissionsPolicy)
|
||||
next.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
Reference in New Issue
Block a user