volumen/internal/httpapi/api.go

// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0

// Package httpapi serves the public JSON API under /api/volumen:
// site metadata, paginated posts, tags, series, feeds, the sitemap,
// and token-authenticated write endpoints.
package httpapi

import (
	"crypto/sha256"
	"encoding/hex"
	json "encoding/json/v2"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"slices"
	"strconv"
	"strings"
	"sync"
	"time"

	"sourcedock.dev/petrbalvin/interpres/v2"
	"sourcedock.dev/petrbalvin/volumen/internal/config"
	"sourcedock.dev/petrbalvin/volumen/internal/feeds"
	"sourcedock.dev/petrbalvin/volumen/internal/frontmatter"
	"sourcedock.dev/petrbalvin/volumen/internal/payloads"
	"sourcedock.dev/petrbalvin/volumen/internal/post"
	"sourcedock.dev/petrbalvin/volumen/internal/preview"
	"sourcedock.dev/petrbalvin/volumen/internal/tokens"
	"sourcedock.dev/petrbalvin/volumen/internal/web"
)

// Content is the content surface the API uses.
type Content interface {
	All() []*post.Post
	Find(slug, lang string) *post.Post
	ResolveAlias(alias string) string
	Save(p *post.Post) (*post.Post, error)
	Delete(slug, lang string) (*post.Post, bool, error)
	CacheKey() string
}

// Deps are the shared services the API needs.
type Deps struct {
	Config  *config.Config
	Store   Content
	Tokens  *tokens.Store
	OnEvent func(event string, payload map[string]any)

	// PreviewKey verifies the shareable preview links: the session
	// secret the app layer resolved, from [admin].session_key or from
	// the secret.key file it generated, which is the same key the admin
	// signs the links with. Empty refuses every token.
	PreviewKey string
}

// API routes /api/volumen requests.
type API struct {
	deps Deps

	sitemapMu  sync.Mutex
	sitemapKey string
	sitemapXML string
}

// New builds the API handler.
func New(deps Deps) http.Handler {
	api := &API{deps: deps}
	mux := http.NewServeMux()
	mux.HandleFunc("OPTIONS /api/volumen/{rest...}", api.handleOptions)
	mux.HandleFunc("GET /api/volumen/site", api.handleSite)
	mux.HandleFunc("GET /api/volumen/posts", api.handlePosts)
	mux.HandleFunc("GET /api/volumen/posts/batch", api.handleBatch)
	mux.HandleFunc("GET /api/volumen/posts/{slug}", api.handleSingle)
	mux.HandleFunc("POST /api/volumen/posts", api.handleCreatePost)
	mux.HandleFunc("PUT /api/volumen/posts/{slug}", api.handleUpdatePost)
	mux.HandleFunc("DELETE /api/volumen/posts/{slug}", api.handleDeletePost)
	mux.HandleFunc("GET /api/volumen/tags", api.handleTags)
	mux.HandleFunc("GET /api/volumen/tags/{tag}", api.handleTagPosts)
	mux.HandleFunc("GET /api/volumen/tags/{tag}/feed.xml", api.handleTagRSS)
	mux.HandleFunc("GET /api/volumen/tags/{tag}/feed.atom", api.handleTagAtom)
	mux.HandleFunc("GET /api/volumen/tags/{tag}/feed.json", api.handleTagJSON)
	mux.HandleFunc("GET /api/volumen/series", api.handleSeries)
	mux.HandleFunc("GET /api/volumen/series/{name}", api.handleSeriesDetail)
	mux.HandleFunc("GET /api/volumen/series/{name}/feed.xml", api.handleSeriesRSS)
	mux.HandleFunc("GET /api/volumen/series/{name}/feed.atom", api.handleSeriesAtom)
	mux.HandleFunc("GET /api/volumen/series/{name}/feed.json", api.handleSeriesJSON)
	mux.HandleFunc("GET /api/volumen/feed.xml", api.handleRSS)
	mux.HandleFunc("GET /api/volumen/feed.atom", api.handleAtom)
	mux.HandleFunc("GET /api/volumen/feed.json", api.handleJSONFeed)
	mux.HandleFunc("GET /api/volumen/sitemap.xml", api.handleSitemap)
	return mux
}

