tapimo 0.15.0 → 0.18.0

package/src/cli/Spec.test.ts

@@ -0,0 +1,133 @@
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import * as TestApp from '../../test/App.js'
+import * as Spec from './Spec.js'
+
+const url = 'http://localhost'
+
+async function temporaryFile() {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'tapimo-spec-'))
+  return Spec.cacheFile({ directory, url })
+}
+
+/** An in-process API whose requests and response statuses are recorded. */
+function api() {
+  const app = TestApp.create()
+  type Call = { ifNoneMatch: string | null; status: number }
+  const calls: Call[] = []
+  return {
+    calls,
+    fetch: async (request: Request) => {
+      const response = await app.fetch(request)
+      calls.push({ ifNoneMatch: request.headers.get('if-none-match'), status: response.status })
+      return response
+    },
+  }
+}
+
+function offline(): Promise<Response> {
+  return Promise.reject(new TypeError('fetch failed'))
+}
+
+// Accepts the request but never answers, like a hung API.
+function unresponsive(request: Request): Promise<Response> {
+  return new Promise((_, reject) =>
+    request.signal.addEventListener('abort', () => reject(request.signal.reason)),
+  )
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('cacheFile', () => {
+  test('names the file after the API host', () => {
+    expect(Spec.cacheFile({ directory: '/cache', url: 'http://localhost:47600' })).toBe(
+      '/cache/localhost_47600.openapi.json',
+    )
+    expect(Spec.cacheFile({ directory: '/cache', url: 'https://api.tempo.xyz/' })).toBe(
+      '/cache/api.tempo.xyz.openapi.json',
+    )
+  })
+})
+
+describe('load', () => {
+  test('caches the document and revalidates it with a 304 on the next load', async () => {
+    const file = await temporaryFile()
+    const server = api()
+
+    const first = await Spec.load({ fetch: server.fetch, file, url })
+    expect(first.status).toBe('current')
+    expect(Object.keys(first.document.paths ?? {}).length).toBeGreaterThan(0)
+
+    const second = await Spec.load({ fetch: server.fetch, file, url })
+    expect(second).toEqual(first)
+    expect(server.calls).toEqual([
+      { ifNoneMatch: null, status: 200 },
+      { ifNoneMatch: expect.stringMatching(/^"[0-9a-f]{32}"$/), status: 304 },
+    ])
+  })
+
+  test('creates the cache directory and missing parents privately', async () => {
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), 'tapimo-spec-'))
+    const file = Spec.cacheFile({ directory: path.join(home, 'api', 'cache'), url })
+    await Spec.load({ fetch: api().fetch, file, url })
+    for (const directory of [path.join(home, 'api'), path.dirname(file)])
+      expect((await fs.stat(directory)).mode & 0o777).toBe(0o700)
+  })
+
+  test('serves the cached document when the API is unreachable', async () => {
+    const file = await temporaryFile()
+    const { document } = await Spec.load({ fetch: api().fetch, file, url })
+
+    const result = await Spec.load({ fetch: offline, file, url })
+    expect(result.status).toBe('cached')
+    expect(result.document).toEqual(document)
+  })
+
+  test('serves the cached document when the API stops responding', async () => {
+    const file = await temporaryFile()
+    const { document } = await Spec.load({ fetch: api().fetch, file, url })
+
+    vi.useFakeTimers()
+    const called = Promise.withResolvers<void>()
+    const pending = Spec.load({
+      fetch: (request) => {
+        called.resolve()
+        return unresponsive(request)
+      },
+      file,
+      url,
+    })
+    await called.promise
+    await vi.advanceTimersByTimeAsync(5_000)
+    expect(await pending).toMatchObject({ document, status: 'cached' })
+  })
+
+  test('falls back to an empty document without a cache', async () => {
+    const result = await Spec.load({ fetch: offline, file: await temporaryFile(), url })
+    expect(result).toMatchObject({ document: { paths: {} }, status: 'missing' })
+  })
+
+  test('skips caching documents served without an ETag', async () => {
+    const file = await temporaryFile()
+    const result = await Spec.load({
+      fetch: async () => Response.json({ openapi: '3.1.0', paths: {} }),
+      file,
+      url,
+    })
+    expect(result.status).toBe('current')
+    await expect(fs.stat(file)).rejects.toThrow()
+  })
+
+  test('treats a corrupt cache as a miss', async () => {
+    const file = await temporaryFile()
+    await fs.mkdir(path.dirname(file), { recursive: true })
+    await fs.writeFile(file, '{not json')
+    const server = api()
+    expect((await Spec.load({ fetch: server.fetch, file, url })).status).toBe('current')
+    expect(server.calls).toEqual([{ ifNoneMatch: null, status: 200 }])
+  })
+})

