## 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.
640 lines
20 KiB
Go
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"
|
|
}
|