Unified · Split
| @@ -49,7 +49,6 @@ import { resetSubjectTouchCache } from "@executor-js/sdk/host-internal"; · 48 unmodified lines | ||
| 49 | 49 | import { createSqliteTestFumaDb, type SqliteTestFumaDb } from "@executor-js/sdk/testing"; |
| 50 | 50 | |
| 51 | 51 | import { RequestScopedServicesLive } from "./api/layers"; |
| 52 | −import { makeApiLive } from "./api/router"; | |
| 53 | 52 | |
| 54 | 53 | class 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 | − | |
| 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 | − | |
| 220 | 177 | // --------------------------------------------------------------------------- |
| 221 | 178 | // `ExecutionStackMiddleware` request scoping. |
| 222 | 179 | // |
| @@ -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; | |
| @@ -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 | −); | |
| @@ -6,7 +6,7 @@ · 5 unmodified lines | ||
| 6 | 6 | // - the WorkOS session routes (login / callback / me / organizations / |
| 7 | 7 | // switch-organization / invitations / MCP-approval) — `NonProtectedApi`. |
| 8 | 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 | 10 | // - the Autumn billing proxy (`/api/billing/*`) — billing-as-extension (the |
| 11 | 11 | // `extensions.routes` SEAM, but served under `/api` like everything else). |
| 12 | 12 | // - the WorkOS webhook (`/api/webhooks/workos`) — signature-verified poke of |
| @@ -24,8 +24,7 @@ · 11 unmodified lines | ||
| 24 | 24 | import { env, waitUntil } from "cloudflare:workers"; |
| 25 | 25 | import { Effect, Layer } from "effect"; |
| 26 | 26 | 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"; | |
| 29 | 28 | |
| 30 | 29 | import { AccountApi, AdminUsersApi } from "@executor-js/api"; |
| 31 | 30 | import { requestScopedMiddleware, type MemberDirectory } from "@executor-js/api/server"; |
| @@ -59,15 +58,93 @@ const apiPrefixedRouter = Layer.effect(HttpRouter.HttpRouter)( · 27 unmodified lines | ||
| 59 | 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. */ | |
| 77 | +const once = <A>(build: () => A): (() => A) => { | |
| 78 | + let cell: { readonly value: A } | undefined; | |
| 79 | + return () => (cell ??= { value: build() }).value; | |
| 80 | +}; | |
| 81 | + | |
| 62 | 82 | // 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 | +); | |
| 69 | 91 | |
| 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, "&").replace(/</g, "<").replace(/>/g, ">"); | |
| 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 | +}; | |
| 71 | 148 | |
| 72 | 149 | /** |
| 73 | 150 | * 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 | 183 | // 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 | 186 | 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 | + ), | |
| 111 | 200 | ); |
| 112 | 201 | |
| 113 | 202 | const BillingRoutes = AutumnRoutesLive.pipe(Layer.provide(requestScopedMiddleware(rsLive).layer)); |
| @@ -41,9 +41,8 @@ scenario( · 40 unmodified lines | ||
| 41 | 41 | // the ONLY thing that documents them — the routes serve either way, so a |
| 42 | 42 | // group dropped from the `.add(...)` chain leaves a mounted, undocumented |
| 43 | 43 | // 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. | |
| 47 | 46 | expect(paths, "the account plane is documented").toContain("/api/account/me"); |
| 48 | 47 | expect(paths, "including the org-key surface the console reads").toContain( |
| 49 | 48 | "/api/account/org-api-keys", |