package/src/cli/Spec.ts

@@ -0,0 +1,132 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import type { Openapi } from 'incur'
+import * as z from 'zod/mini'
+
+// A hung API must not stall every command, built-in ones included; past this the cached copy serves.
+const responseTimeout = 5_000
+
+/** Storage schemas for the cached API document. */
+export namespace schema {
+  /** A cached document and the entity tag it was served with. */
+  export const Entry = z.object({
+    document: z.custom<Openapi.OpenAPISpec>(
+      (value) => typeof value === 'object' && value !== null && !Array.isArray(value),
+    ),
+    etag: z.string(),
+  })
+}
+
+/** Cache file for an API's document under the CLI cache directory (`<directory>/<host>.openapi.json`). */
+export function cacheFile(options: cacheFile.Options): string {
+  const host = new URL(options.url).host.replace(/[^a-z0-9.-]/gi, '_')
+  return path.join(options.directory, `${host}.openapi.json`)
+}
+
+export declare namespace cacheFile {
+  /** Options for {@link cacheFile}. */
+  type Options = {
+    /** CLI cache directory. */
+    directory: string
+    /** Tempo API origin. */
+    url: string | URL
+  }
+}
+
+/**
+ * Loads a hosted API's OpenAPI document, revalidating the cached copy with its ETag so an
+ * unchanged document costs a 304. When the API is unreachable or slow to respond, the cached copy is served.
+ */
+export async function load(options: load.Options): Promise<load.Result> {
+  const { fetch = (request) => globalThis.fetch(request), file, url } = options
+  const cached = await read(file)
+
+  try {
+    const base = new URL(url)
+    if (!base.pathname.endsWith('/')) base.pathname = `${base.pathname}/`
+    const controller = new AbortController()
+    const timer = setTimeout(
+      () => controller.abort(new Error(`No response within ${responseTimeout / 1_000}s`)),
+      responseTimeout,
+    )
+    const response = await fetch(
+      new Request(new URL('openapi.json', base), {
+        headers: cached ? { 'if-none-match': cached.etag } : {},
+        signal: controller.signal,
+      }),
+    ).finally(() => clearTimeout(timer))
+    if (response.status === 304 && cached) return { document: cached.document, status: 'current' }
+    if (!response.ok)
+      throw new Error(`Failed to fetch the OpenAPI document: HTTP ${response.status}`)
+    const document = (await response.json()) as Openapi.OpenAPISpec
+    const etag = response.headers.get('etag')
+    // Without a validator the copy could never be revalidated, so it is not worth keeping.
+    if (etag) await write(file, { document, etag })
+    return { document, status: 'current' }
+  } catch (error) {
+    if (cached) return { document: cached.document, error, status: 'cached' }
+    return { document: { paths: {} }, error, status: 'missing' }
+  }
+}
+
+export declare namespace load {
+  /** Options for {@link load}. */
+  type Options = {
+    /** Sends requests to the Tempo API. @default globalThis.fetch */
+    fetch?: ((request: Request) => Promise<Response>) | undefined
+    /** Cache file for this API's document. */
+    file: string
+    /** Tempo API origin. */
+    url: string | URL
+  }
+
+  /** The loaded document and where it came from. */
+  type Result =
+    | {
+        /** The API's current document. */
+        document: Openapi.OpenAPISpec
+        /** Served by the API, or confirmed unchanged by a 304. */
+        status: 'current'
+      }
+    | {
+        /** The last cached document. */
+        document: Openapi.OpenAPISpec
+        /** Why the API could not be reached. */
+        error: unknown
+        /** The API was unreachable, so the cached copy was served. */
+        status: 'cached'
+      }
+    | {
+        /** An empty document, so only built-in commands are available. */
+        document: Openapi.OpenAPISpec
+        /** Why the API could not be reached. */
+        error: unknown
+        /** The API was unreachable and nothing was cached. */
+        status: 'missing'
+      }
+}
+
+type Entry = z.output<typeof schema.Entry>
+
+async function read(file: string): Promise<Entry | undefined> {
+  const text = await fs.readFile(file, 'utf8').catch(() => undefined)
+  if (text === undefined) return undefined
+  // A corrupt cache is a miss, never an error.
+  const parsed = (() => {
+    try {
+      return schema.Entry.safeParse(JSON.parse(text))
+    } catch {
+      return undefined
+    }
+  })()
+  return parsed?.success ? parsed.data : undefined
+}
+
+async function write(file: string, entry: Entry) {
+  // Private like the credentials directory, which this may create first as a parent.
+  await fs.mkdir(path.dirname(file), { mode: 0o700, recursive: true })
+  // Write then rename so a concurrent run never reads a truncated document.
+  const temporary = `${file}.${process.pid}.tmp`
+  await fs.writeFile(temporary, JSON.stringify(entry))
+  await fs.rename(temporary, file)
+}