var corsHeaders = map[string]string{
	"Access-Control-Allow-Origin":  "*",
	"Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
	"Access-Control-Allow-Headers": "Content-Type, Authorization",
}

const cacheHeader = "public, max-age=60, stale-while-revalidate=21600"

// pageSizeLimit bounds the page size: the documented limit of the list
// endpoints, used both by the clamp and by the error message so the two
// cannot drift.
const pageSizeLimit = 100

// maxWriteBody bounds a write payload.
const maxWriteBody = 10 << 20

// maxPage bounds the page number so offset arithmetic stays far inside
// 32-bit int range.
const maxPage = 1_000_000

func (a *API) fire(event string, payload map[string]any) {
	if a.deps.OnEvent != nil {
		a.deps.OnEvent(event, payload)
	}
}

func writeCORS(w http.ResponseWriter) {
	for key, value := range corsHeaders {
		w.Header().Set(key, value)
	}
	w.Header().Set("Cache-Control", cacheHeader)
}

// writeJSON writes a JSON response with CORS and cache headers.
func writeJSON(w http.ResponseWriter, r *http.Request, status int, v any) {
	writeJSONWithHeaders(w, r, status, v, nil)
}

// writeJSONWithHeaders applies extra headers last, so write endpoints
// can override the public CORS defaults.
func writeJSONWithHeaders(w http.ResponseWriter, r *http.Request, status int, v any, extra map[string]string) {
	writeCORS(w)
	for key, value := range extra {
		w.Header().Set(key, value)
	}
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	writeJSONBody(w, r, v, "cannot encode response")
}

// writeJSONBody writes one JSON document and the newline a line-oriented
// client expects. encoding/json/v2 escapes only what JSON requires, so a
// body keeps the characters the author wrote.
func writeJSONBody(w io.Writer, r *http.Request, v any, what string) {
	if err := json.MarshalWrite(w, v, json.Deterministic(true)); err != nil {
		web.Logger(r.Context()).Warn("httpapi: "+what, "error", err)
		return
	}
	if _, err := io.WriteString(w, "\n"); err != nil {
		web.Logger(r.Context()).Warn("httpapi: "+what, "error", err)
	}
}

// writeError writes the uniform error envelope:
//
//	{"error": "<code>", "message": "<human text>", …extras}
//
// Every failure, in the API and in the middleware, uses this shape with
// CORS headers so cross-origin clients can read it. An error is never
// publicly cacheable.
func writeError(w http.ResponseWriter, r *http.Request, status int, body map[string]any) {
	writeCORS(w)
	w.Header().Set("Cache-Control", "no-store")
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	writeJSONBody(w, r, body, "cannot encode error")
}

func writeXML(w http.ResponseWriter, r *http.Request, contentType, body string) {
	writeCORS(w)
	w.Header().Set("Content-Type", contentType)
	w.WriteHeader(http.StatusOK)
	_, _ = w.Write([]byte(body))
}

// etagFor hashes the canonical serialisation of a payload, so two equal
// payloads always produce one tag: without Deterministic a map inside the
// payload could serialise in a different order on the next request and
// change the tag for the same content.
func etagFor(v any) string {
	raw, err := json.Marshal(v, json.Deterministic(true))
	if err != nil {
		return `""`
	}
	sum := sha256.Sum256(raw)
	return `"` + hex.EncodeToString(sum[:8]) + `"`
}

func etagMatches(header, etag string) bool {
	opaque := func(tag string) string {
		tag = strings.TrimSpace(tag)
		tag = strings.TrimPrefix(tag, "W/")
		return strings.Trim(tag, `"`)
	}
	stored := opaque(etag)
	for tag := range strings.SplitSeq(header, ",") {
		if strings.TrimSpace(tag) == "*" || opaque(tag) == stored {
			return true
		}
	}
	return false
}

func maybeNotModified(w http.ResponseWriter, r *http.Request, etag string) bool {
	inm := r.Header.Get("If-None-Match")
	if inm == "" || !etagMatches(inm, etag) {
		return false
	}
	writeCORS(w)
	w.Header().Set("ETag", etag)
	w.WriteHeader(http.StatusNotModified)
	return true
}

