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
49import { createSqliteTestFumaDb, type SqliteTestFumaDb } from "@executor-js/sdk/testing";49import { createSqliteTestFumaDb, type SqliteTestFumaDb } from "@executor-js/sdk/testing";
50 50
51import { RequestScopedServicesLive } from "./api/layers";51import { RequestScopedServicesLive } from "./api/layers";
52import { makeApiLive } from "./api/router";
53 52
54class Counter extends Context.Service<Counter, { readonly id: number }>()("test/Counter") {}53class Counter extends Context.Service<Counter, { readonly id: number }>()("test/Counter") {}
55 54
@@ -175,48 +174,6 @@ describe("HttpRouter.toWebHandler request scoping", () => { · 119 unmodified lines
175 });174 });
176});175});
177 176
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
185describe("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
220// ---------------------------------------------------------------------------177// ---------------------------------------------------------------------------
221// `ExecutionStackMiddleware` request scoping.178// `ExecutionStackMiddleware` request scoping.
222//179//
apps/cloud/src/api/router.ts+0−56
@@ -1,56 +0,0 @@
1import { Layer } from "effect";
2import { HttpRouter } from "effect/unstable/http";
3
4import {
5 RouterConfigLive,
6 requestScopedMiddleware,
7 type MemberDirectory,
8} from "@executor-js/api/server";
9
10import { UserStoreService } from "../auth/context";
11import { WorkOsMirror } from "../auth/workos-mirror";
12import { DbService } from "../db/db";
13import { makeAccountApiLive } from "../account/account-api";
14
15import { AutumnRoutesLive } from "../extensions/billing/route";
16import { CloudDocsLive } from "../extensions/docs";
17import { ApiErrorLoggingLive } from "../observability/error-logging";
18import {
19 BootSharedServices,
20 RequestScopedServicesLive,
21 makeOrgApiLive,
22 makeNonProtectedApiLive,
23} from "./layers";
24import { 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`.
37export 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
54export const ApiLive = makeApiLive(RequestScopedServicesLive);
55
56export const handleApiRequest = HttpRouter.toWebHandler(ApiLive).handler;
apps/cloud/src/extensions/docs.ts+0−29
@@ -1,29 +0,0 @@
1import { Effect, Layer } from "effect";
2import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
3import { HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
4
5import { AccountApi, AdminUsersApi } from "@executor-js/api";
6
7import { CloudAuthApi, CloudAuthPublicApi } from "../auth/api";
8import { OrgApi } from "../org/api";
9
10import { ProtectedCloudApi } from "../api/layers";
11
12export const CloudOpenApi = ProtectedCloudApi.add(CloudAuthPublicApi)
13 .add(CloudAuthApi)
14 .add(OrgApi)
15 .add(AccountApi)
16 .add(AdminUsersApi);
17
18const spec = OpenApi.fromApi(CloudOpenApi);
19
20export const CloudOpenApiJsonLive = HttpRouter.add(
21 "GET",
22 "/api/openapi.json",
23 Effect.succeed(HttpServerResponse.jsonUnsafe(spec)),
24);
25
26export 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
6// - the WorkOS session routes (login / callback / me / organizations /6// - the WorkOS session routes (login / callback / me / organizations /
7// switch-organization / invitations / MCP-approval) — `NonProtectedApi`.7// switch-organization / invitations / MCP-approval) — `NonProtectedApi`.
8// - the cloud-only WorkOS domain-verification routes — `OrgHttpApi`.8// - 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).
10// - the Autumn billing proxy (`/api/billing/*`) — billing-as-extension (the10// - the Autumn billing proxy (`/api/billing/*`) — billing-as-extension (the
11// `extensions.routes` SEAM, but served under `/api` like everything else).11// `extensions.routes` SEAM, but served under `/api` like everything else).
12// - the WorkOS webhook (`/api/webhooks/workos`) — signature-verified poke of12// - the WorkOS webhook (`/api/webhooks/workos`) — signature-verified poke of
@@ -24,8 +24,7 @@ · 11 unmodified lines
24import { env, waitUntil } from "cloudflare:workers";24import { env, waitUntil } from "cloudflare:workers";
25import { Effect, Layer } from "effect";25import { Effect, Layer } from "effect";
26import { HttpRouter, HttpServerResponse } from "effect/unstable/http";26import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
27import { HttpApiBuilder } from "effect/unstable/httpapi";27import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
28import { HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
29 28
30import { AccountApi, AdminUsersApi } from "@executor-js/api";29import { AccountApi, AdminUsersApi } from "@executor-js/api";
31import { requestScopedMiddleware, type MemberDirectory } from "@executor-js/api/server";30import { requestScopedMiddleware, type MemberDirectory } from "@executor-js/api/server";
@@ -59,15 +58,93 @@ const apiPrefixedRouter = Layer.effect(HttpRouter.HttpRouter)( · 27 unmodified lines
59 Effect.map(HttpRouter.HttpRouter.asEffect(), (router) => router.prefixed("/api")),58 Effect.map(HttpRouter.HttpRouter.asEffect(), (router) => router.prefixed("/api")),
60);59);
61 60
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. */
77const once = <A>(build: () => A): (() => A) => {
78 let cell: { readonly value: A } | undefined;
79 return () => (cell ??= { value: build() }).value;
80};
81
62// The full cloud OpenAPI spec, prefixed so the served paths match `/api/*`.82// The full cloud OpenAPI spec, prefixed so the served paths match `/api/*`.
63const CloudOpenApi = ProtectedCloudApi.add(CloudAuthPublicApi)83const cloudOpenApi = once(() =>
64 .add(CloudAuthApi)84 ProtectedCloudApi.add(CloudAuthPublicApi)
65 .add(OrgApi)85 .add(CloudAuthApi)
66 .add(AccountApi)86 .add(OrgApi)
67 .add(AdminUsersApi)87 .add(AccountApi)
68 .prefix("/api");88 .add(AdminUsersApi)
89 .prefix("/api"),
90);
69 91
70const spec = OpenApi.fromApi(CloudOpenApi);92const 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.
97const escapeHtml = (value: string) =>
98 value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
99
100const escapeSpecJson = (value: unknown) =>
101 JSON.stringify(value)
102 .replace(/<\/script>/gi, "<\\/script>")
103 .replace(/[\u2028\u2029]/g, (c) => (c === "\u2028" ? "\\u2028" : "\\u2029"));
104
105let 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 */
112const 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};
71 148
72/**149/**
73 * Build cloud's app-only extension routes. `rsLive` is the per-request DB layer150 * Build cloud's app-only extension routes. `rsLive` is the per-request DB layer
@@ -104,10 +181,22 @@ export const makeCloudExtensionRoutes = ( · 30 unmodified lines
104 );181 );
105 182
106 // Swagger UI at /api/docs + the OpenAPI JSON at /api/openapi.json, over the183 // 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.
108 const DocsRoutes = Layer.mergeAll(186 const DocsRoutes = Layer.mergeAll(
109 HttpApiSwagger.layer(CloudOpenApi, { path: "/api/docs" }),187 HttpRouter.add(
110 HttpRouter.add("GET", "/api/openapi.json", Effect.succeed(HttpServerResponse.jsonUnsafe(spec))),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 ),
111 );200 );
112 201
113 const BillingRoutes = AutumnRoutesLive.pipe(Layer.provide(requestScopedMiddleware(rsLive).layer));202 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
41 // the ONLY thing that documents them — the routes serve either way, so a41 // the ONLY thing that documents them — the routes serve either way, so a
42 // group dropped from the `.add(...)` chain leaves a mounted, undocumented42 // group dropped from the `.add(...)` chain leaves a mounted, undocumented
43 // plane and nothing else fails. Asserted against the SERVED spec rather43 // plane and nothing else fails. Asserted against the SERVED spec rather
44 // than the module: cloud builds the same composition twice (here and in44 // than the module: the spec is built lazily on the first request, so
45 // `extensions/docs.ts`) and only this one reaches the runtime, so importing45 // importing the module could pass while the wire is wrong.
46 // either module could pass while the wire is wrong.
47 expect(paths, "the account plane is documented").toContain("/api/account/me");46 expect(paths, "the account plane is documented").toContain("/api/account/me");
48 expect(paths, "including the org-key surface the console reads").toContain(47 expect(paths, "including the org-key surface the console reads").toContain(
49 "/api/account/org-api-keys",48 "/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