CDN and edge: shared caches near the user

// Decide applies the shared-cache rules: private and no-store are never stored, s-maxage wins over
// max-age, no-cache means revalidate every time, and stale-while-revalidate lets the edge answer
// from a stale copy for a while. originDown asks what happens when the revalidation fails.
func Decide(d Directives, age time.Duration, originDown bool) Decision {
  if d.NoStore || d.Private {
    return DoNotStore
  }
  lifetime := d.MaxAge
  if d.SMaxAge >= 0 {
    lifetime = d.SMaxAge // the shared-cache lifetime
  }
  a := int(age.Seconds())
  switch {
  case !d.NoCache && lifetime >= 0 && a < lifetime:
    return ServeFresh
  case originDown && !d.MustRevalidate && d.StaleIfError >= 0 && a < max(lifetime, 0)+d.StaleIfError:
    return StaleIfOriginFails
  case !d.NoCache && !d.MustRevalidate && d.StaleWhileRevalidate >= 0 && a < max(lifetime, 0)+d.StaleWhileRevalidate:
    return ServeStaleRefresh
  }
  return RevalidateFirst
}

// Revalidate answers a conditional request: 304 Not Modified when the client's ETag still
// matches, so the body is not sent again; 200 with the body otherwise.
func Revalidate(currentETag, ifNoneMatch string) int {
  for tag := range strings.SplitSeq(ifNoneMatch, ",") {
    tag = strings.TrimSpace(tag)
    if tag == "*" || strings.TrimPrefix(tag, "W/") == strings.TrimPrefix(currentETag, "W/") {
      return 304
    }
  }
  return 200
}

// Key returns the normalised cache key of a request.
func (p KeyPolicy) Key(rawURL string, h http.Header) (string, error) {
  u, err := url.Parse(rawURL)
  if err != nil {
    return "", fmt.Errorf("cache key: %w", err)
  }
  var b strings.Builder
  b.WriteString(strings.ToLower(u.Host)) // host names are case-insensitive
  b.WriteString(u.EscapedPath())
  q := u.Query()
  kept := slices.Sorted(func(yield func(string) bool) {
    for name := range q {
      if slices.Contains(p.Query, name) && !yield(name) { // drop utm_*, session ids, ...
        return
      }
    }
  })
  for i, name := range kept {
    vals := slices.Sorted(slices.Values(q[name]))
    sep := "&"
    if i == 0 {
      sep = "?"
    }
    b.WriteString(sep)
    b.WriteString(url.QueryEscape(name) + "=" + url.QueryEscape(strings.Join(vals, ",")))
  }
  for _, name := range slices.Sorted(slices.Values(p.Vary)) {
    b.WriteString("|" + strings.ToLower(name) + "=" + strings.ToLower(strings.TrimSpace(h.Get(name))))
  }
  return b.String(), nil
}

// Sign returns path with an expiry time and an HMAC-SHA256 signature over both. The origin and
// the edge share the key; the client never sees it.
func Sign(key []byte, path string, expires time.Time) string {
  exp := strconv.FormatInt(expires.Unix(), 10)
  return path + "?exp=" + exp + "&sig=" + mac(key, path, exp)
}

// Verify checks a signed URL at the edge, with no call to the origin.
func Verify(key []byte, signed string, now time.Time) error {
  u, err := url.Parse(signed)
  if err != nil {
    return fmt.Errorf("verify signed url: %w", err)
  }
  exp, sig := u.Query().Get("exp"), u.Query().Get("sig")
  want := mac(key, u.Path, exp)
  if !hmac.Equal([]byte(sig), []byte(want)) { // constant time
    return ErrBadSignature
  }
  secs, err := strconv.ParseInt(exp, 10, 64)
  if err != nil {
    return fmt.Errorf("verify signed url: expiry %q: %w", exp, err)
  }
  if !now.Before(time.Unix(secs, 0)) {
    return ErrExpired
  }
  return nil
}

func mac(key []byte, path, exp string) string {
  m := hmac.New(sha256.New, key)
  m.Write([]byte(path + "\n" + exp))
  return hex.EncodeToString(m.Sum(nil))
}