automc-tutorials/internal/server/server.go

// 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)
	})
}