jamdesk 1.1.75 → 1.1.77

package/vendored/lib/middleware-helpers.ts

@@ -58,8 +58,23 @@ export interface ProjectResolutionResult {
    * (i.e., a user's own domain pointing at our CNAME), vs via the
    * subdomain branch (slug.jamdesk.app). Used by the branded inactive
    * page to show owner-sign-in hints only to real customers.
+   *
+   * Renamed from `customDomain` to disambiguate from the new
+   * `customDomain?: string` mirror below (which carries the public
+   * canonical hostname read from `projectCfg`). The two fields answer
+   * different questions:
+   *   - `viaCustomDomain` = "did this request hit the domain: Redis key?"
+   *   - `customDomain`    = "what is the project's registered public face?"
    */
-  customDomain?: boolean;
+  viaCustomDomain?: boolean;
+  /**
+   * Public canonical hostname for this slug, mirrored from `projectCfg`.
+   * Set only when the project owner has registered + activated a custom
+   * domain. Used by the proxy to override the canonical URL when serving
+   * a hostAtDocs project directly via *.jamdesk.app (avoiding duplicate-
+   * URL indexing — the upstream subdomain is not the public face).
+   */
+  customDomain?: string;
 }
 
 /**
@@ -124,7 +139,11 @@ export async function handleProjectResolution(
       slug,
     });
     const config = await getProjectConfig(slug);
-    return { projectSlug: slug, hostAtDocs: config.hostAtDocs };
+    return {
+      projectSlug: slug,
+      hostAtDocs: config.hostAtDocs,
+      customDomain: config.customDomain,
+    };
   }
 
   log('info', 'Resolving project from hostname', { hostname });
@@ -166,8 +185,18 @@ export async function handleProjectResolution(
         getProjectConfig(projectSlug),
         getProjectInactive(projectSlug),
       ]);
-      log('info', 'Project resolved from subdomain', { hostname, projectSlug, inactive });
-      return { projectSlug, hostAtDocs: config.hostAtDocs, inactive };
+      log('info', 'Project resolved from subdomain', {
+        hostname,
+        projectSlug,
+        inactive,
+        customDomain: config.customDomain,
+      });
+      return {
+        projectSlug,
+        hostAtDocs: config.hostAtDocs,
+        inactive,
+        customDomain: config.customDomain,
+      };
     }
   }
 
@@ -204,7 +233,7 @@ export async function handleProjectResolution(
     hostAtDocs: resolution.hostAtDocs,
     domainStatus: resolution.domainStatus,
     inactive,
-    customDomain: true,
+    viaCustomDomain: true,
   };
 }
 
@@ -596,15 +625,48 @@ const TRUSTED_PROXY_HEADERS = [
   'x-jd-custom-domain',
   'x-jd-project-name',
   'x-jd-project-logo',
+  // Canonical override: middleware writes this when serving *.jamdesk.app
+  // directly for a hostAtDocs project that has a registered custom
+  // domain. The page render path uses it to emit the public-face canonical
+  // instead of the upstream subdomain URL.
+  'x-jd-canonical-host',
+  // Set when *.jamdesk.app serves a hostAtDocs project that has NOT
+  // registered a custom domain yet — page emits robots: noindex so the
+  // upstream URL doesn't compete with the (yet-to-arrive) public face
+  // in search results.
+  'x-jd-noindex',
 ] as const;
 
+/**
+ * Optional extras for `buildProjectHeaders`. All fields are middleware-
+ * authored; the corresponding header is in `TRUSTED_PROXY_HEADERS` so an
+ * inbound spoof is stripped before we set our own value.
+ */
+export interface BuildProjectHeadersOptions {
+  /**
+   * Public-face canonical host. Set when serving *.jamdesk.app directly
+   * for a hostAtDocs project that has a registered custom domain — the
+   * page render path emits this host in <link rel="canonical"> instead
+   * of the upstream subdomain.
+   */
+  canonicalHost?: string;
+  /**
+   * When true, emit `x-jd-noindex: true` so the page emits a robots
+   * noindex tag. Used for *.jamdesk.app subdomains of hostAtDocs
+   * projects without a custom domain yet.
+   */
+  noindex?: boolean;
+}
+
 /**
  * Build response headers with project context.
  *
  * Sets:
- *   - x-project-slug   — resolved project for downstream handlers
- *   - x-host-at-docs   — whether docs are mounted at /docs
- *   - x-jd-language    — locale code if the path starts with one (e.g. /fr/...)
+ *   - x-project-slug       — resolved project for downstream handlers
+ *   - x-host-at-docs       — whether docs are mounted at /docs
+ *   - x-jd-language        — locale code if the path starts with one (e.g. /fr/...)
+ *   - x-jd-canonical-host  — public-face host (opts.canonicalHost)
+ *   - x-jd-noindex         — "true" when opts.noindex is set
  *
  * Strips any client-supplied copies of those headers from the inbound
  * request to prevent header smuggling.
@@ -615,6 +677,7 @@ const TRUSTED_PROXY_HEADERS = [
  * @param pathname - The request pathname (request.nextUrl.pathname or, for
  *   the unlock direct-hit branch, the `from` query param). Used to derive
  *   the active locale so the root layout can emit <html lang>.
+ * @param opts - Optional extras (canonical host override, noindex flag).
  * @returns New headers with project context added
  */
 export function buildProjectHeaders(
@@ -622,6 +685,7 @@ export function buildProjectHeaders(
   existingHeaders: Headers,
   hostAtDocs: boolean,
   pathname: string,
+  opts: BuildProjectHeadersOptions = {},
 ): Headers {
   const newHeaders = new Headers(existingHeaders);
   for (const h of TRUSTED_PROXY_HEADERS) {
@@ -636,6 +700,13 @@ export function buildProjectHeaders(
     newHeaders.set('x-jd-language', language);
   }
 
+  if (opts.canonicalHost) {
+    newHeaders.set('x-jd-canonical-host', opts.canonicalHost);
+  }
+  if (opts.noindex) {
+    newHeaders.set('x-jd-noindex', 'true');
+  }
+
   return newHeaders;
 }
 

package/vendored/lib/page-isr-helpers.ts

@@ -130,15 +130,20 @@ export function parseCacheKey(cacheKey: string): { projectSlug: string; pagePath
 /**
  * Get base URL for SEO metadata in ISR mode.
  *
- * Derives the canonical base URL from request headers.
- * Prefers x-jamdesk-forwarded-host (set by Cloudflare Worker proxy) over the
- * host header, so that canonical URLs point to the user-facing domain
- * (e.g., jamdesk.com) rather than the ISR subdomain (jamdesk-docs.jamdesk.app).
+ * Header priority (highest first):
+ *   1. x-jd-canonical-host  — internal override set by middleware when a
+ *      hostAtDocs project is served directly via *.jamdesk.app and has a
+ *      registered customDomain. Forces the canonical to the public face.
+ *   2. x-jamdesk-forwarded-host — set by the Cloudflare Worker proxy
+ *      (e.g. jamdesk.com → forwarded `jamdesk.com`).
+ *   3. host header — direct request hostname.
+ *   4. Subdomain fallback `<slug>.jamdesk.app` (no headers available).
  *
- * Security: The forwarded host header is validated by middleware
- * (validateForwardedHost in middleware-helpers.ts) before the page component runs.
+ * Both override headers are in TRUSTED_PROXY_HEADERS so a client can't
+ * spoof them.
  *
- * When hostAtDocs=true, includes /docs path prefix to match the actual URL structure.
+ * When hostAtDocs=true, includes /docs path prefix (forwarded-host and
+ * canonical-host paths only; subdomain fallback always serves at root).
  *
  * @param headers - Request headers object
  * @param projectSlug - Project identifier (fallback for subdomain URL)
@@ -146,9 +151,9 @@ export function parseCacheKey(cacheKey: string): { projectSlug: string; pagePath
  * @returns Base URL (e.g., 'https://jamdesk.com/docs' or 'https://acme.jamdesk.app')
  */
 export function getBaseUrl(headers: Headers, projectSlug: string, hostAtDocs = false): string {
-  // Prefer forwarded host (from Cloudflare Worker proxy) for correct canonical URLs
+  const canonicalHost = headers.get('x-jd-canonical-host');
   const forwardedHost = headers.get('x-jamdesk-forwarded-host');
-  const host = forwardedHost || headers.get('host');
+  const host = canonicalHost || forwardedHost || headers.get('host');
 
   if (host) {
     const hostname = host.split(':')[0];

package/vendored/lib/prefetch-batcher.ts

@@ -0,0 +1,51 @@
+/**
+ * Client-side prefetch batcher for sidebar links.
+ *
+ * Fires up to PARALLEL_LIMIT prefetches in parallel synchronously. The
+ * caller is expected to gate calls on "the user's current navigation
+ * has settled" so the batch never races the click that triggered it.
+ *
+ * `seen` is module-lifetime (cleared only on hard navigation/reload).
+ * For a 5,000-page docs site this is ~5,000 short strings ≈ tens of KB.
+ *
+ * In-flight fetches are not cancellable. The bound is the safety story:
+ * at most PARALLEL_LIMIT orphaned fetches outlive a re-click.
+ */
+
+export const PARALLEL_LIMIT = 5;
+
+const seen = new Set<string>();
+
+function safeInvoke(cb: (href: string) => void, href: string): void {
+  try {
+    cb(href);
+  } catch (err) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('[prefetch-batcher] callback threw for', href, err);
+    }
+  }
+}
+
+export const prefetchBatcher = {
+  fire(items: string[], cb: (href: string) => void, limit = PARALLEL_LIMIT): void {
+    // SSR guard: module resolves on the server during initial render of
+    // client components. seen would leak across requests.
+    if (typeof window === 'undefined') return;
+    if (items.length === 0) return;
+
+    const batch = items.slice(0, limit);
+    // Mark seen BEFORE invoking — a thrown callback retires the href
+    // permanently. Intentional: a route that throws once likely throws
+    // again, and prefetches are best-effort. Hard reload clears `seen`.
+    for (const href of batch) seen.add(href);
+    for (const href of batch) safeInvoke(cb, href);
+  },
+
+  hasSeen(href: string): boolean {
+    return seen.has(href);
+  },
+
+  resetForTesting(): void {
+    seen.clear();
+  },
+};

package/vendored/lib/prefetch-rsc.ts

@@ -0,0 +1,19 @@
+// Issues an RSC GET (without `Next-Router-Prefetch`) so the route's full
+// server render runs and the regional Vercel Data Cache is populated.
+
+export function prefetchRsc(href: string): void {
+  if (typeof window === 'undefined') return;
+  const sep = href.includes('?') ? '&' : '?';
+  const url = `${href}${sep}_rsc=${Date.now().toString(36)}`;
+  fetch(url, {
+    method: 'GET',
+    headers: { RSC: '1', Accept: 'text/x-component' },
+    cache: 'no-store',
+    credentials: 'same-origin',
+    priority: 'low',
+  })
+    // Consume the body so the response buffer is released. Letting it
+    // sit unread holds ~100KB per paced fetch in memory until GC.
+    .then((r) => r.arrayBuffer())
+    .catch(() => {});
+}

package/vendored/lib/project-resolver.ts

@@ -97,6 +97,17 @@ export async function resolveCustomDomain(hostname: string): Promise<DomainResol
   }
 }
 
+/**
+ * Resolved project configuration mirrored from Redis `projectCfg:<slug>`.
+ *
+ * `customDomain` is set on activation by the domain.ts helper when a custom
+ * domain is TXT-verified. Used by middleware to emit canonical-host headers.
+ */
+export interface ProjectCfg {
+  hostAtDocs: boolean;
+  customDomain?: string;
+}
+
 /**
  * Get project configuration for a subdomain (silent-fallback variant).
  * Used for hostAtDocs setting on *.jamdesk.app domains.
@@ -111,7 +122,7 @@ export async function resolveCustomDomain(hostname: string): Promise<DomainResol
  * would memoize a wrong `false` for the cache TTL, the exact failure
  * mode that produced the jamdesk.com/docs/* 404 incident.
  */
-export async function getProjectConfig(projectSlug: string): Promise<{ hostAtDocs: boolean }> {
+export async function getProjectConfig(projectSlug: string): Promise<ProjectCfg> {
   if (!redis) {
     return { hostAtDocs: false };
   }
@@ -119,8 +130,10 @@ export async function getProjectConfig(projectSlug: string): Promise<{ hostAtDoc
   try {
     const cfgRaw = await redis.get(`projectCfg:${projectSlug}`);
     const cfg = parseRedisConfig(cfgRaw);
-    // Default to false (root path) for subdomains unless explicitly set to true
-    return { hostAtDocs: cfg?.hostAtDocs === true };
+    return {
+      hostAtDocs: cfg?.hostAtDocs === true,
+      customDomain: typeof cfg?.customDomain === 'string' ? cfg.customDomain : undefined,
+    };
   } catch {
     return { hostAtDocs: false };
   }
@@ -136,14 +149,17 @@ export async function getProjectConfig(projectSlug: string): Promise<{ hostAtDoc
  * A missing `projectCfg:<slug>` key is NOT an error — that's the legitimate
  * "project hasn't opted into hostAtDocs" case and is safe to cache.
  */
-export async function getProjectConfigStrict(projectSlug: string): Promise<{ hostAtDocs: boolean }> {
+export async function getProjectConfigStrict(projectSlug: string): Promise<ProjectCfg> {
   if (!redis) {
     return { hostAtDocs: false };
   }
 
   const cfgRaw = await redis.get(`projectCfg:${projectSlug}`);
   const cfg = parseRedisConfig(cfgRaw);
-  return { hostAtDocs: cfg?.hostAtDocs === true };
+  return {
+    hostAtDocs: cfg?.hostAtDocs === true,
+    customDomain: typeof cfg?.customDomain === 'string' ? cfg.customDomain : undefined,
+  };
 }
 
 /**

package/vendored/lib/r2-content.ts

@@ -61,3 +61,19 @@ export async function fetchStaticFile(_projectSlug: string, _filename: string):
 export async function fetchCustomCss(_projectSlug: string): Promise<string | null> { return null; }
 export async function fetchCustomJs(_projectSlug: string): Promise<string | null> { return null; }
 export function setR2Client(_client: unknown): void {}
+
+// Stubs for the perf observability + race-fetch additions. CLI dev mode
+// reads from the filesystem so these all no-op.
+export const R2_CLIENT_CONFIG = {} as Record<string, unknown>;
+export const R2_OPENAPI_CLIENT_CONFIG = {} as Record<string, unknown>;
+export type R2TimingPhase =
+  | 'layout-metadata'
+  | 'layout-render'
+  | 'page-metadata'
+  | 'page-render';
+export function incrementR2Op(_ms: number): void {}
+export function getR2OpsSnapshot(): { ops: number; ms: number } { return { ops: 0, ms: 0 }; }
+export function withR2OpsContext<T>(fn: () => T): T { return fn(); }
+export function enterR2OpsContextForTest<T>(fn: () => T): T { return fn(); }
+export function emitR2OpsSummary(_phase: R2TimingPhase, _projectSlug?: string | null): void {}
+export async function withTimeout<T>(promise: Promise<T>, _operation: string): Promise<T> { return promise; }

package/vendored/lib/r2-feature-flags.ts

@@ -0,0 +1,7 @@
+// `?.trim()` is defensive against trailing whitespace in Vercel UI / CLI
+// stdin — see ISR_MODE incident in builder/CLAUDE.md. Function (not const)
+// so tests can flip the env var via `vi.stubEnv` without a module reset,
+// matching the existing `isIsrMode()` pattern in page-isr-helpers.ts.
+export function isR2ParallelCounterEnabled(): boolean {
+  return process.env.R2_PARALLEL_COUNTER?.trim() === 'true';
+}

package/vendored/lib/render-doc-page-openapi-helpers.ts

@@ -0,0 +1,110 @@
+// Try OpenAPI spec candidates concurrently and return the first by INDEX
+// (not by resolution order) whose parse succeeds. Multilingual docs sites
+// (e.g. 10 languages × 3 spec extensions = 30 candidates) previously paid
+// up to 30 sequential R2 RTTs on a cache miss. We fire all candidate
+// fetches at once but await them in index order, so latency on the common
+// case (primary succeeds) is bounded by the primary fetch — not by the
+// slowest of all candidates as it would be with Promise.allSettled.
+import type { OpenApiEndpointData, parseEndpoint } from '@/lib/openapi';
+
+type TryCandidate<T> = (specPath: string) => Promise<{ endpoint: T; specPath: string }>;
+
+export type CandidateResult<T> =
+  | { kind: 'success'; endpoint: T; specPath: string }
+  | { kind: 'failure'; lastError: unknown; specPath: string };
+
+type Settled<T> =
+  | { ok: true; endpoint: T; specPath: string }
+  | { ok: false; error: unknown };
+
+export async function tryOpenApiCandidatesInParallel<T = OpenApiEndpointData>(
+  candidates: string[],
+  tryCandidate: TryCandidate<T>,
+): Promise<CandidateResult<T>> {
+  if (candidates.length === 0) {
+    return { kind: 'failure', lastError: new Error('no candidates'), specPath: '' };
+  }
+
+  // Eager catch handlers prevent unhandled-rejection logs when a slow loser
+  // rejects after the primary has already won. Loser GETs continue running
+  // in the background until R2 responds; `maxAttempts: 1` on the OpenAPI
+  // client bounds them to one round-trip each.
+  const inflight: Promise<Settled<T>>[] = candidates.map((c) =>
+    tryCandidate(c).then(
+      ({ endpoint, specPath }) => ({ ok: true as const, endpoint, specPath }),
+      (error: unknown) => ({ ok: false as const, error }),
+    ),
+  );
+
+  // On all-reject, surface the primary candidate's error so logs are
+  // attributed to the intended spec — fallback errors are typically "404".
+  let primaryError: unknown | undefined;
+  for (let i = 0; i < inflight.length; i++) {
+    const r = await inflight[i];
+    if (r.ok) {
+      return { kind: 'success', endpoint: r.endpoint, specPath: r.specPath };
+    }
+    if (primaryError === undefined) primaryError = r.error;
+  }
+
+  return {
+    kind: 'failure',
+    lastError: primaryError ?? new Error('unknown'),
+    specPath: candidates[0],
+  };
+}
+
+interface TryOpenApiSpecOpts {
+  projectSlug: string | null;
+  isIsr: boolean;
+  parsedMethod: string;
+  parsedPath: string;
+  resolveIsrSpec: ((slug: string, specPath: string) => Promise<unknown>) | null;
+  getStaticSpec: ((specPath: string, contentDir: string) => Promise<{ api: unknown }>) | null;
+  contentDir: string | null;
+  parseEndpointFn: typeof parseEndpoint;
+}
+
+export function makeTryOpenApiSpec(opts: TryOpenApiSpecOpts) {
+  return async (specPath: string): Promise<{ endpoint: OpenApiEndpointData; specPath: string }> => {
+    const useIsr = opts.isIsr && !!opts.projectSlug && !!opts.resolveIsrSpec;
+    if (useIsr && opts.resolveIsrSpec && opts.projectSlug) {
+      const spec = await opts.resolveIsrSpec(opts.projectSlug, specPath);
+      const endpoint = opts.parseEndpointFn(
+        spec as Parameters<typeof parseEndpoint>[0],
+        opts.parsedMethod as never,
+        opts.parsedPath,
+        specPath,
+      );
+      return { endpoint, specPath };
+    }
+    if (!opts.getStaticSpec || !opts.contentDir) {
+      throw new Error('static spec branch requires getStaticSpec + contentDir');
+    }
+    const { api } = await opts.getStaticSpec(specPath, opts.contentDir);
+    const endpoint = opts.parseEndpointFn(
+      api as Parameters<typeof parseEndpoint>[0],
+      opts.parsedMethod as never,
+      opts.parsedPath,
+      specPath,
+    );
+    return { endpoint, specPath };
+  };
+}
+
+// Aggregated on-call signal for misconfigured projects: replaces the
+// per-failure spam log from the old sequential for-loop. Returns null
+// when there's no fallback (single candidate, or primary won). Format
+// is grep-stable — on-call dashboards key off the "[openapi] primary spec"
+// prefix and the "resolved via fallback" delimiter.
+export function formatFallbackWarning(
+  candidates: string[],
+  winnerSpecPath: string,
+  method: string,
+  path: string,
+): string | null {
+  if (candidates.length <= 1) return null;
+  const primary = candidates[0];
+  if (winnerSpecPath === primary) return null;
+  return `[openapi] primary spec "${primary}" did not contain ${method} ${path}; resolved via fallback "${winnerSpecPath}"`;
+}

package/vendored/lib/render-doc-page-parallel-helpers.ts

@@ -0,0 +1,60 @@
+// Snippets (R2 I/O) and inline-component extraction (Babel/remark CPU)
+// have no data dependency once raw + preprocessed MDX are available, so
+// they run as Promise.all. The JS event loop interleaves Babel work with
+// R2 await microtasks, giving wall-clock = max(R2, CPU) instead of sum.
+import type React from 'react';
+import type { ExtractedParam } from './remark-extract-param-fields';
+
+// AnyComponent matches the project-wide convention used in
+// process-mdx-with-exports.ts and snippet-loader-isr.ts. ComponentType<unknown>
+// is too strict — MDXComponents includes typed React components like
+// MemoExoticComponent<({ title }: CardProps) => JSX.Element>, which are NOT
+// assignable to ComponentType<unknown> (props variance).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyComponent = React.ComponentType<any>;
+
+interface ParallelInput {
+  isIsr: boolean;
+  projectSlug: string | null;
+  rawContent: string;
+  preprocessedContent: string;
+  mdxComponents: Record<string, AnyComponent>;
+  snippetComponents: Record<string, AnyComponent>;
+  loadSnippets: (
+    projectSlug: string,
+    rawContent: string,
+    builtIns: Record<string, AnyComponent>,
+  ) => Promise<Record<string, AnyComponent>>;
+  buildAlias: (
+    rawContent: string,
+    snippetComponents: Record<string, AnyComponent>,
+  ) => Record<string, AnyComponent>;
+  extractInline: (
+    content: string,
+    components: Record<string, AnyComponent>,
+  ) => Promise<{ inlineComponents: Record<string, AnyComponent>; paramFields: ExtractedParam[] }>;
+}
+
+interface ParallelOutput {
+  snippetAliases: Record<string, AnyComponent>;
+  inlineComponents: Record<string, AnyComponent>;
+  paramFields: ExtractedParam[];
+}
+
+export async function loadSnippetsAndInlineComponents(
+  input: ParallelInput,
+): Promise<ParallelOutput> {
+  const snippetsP = input.isIsr && input.projectSlug
+    ? input.loadSnippets(input.projectSlug, input.rawContent, input.mdxComponents)
+    : Promise.resolve(input.buildAlias(input.rawContent, input.snippetComponents));
+
+  const inlineP = input.extractInline(input.preprocessedContent, input.mdxComponents);
+
+  const [snippetAliases, inline] = await Promise.all([snippetsP, inlineP]);
+
+  return {
+    snippetAliases,
+    inlineComponents: inline.inlineComponents,
+    paramFields: inline.paramFields,
+  };
+}