Unified · Split
| @@ -49,7 +49,6 @@ import { resetSubjectTouchCache } from "@executor-js/sdk/host-internal"; · 48 unmodified lines | |||
| 49 | import { createSqliteTestFumaDb, type SqliteTestFumaDb } from "@executor-js/sdk/testing"; | 49 | import { createSqliteTestFumaDb, type SqliteTestFumaDb } from "@executor-js/sdk/testing"; |
| 50 | 50 | ||
| 51 | import { RequestScopedServicesLive } from "./api/layers"; | 51 | import { RequestScopedServicesLive } from "./api/layers"; |
| 52 | import { makeApiLive } from "./api/router"; | ||
| 53 | 52 | ||
| 54 | class Counter extends Context.Service<Counter, { readonly id: number }>()("test/Counter") {} | 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 | // `ExecutionStackMiddleware` request scoping. | 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 | // - 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 (the | 10 | // - 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 of | 12 | // - the WorkOS webhook (`/api/webhooks/workos`) — signature-verified poke of |
| @@ -24,8 +24,7 @@ · 11 unmodified lines | |||
| 24 | import { env, waitUntil } from "cloudflare:workers"; | 24 | import { env, waitUntil } from "cloudflare:workers"; |
| 25 | import { Effect, Layer } from "effect"; | 25 | import { Effect, Layer } from "effect"; |
| 26 | import { HttpRouter, HttpServerResponse } from "effect/unstable/http"; | 26 | import { HttpRouter, HttpServerResponse } from "effect/unstable/http"; |
| 27 | import { HttpApiBuilder } from "effect/unstable/httpapi"; | 27 | import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi"; |
| 28 | import { HttpApiSwagger, OpenApi } from "effect/unstable/httpapi"; | ||
| 29 | 28 | ||
| 30 | import { AccountApi, AdminUsersApi } from "@executor-js/api"; | 29 | import { AccountApi, AdminUsersApi } from "@executor-js/api"; |
| 31 | import { requestScopedMiddleware, type MemberDirectory } from "@executor-js/api/server"; | 30 | import { 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. */ | ||
| 77 | const 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/*`. |
| 63 | const CloudOpenApi = ProtectedCloudApi.add(CloudAuthPublicApi) | 83 | const 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 | ||
| 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 | * Build cloud's app-only extension routes. `rsLive` is the per-request DB layer | 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 | // Swagger UI at /api/docs + the OpenAPI JSON at /api/openapi.json, over the | 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 | 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)); |
| @@ -41,9 +41,8 @@ scenario( · 40 unmodified lines | |||
| 41 | // the ONLY thing that documents them — the routes serve either way, so a | 41 | // the ONLY thing that documents them — the routes serve either way, so a |
| 42 | // group dropped from the `.add(...)` chain leaves a mounted, undocumented | 42 | // group dropped from the `.add(...)` chain leaves a mounted, undocumented |
| 43 | // plane and nothing else fails. Asserted against the SERVED spec rather | 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 | 44 | // 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 importing | 45 | // 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", |