@kelpie/server 0.1.0

package/src/modules/workspace/idempotencyMiddleware.ts

@@ -0,0 +1,207 @@
+import { createHash } from 'node:crypto'
+import type { Context, MiddlewareHandler } from 'hono'
+
+import type { Database } from '../../lib/database.ts'
+import { AppError, describeThrown } from '../../lib/errors.ts'
+import { PUBLIC_ROUTE_PREFIX } from '../../lib/http.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import type { Logger } from '../../lib/logger.ts'
+import { actorWorkspaceId } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import {
+  completeIdempotencyKey,
+  deleteIdempotencyKey,
+  findIdempotencyKey,
+  pruneExpiredIdempotencyKeys,
+  reserveIdempotencyKey,
+} from './idempotencyRepository.ts'
+import type { IdempotencyKeyRecord } from './idempotencyRepository.ts'
+import type { StoredIdempotentResponse } from './schema.ts'
+
+/**
+ * `POST /v1/*` accepts an optional `Idempotency-Key` header (`api.md`). Applied
+ * once here rather than per route, because every module's `POST` gets the same
+ * behaviour and none of them decide it individually.
+ */
+
+const IDEMPOTENCY_KEY_HEADER = 'Idempotency-Key'
+
+/** `api.md`: a replayed key returns the original response within this window. */
+export const IDEMPOTENCY_REPLAY_WINDOW_MS = 24 * 60 * 60 * 1000
+
+export interface IdempotencyMiddlewareDependencies {
+  readonly db: Database
+  readonly now: () => Date
+  readonly createId: IdFactory
+  readonly credentials: CredentialDependencies
+  readonly log: Logger
+}
+
+/** Method, path, and raw body, so a byte-for-byte different request never replays. */
+function hashRequest(method: string, path: string, rawBody: string): string {
+  return createHash('sha256').update(method).update('\n').update(path).update('\n').update(rawBody).digest('hex')
+}
+
+function isPublicRoute(path: string): boolean {
+  return path === PUBLIC_ROUTE_PREFIX || path.startsWith(`${PUBLIC_ROUTE_PREFIX}/`)
+}
+
+/**
+ * Builds the replayed `Response` directly rather than through `c.json()`: the
+ * stored status is a `number` read back from the database, not one of the
+ * literal `ContentfulStatusCode`s `c.json()`'s type expects, and there is
+ * nothing to narrow it to at this point.
+ */
+function replayResponse(stored: StoredIdempotentResponse): Response {
+  return new Response(JSON.stringify(stored.body), {
+    status: stored.status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+function conflict(message: string): AppError {
+  return AppError.conflict(message, [{ field: 'Idempotency-Key', message }])
+}
+
+/**
+ * Whether `acquireReservation` won the row, found somebody else's live one, or
+ * lost a race entirely. Kept as a tag rather than inferred from the record's
+ * fields afterwards: a concurrent retry of the identical request can leave a
+ * row with a matching hash and a null response that we did *not* reserve, and
+ * that case has to be refused (409, still in flight) rather than run — so
+ * which branch produced the record is the only thing that can decide it.
+ */
+type ReservationOutcome =
+  | { readonly kind: 'reserved'; readonly record: IdempotencyKeyRecord }
+  | { readonly kind: 'existing'; readonly record: IdempotencyKeyRecord }
+  | { readonly kind: 'contended' }
+
+/**
+ * Reserves the key, retrying once if the row we read after a failed reserve
+ * has since disappeared — the concurrent request holding it failed and freed
+ * it between our attempts. A second miss means another request just took it;
+ * treated the same as any other in-flight conflict rather than retried again,
+ * so a pathological case cannot loop.
+ */
+async function acquireReservation(
+  dependencies: IdempotencyMiddlewareDependencies,
+  params: { readonly workspaceId: string; readonly key: string; readonly requestHash: string; readonly now: Date },
+): Promise<ReservationOutcome> {
+  const expiresAt = new Date(params.now.getTime() + IDEMPOTENCY_REPLAY_WINDOW_MS)
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const reserved = await reserveIdempotencyKey(dependencies.db, {
+      id: dependencies.createId('idempotencyKey'),
+      workspaceId: params.workspaceId,
+      key: params.key,
+      requestHash: params.requestHash,
+      expiresAt,
+      now: params.now,
+    })
+
+    if (reserved !== undefined) {
+      return { kind: 'reserved', record: reserved }
+    }
+
+    const existing = await findIdempotencyKey(dependencies.db, params.workspaceId, params.key)
+
+    if (existing !== undefined) {
+      return { kind: 'existing', record: existing }
+    }
+  }
+
+  return { kind: 'contended' }
+}
+
+export function createIdempotencyMiddleware(dependencies: IdempotencyMiddlewareDependencies): MiddlewareHandler {
+  return async (context: Context, next) => {
+    if (context.req.method !== 'POST' || isPublicRoute(context.req.path)) {
+      await next()
+      return
+    }
+
+    const key = context.req.header(IDEMPOTENCY_KEY_HEADER)
+
+    if (key === undefined || key.length === 0) {
+      await next()
+      return
+    }
+
+    const actor = await resolveActorFrom(dependencies.credentials, context)
+    const workspaceId = actorWorkspaceId(actor)
+
+    // Between signup and a first workspace (`POST /v1/workspaces`, `POST
+    // /v1/invites/accept`) there is nothing to scope a key to. The request
+    // runs unguarded rather than refusing a legitimate onboarding call.
+    if (workspaceId === null) {
+      await next()
+      return
+    }
+
+    const rawBody = await context.req.text()
+    const requestHash = hashRequest(context.req.method, context.req.path, rawBody)
+    const now = dependencies.now()
+
+    const outcome = await acquireReservation(dependencies, { workspaceId, key, requestHash, now })
+
+    if (outcome.kind === 'contended') {
+      throw conflict('A request with this Idempotency-Key is already in progress')
+    }
+
+    if (outcome.kind === 'existing') {
+      if (outcome.record.response === null) {
+        throw conflict('A request with this Idempotency-Key is already in progress')
+      }
+
+      if (outcome.record.requestHash !== requestHash) {
+        throw conflict('This Idempotency-Key was already used for a different request')
+      }
+
+      return replayResponse(outcome.record.response)
+    }
+
+    const record = outcome.record
+
+    // `app.onError` (`app.ts`) catches a thrown `AppError` at the dispatch frame
+    // closest to where it was thrown, inside Hono's own `compose`, and resolves
+    // `next()` there rather than rejecting it back up through this middleware.
+    // So "the handler threw" and "the handler answered" are indistinguishable
+    // from here by whether `next()` rejects — both leave `context.res` set. The
+    // `try`/`catch` below only ever fires for something `onError` itself could
+    // not handle (a non-`Error` throw); the real failure signal is the status.
+    try {
+      await next()
+    } catch (error) {
+      await deleteIdempotencyKey(dependencies.db, record.id)
+      throw error
+    }
+
+    if (context.res.status >= 400) {
+      // Not replayed: a retry of this key should run again, not repeat the
+      // failure. Deleting rather than storing it is what makes that happen.
+      await deleteIdempotencyKey(dependencies.db, record.id)
+      return undefined
+    }
+
+    try {
+      const bodyText = await context.res.clone().text()
+      const body: unknown = bodyText.length === 0 ? null : JSON.parse(bodyText)
+
+      await completeIdempotencyKey(dependencies.db, record.id, { status: context.res.status, body })
+      await pruneExpiredIdempotencyKeys(dependencies.db, workspaceId, now)
+    } catch (persistError) {
+      // The handler already answered correctly; a bookkeeping failure here must
+      // not turn that answer into a 500. The reservation is left in flight and
+      // simply expires, so the worst case is a future replay of this key being
+      // refused as in-progress rather than replayed, never a duplicate write.
+      dependencies.log.warn('failed to persist idempotency key response', {
+        workspaceId,
+        key,
+        error: describeThrown(persistError),
+      })
+    }
+
+    return undefined
+  }
+}

package/src/modules/workspace/idempotencyRepository.ts

@@ -0,0 +1,111 @@
+import { and, eq, lt } from 'drizzle-orm'
+
+import { idempotencyKeys } from './schema.ts'
+import type { StoredIdempotentResponse } from './schema.ts'
+import type { Queryable } from './repository.ts'
+
+/** Queries for `idempotency_keys`. The middleware decides; these read and write. */
+
+export type IdempotencyKeyRecord = typeof idempotencyKeys.$inferSelect
+
+/**
+ * Reserves a key, or reclaims one whose reservation has expired.
+ *
+ * A plain insert would raise a unique violation on a second request for the
+ * same `(workspace_id, key)`, which is exactly the signal the caller needs —
+ * but Postgres has no way to say "insert, unless the existing row is expired,
+ * in which case overwrite it" as two statements without a race between them.
+ * `onConflictDoUpdate` with a `setWhere` does it as one: the update only fires
+ * when the existing row's `expires_at` is already past, and `returning()` is
+ * empty exactly when neither the insert nor the update happened, which is the
+ * caller's signal to go read the live row instead.
+ */
+export async function reserveIdempotencyKey(
+  db: Queryable,
+  params: {
+    readonly id: string
+    readonly workspaceId: string
+    readonly key: string
+    readonly requestHash: string
+    readonly expiresAt: Date
+    readonly now: Date
+  },
+): Promise<IdempotencyKeyRecord | undefined> {
+  const [reserved] = await db
+    .insert(idempotencyKeys)
+    .values({
+      id: params.id,
+      workspaceId: params.workspaceId,
+      key: params.key,
+      requestHash: params.requestHash,
+      response: null,
+      expiresAt: params.expiresAt,
+      createdAt: params.now,
+    })
+    .onConflictDoUpdate({
+      target: [idempotencyKeys.workspaceId, idempotencyKeys.key],
+      set: {
+        id: params.id,
+        requestHash: params.requestHash,
+        response: null,
+        expiresAt: params.expiresAt,
+        createdAt: params.now,
+      },
+      setWhere: lt(idempotencyKeys.expiresAt, params.now),
+    })
+    .returning()
+
+  return reserved
+}
+
+/** The live row for a key, whether its reservation is still in flight or answered. */
+export async function findIdempotencyKey(
+  db: Queryable,
+  workspaceId: string,
+  key: string,
+): Promise<IdempotencyKeyRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(idempotencyKeys)
+    .where(and(eq(idempotencyKeys.workspaceId, workspaceId), eq(idempotencyKeys.key, key)))
+    .limit(1)
+
+  return found
+}
+
+/** Fills in the reservation once the handler has answered. */
+export async function completeIdempotencyKey(
+  db: Queryable,
+  id: string,
+  response: StoredIdempotentResponse,
+): Promise<void> {
+  await db.update(idempotencyKeys).set({ response }).where(eq(idempotencyKeys.id, id))
+}
+
+/** Frees a reservation the handler failed to fill, so a retry is not blocked by it. */
+export async function deleteIdempotencyKey(db: Queryable, id: string): Promise<void> {
+  await db.delete(idempotencyKeys).where(eq(idempotencyKeys.id, id))
+}
+
+/**
+ * Clears this workspace's other expired keys.
+ *
+ * Enforced here rather than by a schedule, the same call as
+ * `webhooks/delivery.ts` makes about its delivery log: there is no scheduler in
+ * the service, and the table only grows through a reservation, so pruning on
+ * every reservation caps it where the growth happens. The residue is the same
+ * kind too — a key nobody replays keeps its row until the next reservation in
+ * that workspace sweeps it.
+ */
+export async function pruneExpiredIdempotencyKeys(
+  db: Queryable,
+  workspaceId: string,
+  now: Date,
+): Promise<number> {
+  const deleted = await db
+    .delete(idempotencyKeys)
+    .where(and(eq(idempotencyKeys.workspaceId, workspaceId), lt(idempotencyKeys.expiresAt, now)))
+    .returning({ id: idempotencyKeys.id })
+
+  return deleted.length
+}

package/src/modules/workspace/index.ts

@@ -0,0 +1,64 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { parseModuleCapability } from '../../runtime/moduleConfig.ts'
+import { SEATS_LIMIT } from './capabilities.ts'
+import * as repository from './repository.ts'
+import { mountWorkspaceRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createWorkspaceService } from './service.ts'
+import { registerWorkspaceTools } from './tools.ts'
+
+/**
+ * Workspaces, membership, and invites.
+ *
+ * Requires `auth`: `workspace_members.user_id` references `users`, and every
+ * route here resolves an actor from a session.
+ */
+export function createWorkspaceModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'workspace',
+    requires: ['auth'],
+    structural: true,
+
+    register(context) {
+      context.entitlements.declare(SEATS_LIMIT)
+
+      // Answers `module.<id>` for whatever a config override left undecided
+      // (`runtime/registry.ts` registers that provider first, ahead of this
+      // one, so a locked value never reaches this query).
+      context.entitlements.provide(async (workspaceId, capability) => {
+        const moduleId = parseModuleCapability(capability.name)
+
+        if (moduleId === undefined) {
+          return undefined
+        }
+
+        const setting = await repository.findModuleSetting(context.db, workspaceId, moduleId)
+
+        return setting === undefined ? undefined : { kind: 'flag', granted: setting.enabled }
+      })
+
+      const service = createWorkspaceService({
+        db: context.db,
+        transaction: context.transaction,
+        email: context.email,
+        createId: context.createId,
+        now: context.now,
+        entitlements: context.entitlements,
+        toggleableModuleIds: context.moduleCatalog
+          .filter((entry) => !entry.structural)
+          .map((entry) => entry.id),
+        moduleConfigOverrides: context.moduleConfig,
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountWorkspaceRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerWorkspaceTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}