Proxy /docs to Mintlify at the worker edge (#1035)

Serve executor.sh/docs from the Mintlify deployment
(executor.mintlify.dev) on the first-party origin instead of the
*.mintlify.dev subdomain, via a new docs reverse-proxy edge middleware.

Mirrors the existing PostHog/marketing edge proxies: path-gated on
`/docs`, runs before the app dispatch and the SSR auth gate (docs are
public, so they skip the sign-in redirect), forwards the path/query
unchanged to the upstream, sets X-Forwarded-Host/-Proto so Mintlify can
build canonical links, and strips the session cookie so it never reaches
the docs origin. `/docs` is disjoint from the app-owned `/api/docs`
(Swagger), so it never shadows an Effect-served route.

Author: RhysSullivan

apps/cloud/src/edge/docs.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { buildDocsUpstream, isDocsPath } from "./docs";
+
+// The docs proxy claims `/docs` and forwards it to Mintlify. Two things must
+// hold: the path matcher catches the docs tree without swallowing the app-owned
+// `/api/docs` (Swagger) or unrelated `/docs`-prefixed words, and the rewritten
+// upstream request points at Mintlify with the path preserved and the session
+// cookie stripped.
+describe("isDocsPath", () => {
+  const docs = ["/docs", "/docs/", "/docs/quickstart", "/docs/guides/auth"];
+  for (const pathname of docs) {
+    it(`proxies ${pathname} to Mintlify`, () => {
+      expect(isDocsPath(pathname)).toBe(true);
+    });
+  }
+
+  // `/api/docs` is the app-owned Swagger UI — it must reach the Effect handler,
+  // not Mintlify. `/docsmith` guards against a bare `startsWith("/docs")` that
+  // would capture unrelated words.
+  const notDocs = ["/api/docs", "/docsmith", "/", "/home", "/login", "/mcp"];
+  for (const pathname of notDocs) {
+    it(`leaves ${pathname} alone`, () => {
+      expect(isDocsPath(pathname)).toBe(false);
+    });
+  }
+});
+
+describe("buildDocsUpstream", () => {
+  const upstreamFor = (url: string, headers?: HeadersInit) =>
+    buildDocsUpstream(new Request(url, { headers }));
+
+  it("swaps the origin to Mintlify over https while preserving path + query", () => {
+    const upstream = new URL(upstreamFor("https://executor.sh/docs/guides/auth?theme=dark").url);
+    expect(upstream.hostname).toBe("executor.mintlify.dev");
+    expect(upstream.protocol).toBe("https:");
+    expect(upstream.pathname).toBe("/docs/guides/auth");
+    expect(upstream.search).toBe("?theme=dark");
+  });
+
+  it("forwards the public host so Mintlify can build canonical links", () => {
+    const upstream = upstreamFor("https://executor.sh/docs");
+    expect(upstream.headers.get("x-forwarded-host")).toBe("executor.sh");
+    expect(upstream.headers.get("x-forwarded-proto")).toBe("https");
+  });
+
+  it("strips the cookie so the session never leaks to the docs origin", () => {
+    const upstream = upstreamFor("https://executor.sh/docs", {
+      cookie: "wos-session=secret",
+    });
+    expect(upstream.headers.has("cookie")).toBe(false);
+  });
+});

apps/cloud/src/edge/docs.ts

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// Docs reverse proxy — `/docs` (and everything under it) is served by Mintlify,
+// not this worker. We forward those requests to the Mintlify deployment so the
+// docs live on the first-party origin (`executor.sh/docs`) instead of a
+// `*.mintlify.dev` subdomain. Mintlify hosts the site under the same `/docs`
+// base path, so the pathname is forwarded UNCHANGED — only the host/proto swap
+// to the upstream origin (unlike the PostHog proxy, which strips its prefix).
+//
+// Like the PostHog/Sentry tunnels (and unlike the marketing proxy, which needs
+// the prod-only `env.MARKETING` service binding), this is a plain external
+// `fetch`, so it runs on every host — `/docs` previews against live Mintlify in
+// local dev too. `/docs` is distinct from the app-owned `/api/docs` (Swagger),
+// so this never shadows an Effect-served route.
+// ---------------------------------------------------------------------------
+
+import { createMiddleware } from "@tanstack/react-start";
+
+const DOCS_UPSTREAM_HOST = "executor.mintlify.dev";
+
+export const isDocsPath = (pathname: string) =>
+  pathname === "/docs" || pathname.startsWith("/docs/");
+
+// Build the upstream request for an already-classified `/docs` path. Caller
+// guarantees `isDocsPath(pathname)` — we only swap the origin and fix up the
+// forwarding headers, preserving method, body, path, and query.
+export const buildDocsUpstream = (request: Request): Request => {
+  const url = new URL(request.url);
+  const forwardedHost = url.host;
+
+  url.hostname = DOCS_UPSTREAM_HOST;
+  url.protocol = "https:";
+  url.port = "";
+
+  const upstream = new Request(url, request);
+  // Mintlify keys canonical links off the public host; tell it the real one.
+  upstream.headers.set("X-Forwarded-Host", forwardedHost);
+  upstream.headers.set("X-Forwarded-Proto", "https");
+  // Never leak the executor.sh session cookie to the docs origin.
+  upstream.headers.delete("cookie");
+  return upstream;
+};
+
+export const docsProxyMiddleware = createMiddleware({ type: "request" }).server(
+  ({ pathname, request, next }) => {
+    if (!isDocsPath(pathname)) return next();
+    return fetch(buildDocsUpstream(request));
+  },
+);

apps/cloud/src/edge/index.ts

@@ -1,10 +1,11 @@
 // ---------------------------------------------------------------------------
-// Edge concerns — the analytics/marketing request middlewares that run at the
-// worker edge BEFORE the app's own mcp + api dispatch. None of these touch the
-// Effect app layer; they proxy or tunnel to external services (the marketing
-// worker, Sentry, PostHog).
+// Edge concerns — the analytics/marketing/docs request middlewares that run at
+// the worker edge BEFORE the app's own mcp + api dispatch. None of these touch
+// the Effect app layer; they proxy or tunnel to external services (the
+// marketing worker, Sentry, PostHog, Mintlify docs).
 // ---------------------------------------------------------------------------
 
 export { marketingMiddleware } from "./marketing";
 export { sentryTunnelMiddleware } from "./sentry-tunnel";
 export { posthogProxyMiddleware } from "./posthog";
+export { docsProxyMiddleware } from "./docs";

apps/cloud/src/start.ts

@@ -4,7 +4,12 @@ import { cloudApiHandler } from "./app";
 import { isAppOwnedPath } from "./app-paths";
 import { authGateMiddleware } from "./auth/ssr-gate";
 import { prepareMcpOrgScope } from "./mcp/mount";
-import { marketingMiddleware, posthogProxyMiddleware, sentryTunnelMiddleware } from "./edge";
+import {
+  docsProxyMiddleware,
+  marketingMiddleware,
+  posthogProxyMiddleware,
+  sentryTunnelMiddleware,
+} from "./edge";
 
 // ---------------------------------------------------------------------------
 // The unified app web handler — `ExecutorApp.make`'s `toWebHandler` (app.ts).
@@ -42,15 +47,20 @@ const appRequestMiddleware = createMiddleware({ type: "request" }).server(
   },
 );
 