func writeJSONWithETag(w http.ResponseWriter, r *http.Request, v any) {
	etag := etagFor(v)
	if maybeNotModified(w, r, etag) {
		return
	}
	w.Header().Set("ETag", etag)
	writeJSON(w, r, http.StatusOK, v)
}

func (a *API) baseURL() string {
	return strings.TrimRight(a.deps.Config.Site.BaseURL, "/")
}

func (a *API) handleOptions(w http.ResponseWriter, r *http.Request) {
	// The preflight answers for the whole subtree, so it advertises the
	// write methods as well; a browser preflight for a cross-origin POST
	// fails when the response lists only GET.
	for key, value := range writeCORSHeaders(r, a.deps.Config) {
		w.Header().Set(key, value)
	}
	w.Header().Set("Access-Control-Max-Age", "600")
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.WriteHeader(http.StatusOK)
}

func (a *API) handleSite(w http.ResponseWriter, r *http.Request) {
	writeJSONWithETag(w, r, payloads.BuildSite(a.deps.Config))
}

func queryInt(r *http.Request, name string, def, lo, hi int) (int, bool) {
	raw := r.URL.Query().Get(name)
	if raw == "" {
		return def, true
	}
	n, err := strconv.Atoi(raw)
	if err != nil {
		return 0, false
	}
	if n < lo || n > hi {
		return 0, false
	}
	return n, true
}

func writeQueryValidationError(w http.ResponseWriter, r *http.Request, name, msg string) {
	writeError(w, r, http.StatusUnprocessableEntity, map[string]any{
		"error":   "validation",
		"message": msg,
		"field":   name,
	})
}

func (a *API) handlePosts(w http.ResponseWriter, r *http.Request) {
	q := r.URL.Query()
	page, ok := queryInt(r, "page", 1, 1, maxPage)
	if !ok {
		writeQueryValidationError(w, r, "page", "Input should be between 1 and "+strconv.Itoa(maxPage))
		return
	}
	limit, ok := queryInt(r, "limit", 20, 1, pageSizeLimit)
	if !ok {
		writeQueryValidationError(w, r, "limit", "Input should be between 1 and "+strconv.Itoa(pageSizeLimit))
		return
	}
	payload := payloads.PostsPayload(
		a.deps.Store,
		q.Get("lang"), q.Get("tag"), q.Get("q"),
		page, limit, q.Get("cursor"),
	)
	writeJSONWithETag(w, r, payload)
}

func (a *API) handleBatch(w http.ResponseWriter, r *http.Request) {
	slugsParam := r.URL.Query().Get("slugs")
	if slugsParam == "" {
		writeJSON(w, r, http.StatusOK, map[string]any{"posts": []any{}})
		return
	}
	var slugs []string
	for slug := range strings.SplitSeq(slugsParam, ",") {
		if trimmed := strings.TrimSpace(slug); trimmed != "" {
			slugs = append(slugs, trimmed)
		}
	}
	if len(slugs) > pageSizeLimit {
		slugs = slugs[:pageSizeLimit]
	}
	// One listing serves the whole batch: Find re-walks the content
	// directory per call, so a hundred slugs would walk it a hundred
	// times. The map keeps Find(slug, "") semantics: the first post in
	// listing order that carries the slug.
	posts := a.deps.Store.All()
	first := make(map[string]*post.Post, len(posts))
	for _, p := range posts {
		if _, ok := first[p.Slug()]; !ok {
			first[p.Slug()] = p
		}
	}
	base := a.baseURL()
	results := make([]payloads.Detail, 0, len(slugs))
	for _, slug := range slugs {
		p := first[slug]
		if p == nil || !p.Published() {
			continue
		}
		detail, err := payloads.BuildDetail(p, base)
		if err != nil {
			web.Logger(r.Context()).Warn("httpapi: cannot render post", "slug", slug, "error", err)
			continue
		}
		results = append(results, detail)
	}
	etag := etagFor(results)
	if maybeNotModified(w, r, etag) {
		return
	}
	w.Header().Set("ETag", etag)
	writeJSON(w, r, http.StatusOK, payloads.Batch{Posts: results})
}

func (a *API) validPreviewToken(token, slug string) bool {
	return preview.Valid(token, slug, a.deps.PreviewKey, time.Now())
}

