From a7d3db8fe3109466bbf93165064f3099b00e8083 Mon Sep 17 00:00:00 2001 From: Sanchit Rk <0xsanchit@gmail.com> Date: Tue, 17 Nov 2026 13:56:04 +0530 Subject: [PATCH 01/22] feat(relay): add relay API with Clerk sign-in and default workspace The relay is the cloud API for accounts, workspaces and machines. This first slice verifies Clerk session tokens and serves GET /v1/me, which creates the account and its default workspace on first sight, exactly once even under concurrent first calls. Postgres runs locally from compose.yaml; the E2E suite boots the real relay against it with a real Clerk test user. Co-Authored-By: Claude Opus 5.5 --- infra/relay/compose.yaml | 20 ++++ infra/relay/package.json | 24 +++++ infra/relay/src/accounts.ts | 75 +++++++++++++ infra/relay/src/api.ts | 45 ++++++++ infra/relay/src/clerk.ts | 51 +++++++++ infra/relay/src/db.ts | 14 +++ infra/relay/src/http.ts | 39 +++++++ infra/relay/src/main.ts | 24 +++++ infra/relay/src/migrations.ts | 41 +++++++ infra/relay/test/__artifacts__/me.json | 29 +++++ infra/relay/test/me.test.ts | 141 +++++++++++++++++++++++++ infra/relay/tsconfig.json | 7 ++ infra/relay/vite.config.ts | 10 ++ pnpm-lock.yaml | 101 ++++++++++++++++++ 14 files changed, 621 insertions(+) create mode 100644 infra/relay/compose.yaml create mode 100644 infra/relay/package.json create mode 100644 infra/relay/src/accounts.ts create mode 100644 infra/relay/src/api.ts create mode 100644 infra/relay/src/clerk.ts create mode 100644 infra/relay/src/db.ts create mode 100644 infra/relay/src/http.ts create mode 100644 infra/relay/src/main.ts create mode 100644 infra/relay/src/migrations.ts create mode 100644 infra/relay/test/__artifacts__/me.json create mode 100644 infra/relay/test/me.test.ts create mode 100644 infra/relay/tsconfig.json create mode 100644 infra/relay/vite.config.ts diff --git a/infra/relay/compose.yaml b/infra/relay/compose.yaml new file mode 100644 index 00000000..bf42b5cb --- /dev/null +++ b/infra/relay/compose.yaml @@ -0,0 +1,20 @@ +# Local Postgres for development and the E2E tests. Production is managed Postgres behind Hyperdrive. +services: + postgres: + image: postgres:18 + environment: + POSTGRES_USER: relay + POSTGRES_PASSWORD: relay + POSTGRES_DB: relay + ports: + - "55432:5432" + volumes: + - relay-postgres:/var/lib/postgresql + healthcheck: + test: ["CMD-SHELL", "pg_isready -U relay -d relay"] + interval: 2s + timeout: 3s + retries: 15 + +volumes: + relay-postgres: diff --git a/infra/relay/package.json b/infra/relay/package.json new file mode 100644 index 00000000..2b5fccf0 --- /dev/null +++ b/infra/relay/package.json @@ -0,0 +1,24 @@ +{ + "name": "@codeworksh/relay", + "version": "0.0.0", + "private": true, + "description": "The relay: the cloud API for accounts, workspaces and machines, at relay.codework.sh.", + "type": "module", + "scripts": { + "db": "docker compose up -d --wait", + "start": "node src/main.ts", + "test": "vp test", + "typecheck": "tsc --noEmit" + }, + "dependencies": { + "@clerk/backend": "3.27.0", + "@effect/platform-node": "4.0.5", + "@effect/sql-pg": "4.0.5", + "effect": "4.0.5" + }, + "devDependencies": { + "@types/node": "catalog:", + "typescript": "catalog:", + "vite-plus": "catalog:" + } +} diff --git a/infra/relay/src/accounts.ts b/infra/relay/src/accounts.ts new file mode 100644 index 00000000..10c7de83 --- /dev/null +++ b/infra/relay/src/accounts.ts @@ -0,0 +1,75 @@ +import { Context, Effect, Layer } from "effect"; +import { SqlClient } from "effect/sql"; +import { Account, Me, Workspace } from "./api.ts"; +import { Clerk } from "./clerk.ts"; + +/** People and the workspaces they belong to. */ +export class Accounts extends Context.Service< + Accounts, + { + /** The person's account and workspaces, creating the account and its default workspace on first sight. */ + readonly ensure: (authId: string) => Effect.Effect; + } +>()("relay/Accounts") { + static readonly layer = Layer.effect( + Accounts, + Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + const clerk = yield* Clerk; + + const find = (authId: string) => + sql<{ readonly id: string; readonly email: string; readonly name: string | null }>` + SELECT id, email, name FROM account WHERE auth_id = ${authId} + `.pipe(Effect.map((rows) => rows[0])); + + // Concurrent first calls both reach the insert; the unique auth_id makes the loser wait for the + // winner's commit and insert nothing, so exactly one default workspace is created. + const create = Effect.fn("Accounts.create")(function* (authId: string) { + const profile = yield* clerk.profile(authId); + const workspaceName = `${profile.firstName ?? profile.email.split("@")[0]}'s Workspace`; + yield* sql.withTransaction( + Effect.gen(function* () { + const created = yield* sql<{ readonly id: string; readonly createdBy: string }>` + WITH inserted AS ( + INSERT INTO account (auth_id, email, name) + VALUES (${authId}, ${profile.email}, ${profile.name}) + ON CONFLICT (auth_id) DO NOTHING + RETURNING id + ) + INSERT INTO workspace (name, created_by) + SELECT ${workspaceName}, id FROM inserted + RETURNING id, created_by + `; + for (const workspace of created) { + yield* sql` + INSERT INTO member (workspace_id, account_id, role) + VALUES (${workspace.id}, ${workspace.createdBy}, 'owner') + `; + } + }), + ); + }); + + return Accounts.of({ + ensure: Effect.fn("Accounts.ensure")(function* (authId) { + const account = (yield* find(authId)) ?? (yield* create(authId).pipe(Effect.andThen(find(authId)))); + if (account === undefined) return yield* Effect.die(new Error(`No account for ${authId}`)); + const workspaces = yield* sql<{ + readonly id: string; + readonly name: string; + readonly role: Workspace["role"]; + }>` + SELECT w.id, w.name, m.role + FROM member m JOIN workspace w ON w.id = m.workspace_id + WHERE m.account_id = ${account.id} + ORDER BY w.created_at, w.id + `; + return new Me({ + account: new Account(account), + workspaces: workspaces.map((row) => new Workspace(row)), + }); + }, Effect.orDie), + }); + }), + ); +} diff --git a/infra/relay/src/api.ts b/infra/relay/src/api.ts new file mode 100644 index 00000000..f59a87e7 --- /dev/null +++ b/infra/relay/src/api.ts @@ -0,0 +1,45 @@ +import { Context, Schema } from "effect"; +import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSecurity } from "effect/http-api"; + +export const Role = Schema.Literals(["owner", "admin", "member"]); + +export class Account extends Schema.Class("Account")({ + id: Schema.String, + email: Schema.String, + name: Schema.NullOr(Schema.String), +}) {} + +export class Workspace extends Schema.Class("Workspace")({ + id: Schema.String, + name: Schema.String, + role: Role, +}) {} + +export class Me extends Schema.Class("Me")({ + account: Account, + workspaces: Schema.Array(Workspace), +}) {} + +export class Unauthorized extends Schema.TaggedError()( + "Unauthorized", + { message: Schema.String }, + { httpApiStatus: 401 }, +) {} + +/** A person whose session token the auth vendor verified: only the vendor's subject id. */ +export class Person extends Context.Service()("relay/Person") {} + +/** Verifies a person's bearer session token and provides {@link Person}. */ +export class PersonAuth extends HttpApiMiddleware.Service()( + "relay/PersonAuth", + { + security: { bearer: HttpApiSecurity.bearer }, + error: Unauthorized, + }, +) {} + +export class MeGroup extends HttpApiGroup.make("me") + .add(HttpApiEndpoint.get("get", "/v1/me", { success: Me })) + .middleware(PersonAuth) {} + +export class Api extends HttpApi.make("relay").add(MeGroup) {} diff --git a/infra/relay/src/clerk.ts b/infra/relay/src/clerk.ts new file mode 100644 index 00000000..9a3d8b44 --- /dev/null +++ b/infra/relay/src/clerk.ts @@ -0,0 +1,51 @@ +import { createClerkClient, verifyToken } from "@clerk/backend"; +import { Config, Context, Effect, Layer, Redacted } from "effect"; +import { Unauthorized } from "./api.ts"; + +export interface Profile { + readonly email: string; + readonly firstName: string | null; + readonly name: string | null; +} + +/** The auth vendor, behind the two things the relay needs from it. */ +export class Clerk extends Context.Service< + Clerk, + { + /** The verified subject (`auth_id`) of a session token. */ + readonly verify: (token: string) => Effect.Effect; + readonly profile: (authId: string) => Effect.Effect; + } +>()("relay/Clerk") { + static readonly layer = Layer.effect( + Clerk, + Effect.gen(function* () { + const secretKey = Redacted.value(yield* Config.Redacted("CLERK_SECRET_KEY")); + const client = createClerkClient({ secretKey }); + return Clerk.of({ + verify: Effect.fn("Clerk.verify")(function* (token) { + // The package's verifyToken resolves to the claims and rejects on any verification failure. + const claims: unknown = yield* Effect.tryPromise(() => verifyToken(token, { secretKey })).pipe( + Effect.mapError(() => new Unauthorized({ message: "Invalid or expired session token" })), + ); + if ( + typeof claims !== "object" || + claims === null || + !("sub" in claims) || + typeof claims.sub !== "string" + ) { + return yield* new Unauthorized({ message: "Invalid or expired session token" }); + } + return claims.sub; + }), + profile: Effect.fn("Clerk.profile")(function* (authId) { + const user = yield* Effect.tryPromise(() => client.users.getUser(authId)).pipe(Effect.orDie); + const email = user.primaryEmailAddress?.emailAddress; + if (email === undefined) + return yield* Effect.die(new Error(`Clerk user ${authId} has no email address`)); + return { email, firstName: user.firstName, name: user.fullName }; + }), + }); + }), + ); +} diff --git a/infra/relay/src/db.ts b/infra/relay/src/db.ts new file mode 100644 index 00000000..1098e3e9 --- /dev/null +++ b/infra/relay/src/db.ts @@ -0,0 +1,14 @@ +import { PgClient } from "@effect/sql-pg"; +import { Config, String as Str } from "effect"; +import { Migrator } from "effect/sql"; +import { migrations } from "./migrations.ts"; + +/** The relay's Postgres, from `DATABASE_URL`; camelCase fields map to snake_case columns. */ +export const layer = PgClient.layerConfig({ + url: Config.Redacted("DATABASE_URL"), + transformQueryNames: Config.succeed(Str.camelToSnake), + transformResultNames: Config.succeed(Str.snakeToCamel), +}); + +/** Applies pending migrations. The generic migrator needs only the client, not `pg_dump`. */ +export const migrate = Migrator.make({})({ loader: Migrator.fromRecord(migrations) }); diff --git a/infra/relay/src/http.ts b/infra/relay/src/http.ts new file mode 100644 index 00000000..f8d97660 --- /dev/null +++ b/infra/relay/src/http.ts @@ -0,0 +1,39 @@ +import { Effect, Layer, Redacted } from "effect"; +import { HttpApiBuilder } from "effect/http-api"; +import { Accounts } from "./accounts.ts"; +import { Api, Person, PersonAuth } from "./api.ts"; +import { Clerk } from "./clerk.ts"; + +const PersonAuthLayer = Layer.effect( + PersonAuth, + Effect.gen(function* () { + const clerk = yield* Clerk; + return PersonAuth.of({ + bearer: Effect.fn("PersonAuth.bearer")(function* (httpEffect, { credential }) { + const authId = yield* clerk.verify(Redacted.value(credential)); + return yield* Effect.provideService(httpEffect, Person, { authId }); + }), + }); + }), +); + +const MeHandlers = HttpApiBuilder.group( + Api, + "me", + Effect.fn(function* (handlers) { + const accounts = yield* Accounts; + return handlers.handle("get", () => + Effect.gen(function* () { + const person = yield* Person; + return yield* accounts.ensure(person.authId); + }), + ); + }), +).pipe(Layer.provide(PersonAuthLayer)); + +/** The relay's routes, independent of the runtime that serves them. Requires `SqlClient`. */ +export const routes = HttpApiBuilder.layer(Api).pipe( + Layer.provide(MeHandlers), + Layer.provide(Accounts.layer), + Layer.provide(Clerk.layer), +); diff --git a/infra/relay/src/main.ts b/infra/relay/src/main.ts new file mode 100644 index 00000000..748f75d5 --- /dev/null +++ b/infra/relay/src/main.ts @@ -0,0 +1,24 @@ +/* @effect-diagnostics nodeBuiltinImport:off -- the Node entry serves the relay locally. */ +import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"; +import { Config, Effect, Layer } from "effect"; +import { HttpRouter } from "effect/http"; +import { createServer } from "node:http"; +import * as Db from "./db.ts"; +import { routes } from "./http.ts"; + +// The relay on Node, for development and the E2E suite: migrates, then serves on PORT (0 picks a free +// port) and logs the address it bound. +const server = Layer.unwrap( + Effect.gen(function* () { + // Int, not Port: Port rejects 0. + const port = yield* Config.Int("PORT").pipe(Config.withDefault(8787)); + return NodeHttpServer.layer(createServer, { host: "127.0.0.1", port }); + }), +); + +const app = HttpRouter.serve(routes).pipe( + Layer.provide(server), + Layer.provide(Layer.effectDiscard(Db.migrate).pipe(Layer.provideMerge(Db.layer))), +); + +Layer.launch(app).pipe(NodeRuntime.runMain); diff --git a/infra/relay/src/migrations.ts b/infra/relay/src/migrations.ts new file mode 100644 index 00000000..fe616e7a --- /dev/null +++ b/infra/relay/src/migrations.ts @@ -0,0 +1,41 @@ +import { Effect } from "effect"; +import { SqlClient } from "effect/sql"; + +// Migrations ship as code (Migrator.fromRecord), keyed "YYYYMMDD<2-digit counter>_