History

Build cloud API docs lazily

Rhys Sullivan committed 1 month ago

Commit adcb26c1 parent 24adb125 files · +104 −144Browse files

Unified · Split

5 files
  1. apps/cloud/src/api.request-scope.node.test.ts +0 −43
  2. apps/cloud/src/api/router.ts +0 −56
  3. apps/cloud/src/extensions/docs.ts +0 −29
  4. apps/cloud/src/extensions/routes.ts +102 −13
  5. e2e/cloud/surface-reachability.test.ts +2 −3
apps/cloud/src/api.request-scope.node.test.ts+0−43
@@ -49,7 +49,6 @@ import { resetSubjectTouchCache } from "@executor-js/sdk/host-internal"; · 48 unmodified lines
4949 import { createSqliteTestFumaDb, type SqliteTestFumaDb } from "@executor-js/sdk/testing";
5050
5151 import { RequestScopedServicesLive } from "./api/layers";
52−import { makeApiLive } from "./api/router";
5352
5453 class Counter extends Context.Service<Counter, { readonly id: number }>()("test/Counter") {}
5554
@@ -175,48 +174,6 @@ describe("HttpRouter.toWebHandler request scoping", () => { · 119 unmodified lines
175174 });
176175 });
177176
178−// ---------------------------------------------------------------------------
179−// Regression test against the prod handler factory. If anyone reverts
180−// `makeApiLive` back to wiring `RequestScopedServicesLive` via
181−// `Layer.provideMerge`, this test fails — the counter only increments
182−// once at boot instead of once per request.
183−// ---------------------------------------------------------------------------
184−
185−describe("makeApiLive (prod handler factory) request scoping", () => {
186− it("rebuilds RequestScopedServicesLive per request", async () => {
187− const counts = { acquires: 0, releases: 0 };
188− // Wrap the real per-request layer with an `acquireRelease` counter.
189− // `requestScopedMiddleware` calls `Layer.build` per request, so this
190− // counter increments per request iff the wiring is correct.
191− const trackedRsLive = Layer.effectDiscard(
192− Effect.acquireRelease(
193− Effect.sync(() => {
194− counts.acquires += 1;
195− }),
196− () =>
197− Effect.sync(() => {
198− counts.releases += 1;
199− }),
200− ),
201− ).pipe(Layer.provideMerge(RequestScopedServicesLive));
202−
203− const handler = HttpRouter.toWebHandler(makeApiLive(trackedRsLive), {
204− disableLogger: true,
205− }).handler;
206−
207− // Hit a protected route. ExecutionStackMiddleware short-circuits with
208− // 403 (no session cookie) but not before `requestScopedMiddleware`
209− // has built the per-request layer. We don't care about the response —
210− // only that the layer was built once per request. `/integrations` is a
211− // v2 protected route (the old `/scope` group was removed).
212− await handler(new Request("http://test.local/integrations"), Context.empty());
213− await handler(new Request("http://test.local/integrations"), Context.empty());
214−
215− expect(counts.acquires).toBe(2);
216− expect(counts.releases).toBe(2);
217− });
218−});
219−
220177 // ---------------------------------------------------------------------------
221178 // `ExecutionStackMiddleware` request scoping.
222179 //
apps/cloud/src/api/router.ts+0−56
@@ -1,56 +0,0 @@
1−import { Layer } from "effect";
2−import { HttpRouter } from "effect/unstable/http";
3−
4−import {
5− RouterConfigLive,
6− requestScopedMiddleware,
7− type MemberDirectory,
8−} from "@executor-js/api/server";
9−
10−import { UserStoreService } from "../auth/context";
11−import { WorkOsMirror } from "../auth/workos-mirror";
12−import { DbService } from "../db/db";
13−import { makeAccountApiLive } from "../account/account-api";
14−
15−import { AutumnRoutesLive } from "../extensions/billing/route";
16−import { CloudDocsLive } from "../extensions/docs";
17−import { ApiErrorLoggingLive } from "../observability/error-logging";
18−import {
19− BootSharedServices,
20− RequestScopedServicesLive,
21− makeOrgApiLive,
22− makeNonProtectedApiLive,
23−} from "./layers";
24−import { makeProtectedApiLive } from "./protected";
25−
26−// One router. Each sub-API contributes its routes via `HttpApiBuilder.layer`,
27−// which calls `HttpRouter.use(...)` under the hood. Autumn's catch-all proxy
28−// is added as a plain `HttpRouter.add` route. They all merge into the same
29−// routing table; there is no outer-then-inner router stacking.
30−//
31−// The per-request `DbService` + `UserStoreService` wiring is threaded
32−// through each sub-API's factory. Boot-scoped services come in here via
33−// `Layer.provideMerge`. `requestScopedLive` is exposed as a parameter
34−// so tests can substitute a counting fake for `DbService.Live` and
35−// assert per-request semantics — see
36−// `apps/cloud/src/api.request-scope.node.test.ts`.
37−export const makeApiLive = (
38− requestScopedLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror | MemberDirectory>,
39−) => {
40− const BillingRoutesLive = AutumnRoutesLive.pipe(
41− Layer.provide(requestScopedMiddleware(requestScopedLive).layer),
42− );
43− return Layer.mergeAll(
44− makeNonProtectedApiLive(requestScopedLive),
45− makeOrgApiLive(requestScopedLive),
46− makeAccountApiLive(requestScopedLive),
47− CloudDocsLive,
48− makeProtectedApiLive(requestScopedLive),
49− BillingRoutesLive,
50− ApiErrorLoggingLive,
51− ).pipe(Layer.provideMerge(RouterConfigLive), Layer.provideMerge(BootSharedServices));
52−};
53−
54−export const ApiLive = makeApiLive(RequestScopedServicesLive);
55−
56−export const handleApiRequest = HttpRouter.toWebHandler(ApiLive).handler;
apps/cloud/src/extensions/docs.ts+0−29
@@ -1,29 +0,0 @@
1−import { Effect, Layer } from "effect";
2−import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
3−import { HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
4−
5−import { AccountApi, AdminUsersApi } from "@executor-js/api";
6−
7−import { CloudAuthApi, CloudAuthPublicApi } from "../auth/api";
8−import { OrgApi } from "../org/api";
9−
10−import { ProtectedCloudApi } from "../api/layers";
11−
12−export const CloudOpenApi = ProtectedCloudApi.add(CloudAuthPublicApi)
13− .add(CloudAuthApi)
14− .add(OrgApi)
15− .add(AccountApi)
16− .add(AdminUsersApi);
17−
18−const spec = OpenApi.fromApi(CloudOpenApi);
19−
20−export const CloudOpenApiJsonLive = HttpRouter.add(
21− "GET",
22− "/api/openapi.json",
23− Effect.succeed(HttpServerResponse.jsonUnsafe(spec)),
24−);
25−
26−export const CloudDocsLive = Layer.mergeAll(
27− HttpApiSwagger.layer(CloudOpenApi, { path: "/api/docs" }),
28− CloudOpenApiJsonLive,
29−);
apps/cloud/src/extensions/routes.ts+102−13
@@ -6,7 +6,7 @@ · 5 unmodified lines
66 // - the WorkOS session routes (login / callback / me / organizations /
77 // switch-organization / invitations / MCP-approval) — `NonProtectedApi`.
88 // - the cloud-only WorkOS domain-verification routes — `OrgHttpApi`.
9−// - Swagger UI + the OpenAPI JSON for the full cloud spec.
9+// - Swagger UI + the OpenAPI JSON for the full cloud spec (lazy).
1010 // - the Autumn billing proxy (`/api/billing/*`) — billing-as-extension (the
1111 // `extensions.routes` SEAM, but served under `/api` like everything else).
1212 // - the WorkOS webhook (`/api/webhooks/workos`) — signature-verified poke of
@@ -24,8 +24,7 @@ · 11 unmodified lines
2424 import { env, waitUntil } from "cloudflare:workers";
2525 import { Effect, Layer } from "effect";
2626 import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
27−import { HttpApiBuilder } from "effect/unstable/httpapi";
28−import { HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
27+import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
2928
3029 import { AccountApi, AdminUsersApi } from "@executor-js/api";
3130 import { requestScopedMiddleware, type MemberDirectory } from "@executor-js/api/server";
@@ -59,15 +58,93 @@ const apiPrefixedRouter = Layer.effect(HttpRouter.HttpRouter)( · 27 unmodified lines
5958 Effect.map(HttpRouter.HttpRouter.asEffect(), (router) => router.prefixed("/api")),
6059 );
6160
61+// ---------------------------------------------------------------------------
62+// Docs, built on demand.
63+//
64+// Nothing below runs until someone asks for `/api/docs` or `/api/openapi.json`.
65+// Both were previously built at module scope, so every cold isolate paid for
66+// two routes almost nobody calls: `OpenApi.fromApi` walks all ~91 endpoints,
67+// and effect's Swagger UI bundle is a single ~2 MB string literal that the
68+// isolate had to evaluate before serving any request. The bundle now arrives
69+// through a dynamic import, which keeps it out of the app plane's static
70+// closure entirely.
71+//
72+// Each step is memoized for the life of the isolate, so a second docs request
73+// is as cheap as the old module-scope version.
74+// ---------------------------------------------------------------------------
75+
76+/** Build `build()` at most once per isolate. */
77+const once = <A>(build: () => A): (() => A) => {
78+ let cell: { readonly value: A } | undefined;
79+ return () => (cell ??= { value: build() }).value;
80+};
81+
6282 // The full cloud OpenAPI spec, prefixed so the served paths match `/api/*`.
63−const CloudOpenApi = ProtectedCloudApi.add(CloudAuthPublicApi)
64− .add(CloudAuthApi)
65− .add(OrgApi)
66− .add(AccountApi)
67− .add(AdminUsersApi)
68− .prefix("/api");
83+const cloudOpenApi = once(() =>
84+ ProtectedCloudApi.add(CloudAuthPublicApi)
85+ .add(CloudAuthApi)
86+ .add(OrgApi)
87+ .add(AccountApi)
88+ .add(AdminUsersApi)
89+ .prefix("/api"),
90+);
6991
70−const spec = OpenApi.fromApi(CloudOpenApi);
92+const openApiSpec = once(() => OpenApi.fromApi(cloudOpenApi()));
93+
94+// The two escapes effect applies before interpolating into the page. Copied
95+// rather than imported because they live in an internal module; they are three
96+// lines and their behaviour is fixed by the HTML they guard.
97+const escapeHtml = (value: string) =>
98+ value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
99+
100+const escapeSpecJson = (value: unknown) =>
101+ JSON.stringify(value)
102+ .replace(/<\/script>/gi, "<\\/script>")
103+ .replace(/[\u2028\u2029]/g, (c) => (c === "\u2028" ? "\\u2028" : "\\u2029"));
104+
105+let docsHtml: string | undefined;
106+
107+/**
108+ * The Swagger UI page. Mirrors what `HttpApiSwagger.layer` renders — same
109+ * shell, same inlined bundle, same inlined spec — so the served page is
110+ * byte-identical to the layer this route replaced.
111+ */
112+const renderDocsHtml = async () => {
113+ if (docsHtml !== undefined) return docsHtml;
114+ // The ~2 MB Swagger UI bundle. Loaded here so it never enters the statically
115+ // reachable module graph of a cold isolate.
116+ const swaggerUi =
117+ (await import("effect/unstable/httpapi/internal/httpApiSwagger")) as unknown as {
118+ readonly css: string;
119+ readonly javascript: string;
120+ };
121+ const spec = openApiSpec();
122+ docsHtml = `<!DOCTYPE html>
123+<html lang="en">
124+<head>
125+ <meta charset="utf-8" />
126+ <meta name="viewport" content="width=device-width, initial-scale=1" />
127+ <title>${escapeHtml(spec.info.title)} Documentation</title>
128+ <style>${swaggerUi.css}</style>
129+</head>
130+<body>
131+ <div id="swagger-ui"></div>
132+ <script id="swagger-spec" type="application/json">
133+ ${escapeSpecJson(spec)}
134+ </script>
135+ <script>
136+ ${swaggerUi.javascript}
137+ window.onload = () => {
138+ window.ui = SwaggerUIBundle({
139+ spec: JSON.parse(document.getElementById("swagger-spec").textContent),
140+ dom_id: "#swagger-ui",
141+ });
142+ };
143+ </script>
144+</body>
145+</html>`;
146+ return docsHtml;
147+};
71148
72149 /**
73150 * Build cloud's app-only extension routes. `rsLive` is the per-request DB layer
@@ -104,10 +181,22 @@ export const makeCloudExtensionRoutes = ( · 30 unmodified lines
104181 );
105182
106183 // Swagger UI at /api/docs + the OpenAPI JSON at /api/openapi.json, over the
107− // `/api`-prefixed spec (so the served paths match).
184+ // `/api`-prefixed spec (so the served paths match). Both bodies are built on
185+ // the first request that asks for them — see the block above.
108186 const DocsRoutes = Layer.mergeAll(
109− HttpApiSwagger.layer(CloudOpenApi, { path: "/api/docs" }),
110− HttpRouter.add("GET", "/api/openapi.json", Effect.succeed(HttpServerResponse.jsonUnsafe(spec))),
187+ HttpRouter.add(
188+ "GET",
189+ "/api/docs",
190+ Effect.map(
191+ Effect.promise(() => renderDocsHtml()),
192+ (html) => HttpServerResponse.html(html),
193+ ),
194+ ),
195+ HttpRouter.add(
196+ "GET",
197+ "/api/openapi.json",
198+ Effect.sync(() => HttpServerResponse.jsonUnsafe(openApiSpec())),
199+ ),
111200 );
112201
113202 const BillingRoutes = AutumnRoutesLive.pipe(Layer.provide(requestScopedMiddleware(rsLive).layer));
e2e/cloud/surface-reachability.test.ts+2−3
@@ -41,9 +41,8 @@ scenario( · 40 unmodified lines
4141 // the ONLY thing that documents them — the routes serve either way, so a
4242 // group dropped from the `.add(...)` chain leaves a mounted, undocumented
4343 // plane and nothing else fails. Asserted against the SERVED spec rather
44− // than the module: cloud builds the same composition twice (here and in
45− // `extensions/docs.ts`) and only this one reaches the runtime, so importing
46− // either module could pass while the wire is wrong.
44+ // than the module: the spec is built lazily on the first request, so
45+ // importing the module could pass while the wire is wrong.
4746 expect(paths, "the account plane is documented").toContain("/api/account/me");
4847 expect(paths, "including the org-key surface the console reads").toContain(
4948 "/api/account/org-api-keys",

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t