Files
Nick Vigilante c95b908705 ci: make docs redirects relative and block removed routes (#30805)
## Summary

Moves `docs/redirects.json` to relative routes and makes
`lint/docs-redirects` fail when a PR removes a live docs route without a
redirect.
coder.com and docs-engine build each version's redirects from that
branch's file, so this file becomes the only place contributors add docs
redirects.

Part of DOCS-1290; tracked in DOCS-1296.

## Changes

- New rule format: `{"source": "path/to/page", "destination":
"path/to/another-page"}`, relative to the docs root of the branch's
version.
Trailing `/*` is the only wildcard, `/` is the version's docs root, one
`#fragment` is allowed on exact destinations, and external destinations
are limited to `https://github.com/coder/` and `https://coder.com/`.
The old `/docs/...` form is rejected with the converted rule in the
message.
- Removed-route check now blocks.
Every route in the base manifest, the live page list for the target
branch (`coder.com/beta-docs/<version>/llms.txt`), and the base file's
sources must be a page or resolve through a rule.
The failure names the old file and prints a paste-ready rule, suggesting
a renamed sibling, a page with the same last segment, or `/`.
  An unreadable live list exits 2 in CI; `-offline` skips it locally.
Links under `/docs` count as well, so the check keeps working if the
list URL redirects there after the move to `/docs`.
- `docs/redirects.json` on `main`: 304 rules.
It carries the coder.com docs rules that 404 under `/docs/@main` today,
plus the 144 `@main`-only rules coder.com holds, with three sibling sets
condensed into wildcards (`networking/*`, `admin/notifications/*`,
`guides/*`).
- README, content guidelines, and agent guidance describe the new
format.

## Testing

- `go test ./scripts/docsredirectscheck/...` (also `-race`),
`golangci-lint`, and the pre-commit hook.
- `go run ./scripts/docsredirectscheck -base origin/main -branch main`
online, after merging current `main`: 304 rules OK, 497 routes resolve.
- Renaming `admin/integrations/istio.md` without a rule fails with
`{"source": "admin/integrations/istio", "destination":
"admin/integrations/istio-mesh"}`; adding that rule passes.
- coder.com's `generateRedirects` with this file and `main`'s manifest:
0 dropped; 336 of 336 sampled old URLs resolve to the expected page with
Next's matcher.
- `curl` on every destination under `coder.com/docs/@main`: all 200.
- Live baseline before merge: 185 of 336 sampled `/docs/@main` URLs
return 404.
- The check runs on Linux in `ci.yaml`'s `lint` job; the package's unit
tests also run on macOS and Windows in `test-go-pg`.

## Merge order

Merge after the coder.com generator (coder/coder.com,
`vigilante/docs-redirects-relative`) is deployed, otherwise coder.com
drops these rules with warnings until it is.
The docs-engine change (coder/docs-engine,
`vigilante/version-redirects`) can land before or after.
Then merge the `release/2.38` backport.

<details>
<summary>Contract shared by coder/coder, coder.com, and
docs-engine</summary>

# Docs redirects contract (coder/coder owns the data; coder.com and
docs-engine consume it)

## Ownership

- Every redirect for a moved, renamed, or removed docs page lives in
`coder/coder` `docs/redirects.json`, one file per branch (`main`,
`release/X.Y`).
- A branch's file applies only to that branch's version of the docs.
`main`'s file applies to `@main`; `release/X.Y`'s file applies to vX.Y,
and to unversioned `/docs` while X.Y is mainline.
- URL-scheme rules (`/docs/v1`, `/docs/v2/...`, `/docs/coder-oss/...`,
`/docs/coder/...`, `/docs/code-server/...`, classic `/@v<line>` forms)
are not content moves. They stay in the consumer that owns the URL
scheme, as code or a static engine-owned file.
- Nobody adds content redirects in coder.com or docs-engine. Existing
ones there are removed only after the matching coder/coder rules are
verified live for that version (later phase, not this change).

## File format

`docs/redirects.json` is a JSON array. Each entry is an object with
exactly these fields:

| Field | Required | Meaning |

