feat(db): shared cloud usage queries (M1)

Merged
SA
21h ago
+1039-2

What and why

M1 adds the read side that the customer cloud router (M2) and the admin app's cloud router (A2) share. It is one file, packages/db/src/cloud-usage-query.ts, a sibling of task-list-query.ts. It holds query functions and the plain TypeScript types of what they take and return. It has no zod, no API contract, and no imports from packages/auth or the Autumn client. The admin repo vendors db and shared, not trpc, so these must run whole queries rather than build conditions for a router.

Scope change (agreed with the coordinator): periods are built in each router from cloudBillingPeriod plus queryCloudUsage.

  • queryCloudUsage(db, scope, { window, filters?, groupBy?, limit, cursor?, overagePerGbHour }) returns billed usage (cloud_usage_events, box_gb_minutes, placed by sent_at) and boot counts (placed by started_at). It gives a total, and with groupBy one row per user, UTC day or workspace.
  • A workspace that failed in the window, even with no boot, counts as 1 in workspaces in every grouping and in the total. Grouped by workspace it has its own row with failure { reason, at }; by user it falls under its creator, and by day under failed_at.
  • Paging by amount reads at each call, so an event sent between pages can move a row across the cursor. The doc line says so. Paging by day and paging boots are stable.
  • listCloudBoots(db, scope, { window, filters?, endReason?, open?, limit, cursor?, now, overagePerGbHour }) returns boot rows, newest first, each with the sum of its sent events. Failed and released boots show zero usage.
  • cloudBillingPeriod(anchor, index) and cloudBillingPeriodIndex(anchor, startDate) hold the month arithmetic for billing periods, shared by both routers and by { period } ranges. Autumn's data shows it resets on a fixed day of the month, or on the last day of a shorter month. previousResetAt settles the day when resetsAt is a short month's last day.
  • With scope.userId set, every result has only that user's rows.
  • Cursors are typed keyset objects that the router validates, like task.listPage:
    • CloudUsageCursor.gbMinutes is decimal digits with an optional fraction, cast to numeric in SQL.
    • CloudBootCursor is { startedAt: Date, id }. It is exact because cloud_workspace_boots.started_at is always written from a JS Date (millisecond precision, in meter.ts); the cursor relies on that.
  • Results contain Date values (superjson carries them). usageUsd is gbHours × the caller's overagePerGbHour, rounded to cents once, at output.
  • There is one plain result type per function (CloudUsageResult, CloudBootsResult), and it is the shared contract. Each router ties its own zod output schema to it with satisfies z.ZodType<…>, so drift fails typecheck.

Preparation (own commits):

  • packages/db had test files but no test script, so CI never ran them; this adds the script, and a test preload with a placeholder DATABASE_URL (as in packages/trpc), because seed-default-statuses.test.ts imports the db client.
  • LEGACY_MACHINE_SIZE in @superset/shared/billing replaces the inline "large" in the sandbox claim. No change in behaviour.

Tests run on PGlite, an in-process Postgres 17. DDL is built from the drizzle definitions for only the seeded tables and their foreign-key parents. The file runs in about 2 s; about 1.6 s of that is PGlite starting. It needs no server, so the tests run in the CI unit job. The new dev dependency is @electric-sql/pglite, pinned exactly and imported only by the test. There is one test per behaviour: totals, grouping, a failed workspace with no boot, the sent_at window edge, boots, the scope rule, cursors (including a started_at tie), and billing periods through short months.

Not in this PR: an index on cloud_workspace_boots (organization_id, started_at, id). It goes to the next migration.

What breaks and for whom

Nothing. The PR adds one file, one export path, one dev dependency and one constant. It adds no router and changes no procedure. The admin app gets the code on its next deploy.

Links

Summary by CodeRabbit

  • New Features
    • Added cloud usage reporting with organization and member scoping, filtering, grouping, and pagination.
    • Added cloud boot listings with usage, duration, machine details, and overage cost estimates.
    • Added billing-period calculations that handle month-end dates.
  • Tests
    • Added coverage for usage and boot queries, filtering, pagination, and billing-period calculations.