sm-journal-plugin/classes/site_cache.go

package classes

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"log/slog"
	"net"
	"net/http"
	"net/url"
	"strings"
	"time"

	"git.golem15.com/golem15/summercms/modules/lagoon"
	"gorm.io/gorm"
)

const (
	// SiteCachePurgeURLKey is the config key of the host site's cache purge
	// URL (env SUMMER_GOLEM15__JOURNAL__SITE_CACHE__PURGE_URL).
	SiteCachePurgeURLKey = "golem15.journal.site_cache.purge_url"
	// SiteCachePurgeTokenKey is the config key of the bearer token the purge
	// request carries (env SUMMER_GOLEM15__JOURNAL__SITE_CACHE__PURGE_TOKEN).
	SiteCachePurgeTokenKey = "golem15.journal.site_cache.purge_token"

	// SiteCachePurgeTimeout bounds one purge request.
	SiteCachePurgeTimeout = 2 * time.Second

	// 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 of a Journal post or category. A nil *SiteCachePurger is disabled
// and does nothing.
type SiteCachePurger struct {
	url      string
	endpoint string
	token    string
	client   *http.Client
}

// SiteCachePurgeMinTokenLength is the shortest purge token accepted, the
// same minimum the host site's purge route applies.
const SiteCachePurgeMinTokenLength = 32

// NewSiteCachePurger returns the purger for purgeURL and token. With both
// 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. The error names the offending key and never the token.
func NewSiteCachePurger(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", SiteCachePurgeTokenKey, SiteCachePurgeURLKey)
	}
	if token == "" {
		return nil, fmt.Errorf("%s is set but %s is not; set both or neither", SiteCachePurgeURLKey, SiteCachePurgeTokenKey)
	}
	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", SiteCachePurgeURLKey)
	}
	if u.User != nil {
		return nil, fmt.Errorf("%s must not carry user info", SiteCachePurgeURLKey)
	}
	if u.Fragment != "" || strings.Contains(purgeURL, "#") {
		return nil, fmt.Errorf("%s must not carry a fragment", SiteCachePurgeURLKey)
	}
	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", SiteCachePurgeURLKey)
	}
	if len(token) < SiteCachePurgeMinTokenLength {
		return nil, fmt.Errorf("%s must hold at least %d characters", SiteCachePurgeTokenKey, 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("journal: 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("journal: 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("journal: 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("journal: 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("journal: 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. A nil p does nothing.
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)
	})
}