An open source design system that's fully customizable and agent ready
TypeScript
docsite: read the docs-prompt origins from build configuration (#9397)
Cindy Zhanga64fd1ea8517
diff --git a/.github/scripts/ci-docsite-browser.test.mjs b/.github/scripts/ci-docsite-browser.test.mjsindex 8f2fe75b84..c9912cff43 100644--- a/.github/scripts/ci-docsite-browser.test.mjs+++ b/.github/scripts/ci-docsite-browser.test.mjs@@ -80,6 +80,21 @@ describe('docsite-test', () => {);});+ it('builds and tests the docs prompt with placeholder origins only', () => {+ // One job-level value reaches the build and the browser contracts alike.+ expect(owner.env).toEqual({+ NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN: 'https://docs.example.test',+ NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN: 'https://probe.example.test',+ });+ for (const s of owner.steps) {+ expect(s.env?.NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN, s.name).toBeUndefined();+ expect(+ s.env?.NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN,+ s.name,+ ).toBeUndefined();+ }+ });+it.each([0, 1])('the start step records exit %i from the data tests under bash -e',async code => {diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex b89a74e261..941242d496 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -544,6 +544,12 @@ jobs:permissions:contents: readpull-requests: read+ # Placeholder docs-prompt origins: the build and its browser contracts+ # exercise the configured prompt. Deployed values live only in the+ # deployment environment, never in this repository.+ env:+ NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN: https://docs.example.test+ NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN: https://probe.example.teststeps:- name: Require a branch in this repository or the ci:run labelif: ${{ github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')) }}diff --git a/apps/docsite/e2e/internal-docs-prompt.spec.ts b/apps/docsite/e2e/internal-docs-prompt.spec.tsindex 48c24010bd..3692909b5c 100644--- a/apps/docsite/e2e/internal-docs-prompt.spec.ts+++ b/apps/docsite/e2e/internal-docs-prompt.spec.ts@@ -1,7 +1,8 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @input A production docsite build and exact-origin reachability fixtures+ * @input A production docsite build configured with the docs and probe origins,+ * and exact-origin reachability fixtures* @output Browser evidence of unified banner CTAs and page-view-only dismissal* @position Docsite integration tests; run against both latest and canary builds*/@@ -19,11 +20,26 @@ const deployments = [];const isCanary = process.env.DOCSITE_TEST_TARGET !== 'latest';const target = isCanary ? 'canary' : 'latest';-const internalOrigin = 'https://astryx.internalmeta.com';-const probeOrigin = 'https://codebunny.internalmeta.com';+// The build under test must be configured with these origins (CI builds with+// placeholder values); the probe and the destination are both routed below.+const internalOrigin = process.env.NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN ?? '';+const probeOrigin = process.env.NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN ?? '';+const isConfigured = internalOrigin !== '' && probeOrigin !== '';const noticeName = 'Documentation notice';const dismissName = 'Dismiss documentation notice for this page view';+// CI must always run these contracts; a local build without the origins+// disables the prompt, so there is nothing to check.+if (!isConfigured && (process.env.CI ?? '') !== '') {+ throw new Error(+ 'Set NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN for both the docsite build and this run',+ );+}+test.skip(+ !isConfigured,+ 'Build and run with NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN set',+);+test.afterEach(async ({page}) => {await page.waitForLoadState('networkidle');});diff --git a/apps/docsite/playwright.config.ts b/apps/docsite/playwright.config.tsindex b458d9524b..b60800f82f 100644--- a/apps/docsite/playwright.config.ts+++ b/apps/docsite/playwright.config.ts@@ -22,6 +22,10 @@* Outside CI an already-running `next start` on the port is reused, so a* server started by hand works too.*+ * The docs-prompt spec needs NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and+ * NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN set for both the build and the run (CI+ * uses placeholder origins); without them it skips locally and fails in CI.+ ** SYNC: When the docsite gains another browser-only contract, add its spec* under e2e/.*/diff --git a/apps/docsite/src/__tests__/internal-docs-prompt.test.tsx b/apps/docsite/src/__tests__/internal-docs-prompt.test.tsxindex a6f8f2c72d..4c0f47f4bc 100644--- a/apps/docsite/src/__tests__/internal-docs-prompt.test.tsx+++ b/apps/docsite/src/__tests__/internal-docs-prompt.test.tsx@@ -42,14 +42,16 @@ declare const jsdom: {reconfigure(options: {url: string}): void};let Prompt: typeof InternalDocsPrompt;let href: typeof internalDocsHref;-const internalOrigin = 'https://astryx.internalmeta.com';-const probeOrigin = 'https://codebunny.internalmeta.com';+const internalOrigin = 'https://docs.example.test';+const probeOrigin = 'https://probe.example.test';const message = {type: 'codebunny:access-check:v1', reachable: true};beforeEach(async () => {vi.resetModules();vi.useFakeTimers();vi.stubEnv('NEXT_PUBLIC_DOCS_TARGET', 'latest');+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', internalOrigin);+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', probeOrigin);jsdom.reconfigure({url: 'https://astryx.atmeta.com/components/Button?tab=props',});@@ -127,6 +129,62 @@ describe('InternalDocsPrompt', () => {expect(layout).not.toContain('<InternalDocsPrompt');});+ it.each([+ ['neither origin', undefined, undefined],+ ['only the docs origin', internalOrigin, undefined],+ ['only the probe origin', undefined, probeOrigin],+ ['an empty docs origin', '', probeOrigin],+ ['a malformed probe origin', internalOrigin, 'not a url'],+ ['a non-https probe origin', internalOrigin, 'http://probe.example.test'],+ ])(+ 'never probes or renders with %s configured',+ async (_, docsOrigin, accessCheckOrigin) => {+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', docsOrigin);+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', accessCheckOrigin);+ await loadPrompt();+ const append = vi.spyOn(document.body, 'append');+ await mount();+ await act(async () => vi.advanceTimersByTime(5000));+ expect(append).not.toHaveBeenCalled();+ expect(document.querySelector('iframe')).toBeNull();+ expect(prompt()).toBeNull();+ if (!docsOrigin) {+ expect(href('/docs', 'a=1')).toBeUndefined();+ }+ },+ );++ it('keeps only the public Canary notice when the origins are not configured', async () => {+ vi.stubEnv('NEXT_PUBLIC_DOCS_TARGET', 'canary');+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', undefined);+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', undefined);+ await loadPrompt();+ await mount();+ await act(async () => vi.advanceTimersByTime(5000));+ expect(document.querySelector('iframe')).toBeNull();+ expect(prompt()?.textContent).toContain("You're viewing Canary docs");+ expect(prompt()?.outerHTML).not.toMatch(+ /Meta internal|Meta-specific components/,+ );+ });++ it('uses the exact configured origins, without a trailing path', async () => {+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', `${internalOrigin}/`);+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', ` ${probeOrigin}/x `);+ await loadPrompt();+ await mount();+ const target = frame();+ expect(target.src).toBe(+ `${probeOrigin}/embed/access-check?parent_origin=https%3A%2F%2Fastryx.atmeta.com`,+ );+ showPrompt();+ expect(+ screen+ .getByRole('link', {name: 'Meta internal docs'})+ .getAttribute('href'),+ ).toBe(`${internalOrigin}/components/Button?tab=props`);+ });+it('does not start another probe inside an embedded document', async () => {const parentFrame = document.createElement('iframe');document.body.append(parentFrame);@@ -227,9 +285,9 @@ describe('InternalDocsPrompt', () => {it.each(['https://evil.example',- 'https://codebunny.internalmeta.com.evil.example',- 'http://codebunny.internalmeta.com',- 'https://astryx.internalmeta.com',+ 'https://probe.example.test.evil.example',+ 'http://probe.example.test',+ 'https://docs.example.test','null',])('ignores messages from the wrong origin: %s', async origin => {await mount();diff --git a/apps/docsite/src/components/InternalDocsPrompt.tsx b/apps/docsite/src/components/InternalDocsPrompt.tsxindex 1b28b00666..e9a72f5d2b 100644--- a/apps/docsite/src/components/InternalDocsPrompt.tsx+++ b/apps/docsite/src/components/InternalDocsPrompt.tsx@@ -3,7 +3,8 @@'use client';/**- * @input Build target, exact-origin reachability, and the current docs view+ * @input Build target, configured docs origin, exact-origin reachability, and+ * the current docs view* @output The internal-docs banner after reachability, otherwise the public Canary banner* @position Root-owned detection; banner content lives in the page shell*/@@ -31,7 +32,13 @@ export function InternalDocsReachabilityProvider({);}-export function internalDocsHref(pathname: string, search: string): string {+export function internalDocsHref(+ pathname: string,+ search: string,+): string | undefined {+ if (!INTERNAL_DOCS_ORIGIN) {+ return undefined;+ }// Shared route families use the same topic/name/slug semantics. Public-only// pages (blog, community, changelog, preview) have no same-path counterpart.const hasCounterpart =diff --git a/apps/docsite/src/lib/useInternalDocsPrompt.ts b/apps/docsite/src/lib/useInternalDocsPrompt.tsindex 3064f1c5e7..88f27b3245 100644--- a/apps/docsite/src/lib/useInternalDocsPrompt.ts+++ b/apps/docsite/src/lib/useInternalDocsPrompt.ts@@ -3,9 +3,15 @@'use client';/**- * @input A top-level page and an anonymous iframe's exact-origin reachability message+ * @input Build-time docs and probe origins, a top-level page, and an anonymous+ * iframe's exact-origin reachability message* @output A fail-closed, once-per-page-load reachability result* @position Client-only detection shared across root-layout remounts+ *+ * Both origins are deployment configuration, read from+ * NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN at+ * build time. A build without both (every fork and local build by default)+ * never probes and never shows the prompt.*/import {useSyncExternalStore} from 'react';@@ -15,8 +21,33 @@ export const ALLOWED_PARENT_ORIGINS: readonly string[] = ['https://astryx-git-feat-docs-internal-network-prompt-fbopensource.vercel.app','https://astryx-canary.vercel.app',];-export const INTERNAL_DOCS_ORIGIN = 'https://astryx.internalmeta.com';-export const ACCESS_CHECK_ORIGIN = 'https://codebunny.internalmeta.com';++/**+ * The exact origin of a configured absolute https URL, or undefined when the+ * value is missing, malformed, or not https: a bad value disables the prompt+ * rather than probing or linking somewhere unintended.+ */+export function configuredOrigin(+ value: string | undefined,+): string | undefined {+ if (!value?.trim()) {+ return undefined;+ }+ try {+ const url = new URL(value.trim());+ return url.protocol === 'https:' ? url.origin : undefined;+ } catch {+ return undefined;+ }+}++// Each variable is read by its literal name so the build inlines it.+export const INTERNAL_DOCS_ORIGIN = configuredOrigin(+ process.env.NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN,+);+export const ACCESS_CHECK_ORIGIN = configuredOrigin(+ process.env.NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN,+);export const ACCESS_CHECK_MESSAGE_TYPE = 'codebunny:access-check:v1';const listeners = new Set<() => void>();@@ -34,6 +65,12 @@ function publishReachability(next: boolean) {function startCheck() {attempted = true;+ // Without both configured origins there is nothing to probe or link to.+ const accessCheckOrigin = ACCESS_CHECK_ORIGIN;+ if (!accessCheckOrigin || !INTERNAL_DOCS_ORIGIN) {+ return;+ }+// Embedded documents, including playground previews, must not probe again.if (window.top !== window) {return;@@ -53,7 +90,7 @@ function startCheck() {frame.setAttribute('sandbox', 'allow-scripts allow-same-origin');frame.title = 'Astryx documentation reachability check';frame.referrerPolicy = 'no-referrer';- frame.src = `${ACCESS_CHECK_ORIGIN}/embed/access-check?parent_origin=${encodeURIComponent(parentOrigin)}`;+ frame.src = `${accessCheckOrigin}/embed/access-check?parent_origin=${encodeURIComponent(parentOrigin)}`;let loaded = false;let received = false;@@ -73,7 +110,7 @@ function startCheck() {};const onMessage = (event: MessageEvent) => {if (- event.origin !== ACCESS_CHECK_ORIGIN ||+ event.origin !== accessCheckOrigin ||event.source !== frame.contentWindow ||event.data?.type !== ACCESS_CHECK_MESSAGE_TYPE ||event.data?.reachable !== true