-// The edge concerns (marketing proxy, sentry tunnel, posthog proxy) live in
-// `./edge`; they run before the app's own dispatch. Ordering is load-bearing:
-// marketing first (production landing/page proxy), then the analytics tunnels,
-// then the unified app plane (api + mcp), and last the SSR auth gate — it only
-// sees document requests nothing above claimed, so signed-out visitors are
-// redirected to /login before the SPA (and its app-shell skeleton) is served.
+// The edge concerns (marketing proxy, docs proxy, sentry tunnel, posthog proxy)
+// live in `./edge`; they run before the app's own dispatch. Ordering is
+// load-bearing: marketing first (production landing/page proxy), then the docs
+// proxy and analytics tunnels, then the unified app plane (api + mcp), and last
+// the SSR auth gate — it only sees document requests nothing above claimed, so
+// signed-out visitors are redirected to /login before the SPA (and its
+// app-shell skeleton) is served. The docs proxy sits among the edges (not after
+// the auth gate) because `/docs` is public and must skip the sign-in redirect;
+// its path is disjoint from every other matcher, so its slot is not otherwise
+// load-bearing.
 export const startInstance = createStart(() => ({
   requestMiddleware: [
     marketingMiddleware,
+    docsProxyMiddleware,
     sentryTunnelMiddleware,
     posthogProxyMiddleware,
     appRequestMiddleware,