Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions dist/app.js

Large diffs are not rendered by default.

11 changes: 9 additions & 2 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,15 @@ curl the API to see one the page has not learned to render.
form from a tool's schema. With no write API to submit one to, the read-only
equivalent is to hand the operator a filled-in shape to edit. Required
properties only; a skeleton carrying every optional field is noise.
- **Version-aware docs links.** The docs an operator opens from a running
gateway should be the docs for *that* gateway.
- **Docs links straight to the relevant section**, anchored where the page is
broad and the question is narrow. These were *versioned* first —
`docs.fold.run/1.10/configuration/` — on the reasoning that the docs opened
from a running gateway should match that gateway. It is a good idea borrowed
from tools whose docs are published per release. fold's are one unversioned
site, so every link 404'd, and three topic slugs did not exist under any
prefix. Nothing in the repo could have caught it: external navigations are
invisible to the CSP and to any test that does not leave the machine.
`tests/docs-links.spec.ts` now fetches every URL the console can emit.

## The fonts were shipping twice

Expand Down
5 changes: 4 additions & 1 deletion playwright.contract.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@ import { defineConfig } from '@playwright/test'

export default defineConfig({
testDir: './tests',
testMatch: 'contract.spec.ts',
// Both suites that talk to something outside this repo: the gateway, and
// the documentation site. Neither belongs in the e2e run, which must stay
// answerable to the code in the pull request.
testMatch: /(contract|docs-links)\.spec\.ts/,
forbidOnly: !!process.env.CI,
// No retry. A contract either holds or it does not; retrying a shape
// mismatch just takes longer to tell you the same thing.
Expand Down
5 changes: 2 additions & 3 deletions src/components/DocsLink.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ import { docsLink, type DocTopic } from '@/lib/docs'

interface Props {
topic: DocTopic
version: string | undefined
children: string
}

Expand All @@ -15,9 +14,9 @@ interface Props {
* on every page. Out here it also fills the right side of the page header,
* which was otherwise empty on the two read-only routes.
*/
export function DocsLink({ topic, version, children }: Props) {
export function DocsLink({ topic, children }: Props) {
return (
<a class="group-action" href={docsLink(topic, version)} rel="noopener">
<a class="group-action" href={docsLink(topic)} rel="noopener">
{children} →
</a>
)
Expand Down
53 changes: 35 additions & 18 deletions src/lib/docs.ts
Original file line number Diff line number Diff line change
@@ -1,34 +1,51 @@
// Version-aware documentation links: the docs an operator opens from a
// running gateway should be the docs for *that* gateway, not for whatever is
// on main.
// Links out to the documentation.
//
// These are the only external URLs in the console, and they are navigations
// rather than fetches — CSP's form-action/frame-ancestors do not gate a
// user-initiated link, and connect-src never sees one. The set is fixed and
// CI checks it against the same allowlist fold's own CSP implies.
import { minorLine } from './version'
// These were versioned — `docs.fold.run/1.10/configuration/` — on the reasoning
// that the docs an operator opens from a running gateway should be the docs for
// *that* gateway. It is a good idea, borrowed from tools whose documentation is
// published per release. fold's is not: docs.fold.run is a single unversioned
// Starlight site, so every one of those links was a 404, and three of the topic
// slugs did not exist under any prefix either.
//
// Nothing caught it. They are external navigations, so no CSP rule and no test
// touched them, and a link that looks plausible reads as correct right up until
// somebody clicks it. tests/docs-links.spec.ts now fetches every URL this can
// produce and asserts each one answers 200, which is the only check that would
// have.
//
// Targets below are verified against the live site, anchors included.

const DOCS_ROOT = 'https://docs.fold.run'

export type DocTopic =
| 'configuration'
| 'federation'
| 'upstreams'
| 'policy'
| 'auth'
| 'observability'
| 'tenancy'
| 'discovery'

/**
* Where each surface of this console sends an operator.
*
* Anchors are used where the page is broad and the question is narrow: someone
* reading the Governance cards wants the `policy` block, not the top of a
* configuration reference that opens on `upstreams`.
*/
const TOPIC_PATH: Record<DocTopic, string> = {
configuration: 'configuration',
federation: 'federation',
policy: 'policy',
auth: 'auth',
observability: 'observability',
tenancy: 'tenancy',
discovery: 'discovery',
configuration: 'configuration/',
upstreams: 'configuration/#upstreams-required',
policy: 'configuration/#policy',
auth: 'configuration/#auth-gateway-authentication',
observability: 'operations/',
tenancy: 'tenancy/',
discovery: 'discovery/',
}

export function docsLink(topic: DocTopic, gatewayVersion?: string): string {
return `${DOCS_ROOT}/${minorLine(gatewayVersion)}/${TOPIC_PATH[topic]}/`
/** Every URL this module can produce, for the link check to walk. */
export const DOC_TOPICS = Object.keys(TOPIC_PATH) as DocTopic[]

export function docsLink(topic: DocTopic): string {
return `${DOCS_ROOT}/${TOPIC_PATH[topic]}`
}
6 changes: 0 additions & 6 deletions src/lib/version.ts
Original file line number Diff line number Diff line change
Expand Up @@ -76,12 +76,6 @@ export function skewWarning(gatewayVersion: string | undefined): string | null {
)
}

/** "1.9.3" → "1.9" — the docs are published per minor line. */
export function minorLine(version: string | undefined): string {
const p = parse(version)
return p ? `${p[0]}.${p[1]}` : 'latest'
}

/** Display form: releases get a leading v, "dev" is left alone. */
export function displayVersion(version: string | undefined): string {
if (!version) return ''
Expand Down
8 changes: 4 additions & 4 deletions src/routes/overview.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ function Overview() {
<PageHeader
title="Overview"
lede="The gateway's own view of its configuration and federation."
actions={<DocsLink topic="configuration" version={state.version}>Configuration</DocsLink>}
actions={<DocsLink topic="configuration">Configuration</DocsLink>}
/>

<Attention state={state} />
Expand Down Expand Up @@ -107,7 +107,7 @@ function Overview() {
<CardGroup
title="Governance"
action={
<DocsLink topic="policy" version={state.version}>Policy docs</DocsLink>
<DocsLink topic="policy">Policy docs</DocsLink>
}
>
<Card
Expand Down Expand Up @@ -152,7 +152,7 @@ function Overview() {
<CardGroup
title="Observability"
action={
<DocsLink topic="observability" version={state.version}>Observability docs</DocsLink>
<DocsLink topic="observability">Observability docs</DocsLink>
}
>
<Card
Expand All @@ -167,7 +167,7 @@ function Overview() {
<CardGroup
title="Discovery"
action={
<DocsLink topic="discovery" version={state.version}>Discovery docs</DocsLink>
<DocsLink topic="discovery">Discovery docs</DocsLink>
}
>
<Card label="source" value={state.discovery.url} wrap />
Expand Down
2 changes: 1 addition & 1 deletion src/routes/upstreams.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ function Upstreams() {
<PageHeader
title="Upstreams"
lede="Every MCP server this gateway federates, as the gateway last saw it."
actions={<DocsLink topic="federation" version={state?.version}>Federation docs</DocsLink>}
actions={<DocsLink topic="upstreams">Upstream config</DocsLink>}
>
<div class="filters">
<Segmented
Expand Down
45 changes: 45 additions & 0 deletions tests/docs-links.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
// Every documentation URL this console can emit, fetched.
//
// The links used to carry a version segment — `docs.fold.run/1.10/…` — on the
// reasoning that the docs an operator opens from a running gateway should be
// the docs for that gateway. fold's documentation is a single unversioned
// site, so all of them 404'd, and three of the topic slugs did not exist under
// any prefix either.
//
// Nothing in the repo could have noticed. They are external navigations: the
// CSP never sees them, no unit test renders an href it does not itself supply,
// and a plausible-looking URL reads as correct until somebody clicks it. The
// only check with any power here is the one that asks the internet.
//
// It lives in the contract config rather than the e2e suite for the same
// reason the gateway contract does: it reaches the network, and a docs outage
// should not redden a pull request about a component. It runs on pull
// requests and on the Monday schedule.
import { expect, test } from '@playwright/test'
import { DOC_TOPICS, docsLink } from '../src/lib/docs'

test.describe('documentation links', () => {
for (const topic of DOC_TOPICS) {
test(`${topic} points at a page that exists`, async ({ request }) => {
const url = docsLink(topic)
const res = await request.get(url, { maxRedirects: 5 })
expect(res.status(), `${url} should exist`).toBe(200)
})
}

test('anchors point at headings that exist', async ({ request }) => {
// A wrong anchor does not 404 — it silently lands at the top of the page,
// which is the failure mode that looks like success. Fetch the document
// and look for the id.
const anchored = DOC_TOPICS.map((t) => [t, docsLink(t)] as const).filter(([, url]) =>
url.includes('#'),
)
expect(anchored.length, 'the anchored topics should still be anchored').toBeGreaterThan(0)

for (const [topic, url] of anchored) {
const [page, id] = url.split('#')
const html = await (await request.get(page!)).text()
expect(html, `${topic}: ${page} has no id="${id}"`).toContain(`id="${id}"`)
}
})
})
Loading