package/src/cli/bin.test.ts

@@ -0,0 +1,49 @@
+import * as child_process from 'node:child_process'
+import * as fs from 'node:fs/promises'
+import * as http from 'node:http'
+import type * as net from 'node:net'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as url from 'node:url'
+import * as util from 'node:util'
+
+const execFile = util.promisify(child_process.execFile)
+const root = url.fileURLToPath(new URL('../..', import.meta.url))
+
+describe('tapimo', () => {
+  test('runs admin commands without fetching the API document', async () => {
+    const api = await listen()
+    try {
+      await tapimo(['admin', '--help'], api.url)
+      expect(api.requests).toEqual([])
+
+      await tapimo(['--help'], api.url)
+      expect(api.requests).toEqual(['/openapi.json'])
+    } finally {
+      api.server.close()
+    }
+  })
+})
+
+/** A local API that records request paths and serves an empty document. */
+async function listen() {
+  const requests: string[] = []
+  const server = http.createServer((request, response) => {
+    requests.push(request.url ?? '')
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({ openapi: '3.1.0', paths: {} }))
+  })
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const { port } = server.address() as net.AddressInfo
+  return { requests, server, url: `http://127.0.0.1:${port}` }
+}
+
+// Run it the way `pnpm -C apps/api migrate` does; the repo root does not install tsx.
+async function tapimo(args: readonly string[], apiUrl: string) {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'tapimo-bin-'))
+  return execFile(
+    path.join(root, 'apps', 'api', 'node_modules', '.bin', 'tsx'),
+    [path.join(root, 'src', 'cli', 'bin.ts'), ...args],
+    { cwd: root, env: { ...process.env, TEMPO_API_URL: apiUrl, TEMPO_HOME: home } },
+  )
+}

package/src/cli/bin.ts

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
 import * as Cli from './Cli.js'
+import * as Admin from './commands/admin.js'
 
-await Cli.from('https://api.tempo.xyz').serve()
+// Admin commands only need the database, so they never wait on the hosted API document.
+const admin = process.argv[2] === 'admin'
+const cli = await Cli.fromEnv(process.env, admin ? { openapi: { paths: {} } } : {})
+await cli.command(Admin.admin).serve()

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

