tapimo 0.0.2 → 0.2.0

package/src/{Cli.test.ts → cli/Cli.test.ts}

@@ -1,6 +1,7 @@
-import { Cli } from 'cadent'
-import * as TestApp from '../test/App.js'
-import * as Runtime from '../test/runtime.js'
+import { Cli } from 'tapimo'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
 
 const apiUrl = 'https://api.tempo-api.test'
 
@@ -12,7 +13,7 @@ describe('from', () => {
       const cli = Cli.from(apiUrl, { version: '1.2.3' })
       await serve(cli, ['--help'])
 
-      expect(cli.name).toMatchInlineSnapshot(`"tempo-api"`)
+      expect(cli.name).toMatchInlineSnapshot(`"tapimo"`)
       expect(cli.description).toMatchInlineSnapshot(`"Tempo API CLI"`)
     } finally {
       fetch.mockRestore()
@@ -20,11 +21,11 @@ describe('from', () => {
   })
 
   test('serves the hosted Tempo API command', async () => {
-    // Verified tokens are KV/store-backed (no bundled fallback), so seed the
-    // store for the default chain to exercise the `--verified` listing.
-    const fetch = mockHostedApi(
-      TestApp.create({ verifiedTokens: { store: TestApp.verifiedStore(Runtime.get().chainId) } }),
-    )
+    // Verified tokens are database-backed (no bundled fallback), so seed the
+    // db for the default chain to exercise the `--verified` listing.
+    const db = TestApp.database()
+    await TestApp.verifiedSeed(db, Runtime.get().chainId)
+    const fetch = mockHostedApi(TestApp.create({ db }))
 
     try {
       const cli = Cli.from(apiUrl)

package/src/{Cli.ts → cli/Cli.ts}

@@ -1,22 +1,29 @@
 import { Cli as incur_Cli, Fetch, type Openapi } from 'incur'
 
-/** Creates an incur CLI backed by a hosted Tempo API. */
+import * as Admin from './commands/admin.js'
+
+/**
+ * Creates an incur CLI backed by a hosted Tempo API, plus the super admin
+ * commands (`<cli> admin …`).
+ */
 export function from(url: string | URL, options: from.Options = {}) {
   const {
     description = 'Tempo API CLI',
-    name = 'tempo-api',
+    name = 'tapimo',
     openapi = 'openapi.json',
     request,
     version = '0.0.0',
   } = options
 
-  return incur_Cli.create(name, {
-    description,
-    fetch: Fetch.fromRequest(url, request),
-    openapi,
-    openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
-    version,
-  })
+  return incur_Cli
+    .create(name, {
+      description,
+      fetch: Fetch.fromRequest(url, request),
+      openapi,
+      openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
+      version,
+    })
+    .command(Admin.admin)
 }
 
 export declare namespace from {

package/src/cli/bin.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import * as Cli from './Cli.js'
+
+await Cli.from('https://api.tempo.xyz').serve()

package/src/cli/commands/admin.test.ts

@@ -0,0 +1,71 @@
+import { nanoid } from 'nanoid'
+
+import * as TestCli from '../../../test/cli.js'
+
+describe('admin', () => {
+  describe('migrate', () => {
+    test('behavior: applies migrations', async () => {
+      const { code, envelope } = await TestCli.run([
+        'admin',
+        'migrate',
+        '--db-schema',
+        `t_${nanoid()}`,
+      ])
+      expect(code).toBe(0)
+      expect(envelope).toMatchInlineSnapshot(`
+        {
+          "data": {
+            "migrated": true,
+          },
+          "ok": true,
+        }
+      `)
+    })
+
+    test('behavior: applies migrations from DATABASE_URL without a schema option', async () => {
+      const { code, envelope } = await TestCli.run(['admin', 'migrate'])
+      expect(code).toBe(0)
+      expect(envelope).toEqual({ data: { migrated: true }, ok: true })
+    })
+
+    test('behavior: is idempotent across runs', async () => {
+      const schema = `t_${nanoid()}`
+      expect((await TestCli.run(['admin', 'migrate', '--db-schema', schema])).code).toBe(0)
+      const { code, envelope } = await TestCli.run(['admin', 'migrate', '--db-schema', schema])
+      expect(code).toBe(0)
+      expect(envelope).toEqual({ data: { migrated: true }, ok: true })
+    })
+
+    test('error: a missing connection string exits 1', async () => {
+      const { code, envelope } = await TestCli.run(['admin', 'migrate'], {
+        DATABASE_URL: undefined,
+      })
+      expect(code).toBe(1)
+      expect(envelope).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "missing_database_url",
+            "message": "Set --database-url or DATABASE_URL to the Postgres connection string.",
+          },
+          "ok": false,
+        }
+      `)
+    })
+
+    test('error: a migration failure exits 1', async () => {
+      const { code, envelope } = await TestCli.run(
+        [
+          'admin',
+          'migrate',
+          '--database-url',
+          'postgres://postgres:postgres@127.0.0.1:1/tempo-api',
+          '--db-schema',
+          `t_${nanoid()}`,
+        ],
+        { DATABASE_URL: undefined },
+      )
+      expect(code).toBe(1)
+      expect(envelope.error.code).toBe('migrate_failed')
+    })
+  })
+})

package/src/cli/commands/admin.ts

@@ -0,0 +1,60 @@
+import { Cli as incur_Cli, z } from 'incur'
+
+import * as Db from '../../db/Db.js'
+
+/**
+ * Applies pending Postgres migrations, connecting directly via
+ * `--database-url` or `DATABASE_URL` (never through Hyperdrive — the migrate
+ * advisory lock needs session semantics); `--db-schema` scopes the session.
+ */
+const migrate = incur_Cli.create('migrate', {
+  description: 'Apply pending database migrations.',
+  env: z.object({
+    DATABASE_URL: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Used when --database-url is omitted.'),
+  }),
+  options: z.object({
+    databaseUrl: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Overrides DATABASE_URL.'),
+    dbSchema: z.string().optional().describe('Postgres schema to create and scope the session to.'),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString)
+      return c.error({
+        code: 'missing_database_url',
+        message: 'Set --database-url or DATABASE_URL to the Postgres connection string.',
+      })
+    const db = Db.postgres({
+      connectionString,
+      ...(c.options.dbSchema ? { schema: c.options.dbSchema } : {}),
+    })
+    try {
+      await db.migrate()
+      return { migrated: true }
+    } catch (error) {
+      /* v8 ignore next */
+      const message = error instanceof Error ? error.message : 'Migration failed.'
+      return c.error({
+        code: 'migrate_failed',
+        message,
+      })
+    } finally {
+      await db.close()
+    }
+  },
+})
+
+/**
+ * Super admin commands that run against a deployment's infrastructure rather
+ * than the hosted API (database migrations, …).
+ */
+export const admin = incur_Cli
+  .create('admin', {
+    description: 'Super admin commands for a Tempo API deployment.',
+  })
+  .command(migrate)

package/src/cloudflare.ts

@@ -52,4 +52,14 @@ export class DurableObject extends CloudflareDurableObject {
   async put(key: string, value: string, options?: Store.Store.PutOptions) {
     await this.#store.put(key, value, options)
   }
+
+  /**
+   * Atomically compares-and-swaps a value.
+   *
+   * The compare and write run on the object's single thread behind its input
+   * gate, so concurrent callers cannot interleave between them.
+   */
+  async swap(key: string, expected: null | string, next: string, options?: Store.Store.PutOptions) {
+    return this.#store.swap!(key, expected, next, options)
+  }
 }

package/src/db/Db.test.ts

@@ -0,0 +1,84 @@
+import { nanoid } from 'nanoid'
+
+import { postgresUrl } from '../../test/containers.js'
+import * as Db from './Db.js'
+import * as Organizations from './tables/organizations.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+describe('postgres', () => {
+  test('behavior: migrate is idempotent', async () => {
+    const db = create()
+    await db.migrate()
+    await db.migrate()
+    expect(await Organizations.get(db, 'missing')).toBeUndefined()
+    await db.close()
+  })
+
+  test('behavior: creates a Postgres db without schema scoping', async () => {
+    const db = Db.postgres({ connectionString: postgresUrl })
+    await db.close()
+  })
+
+  test('behavior: concurrent migrate tolerates the ledger race', async () => {
+    const schema = `t_${nanoid()}`
+    // Pre-create the schema so concurrent migrate races only on the
+    // `migrations` ledger, not `CREATE SCHEMA`.
+    const seed = Db.postgres({ connectionString: postgresUrl, schema })
+    await Organizations.get(seed, 'x').catch(() => {})
+    await seed.close()
+
+    // Several runners migrate the same fresh schema at once (mirrors parallel
+    // deploys). The session advisory lock serializes them; none throw.
+    const dbs = Array.from({ length: 5 }, () =>
+      Db.postgres({ connectionString: postgresUrl, schema }),
+    )
+    await Promise.all(dbs.map((db) => db.migrate()))
+    const created = await Organizations.create(dbs[0]!, { id: 'org_race', name: 'Race' })
+    expect(created.id).toBe('org_race')
+    await Promise.all(dbs.map((db) => db.close()))
+  })
+
+  test('error: rejects a modified applied migration', async () => {
+    const db = create()
+    await db.migrate()
+    await db.kysely
+      .updateTable('migrations')
+      .set({ checksum: '00000000' })
+      .where('name', '=', Db.migrations[0]!.name)
+      .execute()
+    await expect(db.migrate()).rejects.toThrow(/checksum mismatch/)
+    await db.close()
+  })
+
+  test('behavior: transaction rolls back on throw', async () => {
+    const db = create()
+    await db.migrate()
+    await expect(
+      db.transaction(async (tx) => {
+        await Organizations.create(tx, { id: 'org_2', name: 'Roll' })
+        throw new Error('boom')
+      }),
+    ).rejects.toThrow('boom')
+    expect(await Organizations.get(db, 'org_2')).toBeUndefined()
+    await db.close()
+  })
+
+  test('error: transaction rejects nesting', async () => {
+    const db = create()
+    await db.migrate()
+    await expect(db.transaction(() => db.transaction(async () => 1))).rejects.toThrow(/nesting/)
+    await db.close()
+  })
+
+  test('behavior: transaction commits and returns the value', async () => {
+    const db = create()
+    await db.migrate()
+    const id = await db.transaction(
+      async (tx) => (await Organizations.create(tx, { id: 'org_3', name: 'Commit' })).id,
+    )
+    expect(id).toBe('org_3')
+    expect((await Organizations.get(db, 'org_3'))?.name).toBe('Commit')
+    await db.close()
+  })
+})