func (a *API) handleSingle(w http.ResponseWriter, r *http.Request) {
	slug := r.PathValue("slug")
	lang := r.URL.Query().Get("lang")
	p := a.deps.Store.Find(slug, lang)
	if p == nil {
		if canonical := a.deps.Store.ResolveAlias(slug); canonical != "" {
			w.Header().Set("Location", "/api/volumen/posts/"+canonical)
			w.WriteHeader(http.StatusMovedPermanently)
			return
		}
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	if !p.Published() && !a.validPreviewToken(r.URL.Query().Get("preview_token"), slug) {
		// A draft and a scheduled post are distinguishable on purpose:
		// the client knows the slug already, and the two states need
		// different handling on the other side.
		if p.Draft() {
			writeError(w, r, http.StatusNotFound, map[string]any{"error": "draft"})
			return
		}
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "scheduled"})
		return
	}
	detail, err := payloads.BuildDetail(p, a.baseURL())
	if err != nil {
		writeError(w, r, http.StatusInternalServerError, map[string]any{"error": "render_failed"})
		return
	}
	if !p.Published() {
		// The URL is only valid with the preview token, but a shared cache
		// would still be allowed to hold the unpublished content for the
		// header's lifetime; a draft or a scheduled post is not
		// publicly cacheable.
		writeJSONWithHeaders(w, r, http.StatusOK, detail,
			map[string]string{"Cache-Control": "no-store"})
		return
	}
	writeJSONWithETag(w, r, detail)
}

func (a *API) handleTags(w http.ResponseWriter, r *http.Request) {
	writeJSONWithETag(w, r, payloads.TagList{Tags: payloads.BuildTagCounts(a.publishedPosts())})
}