|---------------|----------|-------------------------------------------------------------------------|
| `source` | yes | A route relative to the docs root of this version |
| `destination` | yes | A route relative to the docs root, `/` for the
docs root, or an allowed `https://` URL |
| `permanent` | no | Boolean, default `true`. `true` answers 308,
`false` answers 307 |

Unknown fields are an error.

### Routes

- A route is the URL path below `/docs` with no version, no leading
slash, no trailing slash, and no `.md`:
`admin/templates/extending-templates`.
- A route is one or more segments joined by `/`. Each segment matches
`[A-Za-z0-9._-]+`. Nothing else is allowed (no `@`, `%`, `:`, `(`, `?`,
`#`, spaces, empty segments, `.` or `..` segments).
- Routes are derived from `docs/manifest.json` the way the sites do
today: strip a leading `./`, then strip `README.md`, `index.md`, `.md`
in that order as plain text, trim slashes. The empty result is the docs
root.

### Wildcards

- A `source` may end in `/*`: `ai-coder/ai-bridge/*`. It matches the
prefix itself and every route beneath it.
- A `destination` may end in `/*` only when the source does. The part
the source's `*` matched (possibly empty) replaces the destination's
`*`; an empty match means the destination prefix itself
(`ai-coder/ai-gateway/*` with an empty match is `ai-coder/ai-gateway`).
- A wildcard source with a non-wildcard destination sends everything
under the prefix to that one page.
- No other pattern syntax exists. Consumers translate `*` into their own
matcher. For Next.js that is `:path([A-Za-z0-9._-]+)*`, never `(.*)`,
`.+`, or a bare `:name*`.

### Destinations

- `/` is the docs root of the same version (`/docs`, `/docs/@main`,
`/beta-docs/v2.37`, and so on). Pages with no suitable home redirect to
`/`.
- An internal destination always stays in the same version as the
request.
- A non-wildcard internal destination may end in one `#fragment`, where
the fragment matches `[A-Za-z0-9._-]+`:
`user-guides/workspace-access#web-ides`. The route part must still be a
live route. A wildcard destination and `/` never carry a fragment.
- An external destination is an `https://` URL whose host and path start
with an allowed prefix: `https://github.com/coder/` or
`https://coder.com/`. It contains no `:` after the scheme and no
parameter. A `*` is not allowed in an external destination.

### Order and precedence

- Rules apply in file order; the first match wins.
- A page always wins over a redirect: a rule only fires for a request
that is not a live page of that version. The checker rejects any rule
whose source matches a live route, so consumers that check redirects
before pages (Next.js static redirects) behave the same as those that
check on a miss.
- Matching ignores one trailing slash on the request.
- Consumers follow at most 3 chained hops and refuse loops. The checker
rejects chains so a valid file never needs this.

### Legacy entries

- During migration, consumers also accept a `source` or `destination`
that starts with `/docs/` (or equals `/docs`) and treat it as the route
after `/docs/` (or `/` for `/docs`). A legacy `:name*` or `:name(.*)`
trailing parameter is treated as `/*`. The coder/coder checker accepts
only the new form.
- A missing file and an empty array both mean no rules. A file that is
not a JSON array is an error.

## CI check (coder/coder `scripts/docsredirectscheck`)

Structural checks as today, adapted to the new form, plus a blocking
removed-route check:

1. **Inventory.** The set of routes that must keep working is the union
of:
   - the base branch's `docs/manifest.json` routes,
- every route in the live production page list for the PR's target
branch, read from `https://coder.com/beta-docs/<segment>/llms.txt` where
the segment is `@main` for `main` and `vX.Y` for `release/X.Y`, keeping
only links under that segment,
- every `source` in the base branch's `docs/redirects.json` (exact
sources as-is; wildcard sources contribute the prefix).
2. **Resolution.** Each inventory route must be a live route in the head
manifest, or be resolved by the head rules (with wildcard substitution)
to a live head route, `/`, or an allowed external URL.
3. **Failure message.** Name the route, the file it came from on the
base branch when known, and a ready-to-paste rule, for example
`{"source": "path/to/page", "destination": "path/to/another-page"}`,
pointing at `/` when no candidate is obvious.
4. **Live list failures.** A network error, non-200, or a list with no
routes is an infrastructure failure (exit 2) in CI, not a pass. Locally,
`-offline` skips the live list and says so.
5. **Known engine difference.** beta-docs currently serves dotted
segments with hyphens (`esr-2.24-2.29-upgrade` is served as
`esr-2-24-2-29-upgrade`). Until docs-engine fixes it, a live route that
equals a head route with `.` replaced by `-` in each segment counts as
present.

