feat(19.3-04): cooler site-cache purge service with site_cache.purge_url and purge_token

- cooler.SiteCachePurger moved from the Journal plugin: loopback-only http, 32-character token, 2 s detached request, no token in logs or errors - NewSiteCachePurgerFor names caller keys (for plugin alias keys) - PurgeSiteCacheAfterCommit through lagoon.AfterCommit, one POST per save - SiteCacheFromApp for hooks outside serve; Install publishes the purger unless a plugin already did, and fails boot on an invalid config - caching docs section, cooler README, configuration row
2026-10-15 18:21:10 +02:00
parent 1d8e50a1ee
commit 0bc390f39f
8 changed files with 876 additions and 11 deletions
--- a/modules/cooler/sitecache.go
+++ b/modules/cooler/sitecache.go
@@ -0,0 +1,260 @@
+package cooler
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"git.golem15.com/golem15/summercms/modules/backpack"
+	"git.golem15.com/golem15/summercms/modules/lagoon"
+	"gorm.io/gorm"
+)
+
+const (
+	// SiteCachePurgeURLKey is the config key of the host site's cache purge
+	// URL. Environment: SUMMER_SITE_CACHE__PURGE_URL.
+	SiteCachePurgeURLKey = "site_cache.purge_url"
+	// SiteCachePurgeTokenKey is the config key of the bearer token the purge
+	// request carries. Environment: SUMMER_SITE_CACHE__PURGE_TOKEN.
+	SiteCachePurgeTokenKey = "site_cache.purge_token"
+
+	// SiteCachePurgeTimeout bounds one purge request.
+	SiteCachePurgeTimeout = 2 * time.Second
+
+	// SiteCachePurgeMinTokenLength is the shortest purge token accepted, the
+	// same minimum the host site's purge route applies.
+	SiteCachePurgeMinTokenLength = 32
+
+	// siteCacheAnswerLimit is how much of the purge answer is read.
+	siteCacheAnswerLimit = 4 << 10
+)
+
+// SiteCachePurger asks the host site to drop its page caches after an admin
+// save. A nil *SiteCachePurger is disabled and does nothing.
+type SiteCachePurger struct {
+	url      string
+	endpoint string
+	token    string
+	client   *http.Client
+}
+
+// NewSiteCachePurger returns the purger for purgeURL and token, read from
+// site_cache.purge_url and site_cache.purge_token. Validation errors name
+// those keys; see NewSiteCachePurgerFor for the rules.
+func NewSiteCachePurger(purgeURL, token string) (*SiteCachePurger, error) {
+	return NewSiteCachePurgerFor(SiteCachePurgeURLKey, SiteCachePurgeTokenKey, purgeURL, token)
+}
+
+// NewSiteCachePurgerFor returns the purger for purgeURL and token, read
+// from the config keys urlKey and tokenKey, which its errors name. With
+// both values empty the purge is disabled and it returns nil, nil.
+// Otherwise both must be set, the URL must be http or https with a host and
+// without user info or a fragment, an http URL must point at a loopback
+// host (127.0.0.0/8, ::1 or localhost) so the bearer token never crosses
+// the network in clear, and the token must hold at least
+// SiteCachePurgeMinTokenLength characters. An error never contains the
+// token.
+func NewSiteCachePurgerFor(urlKey, tokenKey, purgeURL, token string) (*SiteCachePurger, error) {
+	purgeURL = strings.TrimSpace(purgeURL)
+	if purgeURL == "" && token == "" {
+		return nil, nil
+	}
+	if purgeURL == "" {
+		return nil, fmt.Errorf("%s is set but %s is not; set both or neither", tokenKey, urlKey)
+	}
+	if token == "" {
+		return nil, fmt.Errorf("%s is set but %s is not; set both or neither", urlKey, tokenKey)
+	}
+	u, err := url.Parse(purgeURL)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" || u.Hostname() == "" {
+		return nil, fmt.Errorf("%s must be an http or https URL with a host", urlKey)
+	}
+	if u.User != nil {
+		return nil, fmt.Errorf("%s must not carry user info", urlKey)
+	}
+	if u.Fragment != "" || strings.Contains(purgeURL, "#") {
+		return nil, fmt.Errorf("%s must not carry a fragment", urlKey)
+	}
+	if u.Scheme == "http" && !loopbackHost(u.Hostname()) {
+		return nil, fmt.Errorf("%s: an http URL must point at a loopback host (127.0.0.0/8, ::1 or localhost); use https for any other host", urlKey)
+	}
+	if len(token) < SiteCachePurgeMinTokenLength {
+		return nil, fmt.Errorf("%s must hold at least %d characters", tokenKey, SiteCachePurgeMinTokenLength)
+	}
+	return &SiteCachePurger{url: u.String(), endpoint: u.Host + u.Path, token: token, client: &http.Client{}}, nil
+}
+
+// Endpoint returns the purge URL's host and path, without the scheme, user
+// info or query, for log lines.
+func (p *SiteCachePurger) Endpoint() string {
+	if p == nil {
+		return ""
+	}
+	return p.endpoint
+}
+
+func loopbackHost(host string) bool {
+	if strings.EqualFold(host, "localhost") {
+		return true
+	}
+	ip := net.ParseIP(host)
+	return ip != nil && ip.IsLoopback()
+}
+
+type siteCachePurgeBody struct {
+	Kind string `json:"kind"`
+	Slug string `json:"slug"`
+}
+
+// Purge sends the purge request for one saved entity: a POST of
+// {"kind":kind,"slug":slug} with the bearer token, bounded by
+// SiteCachePurgeTimeout and detached from ctx's cancellation. It logs the
+// outcome and returns nothing: a purge never fails a save. The token is
+// never logged.
+func (p *SiteCachePurger) Purge(ctx context.Context, kind, slug string) {
+	if p == nil {
+		return
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), SiteCachePurgeTimeout)
+	defer cancel()
+	log := slog.Default()
+
+	raw, err := json.Marshal(siteCachePurgeBody{Kind: kind, Slug: slug})
+	if err != nil {
+		log.Warn("cooler: site cache purge failed", "kind", kind, "slug", slug, "error", err.Error())
+		return
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.url, bytes.NewReader(raw))
+	if err != nil {
+		log.Warn("cooler: site cache purge failed", "kind", kind, "slug", slug, "error", "invalid request")
+		return
+	}
+	req.Header.Set("Authorization", "Bearer "+p.token)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+
+	res, err := p.client.Do(req)
+	if err != nil {
+		log.Warn("cooler: site cache purge failed", "kind", kind, "slug", slug, "error", purgeTransportError(err))
+		return
+	}
+	defer res.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(res.Body, siteCacheAnswerLimit))
+	if res.StatusCode < 200 || res.StatusCode > 299 {
+		log.Warn("cooler: site cache purge failed", "kind", kind, "slug", slug, "status", res.StatusCode)
+		return
+	}
+	attrs := []any{"kind", kind, "slug", slug, "status", res.StatusCode}
+	var answer struct {
+		Purged *int `json:"purged"`
+	}
+	if json.Unmarshal(body, &answer) == nil && answer.Purged != nil {
+		attrs = append(attrs, "purged", *answer.Purged)
+	}
+	log.Info("cooler: site cache purged", attrs...)
+}
+
+// purgeTransportError describes a failed request without the request URL
+// or headers.
+func purgeTransportError(err error) string {
+	var uerr *url.Error
+	if errors.As(err, &uerr) {
+		err = uerr.Err
+	}
+	if errors.Is(err, context.DeadlineExceeded) {
+		return "timeout"
+	}
+	return err.Error()
+}
+
+// PurgeSiteCacheAfterCommit registers p.Purge(kind, slug) to run after the
+// transaction db belongs to commits, through lagoon.AfterCommit: a failed
+// save never purges, and a concurrent page view cannot re-cache the old
+// content between the purge and the commit. Each call sends one request
+// after its commit; there is no debounce. A nil p does nothing; outside a
+// transaction (db nil or not in one) the purge runs at once.
+func PurgeSiteCacheAfterCommit(ctx context.Context, db *gorm.DB, p *SiteCachePurger, kind, slug string) {
+	if p == nil {
+		return
+	}
+	lagoon.AfterCommit(ctx, db, func(ctx context.Context, _ *gorm.DB) {
+		p.Purge(ctx, kind, slug)
+	})
+}
+
+// SiteCacheFromApp returns the *SiteCachePurger published on app (by
+// Install, by a plugin's alias configuration or by an earlier call), or
+// builds one from site_cache.purge_url and site_cache.purge_token and
+// publishes it. It returns nil when neither key is set, and when the
+// configuration is invalid, which it logs as one error naming the key (the
+// serve command fails at boot on the same configuration). Admin hooks call
+// it, so it serves commands and tests that never run serve.
+func SiteCacheFromApp(app *backpack.App) *SiteCachePurger {
+	if app == nil {
+		return nil
+	}
+	if p, ok := app.Lookup[*SiteCachePurger](); ok && p != nil {
+		return p
+	}
+	p, err := siteCacheFromConfig(app)
+	if err != nil {
+		loggerFromApp(app).Error("cooler: site cache purge disabled", "error", err.Error())
+		return nil
+	}
+	if p == nil {
+		return nil
+	}
+	if err := app.Publish(p); err != nil {
+		if winner, ok := app.Lookup[*SiteCachePurger](); ok && winner != nil {
+			return winner
+		}
+		return nil
+	}
+	return p
+}
+
+// siteCacheFromConfig builds the purger from the framework keys.
+func siteCacheFromConfig(app *backpack.App) (*SiteCachePurger, error) {
+	if app == nil || app.Config == nil {
+		return nil, nil
+	}
+	p, err := NewSiteCachePurger(app.Config.String(SiteCachePurgeURLKey), app.Config.String(SiteCachePurgeTokenKey))
+	if err != nil {
+		return nil, fmt.Errorf("cooler: %w", err)
+	}
+	return p, nil
+}
+
+// installSiteCache publishes the site-cache purger unless one is already
+// published (a plugin's alias configuration): an invalid configuration is a
+// boot error naming the key.
+func installSiteCache(app *backpack.App, log *slog.Logger) error {
+	if p, ok := app.Lookup[*SiteCachePurger](); ok && p != nil {
+		log.Info("cooler: site cache purge enabled", "endpoint", p.Endpoint())
+		return nil
+	}
+	p, err := siteCacheFromConfig(app)
+	if err != nil {
+		return err
+	}
+	if p == nil {
+		return nil
+	}
+	if err := app.Publish(p); err != nil {
+		return fmt.Errorf("cooler: %w", err)
+	}
+	log.Info("cooler: site cache purge enabled", "endpoint", p.Endpoint())
+	return nil
+}