@@ -0,0 +1,138 @@
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import * as TestCli from '../../../test/cli.js'
+import * as Cli from '../Cli.js'
+import * as Credentials from '../Credentials.js'
+
+describe('login', () => {
+  test('stores a CLI session that acts as the approving user', async () => {
+    const context = await TestCli.create()
+    const { code, cookie, lines } = await TestCli.login(context)
+    expect(code).toBe(0)
+
+    const records = lines.map((line) => JSON.parse(line))
+    const chunks = records.filter((record) => record.type === 'chunk').map(({ data }) => data)
+    expect(chunks[0]).toMatchObject({
+      code: expect.stringMatching(/^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/),
+      verificationUrl: expect.stringMatching(/^https:\/\/console\.tempo\.xyz\/cli\?code=/),
+    })
+    expect(chunks.at(-1)).toMatchObject({ apiUrl: TestCli.origin })
+    expect(records.at(-1)).toMatchObject({ ok: true, type: 'done' })
+
+    const session = await context.credentials.get(TestCli.origin)
+    expect(session?.token).toMatch(/^tempo:cli:[a-f0-9]{64}$/)
+    const me = await context.app.request('/v1/me', { headers: { cookie } })
+    expect(session?.userId).toBe(((await me.json()) as { id: string }).id)
+  })
+
+  test('fails when the console denies the request', async () => {
+    const context = await TestCli.create()
+    const { code, lines } = await TestCli.login(context, { decision: 'deny' })
+    expect(code).toBe(1)
+    expect(lines.at(-1)).toContain('login_denied')
+    expect(await context.credentials.get(TestCli.origin)).toBeUndefined()
+  })
+
+  test('revokes the new session when the account cannot load', async () => {
+    const context = await TestCli.create({
+      intercept: (request) =>
+        new URL(request.url).pathname === '/v1/me'
+          ? new Response(null, { status: 503 })
+          : undefined,
+    })
+    const { code, lines } = await TestCli.login(context)
+    expect(code).toBe(1)
+    expect(lines.at(-1)).toContain('login_failed')
+    expect(await context.credentials.get(TestCli.origin)).toBeUndefined()
+
+    const logout = context.requests.find(
+      (request) => new URL(request.url).pathname === '/v1/auth/logout',
+    )
+    const authorization = logout?.headers.get('authorization') ?? ''
+    expect(authorization).toMatch(/^Bearer tempo:cli:[a-f0-9]{64}$/)
+    const me = await context.app.request('/v1/me', { headers: { authorization } })
+    expect(me.status).toBe(401)
+  })
+
+  test('revokes the previous session when signing in again', async () => {
+    const context = await TestCli.create()
+    const { cookie } = await TestCli.login(context)
+    const first = (await context.credentials.get(TestCli.origin))?.token
+    await TestCli.login(context, { cookie })
+    const second = (await context.credentials.get(TestCli.origin))?.token
+    expect(second).not.toBe(first)
+
+    const me = (token: string | undefined) =>
+      context.app.request('/v1/me', { headers: { authorization: `Bearer ${token}` } })
+    expect((await me(first)).status).toBe(401)
+    expect((await me(second)).status).toBe(200)
+  })
+})
+
+describe('whoami', () => {
+  test('shows the signed-in account', async () => {
+    const context = await TestCli.create()
+    await TestCli.login(context)
+    const { code, lines } = await TestCli.serve(context.cli, ['whoami', '--format', 'json'])
+    expect(code).toBe(0)
+    const { expiresAt, userId, ...output } = JSON.parse(lines.join('\n'))
+    expect(Date.parse(expiresAt)).toBeGreaterThan(Date.now())
+    expect(userId).toBe((await context.credentials.get(TestCli.origin))?.userId)
+    expect(output).toEqual({ apiUrl: TestCli.origin })
+  })
+
+  test('asks to sign in when no session is stored', async () => {
+    const { cli } = await TestCli.create()
+    const { code, lines } = await TestCli.serve(cli, ['whoami', '--format', 'json'])
+    expect(code).toBe(1)
+    expect(lines.join('\n')).toContain('not_signed_in')
+  })
+})
+
+describe('logout', () => {
+  test('revokes the session server-side and forgets it', async () => {
+    const context = await TestCli.create()
+    await TestCli.login(context)
+    const token = (await context.credentials.get(TestCli.origin))?.token
+
+    const { code, lines } = await TestCli.serve(context.cli, ['logout', '--format', 'json'])
+    expect(code).toBe(0)
+    expect(JSON.parse(lines.join('\n'))).toEqual({
+      apiUrl: TestCli.origin,
+      keysRevoked: true,
+      revoked: true,
+      signedOut: true,
+    })
+    expect(await context.credentials.get(TestCli.origin)).toBeUndefined()
+    const me = await context.app.request('/v1/me', {
+      headers: { authorization: `Bearer ${token}` },
+    })
+    expect(me.status).toBe(401)
+  })
+
+  test('revokes through the API base path', async () => {
+    const apiUrl = 'https://api.tempo-api.test/base'
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'tapimo-cli-'))
+    const credentials = Credentials.store({ file: path.join(directory, 'credentials.json') })
+    await credentials.set(new URL(apiUrl), {
+      expiresAt: '2099-01-01T00:00:00.000Z',
+      token: `tempo:cli:${'ab'.repeat(32)}`,
+      userId: 'usr_1a2b3c4d5e6f7g8h9j0k1m2n',
+    })
+    const requests: string[] = []
+    const cli = Cli.from(apiUrl, {
+      credentials,
+      docs: false,
+      fetch: async (request) => {
+        requests.push(new URL(request.url).pathname)
+        return new Response(null, { status: 204 })
+      },
+      openapi: { paths: {} },
+    })
+
+    await TestCli.serve(cli, ['logout'])
+    expect(requests).toEqual(['/base/v1/auth/logout'])
+  })
+})