## Consumers

- **coder.com classic** (`scripts/generate-docs-redirects.ts`): reads
`main` (scoped to `/docs/@main/...`) and the mainline release branch
(unversioned `/docs/...`) as today, in the new format, and emits Next.js
redirects. Version coverage beyond those two is out of scope.
- **docs-engine beta**: each version's publish reads
`docs/redirects.json` from the commit it builds, validates it, and
stores the compiled rules with that version's archive. The router
applies a version's own rules on a miss inside that version. Versions
published before this change keep today's behavior.

</details>

---

🤖 Built with AI assistance.
2026-11-05 14:04:17 -05:00

640 lines
20 KiB
Go

package main
import (
"bytes"
"cmp"
"encoding/json"
"errors"
"fmt"
"net/url"
"regexp"
"slices"
"strconv"
"strings"
)
// allowedExternalPrefixes are the only places a destination may send a reader
// outside the docs.
var allowedExternalPrefixes = []string{
"https://github.com/coder/",
"https://coder.com/",
}
// pattern is a rule source: an exact route, or a route prefix ending in "/*"
// that matches the prefix itself and every route beneath it.
type pattern struct {
wild bool
// prefix is the route with any trailing "/*" removed.
prefix string
}
func (p pattern) matches(route string) bool {
route = normalizeRoute(route)
if p.wild {
return route == p.prefix || strings.HasPrefix(route, p.prefix+"/")
}
return route == p.prefix
}
// key identifies a source for duplicate detection.
func (p pattern) key() string {
return fmt.Sprintf("%t %s", p.wild, p.prefix)
}
// covers reports whether every route q matches is also matched by p, which
// makes q unreachable when p is earlier in the file. Rules apply in order and
// the first match wins, so a broad pattern above a narrower rule swallows it.
//
// An exact p never covers anything but an identical exact q, which the
// duplicate check already reports. In particular an exact rule above a
// wildcard on the same prefix is deliberate: it claims the bare prefix and
// leaves the subtree to the wildcard.
func (p pattern) covers(q pattern) bool {
if !p.wild {
return false
}
return q.prefix == p.prefix || strings.HasPrefix(q.prefix, p.prefix+"/")
}
type destKind int
const (
// destRoute is a route of the same docs version, possibly ending in "/*".
destRoute destKind = iota
// destRoot is the docs root of the same version.
destRoot
// destExternal is an allowed https URL.
destExternal
)
type destination struct {
kind destKind
// raw is the destination as written, for messages.
raw string
// wild is true for a route ending in "/*".
wild bool
// prefix is the route of a destRoute destination, without any "/*" or
// fragment.
prefix string
// fragment is the part after "#" of an exact route destination.
fragment string
// valid is false when the destination could not be parsed, in which case
// no cross-rule check uses it.
valid bool
}
// rule is one validated entry of docs/redirects.json.
type rule struct {
index int
source string
src pattern
dst destination
}
func (r rule) matches(route string) bool {
return r.src.matches(route)
}
// target returns where the rule sends a request for route: the destination
// kind and, for a route destination, the route with the wildcard substituted.
func (r rule) target(route string) (destKind, string) {
if r.dst.kind != destRoute {
return r.dst.kind, ""
}
if !r.dst.wild {
return destRoute, r.dst.prefix
}
rest := strings.TrimPrefix(strings.TrimPrefix(normalizeRoute(route), r.src.prefix), "/")
if rest == "" {
return destRoute, r.dst.prefix
}
return destRoute, r.dst.prefix + "/" + rest
}
// problem is one thing wrong with docs/redirects.json. index is the position
// of the offending rule in the array, or -1 for a problem with the whole file.
type problem struct {
index int
source string
message string
}
func formatProblem(file string, p problem) string {
switch {
case p.index < 0:
return fmt.Sprintf("%s: %s", file, p.message)
case p.source != "":
return fmt.Sprintf("%s[%d] (source %q): %s", file, p.index, p.source, p.message)
default:
return fmt.Sprintf("%s[%d]: %s", file, p.index, p.message)
}
}
// segmentRe matches one route segment. "." and ".." match it and are rejected
// separately.
var segmentRe = regexp.MustCompile(`^[A-Za-z0-9._-]+$`)
// fragmentRe matches the fragment of a destination, which has the same
// characters as a segment.
var fragmentRe = segmentRe
// legacyParam matches a trailing path parameter in the old syntax: ":name",
// ":name*" and ":name(.*)".
var legacyParam = regexp.MustCompile(`^:[A-Za-z_][A-Za-z0-9_]*(\*|\(\.\*\))?$`)
// normalizeRoute drops trailing slashes so "a/b/" and "a/b" compare equal, the
// way the websites route them.
func normalizeRoute(p string) string {
return strings.TrimRight(p, "/")
}
// checkRoute returns why route is not a valid route, or "" when it is. The
// empty route is not valid here: it is the docs root, which only a destination
// can name, as "/".
func checkRoute(route string) string {
switch {
case route == "":
return "empty route"
case strings.HasPrefix(route, "/"):
return "routes are relative to the docs root and have no leading slash"
case strings.HasSuffix(route, "/"):
return "routes have no trailing slash"
}
segments := strings.Split(route, "/")
for _, seg := range segments {
switch {
case seg == "":
return "empty path segment"
case seg == "." || seg == "..":
return fmt.Sprintf("segment %q is not allowed", seg)
case !segmentRe.MatchString(seg):
return fmt.Sprintf("segment %q must match [A-Za-z0-9._-]+", seg)
}
}
if strings.HasSuffix(segments[len(segments)-1], ".md") {
return `routes do not end in ".md"`
}
return ""
}
func parseSource(raw string) (pattern, string) {
prefix, wild := strings.CutSuffix(raw, "/*")
if msg := checkRoute(prefix); msg != "" {
if strings.Contains(raw, "*") && !wild {
return pattern{}, fmt.Sprintf(`unsupported source %q: "*" is only allowed as a trailing "/*"`, raw)
}
return pattern{}, fmt.Sprintf("unsupported source %q: %s", raw, msg)
}
return pattern{wild: wild, prefix: prefix}, ""
}
func parseDestination(raw string) (destination, string) {
d := destination{raw: raw}
switch {
case raw == "/":
d.kind = destRoot
case strings.HasPrefix(raw, "https://"):
if msg := checkExternal(raw); msg != "" {
return d, msg
}
d.kind = destExternal
case strings.Contains(raw, "://"):
return d, fmt.Sprintf(`unsupported destination %q: external destinations must be https:// URLs under %s`, raw, strings.Join(allowedExternalPrefixes, " or "))
default:
route, fragment, hasFragment := strings.Cut(raw, "#")
if hasFragment {
switch {
case route == "/" || strings.HasSuffix(route, "/*"):
return d, fmt.Sprintf(`unsupported destination %q: "/" and wildcard destinations do not take a fragment`, raw)
case !fragmentRe.MatchString(fragment):
return d, fmt.Sprintf(`unsupported destination %q: a fragment must match [A-Za-z0-9._-]+ and there is at most one`, raw)
}
}
prefix, wild := strings.CutSuffix(route, "/*")
if msg := checkRoute(prefix); msg != "" {
if strings.Contains(route, "*") && !wild {
return d, fmt.Sprintf(`unsupported destination %q: "*" is only allowed as a trailing "/*"`, raw)
}
return d, fmt.Sprintf(`unsupported destination %q: %s (use a route such as "admin/users", "/" for the docs root, or an allowed https URL)`, raw, msg)
}
d.kind, d.prefix, d.wild, d.fragment = destRoute, prefix, wild, fragment
}
d.valid = true
return d, ""
}
func checkExternal(raw string) string {
allowed := false
for _, p := range allowedExternalPrefixes {
if strings.HasPrefix(raw, p) {
allowed = true
break
}
}
switch {
case !allowed:
return fmt.Sprintf("external destination %q must start with %s", raw, strings.Join(allowedExternalPrefixes, " or "))
case strings.Contains(strings.TrimPrefix(raw, "https://"), ":"):
return fmt.Sprintf(`external destination %q must not contain ":" after the scheme`, raw)
case strings.ContainsAny(raw, "*{} \t\r\n"):
return fmt.Sprintf("external destination %q must not contain a wildcard, parameter, or whitespace", raw)
case strings.Contains(raw, `\`):
// Browsers read "\" as "/" in https URLs.
return fmt.Sprintf(`external destination %q must not contain "\"`, raw)
}
// A "." or ".." segment, also when percent-encoded, would let a URL that
// starts with an allowed prefix resolve outside it.
u, err := url.Parse(raw)
if err != nil {
return fmt.Sprintf("external destination %q is not a valid URL: %v", raw, err)
}
for _, seg := range strings.Split(u.Path, "/") {
if seg == "." || seg == ".." {
return fmt.Sprintf(`external destination %q must not contain a "." or ".." path segment`, raw)
}
}
return ""
}
func isLegacyPath(s string) bool {
return s == "/docs" || strings.HasPrefix(s, "/docs/")
}
// convertLegacy rewrites a source or destination from the old absolute form
// ("/docs/admin/old", "/docs/x/:path*") to a route ("admin/old", "x/*").
// Anything else is returned unchanged.
func convertLegacy(s string) string {
if !isLegacyPath(s) {
return s
}
route := strings.Trim(strings.TrimPrefix(s, "/docs"), "/")
segments := strings.Split(route, "/")
if last := len(segments) - 1; last > 0 && legacyParam.MatchString(segments[last]) {
segments[last] = "*"
}
return strings.Join(segments, "/")
}
// convertLegacyDestination is convertLegacy for a destination, where the old
// docs root "/docs" is "/".
func convertLegacyDestination(s string) string {
if s == "/docs" || s == "/docs/" {
return "/"
}
return convertLegacy(s)
}
// ruleJSON renders a rule the way it is written in docs/redirects.json, on one
// line, so a message can be pasted into the file.
func ruleJSON(source, destination string, permanent *bool) string {
quote := func(s string) string {
b, err := json.Marshal(s)
if err != nil {
return strconv.Quote(s)
}
// json.Marshal escapes HTML characters, which would make a URL with a
// query string harder to read and paste.
return strings.NewReplacer(`\u0026`, "&", `\u003c`, "<", `\u003e`, ">").Replace(string(b))
}
out := fmt.Sprintf(`{"source": %s, "destination": %s`, quote(source), quote(destination))
if permanent != nil {
out += fmt.Sprintf(`, "permanent": %t`, *permanent)
}
return out + "}"
}
// checkRedirects validates the contents of docs/redirects.json against the set
// of live docs routes. It returns the rules whose source could be parsed, which
// the removed-route check resolves routes through, and every problem it found,
// ordered by rule.
func checkRedirects(data []byte, live routeSet) ([]rule, []problem) {
var entries []json.RawMessage
if err := json.Unmarshal(data, &entries); err != nil {
var typeErr *json.UnmarshalTypeError
if errors.As(err, &typeErr) {
// Valid JSON, but an object or scalar rather than an array.
return nil, []problem{{index: -1, message: "must be a JSON array of rules"}}
}
return nil, []problem{{index: -1, message: fmt.Sprintf("is not valid JSON: %v", err)}}
}
if entries == nil {
// A JSON null decodes to a nil slice without an error.
return nil, []problem{{index: -1, message: "must be a JSON array of rules"}}
}
var (
rules []rule
problems []problem
)
for i, entry := range entries {
r, ps := checkEntry(i, entry, live)
problems = append(problems, ps...)
if r != nil {
rules = append(rules, *r)
}
}
problems = append(problems, checkAcrossRules(rules)...)
slices.SortStableFunc(problems, func(a, b problem) int { return cmp.Compare(a.index, b.index) })
return rules, problems
}
const entryShape = `must be an object with "source", "destination" and optional "permanent"`
// checkEntry validates one array element on its own. It returns the rule when
// the source parsed, so that cross-rule checks can still use it.
func checkEntry(i int, entry json.RawMessage, live routeSet) (*rule, []problem) {
if bytes.Equal(bytes.TrimSpace(entry), []byte("null")) {
return nil, []problem{{index: i, message: entryShape}}
}
var fields map[string]json.RawMessage
if err := json.Unmarshal(entry, &fields); err != nil {
return nil, []problem{{index: i, message: entryShape}}
}
var problems []problem
add := func(source, msg string) {
problems = append(problems, problem{index: i, source: source, message: msg})
}
keys := make([]string, 0, len(fields))
for k := range fields {
keys = append(keys, k)
}
slices.Sort(keys)
for _, k := range keys {
switch k {
case "source", "destination", "permanent":
default:
add("", fmt.Sprintf("unknown field %q (allowed: source, destination, permanent)", k))
}
}
source, sourceOK := stringField(fields, "source")
if !sourceOK {
add("", `"source" is required and must be a non-empty string`)
}
dest, destOK := stringField(fields, "destination")
if !destOK {
add(source, `"destination" is required and must be a non-empty string`)
}
var permanent *bool
if raw, ok := fields["permanent"]; ok {
var b bool
if bytes.Equal(bytes.TrimSpace(raw), []byte("null")) || json.Unmarshal(raw, &b) != nil {
add(source, `"permanent" must be a boolean`)
} else {
permanent = &b
}
}
if !sourceOK {
return nil, problems
}
if isLegacyPath(source) || (destOK && isLegacyPath(dest)) {
fixed := ruleJSON(convertLegacy(source), convertLegacyDestination(dest), permanent)
add(source, fmt.Sprintf(`legacy absolute "/docs/..." form: write routes relative to the docs root, "/" for the docs root, and "/*" for a trailing wildcard. Converted rule: %s`, fixed))
return nil, problems
}
src, msg := parseSource(source)
if msg != "" {
add(source, msg)
return nil, problems
}
r := &rule{index: i, source: source, src: src}
if destOK {
d, msg := parseDestination(dest)
r.dst = d
if msg != "" {
add(source, msg)
} else {
for _, m := range checkDestination(d, src, live) {
add(source, m)
}
}
}
if m := checkShadowing(src, live); m != "" {
add(source, m)
}
return r, problems
}
func stringField(fields map[string]json.RawMessage, name string) (string, bool) {
raw, ok := fields[name]
if !ok {
return "", false
}
var s string
if err := json.Unmarshal(raw, &s); err != nil || strings.TrimSpace(s) == "" {
return "", false
}
return s, true
}
// checkDestination verifies that an internal destination lands on a page that
// exists and that a wildcard destination has a wildcard source to take its
// match from.
func checkDestination(d destination, src pattern, live routeSet) []string {
if d.kind != destRoute {
return nil
}
if !d.wild {
if !live.has(d.prefix) {
return []string{fmt.Sprintf("destination %q is not a page in docs/manifest.json; point it at an existing page", d.raw)}
}
return nil
}
var msgs []string
if !src.wild {
msgs = append(msgs, fmt.Sprintf(`destination %q ends in "/*" but the source is not a wildcard; end the source in "/*" too, or use an exact destination`, d.raw))
}
if !prefixHasPages(d.prefix, live) {
msgs = append(msgs, fmt.Sprintf("no docs page exists under %q; point the destination at an existing section", d.prefix))
}
return msgs
}
// prefixHasPages reports whether a wildcard destination with this prefix can
// land on a page: the prefix is a page or a section of pages.
func prefixHasPages(prefix string, live routeSet) bool {
if live.has(prefix) {
return true
}
for route := range live {
if strings.HasPrefix(route, prefix+"/") {
return true
}
}
return false
}
// checkShadowing reports a source that matches live docs pages. A page always
// wins over a redirect, and sites that apply redirects before pages would hide
// it, so such a rule is rejected.
func checkShadowing(src pattern, live routeSet) string {
var hidden []string
for route := range live {
if src.matches(route) {
hidden = append(hidden, route)
}
}
if len(hidden) == 0 {
return ""
}
slices.Sort(hidden)
more := ""
if len(hidden) > 1 {
more = fmt.Sprintf(" (and %d more)", len(hidden)-1)
}
return fmt.Sprintf("source hides a live docs page: %q%s; remove the redirect, or remove the page from docs/manifest.json first", displayRoute(hidden[0]), more)
}
func displayRoute(route string) string {
if route == "" {
return "/ (the docs root)"
}
return route
}
// checkOrder reports rules that can never apply because an earlier rule
// already matches every route they would. Rules apply in file order and the
// first match wins, so they have to run from most specific to least: a
// trailing wildcard above a rule inside its subtree swallows it.
//
// Each unreachable rule is reported once, against the first rule that covers
// it. Pairs with the same source are left to the duplicate check.
func checkOrder(rules []rule) []problem {
var problems []problem
for j, later := range rules {
for _, earlier := range rules[:j] {
if earlier.src.key() == later.src.key() {
continue
}
if !earlier.src.covers(later.src) {
continue
}
problems = append(problems, problem{
index: later.index,
source: later.source,
message: fmt.Sprintf(
"unreachable: rule [%d] (source %q) comes first and matches every route this rule would; order rules from most specific to least",
earlier.index, earlier.source,
),
})
break
}
}
return problems
}
// checkAcrossRules finds duplicate sources, unreachable rules, chains, and
// loops.
func checkAcrossRules(rules []rule) []problem {
var problems []problem
seen := make(map[string]int, len(rules))
for _, r := range rules {
k := r.src.key()
if first, dup := seen[k]; dup {
problems = append(problems, problem{
index: r.index,
source: r.source,
message: fmt.Sprintf("duplicate of rule [%d]: two rules with the same source; remove one", first),
})
continue
}
seen[k] = r.index
}
problems = append(problems, checkOrder(rules)...)
// next[i] is the rule whose source the destination of rule i lands on.
// Only exact route destinations are followed. Where a wildcard destination
// ends up depends on the route being redirected, so chains through one are
// not checked.
next := make(map[int]int, len(rules))
byIndex := make(map[int]rule, len(rules))
for _, r := range rules {
byIndex[r.index] = r
}
for _, r := range rules {
if !r.dst.valid || r.dst.kind != destRoute || r.dst.wild {
continue
}
for _, other := range rules {
if other.matches(r.dst.prefix) {
next[r.index] = other.index
break
}
}
}
for _, r := range rules {
if _, ok := next[r.index]; !ok {
continue
}
path, cycleStart, cyclic := followRedirects(r.index, next)
switch {
case cyclic && cycleStart == 0:
cycle := path
// Report a loop once, on its lowest-numbered rule.
if r.index != slices.Min(cycle) {
continue
}
problems = append(problems, problem{index: r.index, source: r.source, message: describeLoop(cycle, byIndex)})
case cyclic:
// Leads into a loop it is not part of.
problems = append(problems, problem{
index: r.index,
source: r.source,
message: fmt.Sprintf("redirect chain into a loop: destination %q is the source of rule [%d], which never reaches a page", r.dst.raw, path[1]),
})
default:
last := byIndex[path[len(path)-1]]
problems = append(problems, problem{
index: r.index,
source: r.source,
message: fmt.Sprintf(
"redirect chain: destination %q is the source of rule [%d], which redirects to %q; point this rule at %q directly",
r.dst.raw, path[1], last.dst.raw, last.dst.raw,
),
})
}
}
return problems
}
// followRedirects walks next from start. It returns the rules visited in
// order, and when the walk revisits a rule, cyclic is true and cycleStart is
// the position in path where that rule first appeared.
func followRedirects(start int, next map[int]int) (path []int, cycleStart int, cyclic bool) {
pos := map[int]int{start: 0}
path = []int{start}
cur := start
for {
n, ok := next[cur]
if !ok {
return path, 0, false
}
if at, seen := pos[n]; seen {
return path, at, true
}
pos[n] = len(path)
path = append(path, n)
cur = n
}
}
func describeLoop(cycle []int, byIndex map[int]rule) string {
if len(cycle) == 1 {
return "redirects to itself; remove the rule or point it at a different page"
}
parts := make([]string, 0, len(cycle)+1)
for _, idx := range cycle {
parts = append(parts, fmt.Sprintf("rule [%d] %q", idx, byIndex[idx].source))
}
parts = append(parts, fmt.Sprintf("rule [%d]", cycle[0]))
return "redirect loop: " + strings.Join(parts, " -> ") + "; break the loop by pointing one rule at a real page"
}