func (a *API) handleTagPosts(w http.ResponseWriter, r *http.Request) {
	tag := r.PathValue("tag")
	q := r.URL.Query()
	page, ok := queryInt(r, "page", 1, 1, maxPage)
	if !ok {
		writeQueryValidationError(w, r, "page", "Input should be between 1 and "+strconv.Itoa(maxPage))
		return
	}
	limit, ok := queryInt(r, "limit", 20, 1, 100)
	if !ok {
		writeQueryValidationError(w, r, "limit", "Input should be between 1 and "+strconv.Itoa(pageSizeLimit))
		return
	}
	payload := payloads.PostsPayload(a.deps.Store, q.Get("lang"), tag, "", page, limit, q.Get("cursor"))
	if payloads.IsEmpty(payload) {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	writeJSONWithETag(w, r, payload)
}

func (a *API) handleSeries(w http.ResponseWriter, r *http.Request) {
	writeJSON(w, r, http.StatusOK, payloads.SeriesList{Series: payloads.BuildSeriesList(a.deps.Store)})
}

func (a *API) handleSeriesDetail(w http.ResponseWriter, r *http.Request) {
	name := r.PathValue("name")
	posts := payloads.SeriesPosts(a.deps.Store, name)
	if len(posts) == 0 {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	summaries := make([]payloads.Summary, 0, len(posts))
	for _, p := range posts {
		summaries = append(summaries, payloads.BuildSummary(p))
	}
	writeJSON(w, r, http.StatusOK, payloads.SeriesDetail{
		Name:  name,
		Count: len(posts),
		Posts: summaries,
	})
}

func (a *API) publishedPosts() []*post.Post {
	return payloads.PublishedPosts(a.deps.Store)
}

func (a *API) postsWithTag(tag string) []*post.Post {
	var out []*post.Post
	for _, p := range a.publishedPosts() {
		if slices.Contains(p.Tags(), tag) {
			out = append(out, p)
		}
	}
	return out
}

func (a *API) handleTagRSS(w http.ResponseWriter, r *http.Request) {
	tag := r.PathValue("tag")
	posts := a.postsWithTag(tag)
	if len(posts) == 0 {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	writeXML(w, r, "application/rss+xml",
		feeds.RenderRSSFeed(posts, a.deps.Config.Site, a.baseURL(), tagFeedPath(tag, "xml")))
}

func (a *API) handleTagAtom(w http.ResponseWriter, r *http.Request) {
	tag := r.PathValue("tag")
	posts := a.postsWithTag(tag)
	if len(posts) == 0 {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	writeXML(w, r, "application/atom+xml",
		feeds.RenderAtomFeed(posts, a.deps.Config.Site, a.baseURL(), tagFeedPath(tag, "atom")))
}

func (a *API) handleTagJSON(w http.ResponseWriter, r *http.Request) {
	tag := r.PathValue("tag")
	posts := a.postsWithTag(tag)
	if len(posts) == 0 {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	a.writeJSONFeed(w, r, posts, tagFeedPath(tag, "json"))
}

func (a *API) handleSeriesRSS(w http.ResponseWriter, r *http.Request) {
	name := r.PathValue("name")
	posts := payloads.SeriesPosts(a.deps.Store, name)
	if len(posts) == 0 {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	writeXML(w, r, "application/rss+xml",
		feeds.RenderRSSFeed(posts, a.deps.Config.Site, a.baseURL(), seriesFeedPath(name, "xml")))
}

func (a *API) handleSeriesAtom(w http.ResponseWriter, r *http.Request) {
	name := r.PathValue("name")
	posts := payloads.SeriesPosts(a.deps.Store, name)
	if len(posts) == 0 {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	writeXML(w, r, "application/atom+xml",
		feeds.RenderAtomFeed(posts, a.deps.Config.Site, a.baseURL(), seriesFeedPath(name, "atom")))
}

func (a *API) handleSeriesJSON(w http.ResponseWriter, r *http.Request) {
	name := r.PathValue("name")
	posts := payloads.SeriesPosts(a.deps.Store, name)
	if len(posts) == 0 {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	a.writeJSONFeed(w, r, posts, seriesFeedPath(name, "json"))
}

func (a *API) handleRSS(w http.ResponseWriter, r *http.Request) {
	writeXML(w, r, "application/rss+xml",
		feeds.RenderRSSFeed(a.publishedPosts(), a.deps.Config.Site, a.baseURL(), siteFeedPath("xml")))
}

func (a *API) handleAtom(w http.ResponseWriter, r *http.Request) {
	writeXML(w, r, "application/atom+xml",
		feeds.RenderAtomFeed(a.publishedPosts(), a.deps.Config.Site, a.baseURL(), siteFeedPath("atom")))
}

func (a *API) handleJSONFeed(w http.ResponseWriter, r *http.Request) {
	a.writeJSONFeed(w, r, a.publishedPosts(), siteFeedPath("json"))
}

// Feed paths, used for the self link and feed_url of each document.
func siteFeedPath(format string) string { return "/api/volumen/feed." + format }
func tagFeedPath(tag, format string) string {
	return "/api/volumen/tags/" + url.PathEscape(tag) + "/feed." + format
}
func seriesFeedPath(name, format string) string {
	return "/api/volumen/series/" + url.PathEscape(name) + "/feed." + format
}

func (a *API) writeJSONFeed(w http.ResponseWriter, r *http.Request, posts []*post.Post, selfPath string) {
	body, err := feeds.MarshalJSONFeed(feeds.RenderJSONFeed(posts, a.deps.Config.Site, a.baseURL(), selfPath))
	if err != nil {
		writeError(w, r, http.StatusInternalServerError, map[string]any{"error": "render_failed"})
		return
	}
	writeCORS(w)
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	_, _ = w.Write(append(body, '\n'))
}

func (a *API) handleSitemap(w http.ResponseWriter, r *http.Request) {
	// The key is the store's snapshot, which changes whenever a post file
	// is added, edited, touched or removed: the sitemap's lastmod comes
	// from the file's modification time, so keying on the path and date
	// alone would serve a stale lastmod for the life of the process.
	// The key is taken before the posts: content changing between the two
	// reads would pin XML rendered from the older snapshot under the newer
	// key, and the cache would serve it until the next change. Key-first,
	// the worst case is XML newer than its key, which recomputes.
	key := a.deps.Store.CacheKey()
	posts := a.publishedPosts()

	a.sitemapMu.Lock()
	if a.sitemapXML != "" && a.sitemapKey == key {
		xml := a.sitemapXML
		a.sitemapMu.Unlock()
		writeXML(w, r, "application/xml", xml)
		return
	}
	a.sitemapMu.Unlock()

	xml := feeds.RenderSitemap(posts, a.baseURL())
	a.sitemapMu.Lock()
	a.sitemapKey = key
	a.sitemapXML = xml
	a.sitemapMu.Unlock()
	writeXML(w, r, "application/xml", xml)
}

// --- token-authenticated writes ---------------------------------------------

var writeFields = []string{
	"title", "slug", "lang", "author", "fediverse_creator",
	"excerpt", "cover", "cover_alt", "cover_caption", "series",
}

func (a *API) requireToken(w http.ResponseWriter, r *http.Request, scope string) (*tokens.Token, bool) {
	header := r.Header.Get("Authorization")
	scheme, raw, found := strings.Cut(header, " ")
	if !found || !strings.EqualFold(scheme, "Bearer") || strings.TrimSpace(raw) == "" {
		writeUnauthorized(w, r)
		return nil, false
	}
	token := a.deps.Tokens.Authenticate(strings.TrimSpace(raw))
	if token == nil {
		writeUnauthorized(w, r)
		return nil, false
	}
	a.deps.Tokens.Touch(token.Name)
	if !token.HasScope(scope) {
		writeError(w, r, http.StatusForbidden, map[string]any{
			"error":   "forbidden",
			"message": fmt.Sprintf("Token lacks '%s' scope", scope),
		})
		return nil, false
	}
	return token, true
}

// writeUnauthorized answers a missing or invalid token. The challenge
// goes out with the status line: a header set after WriteHeader never
// reaches the client.
func writeUnauthorized(w http.ResponseWriter, r *http.Request) {
	writeJSONWithHeaders(w, r, http.StatusUnauthorized,
		map[string]any{"error": "unauthorized"},
		map[string]string{"WWW-Authenticate": "Bearer", "Cache-Control": "no-store"})
}

// writeCORSHeaders builds the restrictive CORS header set for
// token-authenticated write endpoints; only the configured base_url is
// allowed as an origin (with a wildcard fallback for setups without
// one).
func writeCORSHeaders(r *http.Request, cfg *config.Config) map[string]string {
	base := strings.TrimRight(cfg.Site.BaseURL, "/")
	origin := r.Header.Get("Origin")
	allowed := "*"
	if base != "" && origin != "" {
		allowed = base
	}
	return map[string]string{
		"Access-Control-Allow-Origin":  allowed,
		"Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
		"Access-Control-Allow-Headers": "Content-Type, Authorization",
		"Cache-Control":                "no-store",
	}
}

// readJSONBody decodes a write payload. The decoder rejects a duplicate
// object member and invalid UTF-8, so a body that a JSON parser could
// read two ways is a 400 rather than a silent choice. A body over the
// limit is a 413, not a parse failure.
func readJSONBody(w http.ResponseWriter, r *http.Request) (map[string]any, bool) {
	var data map[string]any
	if err := json.UnmarshalRead(http.MaxBytesReader(w, r.Body, maxWriteBody), &data); err != nil {
		if _, ok := errors.AsType[*http.MaxBytesError](err); ok {
			writeError(w, r, http.StatusRequestEntityTooLarge, map[string]any{"error": "payload_too_large"})
			return nil, false
		}
		writeError(w, r, http.StatusBadRequest, map[string]any{"error": "invalid_json"})
		return nil, false
	}
	return data, true
}

// postFromJSON merges a JSON write payload into a post: omitted fields
// keep their values on update, an explicit null or empty string clears a
// field, and a malformed type is rejected with a validation message
// rather than coerced.
func postFromJSON(data map[string]any, existing *post.Post) (*post.Post, error) {
	meta := frontmatterMetaFrom(existing)
	body := ""
	if existing != nil {
		body = existing.Body
	}
	if rawBody, present := data["body"]; present {
		// An explicit null clears the body, as it does every metadata
		// field; keeping the stored text would contradict the merge
		// contract the comment above documents.
		if rawBody == nil {
			body = ""
		} else {
			text, ok := rawBody.(string)
			if !ok {
				return nil, &payloads.ValidationError{Message: "body must be a string"}
			}
			body = text
		}
	}

	bad := func(message string) (*post.Post, error) { return nil, &payloads.ValidationError{Message: message} }

	for _, field := range writeFields {
		value, present := data[field]
		if !present {
			continue
		}
		switch v := value.(type) {
		case string:
			if strings.TrimSpace(v) != "" {
				meta.Set(field, strings.TrimSpace(v))
			} else {
				meta.Delete(field)
			}
		case nil:
			meta.Delete(field)
		default:
			return bad(fmt.Sprintf("%s must be a string", field))
		}
	}
	for _, dateField := range []string{"date", "publish_at"} {
		value, present := data[dateField]
		if !present {
			continue
		}
		if parsed, ok := payloads.ParseDate(value); ok {
			meta.Set(dateField, interpres.LocalDate{Time: parsed})
		} else if value == nil || value == "" {
			meta.Delete(dateField)
		} else {
			return bad(fmt.Sprintf("%s must be an ISO 8601 date", dateField))
		}
	}
	if value, present := data["tags"]; present {
		switch v := value.(type) {
		case []any:
			var cleaned []string
			for _, item := range v {
				// A malformed item is rejected, not coerced: fmt.Sprintf
				// would turn null into the tag "<nil>".
				s, ok := item.(string)
				if !ok {
					return bad("tags must be a list of strings")
				}
				if trimmed := strings.TrimSpace(s); trimmed != "" {
					cleaned = append(cleaned, trimmed)
				}
			}
			if len(cleaned) > 0 {
				meta.Set("tags", cleaned)
			} else {
				meta.Delete("tags")
			}
		case string:
			if strings.TrimSpace(v) != "" {
				meta.Set("tags", payloads.ParseTags(v))
			} else {
				meta.Delete("tags")
			}
		case nil:
			meta.Delete("tags")
		default:
			return bad("tags must be a list of strings")
		}
	}
	for _, boolField := range []string{"draft", "all_langs"} {
		value, present := data[boolField]
		if !present {
			continue
		}
		b, ok := value.(bool)
		if !ok {
			return bad(fmt.Sprintf("%s must be a boolean", boolField))
		}
		if b {
			meta.Set(boolField, true)
		} else {
			meta.Delete(boolField)
		}
	}
	if value, present := data["series_order"]; present {
		switch v := value.(type) {
		case nil:
			meta.Delete("series_order")
		case bool:
			return bad("series_order must be an integer")
		case float64:
			if v != float64(int64(v)) {
				return bad("series_order must be an integer")
			}
			meta.Set("series_order", int64(v))
		case string:
			if strings.TrimSpace(v) == "" {
				meta.Delete("series_order")
				break
			}
			n, ok := payloads.ParseInt(v)
			if !ok {
				return bad("series_order must be an integer")
			}
			meta.Set("series_order", int64(n))
		default:
			return bad("series_order must be an integer")
		}
	}

	p := post.New(meta, body)
	if existing != nil {
		p.Path = existing.Path
	}
	return p, nil
}

func frontmatterMetaFrom(existing *post.Post) *frontmatter.Meta {
	meta := frontmatter.NewMeta()
	if existing != nil {
		for _, key := range existing.Metadata.Keys() {
			value, _ := existing.Metadata.Get(key)
			meta.Set(key, value)
		}
	}
	return meta
}

func (a *API) handleCreatePost(w http.ResponseWriter, r *http.Request) {
	if _, ok := a.requireToken(w, r, "write"); !ok {
		return
	}
	data, ok := readJSONBody(w, r)
	if !ok {
		return
	}
	p, err := postFromJSON(data, nil)
	if err != nil {
		writeError(w, r, http.StatusBadRequest, map[string]any{"error": "validation", "message": err.Error()})
		return
	}
	if err := payloads.CreationError(p, a.deps.Store, nil); err != nil {
		writeError(w, r, http.StatusBadRequest, map[string]any{"error": "validation", "message": err.Error()})
		return
	}
	saved, err := a.deps.Store.Save(p)
	if err != nil {
		writeError(w, r, http.StatusInternalServerError, map[string]any{"error": "save_failed"})
		return
	}
	summary := payloads.BuildSummary(saved)
	a.fire("post.created", map[string]any{"post": summary})
	headers := writeCORSHeaders(r, a.deps.Config)
	// The ETag names the resource state the single-post GET serves, so a
	// client can chain the create straight into an If-Match write.
	if detail, err := payloads.BuildDetail(saved, a.baseURL()); err == nil {
		headers["ETag"] = etagFor(detail)
	}
	writeJSONWithHeaders(w, r, http.StatusCreated, summary, headers)
}

// preconditionHolds checks the request's If-Match against the ETag the
// single-post GET serves for the same resource, so a client that read
// the post, edited it and writes it back fails instead of overwriting a
// change it never saw. No header is unconditional; `*` demands the post
// exists, which the caller has already established.
func (a *API) preconditionHolds(w http.ResponseWriter, r *http.Request, existing *post.Post) bool {
	header := r.Header.Get("If-Match")
	if header == "" {
		return true
	}
	detail, err := payloads.BuildDetail(existing, a.baseURL())
	if err != nil {
		writeError(w, r, http.StatusInternalServerError, map[string]any{"error": "render_failed"})
		return false
	}
	if etagMatches(header, etagFor(detail)) {
		return true
	}
	writeError(w, r, http.StatusPreconditionFailed, map[string]any{"error": "precondition_failed"})
	return false
}

func (a *API) handleUpdatePost(w http.ResponseWriter, r *http.Request) {
	if _, ok := a.requireToken(w, r, "write"); !ok {
		return
	}
	slug := r.PathValue("slug")
	existing := a.deps.Store.Find(slug, "")
	if existing == nil {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	if !a.preconditionHolds(w, r, existing) {
		return
	}
	data, ok := readJSONBody(w, r)
	if !ok {
		return
	}
	p, err := postFromJSON(data, existing)
	if err != nil {
		writeError(w, r, http.StatusBadRequest, map[string]any{"error": "validation", "message": err.Error()})
		return
	}
	if p.Slug() == "" {
		p.Metadata.Set("slug", slug)
	}
	if err := payloads.CreationError(p, a.deps.Store, existing); err != nil {
		writeError(w, r, http.StatusBadRequest, map[string]any{"error": "validation", "message": err.Error()})
		return
	}
	// A post whose language came from its directory (not the frontmatter)
	// keeps it through a rename: the payload set no lang, so the new
	// default path would otherwise drop the language subdirectory and
	// silently move the post into the default language.
	if p.Lang() == "" {
		p.SetFileLocation(existing.Slug(), existing.Lang())
	}
	// SavePost moves the file when the slug changed and archives the old
	// one under its own language, the same way the admin editor does, so
	// a rename behaves alike from either entry point.
	saved, err := payloads.SavePost(a.deps.Store, p, existing)
	if err != nil {
		writeError(w, r, http.StatusInternalServerError, map[string]any{"error": "save_failed"})
		return
	}
	summary := payloads.BuildSummary(saved)
	a.fire("post.updated", map[string]any{"post": summary})
	headers := writeCORSHeaders(r, a.deps.Config)
	if detail, err := payloads.BuildDetail(saved, a.baseURL()); err == nil {
		headers["ETag"] = etagFor(detail)
	}
	writeJSONWithHeaders(w, r, http.StatusOK, summary, headers)
}

func (a *API) handleDeletePost(w http.ResponseWriter, r *http.Request) {
	if _, ok := a.requireToken(w, r, "delete"); !ok {
		return
	}
	slug := r.PathValue("slug")
	existing := a.deps.Store.Find(slug, "")
	if existing == nil {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	if !a.preconditionHolds(w, r, existing) {
		return
	}
	deleted, _, err := a.deps.Store.Delete(slug, "")
	if err != nil {
		web.Logger(r.Context()).Error("httpapi: cannot delete post", "slug", slug, "error", err)
		writeError(w, r, http.StatusInternalServerError, map[string]any{"error": "delete_failed"})
		return
	}
	if deleted == nil {
		writeError(w, r, http.StatusNotFound, map[string]any{"error": "not_found"})
		return
	}
	a.fire("post.deleted", map[string]any{"post": map[string]any{
		"slug": deleted.Slug(), "title": deleted.Title(),
	}})
	for key, value := range writeCORSHeaders(r, a.deps.Config) {
		w.Header().Set(key, value)
	}
	w.WriteHeader(http.StatusNoContent)
}