feat(16.2-07): purge the host site cache on every admin post and category write

- posts: FormAfterCreate/Update purge after the content_html translations,
  new FormAfterDelete; categories: FormAfterCreate and FormAfterDelete
- NewSiteCachePurger refuses half configuration, non-http(s) URLs, user
  info, fragments, http to a non-loopback host and tokens under 32 chars;
  Boot logs the endpoint host and path once
- TestPostsAdminPurgesSiteCache smoke test
- README: Configuration section (keys, contract, timing, scope), API rows

classes/site_cache.go

@@ -8,8 +8,10 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
+	"net"
 	"net/http"
 	"net/url"
+	"strings"
 	"time"
 
 	"git.golem15.com/golem15/summercms/modules/lagoon"
@@ -35,25 +37,68 @@ const (
 // save of a Journal post or category. A nil *SiteCachePurger is disabled
 // and does nothing.
 type SiteCachePurger struct {
-	url    string
-	token  string
-	client *http.Client
+	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.
+// 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
 	}
-	u, err := url.Parse(purgeURL)
-	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
-		return nil, fmt.Errorf("%s must be an http or https URL with a host", SiteCachePurgeURLKey)
+	if purgeURL == "" {
+		return nil, fmt.Errorf("%s is set but %s is not; set both or neither", SiteCachePurgeTokenKey, SiteCachePurgeURLKey)
 	}
 	if token == "" {
-		return nil, errors.New(SiteCachePurgeTokenKey + " must be set")
+		return nil, fmt.Errorf("%s is set but %s is not; set both or neither", SiteCachePurgeURLKey, SiteCachePurgeTokenKey)
 	}
-	return &SiteCachePurger{url: purgeURL, token: token, client: &http.Client{}}, nil
+	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 {