From d8a5aa66e8a8fe7850569dcb69dcfa3269fff0d9 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Fri, 13 Nov 2026 21:05:20 +0800 Subject: [PATCH] Publish AI logging settings from the installer and show them in the CLI - Every install, upgrade and repair copies each project's AI logging setting from Postgres to ROUTING KV, once before the Worker upload (the new proxy may go live first) and once after it (the old API may have saved changes meanwhile). It holds the same project row locks as the API, stamps keys with the database clock, and uses new bulk KV list, put and delete calls. - `void platform project ai-logging` prints where the setting comes from and when new requests are expected to follow it; `project show` prints the effective mode, its source and its state. - `void platform config plans` accepts `aiLogging` in plan files and the picker, shows it in diffs, and keeps running `sync` until the AI logging publish is complete. - The end-to-end test runs the built CLI against the real proxy without the uncached-database flag. Refs #793. Co-Authored-By: Claude Opus 5.5 --- packages/void/src/cli/client.ts | 10 +- packages/void/src/cli/help.ts | 9 +- packages/void/src/cli/operator-ai-logging.ts | 169 ++++++++ packages/void/src/cli/operator-args.ts | 6 +- packages/void/src/cli/operator-cmd.ts | 38 +- .../src/cli/platform-ai-logging-projection.ts | 249 ++++++++++++ packages/void/src/cli/platform-cloudflare.ts | 92 +++++ .../src/cli/platform-install-provisioning.ts | 13 + .../src/cli/platform-installer-database.ts | 3 + .../void/src/cli/platform-installer-types.ts | 15 + packages/void/src/cli/platform-installer.ts | 10 + packages/void/src/cli/platform-management.ts | 1 + .../void/src/cli/platform-plans-config.ts | 225 +++++++++-- packages/void/test/unit/operator-cli.test.ts | 205 ++++++++++ .../platform-ai-logging-projection.test.ts | 373 ++++++++++++++++++ .../test/unit/platform-cloudflare.test.ts | 83 ++++ .../platform-deployment-execution.test.ts | 3 + .../unit/platform-install-cutover.test.ts | 18 + .../void/test/unit/platform-installer.test.ts | 117 ++++++ .../unit/platform-management-upgrade.test.ts | 4 + .../test/unit/platform-plans-config.test.ts | 225 +++++++++++ .../test/integration/operator-cli-e2e.test.ts | 35 +- 22 files changed, 1855 insertions(+), 48 deletions(-) create mode 100644 packages/void/src/cli/operator-ai-logging.ts create mode 100644 packages/void/src/cli/platform-ai-logging-projection.ts create mode 100644 packages/void/test/unit/platform-ai-logging-projection.test.ts diff --git a/packages/void/src/cli/client.ts b/packages/void/src/cli/client.ts index fdc2e125b..83293aff8 100644 --- a/packages/void/src/cli/client.ts +++ b/packages/void/src/cli/client.ts @@ -61,12 +61,12 @@ type PlatformVersionProbe = | { kind: 'unknown' }; /** - * Returns whether `version` is older than MIN_PLATFORM_VERSION, or null when - * it is not a release version. A prerelease sorts before its release. + * Returns whether `version` is older than the release `minimumVersion`, or null + * when it is not a release version. A prerelease sorts before its release. */ -function isOlderThanMinimumPlatform(version: string): boolean | null { +export function isOlderPlatformVersion(version: string, minimumVersion: string): boolean | null { const actual = RELEASE_VERSION.exec(version); - const minimum = RELEASE_VERSION.exec(MIN_PLATFORM_VERSION)!; + const minimum = RELEASE_VERSION.exec(minimumVersion)!; if (!actual) { return null; } @@ -99,7 +99,7 @@ function assertSupportedPlatform(apiUrl: string, probe: PlatformVersionProbe): v // comes from a hosted deployment that does not set PLATFORM_VERSION yet. // Any other value that is not a release version comes from a custom or // development build and cannot be ordered. Both pass. - if (version === 'hosted' || isOlderThanMinimumPlatform(version) !== true) { + if (version === 'hosted' || isOlderPlatformVersion(version, MIN_PLATFORM_VERSION) !== true) { return; } throw new Error( diff --git a/packages/void/src/cli/help.ts b/packages/void/src/cli/help.ts index 170113af8..a69948db2 100644 --- a/packages/void/src/cli/help.ts +++ b/packages/void/src/cli/help.ts @@ -337,7 +337,7 @@ const HELP_TREE: HelpTree = { }, { command: 'set ', - description: 'Edit a plan name, limits, or build instance size', + description: 'Edit a plan name, limits, build size, or AI Gateway logging default', }, { command: 'reset ', @@ -356,7 +356,10 @@ const HELP_TREE: HelpTree = { description: 'Remove an unused plan or move its accounts to a replacement', }, { command: 'default ', description: 'Choose the plan new accounts receive' }, - { command: 'sync', description: 'Continue pending account limit updates' }, + { + command: 'sync', + description: 'Continue pending account limit and AI logging updates', + }, ], options: [ { @@ -365,7 +368,7 @@ const HELP_TREE: HelpTree = { }, { command: '--file ', - description: 'Read plan settings and partial limits from JSON', + description: 'Read plan settings, partial limits, and aiLogging from JSON', }, { command: '--name ', diff --git a/packages/void/src/cli/operator-ai-logging.ts b/packages/void/src/cli/operator-ai-logging.ts new file mode 100644 index 000000000..0d117050c --- /dev/null +++ b/packages/void/src/cli/operator-ai-logging.ts @@ -0,0 +1,169 @@ +import { AI_LOGGING_SETTLE_MS } from '@void/platform/ai-logging'; +import { cfAccessHeaders } from '../shared/cf-access.ts'; +import { ensurePlatformAccessToken } from './cf-access.ts'; +import { OperatorClientError } from './operator-client.ts'; +import { sanitizeTerminalText } from './output.ts'; +import { readPlatformDiscoveryResponse } from './platform-discovery.ts'; + +/** The first platform release with per-project AI logging settings. */ +export const AI_LOGGING_PLATFORM_VERSION = '1.8.0'; + +type Fields = Record; + +function text(value: unknown): string { + return typeof value === 'string' ? sanitizeTerminalText(value) : ''; +} + +function record(value: unknown): Fields | null { + return value && typeof value === 'object' && !Array.isArray(value) ? (value as Fields) : null; +} + +/** `14:03:20 UTC`, or null when the value is not a time. */ +export function utcTime(value: unknown, offsetMs = 0): string | null { + const time = typeof value === 'string' ? Date.parse(value) : Number.NaN; + if (Number.isNaN(time)) { + return null; + } + return `${new Date(time + offsetMs).toISOString().slice(11, 19)} UTC`; +} + +/** `plan "pro"`, naming the default plan an unknown plan ID follows. */ +function planLabel(fields: Fields): string { + const plan = `plan "${text(fields.planId)}"`; + if (fields.planKnown === false) { + return `${plan} (not in catalog; uses default plan "${text(fields.defaultPlanId)}")`; + } + return plan; +} + +/** Where the effective mode comes from, or null for a platform that does not say. */ +function sourceText(fields: Fields): string | null { + if (typeof fields.planId !== 'string') { + return null; + } + const planDefault = `${planLabel(fields)} default: ${text(fields.planMode) || 'inherit'}`; + switch (fields.source) { + case 'project': + return `set on project; ${planDefault}`; + case 'plan': + return `from ${planLabel(fields)}`; + case 'gateway': + return `AI Gateway setting; ${planDefault}`; + default: + return null; + } +} + +function effective(fields: Fields): string { + return text(fields.effective) || text(fields.mode); +} + +function withSource(mode: string, fields: Fields): string { + const source = sourceText(fields); + return source ? `${mode} (${source})` : mode; +} + +/** The `project ai-logging` result: the setting and when new requests follow it. */ +export function aiLoggingChangeLines(projectId: string, result: Fields): Array { + const lines = [ + `AI logging for ${sanitizeTerminalText(projectId)}: ${withSource(effective(result), result)}`, + ]; + const expectedBy = utcTime(result.expectedBy); + if (expectedBy) { + lines.push( + `New AI requests are expected to follow it by ${expectedBy} (normally within 2 minutes).`, + ); + } + return lines; +} + +/** The `project ai-logging --plan` preview: current and new effective modes. */ +export function aiLoggingPreviewLines(projectId: string, preview: Fields): Array { + const previous = text(preview.previous); + const next = effective(preview); + const change = previous ? `${previous} → ${next}` : next; + return [ + `AI logging for ${sanitizeTerminalText(projectId)}: ${withSource(change, preview)}`, + 'No change was made. Run the command again without --plan to apply it.', + ]; +} + +const STATES: Record string> = { + applied: () => 'applied', + pending: (fields) => { + const by = utcTime(fields.publishedAt, AI_LOGGING_SETTLE_MS); + return by ? `pending (expected by ${by})` : 'pending (normally within 2 minutes)'; + }, + pending_plan_publish: () => 'pending (the plan default is still being published)', + drift: (fields) => `drift (published: ${text(fields.published) || 'unknown value'})`, + unknown: () => 'state unknown (the published setting could not be read)', +}; + +/** + * `project show` line, such as `metadata (from plan "pro") — applied`, or null + * when the response has no AI logging data. + */ +export function aiLoggingStatusLine(value: unknown): string | null { + const fields = record(value); + if (!fields || typeof fields.mode !== 'string') { + return null; + } + const state = + typeof fields.state === 'string' && Object.hasOwn(STATES, fields.state) + ? STATES[fields.state] + : undefined; + const summary = withSource(effective(fields), fields); + return `AI Gateway logging: ${state ? `${summary} — ${state(fields)}` : summary}`; +} + +type DiscoveryProbe = { kind: 'version'; version: string } | { kind: 'missing' | 'unknown' }; + +async function probePlatformVersion(origin: string): Promise { + ensurePlatformAccessToken(origin); + let response: Response; + try { + response = await fetch(`${origin}/.well-known/void-platform`, { + headers: { Accept: 'application/json', ...cfAccessHeaders(process.env, origin) }, + redirect: 'manual', + signal: AbortSignal.timeout(15_000), + }); + } catch { + return { kind: 'unknown' }; + } + if (response.status === 404) { + await response.body?.cancel(); + return { kind: 'missing' }; + } + try { + return { + kind: 'version', + version: (await readPlatformDiscoveryResponse(origin, response)).platformVersion, + }; + } catch { + return { kind: 'unknown' }; + } +} + +/** + * Refuses `project ai-logging` on a platform before AI logging settings existed. + * It reads the platform version instead of guessing from a 404, because "Project + * not found" is also a 404. When the version cannot be read, the request runs and + * reports its own error. + */ +export async function assertAiLoggingPlatform(origin: string): Promise { + const probe = await probePlatformVersion(origin); + if (probe.kind === 'unknown') { + return; + } + if (probe.kind === 'version') { + const { isOlderPlatformVersion } = await import('./client.ts'); + // "hosted" and development builds are not release versions and pass. + if (isOlderPlatformVersion(probe.version, AI_LOGGING_PLATFORM_VERSION) !== true) { + return; + } + } + throw new OperatorClientError( + 'This platform does not support AI logging policies. Run `void platform upgrade`.', + 'unsupported', + ); +} diff --git a/packages/void/src/cli/operator-args.ts b/packages/void/src/cli/operator-args.ts index 79e39d5ce..70f715132 100644 --- a/packages/void/src/cli/operator-args.ts +++ b/packages/void/src/cli/operator-args.ts @@ -104,7 +104,7 @@ export const operatorCommands: Array = [ { group: 'project', action: 'show', - description: 'Inspect a project and its resources', + description: 'Inspect a project, its resources, and its effective AI Gateway logging', path: '/projects/:id', positional: ['id'], }, @@ -127,9 +127,11 @@ export const operatorCommands: Array = [ { group: 'project', action: 'ai-logging', - description: 'Set AI Gateway logging: inherit, off, metadata, or full', + description: + 'Set AI Gateway logging (inherit, off, metadata, or full); new AI requests normally follow it within 2 minutes', path: '/projects/:id/ai-logging', positional: ['id', 'mode'], + usage: ['void platform project ai-logging [options]'], method: 'POST', }, { diff --git a/packages/void/src/cli/operator-cmd.ts b/packages/void/src/cli/operator-cmd.ts index 2bb5b2ab9..9876af11a 100644 --- a/packages/void/src/cli/operator-cmd.ts +++ b/packages/void/src/cli/operator-cmd.ts @@ -1,6 +1,12 @@ import { createHash } from 'node:crypto'; import { createInterface } from 'node:readline/promises'; import { setTimeout as delay } from 'node:timers/promises'; +import { + aiLoggingChangeLines, + aiLoggingPreviewLines, + aiLoggingStatusLine, + assertAiLoggingPlatform, +} from './operator-ai-logging.ts'; import type { OperatorArgs } from './operator-args.ts'; import { exchangeOperatorSession, @@ -649,6 +655,11 @@ async function migrateDeploymentAssets( } } +/** The project ID from the request path `/projects/:id/ai-logging`. */ +function aiLoggingProjectId(args: OperatorArgs): string { + return decodeURIComponent(args.path.slice('/projects/'.length, -'/ai-logging'.length)); +} + export async function runOperatorCommand(args: OperatorArgs): Promise { if (!args.action) { const { printHelpPage } = await import('./help.ts'); @@ -671,6 +682,10 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { if (args.group === 'deployment' && args.action === 'migrate-assets') { return migrateDeploymentAssets(client, origin, args); } + const aiLogging = args.group === 'project' && args.action === 'ai-logging'; + if (aiLogging) { + await assertAiLoggingPlatform(origin); + } // Read once for preview and apply; the server excludes the token from audit output. if ( args.tokenStdin && @@ -725,6 +740,10 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { 'unsupported', ); } + if (aiLogging && args.plan && !args.json) { + console.log(aiLoggingPreviewLines(aiLoggingProjectId(args), preview).join('\n')); + return; + } if (!(await confirmOperatorMutation(origin, preview, args))) { return; } @@ -738,10 +757,16 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { : {}), ...recoveryFence, }; - outputMutation( - await client.request(args.path, { method: 'POST', body, timeoutMs: args.timeoutMs }), - args, - ); + const result = await client.request(args.path, { + method: 'POST', + body, + timeoutMs: args.timeoutMs, + }); + if (aiLogging && !args.json) { + console.log(aiLoggingChangeLines(aiLoggingProjectId(args), result).join('\n')); + return; + } + outputMutation(result, args); } else if (args.follow) { await followOperatorLogs(client, args); } else { @@ -762,6 +787,11 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { ...eventLines(result.deployments, ' '), ].join('\n'), ); + } else if (args.group === 'project' && args.action === 'show' && !args.json) { + // One readable line instead of the raw AI logging fields; --json keeps them all. + const { aiLogging, ...project } = result; + const line = aiLoggingStatusLine(aiLogging); + console.log((line ? [...humanLines(project), line] : humanLines(result)).join('\n')); } else { output(result, args.json); } diff --git a/packages/void/src/cli/platform-ai-logging-projection.ts b/packages/void/src/cli/platform-ai-logging-projection.ts new file mode 100644 index 000000000..3609507dd --- /dev/null +++ b/packages/void/src/cli/platform-ai-logging-projection.ts @@ -0,0 +1,249 @@ +import { + AI_LOGGING_ORPHAN_GRACE_MS, + aiLoggingClearedKey, + aiLoggingClearedMarker, + aiLoggingKey, + isPublishedAiLoggingMode, + parseAiLoggingKeyMetadata, + parsePlanAiLoggingSettings, + PLAN_AI_LOGGING_SETTING, + planAiLogging, + resolveAiLogging, + type AiLoggingPlanCatalog, + type PlanAiLoggingSettings, +} from '@void/platform/ai-logging'; +import { createDefaultPlanCatalog, parsePlatformPlanCatalog } from '@void/platform/plans'; +import type { + CloudflareKvBulkEntry, + CloudflareKvKey, + PlatformCloudflareClient, +} from './platform-cloudflare.ts'; +import type { PlatformDatabaseLifecycleLock } from './platform-installer-types.ts'; +import type { QueryConnection } from './platform-zero-trust-uninstall.ts'; + +const KEY_PREFIX = aiLoggingKey(''); +const PLAN_CATALOG_SETTING = 'plans:catalog'; +/** Wait at most this long for a project row lock held by the API. */ +const LOCK_TIMEOUT = '30s'; + +/** ROUTING KV access for one installation, bound to its account and namespace. */ +export type AiLoggingProjectionKv = Readonly<{ + list: (prefix: string) => Promise>; + put: (entries: ReadonlyArray) => Promise; + delete: (keys: ReadonlyArray) => Promise; +}>; + +export type AiLoggingProjectionResult = + | Readonly<{ skipped: true }> + | Readonly<{ skipped: false; projects: number; written: number; deleted: number }>; + +type ProjectRow = { id: string; status: string; plan: string; mode: string | null }; + +type Inputs = Readonly<{ + catalog: AiLoggingPlanCatalog; + settings: PlanAiLoggingSettings; +}>; + +async function readInputs(client: QueryConnection): Promise { + const result = await client.query<{ key: string; value: unknown }>( + 'SELECT "key", "value" FROM "platform_settings" WHERE "key" = ANY($1::text[])', + [[PLAN_CATALOG_SETTING, PLAN_AI_LOGGING_SETTING]], + ); + const saved = new Map(result.rows.map((row) => [row.key, row.value])); + let catalog: AiLoggingPlanCatalog; + let settings: PlanAiLoggingSettings; + try { + // Installed platforms start with the custom plan as the default (see the API's + // initialPlanDefaultFor). + const savedCatalog = saved.get(PLAN_CATALOG_SETTING); + catalog = + savedCatalog === undefined || savedCatalog === null + ? createDefaultPlanCatalog('custom') + : parsePlatformPlanCatalog(savedCatalog); + settings = parsePlanAiLoggingSettings(saved.get(PLAN_AI_LOGGING_SETTING)); + } catch (error) { + throw new Error( + `platform: The saved plan settings are not valid for this platform version, so AI logging settings cannot be published. If a newer platform release saved them, upgrade to that release again. (${error instanceof Error ? error.message : String(error)})`, + ); + } + return { catalog, settings }; +} + +function effectiveMode(row: ProjectRow, inputs: Inputs) { + if (row.mode !== null && !isPublishedAiLoggingMode(row.mode)) { + throw new Error(`platform: Project ${row.id} has an invalid saved AI logging setting.`); + } + const plan = planAiLogging(inputs.settings, inputs.catalog, row.plan); + return resolveAiLogging(row.mode, plan.planMode).mode; +} + +/** + * The database server's clock in ms. Readback and the sweep compare `at` with the + * API's clock, so it must not come from the operator's machine. + */ +async function databaseNow(client: QueryConnection): Promise { + const result = await client.query<{ now: unknown }>( + 'SELECT floor(extract(epoch FROM clock_timestamp()) * 1000)::float8 AS "now"', + ); + const now = Number(result.rows[0]?.now); + if (!Number.isSafeInteger(now)) { + throw new Error('platform: The database did not return its current time.'); + } + return now; +} + +const PROJECT_ROWS = `SELECT p."id", p."status", u."plan", o."mode" + FROM "projects" AS p + JOIN "users" AS u ON u."id" = p."user_id" + LEFT JOIN "project_ai_logging" AS o ON o."project_id" = p."id"`; + +/** + * Publishes every project's effective AI logging mode to ROUTING KV from Postgres, + * the same values the API publishes. The installer runs it on every install, upgrade + * and repair, once before the Workers upload (a new proxy may go live before the new + * API) and once after (the old API may have saved changes meanwhile). + * + * It holds the project row locks the API publisher takes while it reads the inputs + * and writes KV, so it never overwrites a newer value the API published. Running it + * again changes nothing. + */ +export async function projectPlatformAiLoggingConnection( + client: QueryConnection, + kv: AiLoggingProjectionKv, + options: Readonly<{ + /** Overrides the database clock (tests). */ + now?: () => number; + onProgress?: (message: string) => void; + }> = {}, +): Promise { + const tables = await client.query<{ present: boolean }>( + `SELECT to_regclass('public.project_ai_logging') IS NOT NULL AS "present"`, + ); + if (tables.rows[0]?.present !== true) { + // Older schema (or a rollback runtime before 1.8.0): nothing is saved yet. + return { skipped: true }; + } + const listed = new Map(); + for (const key of await kv.list(KEY_PREFIX)) { + if (key.name.startsWith(KEY_PREFIX) && key.name.length > KEY_PREFIX.length) { + listed.set(key.name.slice(KEY_PREFIX.length), key); + } + } + + await client.query('BEGIN'); + try { + await client.query(`SET LOCAL lock_timeout = '${LOCK_TIMEOUT}'`); + // Pick candidates: projects with an override, projects whose plan has a default, + // and projects that already have a key (so stale keys are removed). + const before = await readInputs(client); + const rows = (await client.query(PROJECT_ROWS)).rows; + const candidates = rows + .filter( + (row) => + row.mode !== null || listed.has(row.id) || effectiveMode(row, before) !== 'inherit', + ) + .map((row) => row.id); + options.onProgress?.(`Publishing AI logging settings (${candidates.length} projects)`); + // Same lock as the API publisher's no-op UPDATE (so rows that reference a project + // can still be inserted), taken in id order. Inputs are read again after the + // locks are held, so a change the API committed meanwhile is the one written. + if (candidates.length > 0) { + await client.query( + 'SELECT "id" FROM "projects" WHERE "id" = ANY($1::text[]) ORDER BY "id" FOR NO KEY UPDATE', + [candidates], + ); + } + const inputs = await readInputs(client); + const locked = new Set(candidates); + const current = new Map( + ( + await client.query(`${PROJECT_ROWS} WHERE p."id" = ANY($1::text[])`, [ + candidates, + ]) + ).rows.map((row) => [row.id, row]), + ); + const at = options.now ? options.now() : await databaseNow(client); + const writes: Array = []; + const deletes: Array = []; + let markers = 0; + for (const id of locked) { + const row = current.get(id); + if (!row) { + continue; + } + if (row.status !== 'active') { + // Deletion is in progress; its cleanup job removes the key. + continue; + } + const mode = effectiveMode(row, inputs); + if (mode !== 'inherit') { + writes.push({ key: aiLoggingKey(id), value: mode, metadata: { mode, at } }); + } else if (listed.has(id)) { + // The marker lets readback report `pending` while the old value may linger. + const marker = aiLoggingClearedMarker(at); + writes.push({ + key: aiLoggingClearedKey(id), + value: marker.value, + metadata: marker.metadata, + expiration_ttl: marker.expirationTtl, + }); + markers++; + deletes.push(aiLoggingKey(id)); + } + } + const existing = new Set(rows.map((row) => row.id)); + for (const [id, key] of listed) { + if (existing.has(id) || current.has(id)) { + continue; + } + // No project row: the project is gone, unless it was created moments ago. + const metadata = parseAiLoggingKeyMetadata(key.metadata); + if (!metadata || at - metadata.at >= AI_LOGGING_ORPHAN_GRACE_MS) { + deletes.push(key.name); + } + } + if (writes.length > 0) { + await kv.put(writes); + } + if (deletes.length > 0) { + await kv.delete(deletes); + } + await client.query('COMMIT'); + return { + skipped: false, + projects: locked.size, + written: writes.length - markers, + deleted: deletes.length, + }; + } catch (error) { + await client.query('ROLLBACK').catch(() => undefined); + throw error; + } +} + +/** + * Runs the projection through the installer's database lock, with a KV client bound + * to the installation's ROUTING namespace. A lock without it (test doubles) skips it. + */ +export async function publishInstallationAiLogging(input: { + readonly client: Pick; + readonly accountId: string; + readonly routingKvId: string; + readonly databaseLock: Pick; + readonly onProgress?: (message: string) => void; +}): Promise { + const publish = input.databaseLock.publishAiLogging; + if (!publish) { + return null; + } + const { client, accountId, routingKvId } = input; + input.onProgress?.('Publishing AI logging settings'); + return publish( + { + list: (prefix) => client.listKvKeys(accountId, routingKvId, prefix), + put: (entries) => client.putKvBulk(accountId, routingKvId, entries), + delete: (keys) => client.deleteKvBulk(accountId, routingKvId, keys), + }, + input.onProgress, + ); +} diff --git a/packages/void/src/cli/platform-cloudflare.ts b/packages/void/src/cli/platform-cloudflare.ts index 3d3b1341b..f430acb61 100644 --- a/packages/void/src/cli/platform-cloudflare.ts +++ b/packages/void/src/cli/platform-cloudflare.ts @@ -66,6 +66,17 @@ export class PlatformRuntimeTokenEmailPermissionError extends Error { } export type CloudflareAccount = Readonly<{ id: string; name: string }>; +/** A key from a KV listing; `metadata` is whatever was stored with it, or undefined. */ +export type CloudflareKvKey = Readonly<{ name: string; metadata?: unknown }>; +export type CloudflareKvBulkEntry = Readonly<{ + key: string; + value: string; + metadata?: unknown; + /** Seconds until the pair expires (at least 60). */ + expiration_ttl?: number; +}>; +/** Largest number of pairs or keys one KV bulk request accepts. */ +export const KV_BULK_LIMIT = 10_000; export type CloudflareNamedResource = Readonly<{ /** When Cloudflare created it, where the API reports that. */ createdAt?: string; @@ -931,6 +942,74 @@ export class PlatformCloudflareClient { ); } + /** Every key under `prefix`, with its metadata, across all list pages. */ + async listKvKeys( + accountId: string, + namespaceId: string, + prefix: string, + ): Promise> { + const keys: Array = []; + const seenCursors = new Set(); + let cursor = ''; + for (;;) { + const query = new URLSearchParams({ prefix, limit: '1000' }); + if (cursor) { + query.set('cursor', cursor); + } + const { result, resultInfo } = await this.#requestEnvelope< + ReadonlyArray<{ name?: unknown; metadata?: unknown }> + >( + `/accounts/${encodeURIComponent(accountId)}/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/keys?${query}`, + ); + if (!Array.isArray(result)) { + throw new Error('platform: Cloudflare returned an invalid KV key list.'); + } + for (const entry of result) { + const name = requiredString(entry.name, 'KV key name'); + keys.push(entry.metadata === undefined ? { name } : { name, metadata: entry.metadata }); + } + const next = resultInfo?.cursor ?? ''; + if (!next) { + return keys; + } + if (seenCursors.has(next)) { + throw new Error('platform: Cloudflare returned a repeated KV key cursor.'); + } + seenCursors.add(next); + cursor = next; + } + } + + /** Writes up to KV_BULK_LIMIT pairs per request; fails if any key is not written. */ + async putKvBulk( + accountId: string, + namespaceId: string, + entries: ReadonlyArray, + ): Promise { + for (let offset = 0; offset < entries.length; offset += KV_BULK_LIMIT) { + const result = await this.request( + `/accounts/${encodeURIComponent(accountId)}/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/bulk`, + { method: 'PUT', body: JSON.stringify(entries.slice(offset, offset + KV_BULK_LIMIT)) }, + ); + assertKvBulkComplete(result, 'write'); + } + } + + /** Deletes up to KV_BULK_LIMIT keys per request; a missing key counts as deleted. */ + async deleteKvBulk( + accountId: string, + namespaceId: string, + keys: ReadonlyArray, + ): Promise { + for (let offset = 0; offset < keys.length; offset += KV_BULK_LIMIT) { + const result = await this.request( + `/accounts/${encodeURIComponent(accountId)}/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/bulk/delete`, + { method: 'POST', body: JSON.stringify(keys.slice(offset, offset + KV_BULK_LIMIT)) }, + ); + assertKvBulkComplete(result, 'delete'); + } + } + async getKvValue(accountId: string, namespaceId: string, key: string): Promise { const response = await this.#fetcher( `${this.apiBaseUrl}/accounts/${encodeURIComponent(accountId)}/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/values/${encodeURIComponent(key)}`, @@ -1523,6 +1602,19 @@ function withCreatedAt(value: unknown): { createdAt?: string } { return Number.isNaN(time) ? {} : { createdAt: new Date(time).toISOString() }; } +type KvBulkResult = { successful_key_count?: unknown; unsuccessful_keys?: unknown } | null; + +/** A bulk call answers 200 even when some keys failed; treat any failed key as an error. */ +function assertKvBulkComplete(result: KvBulkResult, operation: 'write' | 'delete'): void { + const failed = result?.unsuccessful_keys; + if (failed !== undefined && failed !== null && (!Array.isArray(failed) || failed.length > 0)) { + const count = Array.isArray(failed) ? failed.length : 'some'; + throw new Error( + `platform: Cloudflare did not ${operation} ${count} KV keys in a bulk request.`, + ); + } +} + function requiredString(value: unknown, label: string): string { if (typeof value !== 'string' || value === '') { throw new Error(`platform: ${label} is missing from the Cloudflare response.`); diff --git a/packages/void/src/cli/platform-install-provisioning.ts b/packages/void/src/cli/platform-install-provisioning.ts index 95e3e8439..386778316 100644 --- a/packages/void/src/cli/platform-install-provisioning.ts +++ b/packages/void/src/cli/platform-install-provisioning.ts @@ -5,6 +5,7 @@ import { } from '@void/platform'; import type { PlatformRuntimeManifest } from '@void/platform/installer'; import { join } from 'pathslash'; +import { publishInstallationAiLogging } from './platform-ai-logging-projection.ts'; import { verifyPlatformAuthenticationDatabase } from './platform-auth-database.ts'; import { preparePlatformDatabaseSchema } from './platform-installer-database.ts'; import { @@ -189,6 +190,18 @@ export async function provisionInstallationServices(input: { }, ); + // First pass: the new proxy reads only ROUTING KV and may go live before the new API. + await publishInstallationAiLogging({ + client: dependencies.client, + accountId: plan.account.id, + routingKvId: requireId( + Object.fromEntries(state.manifest.resources.map((resource) => [resource.key, resource.id])), + 'routing-kv', + ), + databaseLock: releaseDatabaseLock, + onProgress: dependencies.onProgress, + }); + dependencies.onProgress?.('Checking platform safety'); const targetSandboxDrainProtocol = runtime.safetyProtocols.sandboxDrain; const prepareSandboxDrain = diff --git a/packages/void/src/cli/platform-installer-database.ts b/packages/void/src/cli/platform-installer-database.ts index 6add1ac53..09846d92b 100644 --- a/packages/void/src/cli/platform-installer-database.ts +++ b/packages/void/src/cli/platform-installer-database.ts @@ -14,6 +14,7 @@ import type { import { platformDatabaseSchemaDigest } from '@void/platform/installer'; import { join } from 'pathslash'; import type { Pool } from 'pg'; +import { projectPlatformAiLoggingConnection } from './platform-ai-logging-projection.ts'; import { verifyPlatformDatabaseArtifacts } from './platform-installer-runtime.ts'; import { type PlatformAdministratorSetupState, @@ -627,6 +628,8 @@ export async function acquirePlatformDatabaseLifecycleLockConnection( release.readAdministratorSetup = () => readPlatformAdministratorSetupConnection(client); release.readProjectZeroTrust = () => readPlatformProjectZeroTrustStateConnection(client); release.readProjects = () => readPlatformProjectSlugsConnection(client); + release.publishAiLogging = (kv, onProgress) => + projectPlatformAiLoggingConnection(client, kv, { onProgress }); release.lockProjectZeroTrust = () => lockPlatformProjectZeroTrustConnection(client); release.fenceProjectZeroTrust = () => fencePlatformProjectZeroTrustConnection(client); release.liftProjectZeroTrustFence = () => liftPlatformProjectZeroTrustFenceConnection(client); diff --git a/packages/void/src/cli/platform-installer-types.ts b/packages/void/src/cli/platform-installer-types.ts index 544abeba8..46a4be4ea 100644 --- a/packages/void/src/cli/platform-installer-types.ts +++ b/packages/void/src/cli/platform-installer-types.ts @@ -13,6 +13,10 @@ import type { } from '@void/platform/installer'; import type { ensurePlatformAccessHealthChecks } from './platform-access-health.ts'; import type { verifyInstalledPlatformAccessProtection } from './platform-access-preflight.ts'; +import type { + AiLoggingProjectionKv, + AiLoggingProjectionResult, +} from './platform-ai-logging-projection.ts'; import type { initializeInstalledAppAccess } from './platform-app-access.ts'; import type { initializeInstalledPlatformAuthentication } from './platform-auth-bootstrap.ts'; import { @@ -125,6 +129,14 @@ export type PlatformDatabaseLifecycleLock = (() => Promise) & { readAdministratorSetup?: () => Promise; /** Project Zero Trust state that decides whether uninstall may start. */ readProjectZeroTrust?: () => Promise; + /** + * Publishes every project's AI logging setting from the database to ROUTING KV + * under the project row locks. Missing on test locks, which then skip it. + */ + publishAiLogging?: ( + kv: AiLoggingProjectionKv, + onProgress?: (message: string) => void, + ) => Promise; /** Project slugs, which --purge-resources requires to be empty. */ readProjects?: () => Promise>; /** Block Zero Trust writers in the API until the returned release runs. */ @@ -196,14 +208,17 @@ export type InstallerClient = Pick< | 'createQueue' | 'createR2Bucket' | 'createZone' + | 'deleteKvBulk' | 'deleteKvValue' | 'getWorkerPlainTextBindings' + | 'listKvKeys' | 'listWorkerDomains' | 'listWorkerNames' | 'listWorkerRoutes' | 'listWorkerServiceRoutes' | 'publishWorkerCustomDomainsSafely' | 'publishWorkerRoutesSafely' + | 'putKvBulk' | 'putKvValue' | 'putR2Object' | 'request' diff --git a/packages/void/src/cli/platform-installer.ts b/packages/void/src/cli/platform-installer.ts index bff8cce15..137c822a9 100644 --- a/packages/void/src/cli/platform-installer.ts +++ b/packages/void/src/cli/platform-installer.ts @@ -15,6 +15,7 @@ import { PLATFORM_ADMIN_ASSETS_DIRECTORY, resolvePlatformRuntime } from '@void/p import { join } from 'pathslash'; import { ensurePlatformAccessToken } from './cf-access.ts'; import { getErrorMessage } from './output.ts'; +import { publishInstallationAiLogging } from './platform-ai-logging-projection.ts'; import { initializeInstalledAppAccess, PlatformAppAccessCredentialError, @@ -762,6 +763,15 @@ export async function installPlatform( runParallelPinnedPlatformWrangler, runPinnedPlatformWrangler, }); + // Second pass: the old API may have saved settings to the database only while + // the Workers were uploading. + await publishInstallationAiLogging({ + client: dependencies.client, + accountId: state.plan.account.id, + routingKvId: requireId(ids, 'routing-kv'), + databaseLock: releaseDatabaseLock, + onProgress: dependencies.onProgress, + }); state.manifest = setInstallationEndpoints( state.manifest, diff --git a/packages/void/src/cli/platform-management.ts b/packages/void/src/cli/platform-management.ts index 174b626ca..862c02f56 100644 --- a/packages/void/src/cli/platform-management.ts +++ b/packages/void/src/cli/platform-management.ts @@ -725,6 +725,7 @@ export async function runInstalledPlatformCommand(args: PlatformArgs): Promise>; + +type AiLoggingListing = { + modes: PlanAiLoggingModes; + publish: { complete: boolean; error?: string } | null; + remaining: number; +}; + type Listing = { catalog: PlatformPlanCatalog; accounts: Array<{ planId: string; count: number }>; + /** Plan AI logging defaults. Platforms before plan defaults do not send it. */ + aiLogging?: AiLoggingListing; }; +const aiLoggingLabels: Record = { + inherit: 'inherit (AI Gateway setting)', + off: 'off', + metadata: 'metadata (no prompts or responses)', + full: 'full (prompts and responses)', +}; + +function planAiLogging(modes: PlanAiLoggingModes | undefined, planId: string): string { + const mode = modes && Object.hasOwn(modes, planId) ? modes[planId] : undefined; + return typeof mode === 'string' ? stripVTControlCharacters(mode) : 'inherit'; +} + +function aiLoggingPending(listing: Listing): boolean { + return Boolean(listing.aiLogging?.publish && !listing.aiLogging.publish.complete); +} + +/** Refuses plan AI logging on a platform whose API would refuse or drop it. */ +function assertPlanAiLoggingSupported(listing: Listing, body: Record): void { + if (body.aiLogging !== undefined && !listing.aiLogging) { + throw new Error( + 'platform: This platform does not support plan AI logging defaults. Upgrade the platform first with `void platform upgrade`.', + ); + } +} + const limitLabels: Record<(typeof PLAN_EDITABLE_LIMIT_KEYS)[number], string> = { requestsPerMonth: 'Requests per billing month', cpuMsPerRequest: 'Default CPU per request (ms)', @@ -56,7 +97,11 @@ function writePlanDiff( from: PlatformPlanDefinition, to: PlatformPlanDefinition, write: (line: string) => void, + aiLogging?: Readonly<{ from: string; to: string }>, ): void { + if (aiLogging && aiLogging.from !== aiLogging.to) { + write(`AI Gateway logging: ${aiLogging.from} → ${aiLogging.to}`); + } if (from.buildInstanceType !== to.buildInstanceType) { write(`Build size: ${from.buildInstanceType} → ${to.buildInstanceType}`); } @@ -87,16 +132,36 @@ function showListing(listing: Listing, json: boolean): void { if (listing.catalog.reconciliation && !listing.catalog.reconciliation.complete) { console.log('Account updates are pending. Run void platform config plans sync --yes.'); } + if (aiLoggingPending(listing)) { + console.log( + `AI logging publish is pending for ${listing.aiLogging!.remaining} projects. Run void platform config plans sync --yes.`, + ); + } } function showPreview( preview: Record, before: PlatformPlanCatalog, + beforeAiLogging: PlanAiLoggingModes | undefined, write = console.error, ): void { const after = preview.catalog as PlatformPlanCatalog; + const change = preview.aiLogging as + | { modes?: PlanAiLoggingModes; modesBefore?: PlanAiLoggingModes } + | undefined; + const afterAiLogging = change?.modes; + // The preview reads the saved defaults under the catalog lock; the listing may be cached. + const savedAiLogging = change?.modesBefore ?? beforeAiLogging; + const aiLogging = (from: string, to: string) => + afterAiLogging + ? { from: planAiLogging(savedAiLogging, from), to: planAiLogging(afterAiLogging, to) } + : undefined; write(`Change: ${preview.action} ${preview.target}`); write(`Accounts affected: ${preview.affectedAccounts}`); + const publish = preview.aiLoggingPublish as { remaining?: unknown } | undefined; + if (typeof publish?.remaining === 'number' && publish.remaining > 0) { + write(`AI logging settings to publish: ${publish.remaining} projects`); + } for (const warning of (preview.warnings ?? []) as Array) { write(stripVTControlCharacters(warning)); } @@ -114,6 +179,9 @@ function showPreview( write(` ${limitLabels[key]}: ${limitValue(plan.limits[key], key)}`); } write(` Short project slugs: ${shortSlugsLabel(plan.allowShortSlugs)}`); + if (afterAiLogging) { + write(` AI Gateway logging: ${planAiLogging(afterAiLogging, plan.id)}`); + } continue; } if (previous.name !== plan.name) { @@ -122,7 +190,7 @@ function showPreview( if (previous.archived !== plan.archived) { write(`${plan.id}: ${plan.archived ? 'archive for new assignments' : 'restore assignments'}`); } - writePlanDiff(previous, plan, write); + writePlanDiff(previous, plan, write, aiLogging(plan.id, plan.id)); } for (const plan of before.plans) { if (!after.plans.some((entry) => entry.id === plan.id)) { @@ -130,7 +198,7 @@ function showPreview( const replacement = after.plans.find((entry) => entry.id === preview.replacementPlanId); if (replacement) { write(`Move accounts to ${label(replacement)}`); - writePlanDiff(plan, replacement, write); + writePlanDiff(plan, replacement, write, aiLogging(plan.id, replacement.id)); } } } @@ -182,6 +250,7 @@ async function choosePlan( async function changesInput( args: PlatformPlansArgs, plan?: PlatformPlanDefinition, + listing?: Listing, ): Promise> { if (args.file) { const input: unknown = JSON.parse(await readFile(args.file, 'utf8')); @@ -190,12 +259,17 @@ async function changesInput( } const object = input as Record; for (const key of Object.keys(object)) { - if (!['name', 'limits', 'buildInstanceType', 'allowShortSlugs'].includes(key)) { + if (!['name', 'limits', 'buildInstanceType', 'allowShortSlugs', 'aiLogging'].includes(key)) { throw new Error( - `platform: Unknown plan field ${key}. Use name, limits, buildInstanceType, or allowShortSlugs.`, + `platform: Unknown plan field ${key}. Use name, limits, buildInstanceType, allowShortSlugs, or aiLogging.`, ); } } + try { + parsePlanAiLoggingInput(object.aiLogging); + } catch (error) { + throw new Error(`platform: ${(error as Error).message}`); + } if (object.allowShortSlugs !== undefined && typeof object.allowShortSlugs !== 'boolean') { throw new Error('platform: allowShortSlugs must be a boolean.'); } @@ -235,9 +309,28 @@ async function changesInput( label: `${limitLabels[key]}: ${limitValue(plan!.limits[key], key)}`, })), { value: 'buildInstanceType', label: 'Build instance size' }, + ...(listing?.aiLogging + ? [ + { + value: 'aiLogging', + label: `AI Gateway logging: ${planAiLogging(listing.aiLogging.modes, plan!.id)}`, + }, + ] + : []), ], }), ); + if (field === 'aiLogging') { + return { + aiLogging: value( + await select({ + message: 'AI Gateway logging for projects on this plan without a project setting:', + initialValue: planAiLogging(listing!.aiLogging!.modes, plan!.id), + options: AI_LOGGING_MODES.map((mode) => ({ value: mode, label: aiLoggingLabels[mode] })), + }), + ), + }; + } if (field === 'name') { return { name: parsePlanName(value(await text({ message: 'Plan name:', initialValue: plan!.name }))), @@ -276,8 +369,10 @@ async function apply( path: string, body: Record, args: PlatformPlansArgs, - catalog: PlatformPlanCatalog, + listing: Listing, ): Promise { + const { catalog } = listing; + assertPlanAiLoggingSupported(listing, body); if (!args.plan && !args.yes && (!process.stdin.isTTY || args.json)) { throw new Error( 'platform: Configuration changes require --yes or --plan in non-interactive mode.', @@ -288,7 +383,7 @@ async function apply( if (args.json) { print(preview); } else { - showPreview(preview, catalog, console.log); + showPreview(preview, catalog, listing.aiLogging?.modes, console.log); } return; } @@ -296,7 +391,7 @@ async function apply( throw new Error('platform: The platform returned an invalid plan revision.'); } if (!args.yes) { - showPreview(preview, catalog); + showPreview(preview, catalog, listing.aiLogging?.modes); if ( !value( await confirm({ message: `Apply this change to ${client.origin}?`, initialValue: false }), @@ -305,10 +400,7 @@ async function apply( throw new Error('platform: Cancelled.'); } } - let result = await client.request(path, { - method: 'POST', - body: { ...body, expectedRevision: preview.expectedRevision }, - }); + let result = await save(client, path, { ...body, expectedRevision: preview.expectedRevision }); const committedCatalog = result.catalog as PlatformPlanCatalog; if (!Number.isSafeInteger(committedCatalog?.revision)) { throw new Error( @@ -318,36 +410,43 @@ async function apply( const committedRevision = committedCatalog.revision; const applied = result; let previousCursor = catalog.reconciliation?.cursor ?? null; + let published = 0; + let expectedBy: string | null = null; while (true) { - const reconciliation = result.reconciliation as - | { complete?: boolean; processed?: number; error?: string } - | undefined; - if (!reconciliation || reconciliation.complete !== false) { + const reconciliation = result.reconciliation as Progress | undefined; + const aiLogging = result.aiLoggingPublish as Progress | undefined; + if (aiLogging && Number.isSafeInteger(aiLogging.processed)) { + published += aiLogging.processed!; + } + if (typeof aiLogging?.expectedBy === 'string') { + expectedBy = aiLogging.expectedBy; + } + const accountsPending = reconciliation?.complete === false; + if (!accountsPending && aiLogging?.complete !== false && !aiLogging?.error) { break; } const currentCatalog = result.catalog as PlatformPlanCatalog; const cursor = currentCatalog.reconciliation?.cursor ?? null; - if ( - reconciliation.error || - !Number.isSafeInteger(reconciliation.processed) || - reconciliation.processed! <= 0 || - cursor === previousCursor || - currentCatalog.revision !== committedRevision - ) { + const accountsStuck = + accountsPending && (!progressed(reconciliation) || cursor === previousCursor); + const aiLoggingStuck = + aiLogging?.complete === false ? !progressed(aiLogging) : !!aiLogging?.error; + if (accountsStuck || aiLoggingStuck || currentCatalog.revision !== committedRevision) { const pending = { ...applied, ...result }; print(pending); throw new OperatorClientError( - 'Plan configuration was saved, but account updates are pending. Run void platform config plans sync --yes.', + accountsStuck || !aiLoggingStuck + ? 'Plan configuration was saved, but account updates are pending. Run void platform config plans sync --yes.' + : 'Plan configuration was saved, but the AI logging setting is not published to every project yet. Run void platform config plans sync --yes.', 'plan_sync_pending', undefined, pending, ); } - previousCursor = cursor; - result = await client.request('/config/plans/sync', { - method: 'POST', - body: { expectedRevision: committedRevision }, - }); + if (accountsPending) { + previousCursor = cursor; + } + result = await save(client, '/config/plans/sync', { expectedRevision: committedRevision }); } const completed = { ...applied, ...result }; if (args.json) { @@ -356,9 +455,58 @@ async function apply( printSuccess( `Saved ${applied.action ?? 'plans.sync'} ${applied.target ?? ''}. Account updates complete.`, ); + const change = preview.aiLogging as + | { planIds?: Array; includeUnknown?: boolean } + | undefined; + if (published > 0 || change?.planIds?.length || change?.includeUnknown) { + const by = utcTime(expectedBy); + console.log( + `AI logging published to ${published} projects${by ? `; expected by ${by} (normally within 2 minutes)` : ''}.`, + ); + } } } +/** + * Send a plan change or sync page. The API answers `ok: false` when the catalog saved but an + * account or AI logging page failed; that body still carries the saved catalog, so return it and + * let the caller name the resumption command instead of a generic partial failure. + */ +async function save( + client: OperatorClient, + path: string, + body: Record, +): Promise> { + try { + return await client.request(path, { method: 'POST', body }); + } catch (error) { + const details = error instanceof OperatorClientError ? error.details : undefined; + if ( + error instanceof OperatorClientError && + error.code === 'partial_failure' && + details && + typeof details === 'object' && + 'catalog' in details + ) { + return details as Record; + } + throw error; + } +} + +type Progress = { + complete?: boolean; + processed?: number; + remaining?: number; + expectedBy?: string | null; + error?: unknown; +}; + +/** A sync step that wrote something and reported no error. */ +function progressed(progress: Progress): boolean { + return !progress.error && Number.isSafeInteger(progress.processed) && progress.processed! > 0; +} + export async function runPlatformPlansConfig(args: PlatformPlansArgs): Promise { const origin = resolveOperatorOrigin(args.connection); const client = new OperatorClient(origin, readOperatorToken(origin)); @@ -380,8 +528,9 @@ export async function runPlatformPlansConfig(args: PlatformPlansArgs): Promise ({ read: vi.fn(), write: vi.fn(), remove: vi.fn() })); const mutationPrompt = vi.hoisted(() => ({ question: vi.fn(), close: vi.fn() })); @@ -1782,3 +1783,207 @@ describe('operator transport and execution', () => { expect(write.mock.calls.map(([line]) => String(line)).join('\n')).toContain('historical row'); }); }); + +describe('project AI logging commands', () => { + const resolution = { + mode: 'off', + planId: 'pro', + planKnown: true, + defaultPlanId: 'free', + planMode: null, + effective: 'off', + source: 'project', + }; + + /** Serves discovery at `platformVersion` (or a status) and operator API replies in order. */ + function serve( + platformVersion: string | number, + replies: Array | Response>, + ): ReturnType> { + vi.stubEnv('VOID_API_URL', 'https://one.example'); + vi.stubEnv('VOID_OPERATOR_TOKEN', 'operator'); + const queue = [...replies]; + const fetcher = vi.fn().mockImplementation(async (input) => { + const url = new URL(String(input)); + if (url.pathname === '/.well-known/void-platform') { + return typeof platformVersion === 'number' + ? new Response(null, { status: platformVersion }) + : platformDiscoveryResponse(url.origin, platformVersion); + } + const reply = queue.shift() ?? { error: 'unexpected_request' }; + return reply instanceof Response ? reply : Response.json(reply); + }); + vi.stubGlobal('fetch', fetcher); + return fetcher; + } + + function printed(log: { mock: { calls: Array> } }): string { + return log.mock.calls.map(([line]) => String(line)).join('\n'); + } + + it('prints the source, plan default, and expected time after a change', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + vi.spyOn(process.stderr, 'write').mockImplementation(() => true); + const fetcher = serve('1.9.0', [ + { dryRun: true, action: 'project.ai-logging', target: 'p1', ...resolution, previous: 'full' }, + { ...resolution, previous: 'full', expectedBy: '2026-11-13T14:03:20.000Z' }, + ]); + await runOperatorCommand(parseOperatorArgs(['project', 'ai-logging', 'p1', 'off', '--yes'])); + expect(printed(log)).toBe( + [ + 'AI logging for p1: off (set on project; plan "pro" default: inherit)', + 'New AI requests are expected to follow it by 14:03:20 UTC (normally within 2 minutes).', + ].join('\n'), + ); + expect(fetcher.mock.calls.map(([input]) => new URL(String(input)).pathname)).toEqual([ + '/.well-known/void-platform', + '/operator/v1/projects/p1/ai-logging', + '/operator/v1/projects/p1/ai-logging', + ]); + }); + + it('shows a plan default from an unknown plan ID in the dry run', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + serve('hosted', [ + { + dryRun: true, + action: 'project.ai-logging', + target: 'p1', + ...resolution, + mode: 'inherit', + planId: 'legacy-x', + planKnown: false, + planMode: 'metadata', + effective: 'metadata', + source: 'plan', + previous: 'off', + }, + ]); + await runOperatorCommand( + parseOperatorArgs(['project', 'ai-logging', 'p1', 'inherit', '--plan']), + ); + expect(printed(log)).toBe( + [ + 'AI logging for p1: off → metadata (from plan "legacy-x" (not in catalog; uses default plan "free"))', + 'No change was made. Run the command again without --plan to apply it.', + ].join('\n'), + ); + }); + + it('keeps the JSON reply unchanged', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + const reply = { ...resolution, previous: 'full', expectedBy: '2026-11-13T14:03:20.000Z' }; + serve('1.9.0', [ + { dryRun: true, action: 'project.ai-logging', target: 'p1', ...resolution, previous: 'full' }, + reply, + ]); + await runOperatorCommand( + parseOperatorArgs(['project', 'ai-logging', 'p1', 'off', '--yes', '--json']), + ); + expect(log).toHaveBeenCalledExactlyOnceWith(JSON.stringify(reply)); + }); + + it.each([ + ['1.7.2', '1.7.2'], + ['1.8.0-beta.1', '1.8.0-beta.1'], + ['a platform without discovery', 404], + ])('refuses before any request on %s', async (_name, version) => { + const fetcher = serve(version, []); + await expect( + runOperatorCommand(parseOperatorArgs(['project', 'ai-logging', 'p1', 'off', '--yes'])), + ).rejects.toMatchObject({ + code: 'unsupported', + message: 'This platform does not support AI logging policies. Run `void platform upgrade`.', + }); + expect(fetcher).toHaveBeenCalledTimes(1); + }); + + it('lets the request report its own error when the version cannot be read', async () => { + vi.spyOn(console, 'log').mockImplementation(() => {}); + const fetcher = serve(503, [ + Response.json({ error: 'not_found', message: 'Project not found.' }, { status: 404 }), + ]); + await expect( + runOperatorCommand(parseOperatorArgs(['project', 'ai-logging', 'p1', 'off', '--yes'])), + ).rejects.toThrow('Project not found.'); + expect(fetcher).toHaveBeenCalledTimes(2); + }); + + it('prints a 1.8.0 reply that has only the saved mode', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + vi.spyOn(process.stderr, 'write').mockImplementation(() => true); + serve('1.8.0', [ + { dryRun: true, action: 'project.ai-logging', target: 'p1', mode: 'off' }, + { mode: 'off' }, + ]); + await runOperatorCommand(parseOperatorArgs(['project', 'ai-logging', 'p1', 'off', '--yes'])); + expect(printed(log)).toBe('AI logging for p1: off'); + }); + + it.each([ + ['applied', {}, 'AI Gateway logging: metadata (from plan "pro") — applied'], + [ + 'pending', + { publishedAt: '2026-11-13T14:01:20.000Z' }, + 'AI Gateway logging: metadata (from plan "pro") — pending (expected by 14:03:20 UTC)', + ], + [ + 'pending_plan_publish', + {}, + 'AI Gateway logging: metadata (from plan "pro") — pending (the plan default is still being published)', + ], + [ + 'drift', + { published: 'full' }, + 'AI Gateway logging: metadata (from plan "pro") — drift (published: full)', + ], + [ + 'unknown', + {}, + 'AI Gateway logging: metadata (from plan "pro") — state unknown (the published setting could not be read)', + ], + ])( + 'summarizes the effective setting and %s state in project show', + async (state, extra, line) => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + const aiLogging = { + ...resolution, + mode: 'inherit', + planMode: 'metadata', + effective: 'metadata', + source: 'plan', + published: 'metadata', + publishedAt: null, + state, + ...extra, + }; + serve('1.9.0', [{ project: { id: 'p1', slug: 'app' }, aiLogging }]); + await runOperatorCommand(parseOperatorArgs(['project', 'show', 'p1'])); + const output = printed(log); + expect(output).toContain('Project:\n ID: p1\n Slug: app'); + expect(output.split('\n').at(-1)).toBe(line); + expect(output).not.toContain('Ai logging'); + }, + ); + + it('keeps every AI logging field in project show JSON', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + const reply = { project: { id: 'p1' }, aiLogging: { ...resolution, state: 'applied' } }; + serve('1.9.0', [reply]); + await runOperatorCommand(parseOperatorArgs(['project', 'show', 'p1', '--json'])); + expect(log).toHaveBeenCalledExactlyOnceWith(JSON.stringify(reply)); + }); + + it('documents the modes and timing in help', () => { + const command = operatorCommands.find( + (entry) => entry.group === 'project' && entry.action === 'ai-logging', + )!; + expect(command.usage).toEqual([ + 'void platform project ai-logging [options]', + ]); + expect(command.description).toContain('normally follow it within 2 minutes'); + expect(() => parseOperatorArgs(['project', 'ai-logging', 'p1'])).toThrow( + 'Usage: void platform project ai-logging .', + ); + }); +}); diff --git a/packages/void/test/unit/platform-ai-logging-projection.test.ts b/packages/void/test/unit/platform-ai-logging-projection.test.ts new file mode 100644 index 000000000..f16b23dd5 --- /dev/null +++ b/packages/void/test/unit/platform-ai-logging-projection.test.ts @@ -0,0 +1,373 @@ +import { PGlite } from '@electric-sql/pglite'; +import { + AI_LOGGING_CLEARED_TTL_SECONDS, + AI_LOGGING_ORPHAN_GRACE_MS, +} from '@void/platform/ai-logging'; +import { getPlatformRuntimeDirectory, readPlatformRuntimeManifest } from '@void/platform/installer'; +import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; +import { + projectPlatformAiLoggingConnection, + publishInstallationAiLogging, + type AiLoggingProjectionKv, +} from '../../src/cli/platform-ai-logging-projection.ts'; +import type { CloudflareKvBulkEntry } from '../../src/cli/platform-cloudflare.ts'; +import { preparePlatformDatabaseConnection } from '../../src/cli/platform-installer-database.ts'; +import type { QueryConnection } from '../../src/cli/platform-zero-trust-uninstall.ts'; + +const NOW = 1_800_000_000_000; + +let database: PGlite; +let connection: QueryConnection; + +/** An in-memory ROUTING namespace that records every bulk call. */ +function memoryKv(initial: Record = {}) { + const store = new Map(Object.entries(initial)); + const calls: Array = []; + const expirations = new Map(); + const kv: AiLoggingProjectionKv = { + list: async (prefix) => { + calls.push('list'); + return [...store] + .filter(([name]) => name.startsWith(prefix)) + .map(([name, entry]) => + entry.metadata === undefined ? { name } : { name, metadata: entry.metadata }, + ); + }, + put: async (entries: ReadonlyArray) => { + calls.push('put'); + for (const entry of entries) { + store.set(entry.key, { value: entry.value, metadata: entry.metadata }); + if (entry.expiration_ttl !== undefined) { + expirations.set(entry.key, entry.expiration_ttl); + } + } + }, + delete: async (keys) => { + calls.push('delete'); + for (const key of keys) { + store.delete(key); + } + }, + }; + return { kv, store, calls, expirations }; +} + +/** Records each statement so tests can check lock and transaction order. */ +function recording(statements: Array, onStatement?: (sql: string) => void) { + return { + query: async (sql: string, values?: ReadonlyArray) => { + statements.push(sql); + onStatement?.(sql); + return connection.query(sql, values); + }, + } as QueryConnection; +} + +async function seed(sql: string) { + await database.exec(sql); +} + +beforeAll(async () => { + database = new PGlite(); + await database.waitReady; + connection = database as unknown as QueryConnection; + const runtime = readPlatformRuntimeManifest(); + await preparePlatformDatabaseConnection( + connection as Parameters[0], + getPlatformRuntimeDirectory(), + runtime.database, + null, + false, + ); +}, 60_000); + +afterAll(async () => { + await database.close(); +}); + +beforeEach(async () => { + await seed(`DELETE FROM project_ai_logging; DELETE FROM projects; DELETE FROM users; + DELETE FROM platform_settings WHERE key IN ('plans:catalog', 'plans:ai-logging');`); +}); + +describe('installer AI logging projection', () => { + it('skips an older schema without the AI logging table', async () => { + const empty = new PGlite(); + await empty.waitReady; + try { + const { kv, calls } = memoryKv(); + await expect( + projectPlatformAiLoggingConnection(empty as unknown as QueryConnection, kv), + ).resolves.toEqual({ skipped: true }); + expect(calls).toEqual([]); + } finally { + await empty.close(); + } + }); + + it('publishes overrides and plan defaults with metadata and deletes stale keys', async () => { + await seed(` + INSERT INTO users (id, login, provider_id, plan) VALUES + ('u-pro', 'pro', '1', 'pro'), ('u-free', 'free', '2', 'free'), + ('u-legacy', 'legacy', '3', 'legacy-x'); + INSERT INTO projects (id, user_id, slug) VALUES + ('p-override', 'u-free', 'override'), ('p-plan', 'u-pro', 'plan'), + ('p-inherit', 'u-free', 'inherit'), ('p-stale', 'u-free', 'stale'), + ('p-legacy', 'u-legacy', 'legacy'), ('p-wins', 'u-pro', 'wins'), + ('p-deleting', 'u-free', 'deleting'); + UPDATE projects SET status = 'deleting' WHERE id = 'p-deleting'; + INSERT INTO project_ai_logging (project_id, mode) VALUES + ('p-override', 'off'), ('p-wins', 'full'), ('p-deleting', 'off'); + INSERT INTO platform_settings (key, value) VALUES + ('plans:ai-logging', '{"modes":{"pro":"metadata","custom":"off"},"publish":null}'); + `); + const { kv, store, expirations } = memoryKv({ + 'ai-logging:p-stale': { value: 'off', metadata: { mode: 'off', at: 1 } }, + 'ai-logging:p-plan': { value: 'full', metadata: { mode: 'full', at: 1 } }, + 'ai-logging:p-gone-old': { value: 'off', metadata: { mode: 'off', at: 1 } }, + 'ai-logging:p-gone-bare': { value: 'off' }, + 'ai-logging:p-just-created': { + value: 'off', + metadata: { mode: 'off', at: NOW - AI_LOGGING_ORPHAN_GRACE_MS + 1_000 }, + }, + 'ai-block:p-plan': { value: '1' }, + }); + const progress: Array = []; + + const result = await projectPlatformAiLoggingConnection(connection, kv, { + now: () => NOW, + onProgress: (message) => progress.push(message), + }); + + expect(result).toEqual({ skipped: false, projects: 6, written: 4, deleted: 3 }); + expect(progress).toEqual(['Publishing AI logging settings (6 projects)']); + expect(Object.fromEntries(store)).toEqual({ + 'ai-logging:p-override': { value: 'off', metadata: { mode: 'off', at: NOW } }, + 'ai-logging:p-plan': { value: 'metadata', metadata: { mode: 'metadata', at: NOW } }, + 'ai-logging:p-wins': { value: 'full', metadata: { mode: 'full', at: NOW } }, + // A plan ID missing from the catalog follows the default plan (custom on installs). + 'ai-logging:p-legacy': { value: 'off', metadata: { mode: 'off', at: NOW } }, + // Too young to call an orphan: its create transaction may still commit. + 'ai-logging:p-just-created': { + value: 'off', + metadata: { mode: 'off', at: NOW - AI_LOGGING_ORPHAN_GRACE_MS + 1_000 }, + }, + 'ai-block:p-plan': { value: '1' }, + // A project that now inherits leaves a short-lived marker so readback says pending. + 'ai-logging-cleared:p-stale': { value: 'inherit', metadata: { at: NOW } }, + }); + expect(Object.fromEntries(expirations)).toEqual({ + 'ai-logging-cleared:p-stale': AI_LOGGING_CLEARED_TTL_SECONDS, + }); + }); + + it('stamps keys with the database clock, not the operator machine clock', async () => { + await seed(` + INSERT INTO users (id, login, plan) VALUES ('u1', 'one', 'free'); + INSERT INTO projects (id, user_id, slug) VALUES ('p1', 'u1', 'one'); + INSERT INTO project_ai_logging (project_id, mode) VALUES ('p1', 'off'); + `); + // An orphan the API wrote 5 minutes ago by its own clock: inside the grace period. + const { kv, store } = memoryKv({ + 'ai-logging:p-young': { value: 'off', metadata: { mode: 'off', at: NOW - 300_000 } }, + }); + const databaseClock = { + query: async (sql: string, values?: ReadonlyArray) => + sql.includes('clock_timestamp()') + ? { rows: [{ now: NOW }] } + : connection.query(sql, values), + } as QueryConnection; + // The operator machine runs an hour fast. + vi.spyOn(Date, 'now').mockReturnValue(NOW + 3_600_000); + try { + await projectPlatformAiLoggingConnection(databaseClock, kv); + } finally { + vi.mocked(Date.now).mockRestore(); + } + expect(Object.fromEntries(store)).toEqual({ + 'ai-logging:p1': { value: 'off', metadata: { mode: 'off', at: NOW } }, + 'ai-logging:p-young': { value: 'off', metadata: { mode: 'off', at: NOW - 300_000 } }, + }); + }); + + it('reads the clock from a real database', async () => { + await seed(` + INSERT INTO users (id, login, plan) VALUES ('u1', 'one', 'free'); + INSERT INTO projects (id, user_id, slug) VALUES ('p1', 'u1', 'one'); + INSERT INTO project_ai_logging (project_id, mode) VALUES ('p1', 'off'); + `); + const { kv, store } = memoryKv(); + const before = Date.now(); + await projectPlatformAiLoggingConnection(connection, kv); + const { at } = store.get('ai-logging:p1')!.metadata as { at: number }; + expect(Number.isSafeInteger(at)).toBe(true); + expect(at).toBeGreaterThanOrEqual(before - 60_000); + expect(at).toBeLessThanOrEqual(Date.now() + 60_000); + }); + + it('holds the project row locks while it reads inputs and writes KV', async () => { + await seed(` + INSERT INTO users (id, login, plan) VALUES ('u1', 'one', 'free'); + INSERT INTO projects (id, user_id, slug) VALUES ('p1', 'u1', 'one'), ('p2', 'u1', 'two'); + INSERT INTO project_ai_logging (project_id, mode) VALUES ('p1', 'metadata'); + `); + const statements: Array = []; + const { kv, calls } = memoryKv(); + const order: Array = []; + const wrapped: AiLoggingProjectionKv = { + list: async (prefix) => { + order.push('kv list'); + return kv.list(prefix); + }, + put: async (entries) => { + order.push('kv put'); + // The change the API saved while the projection waited for the lock is the + // one written, because the inputs are read again under the lock. + expect(entries).toEqual([ + { key: 'ai-logging:p1', value: 'off', metadata: { mode: 'off', at: NOW } }, + ]); + return kv.put(entries); + }, + delete: kv.delete, + }; + const client = recording(statements, (sql) => { + if (sql.includes('FOR NO KEY UPDATE')) { + order.push('lock'); + } else if (sql === 'COMMIT') { + order.push('commit'); + } + }); + // Simulate the API saving a newer override just before the lock is granted. + const lockingClient = { + query: async (sql: string, values?: ReadonlyArray) => { + if (sql.includes('FOR NO KEY UPDATE')) { + await connection.query( + `UPDATE project_ai_logging SET mode = 'off' WHERE project_id = 'p1'`, + ); + } + return client.query(sql, values); + }, + } as QueryConnection; + + await projectPlatformAiLoggingConnection(lockingClient, wrapped, { now: () => NOW }); + + expect(order).toEqual(['kv list', 'lock', 'kv put', 'commit']); + const lock = statements.find((sql) => sql.includes('FOR NO KEY UPDATE'))!; + expect(lock).toContain('FROM "projects"'); + expect(lock).toContain('ORDER BY "id"'); + expect(statements[statements.indexOf('BEGIN') + 1]).toContain('lock_timeout'); + expect(calls).toEqual(['list', 'put']); + }); + + it('reads plan defaults again once the project row locks are held', async () => { + await seed(` + INSERT INTO users (id, login, plan) VALUES ('u1', 'one', 'pro'); + INSERT INTO projects (id, user_id, slug) VALUES ('p1', 'u1', 'one'); + INSERT INTO platform_settings (key, value) VALUES + ('plans:ai-logging', '{"modes":{"pro":"metadata"},"publish":null}'); + `); + const { kv, store } = memoryKv(); + // Simulate the API saving a newer plan default just before the lock is granted. + const lockingClient = { + query: async (sql: string, values?: ReadonlyArray) => { + if (sql.includes('FOR NO KEY UPDATE')) { + await connection.query( + `UPDATE platform_settings SET value = '{"modes":{"pro":"off"},"publish":null}' + WHERE key = 'plans:ai-logging'`, + ); + } + return connection.query(sql, values); + }, + } as QueryConnection; + + await projectPlatformAiLoggingConnection(lockingClient, kv, { now: () => NOW }); + + expect(Object.fromEntries(store)).toEqual({ + 'ai-logging:p1': { value: 'off', metadata: { mode: 'off', at: NOW } }, + }); + }); + + it('rolls back and fails when a bulk write fails', async () => { + await seed(` + INSERT INTO users (id, login, plan) VALUES ('u1', 'one', 'free'); + INSERT INTO projects (id, user_id, slug) VALUES ('p1', 'u1', 'one'); + INSERT INTO project_ai_logging (project_id, mode) VALUES ('p1', 'off'); + `); + const statements: Array = []; + const { kv } = memoryKv(); + const failing = { + ...kv, + put: vi.fn(async () => { + throw new Error('KV down'); + }), + }; + await expect( + projectPlatformAiLoggingConnection(recording(statements), failing), + ).rejects.toThrow('KV down'); + expect(statements.at(-1)).toBe('ROLLBACK'); + expect(statements).not.toContain('COMMIT'); + }); + + it('changes nothing visible when run again', async () => { + await seed(` + INSERT INTO users (id, login, plan) VALUES ('u1', 'one', 'free'); + INSERT INTO projects (id, user_id, slug) VALUES ('p1', 'u1', 'one'), ('p2', 'u1', 'two'); + INSERT INTO project_ai_logging (project_id, mode) VALUES ('p1', 'full'); + `); + const { kv, store } = memoryKv(); + await projectPlatformAiLoggingConnection(connection, kv, { now: () => NOW }); + const first = Object.fromEntries(store); + await expect( + projectPlatformAiLoggingConnection(connection, kv, { now: () => NOW }), + ).resolves.toEqual({ skipped: false, projects: 1, written: 1, deleted: 0 }); + expect(Object.fromEntries(store)).toEqual(first); + // Inherit projects never get a key. + expect(store.has('ai-logging:p2')).toBe(false); + }); + + it('refuses to publish from invalid saved plan defaults', async () => { + await seed(`INSERT INTO platform_settings (key, value) + VALUES ('plans:ai-logging', '{"modes":{"pro":"loud"}}');`); + const { kv, calls } = memoryKv(); + await expect(projectPlatformAiLoggingConnection(connection, kv)).rejects.toThrow( + 'The saved plan settings are not valid for this platform version', + ); + expect(calls).toEqual(['list']); + }); + + it('runs through the database lock with a KV client bound to the routing namespace', async () => { + const client = { + listKvKeys: vi.fn(async () => []), + putKvBulk: vi.fn(async () => {}), + deleteKvBulk: vi.fn(async () => {}), + }; + const progress: Array = []; + const publishAiLogging = vi.fn(async (kv: AiLoggingProjectionKv) => { + await kv.list('ai-logging:'); + await kv.put([{ key: 'ai-logging:p1', value: 'off' }]); + await kv.delete(['ai-logging:p2']); + return { skipped: false as const, projects: 2, written: 1, deleted: 1 }; + }); + await publishInstallationAiLogging({ + client, + accountId: 'account', + routingKvId: 'routing', + databaseLock: { publishAiLogging }, + onProgress: (message) => progress.push(message), + }); + expect(progress).toEqual(['Publishing AI logging settings']); + expect(client.listKvKeys).toHaveBeenCalledWith('account', 'routing', 'ai-logging:'); + expect(client.putKvBulk).toHaveBeenCalledWith('account', 'routing', [ + { key: 'ai-logging:p1', value: 'off' }, + ]); + expect(client.deleteKvBulk).toHaveBeenCalledWith('account', 'routing', ['ai-logging:p2']); + await expect( + publishInstallationAiLogging({ + client, + accountId: 'account', + routingKvId: 'routing', + databaseLock: {}, + }), + ).resolves.toBeNull(); + }); +}); diff --git a/packages/void/test/unit/platform-cloudflare.test.ts b/packages/void/test/unit/platform-cloudflare.test.ts index b35515604..ee757d202 100644 --- a/packages/void/test/unit/platform-cloudflare.test.ts +++ b/packages/void/test/unit/platform-cloudflare.test.ts @@ -807,6 +807,89 @@ describe('platform Cloudflare client', () => { }); }); + it('lists KV keys with metadata across cursor pages', async () => { + const requests: Array = []; + const client = new PlatformCloudflareClient('token', { + apiBase: 'https://cloudflare.example.test/client/v4', + fetcher: async (input) => { + const url = new URL(String(input)); + requests.push(url); + const first = !url.searchParams.has('cursor'); + return Response.json({ + success: true, + result: first + ? [{ name: 'ai-logging:p1', metadata: { mode: 'off', at: 1 } }] + : [{ name: 'ai-logging:p2' }], + result_info: { count: 1, cursor: first ? 'next' : '' }, + }); + }, + }); + await expect(client.listKvKeys('account', 'routing', 'ai-logging:')).resolves.toEqual([ + { name: 'ai-logging:p1', metadata: { mode: 'off', at: 1 } }, + { name: 'ai-logging:p2' }, + ]); + expect(requests.map((url) => url.pathname)).toEqual([ + '/client/v4/accounts/account/storage/kv/namespaces/routing/keys', + '/client/v4/accounts/account/storage/kv/namespaces/routing/keys', + ]); + expect(requests.map((url) => Object.fromEntries(url.searchParams))).toEqual([ + { prefix: 'ai-logging:', limit: '1000' }, + { prefix: 'ai-logging:', limit: '1000', cursor: 'next' }, + ]); + }); + + it('stops on a repeated KV key cursor instead of looping', async () => { + const client = new PlatformCloudflareClient('token', { + fetcher: async () => + Response.json({ success: true, result: [], result_info: { cursor: 'same' } }), + }); + await expect(client.listKvKeys('account', 'routing', 'ai-logging:')).rejects.toThrow( + 'repeated KV key cursor', + ); + }); + + it('writes and deletes KV keys in bulk batches and fails on any unwritten key', async () => { + const requests: Array<{ method: string; path: string; body: Array }> = []; + let failed: Array = []; + const client = new PlatformCloudflareClient('token', { + apiBase: 'https://cloudflare.example.test/client/v4', + fetcher: async (input, init) => { + const body = JSON.parse(String(init?.body)) as Array; + requests.push({ + method: init?.method ?? 'GET', + path: new URL(String(input)).pathname, + body, + }); + return Response.json({ + success: true, + result: { successful_key_count: body.length, unsuccessful_keys: failed }, + }); + }, + }); + const entries = Array.from({ length: 10_001 }, (_, index) => ({ + key: `ai-logging:p${index}`, + value: 'off', + metadata: { mode: 'off', at: 1 }, + })); + await client.putKvBulk('account', 'routing', entries); + await client.deleteKvBulk('account', 'routing', ['ai-logging:gone']); + expect(requests.map(({ method, path, body }) => [method, path, body.length])).toEqual([ + ['PUT', '/client/v4/accounts/account/storage/kv/namespaces/routing/bulk', 10_000], + ['PUT', '/client/v4/accounts/account/storage/kv/namespaces/routing/bulk', 1], + ['POST', '/client/v4/accounts/account/storage/kv/namespaces/routing/bulk/delete', 1], + ]); + expect(requests[0]!.body[0]).toEqual(entries[0]); + expect(requests[2]!.body).toEqual(['ai-logging:gone']); + + failed = ['ai-logging:p1']; + await expect(client.putKvBulk('account', 'routing', entries.slice(0, 2))).rejects.toThrow( + 'did not write 1 KV keys', + ); + await expect(client.deleteKvBulk('account', 'routing', ['ai-logging:p1'])).rejects.toThrow( + 'did not delete 1 KV keys', + ); + }); + it('filters KV namespaces by exact title instead of trusting an unsupported API filter', async () => { const entries = [ { id: 'routing-id', title: 'void-example-routing' }, diff --git a/packages/void/test/unit/platform-deployment-execution.test.ts b/packages/void/test/unit/platform-deployment-execution.test.ts index 0338410b7..89b30d2fd 100644 --- a/packages/void/test/unit/platform-deployment-execution.test.ts +++ b/packages/void/test/unit/platform-deployment-execution.test.ts @@ -185,14 +185,17 @@ it.each([1, 0])( createQueue: provision, createR2Bucket: provision, createDispatchNamespace: provision, + deleteKvBulk: provision, deleteKvValue: provision, getWorkerPlainTextBindings: provision, + listKvKeys: provision, listWorkerDomains: provision, listWorkerNames: provision, listWorkerRoutes: provision, listWorkerServiceRoutes: provision, publishWorkerCustomDomainsSafely: provision, publishWorkerRoutesSafely: provision, + putKvBulk: provision, putKvValue: async () => {}, putR2Object: async () => {}, request: provision, diff --git a/packages/void/test/unit/platform-install-cutover.test.ts b/packages/void/test/unit/platform-install-cutover.test.ts index 8bc9be0f4..5775a7b70 100644 --- a/packages/void/test/unit/platform-install-cutover.test.ts +++ b/packages/void/test/unit/platform-install-cutover.test.ts @@ -254,6 +254,11 @@ async function createFakeCloudflare() { createZone: async (): Promise => { throw new Error('No zone expected'); }, + deleteKvBulk: async (_account: string, namespace: string, keys: ReadonlyArray) => { + for (const key of keys) { + kv.delete(`${namespace}/${key}`); + } + }, deleteKvValue: async (_account: string, namespace: string, key: string) => { kv.delete(`${namespace}/${key}`); }, @@ -265,12 +270,25 @@ async function createFakeCloudflare() { origin: hyperdriveOriginFromConnectionString(DATABASE_URL), }), getWorkerPlainTextBindings: plainTextBindings, + listKvKeys: async (_account: string, namespace: string, prefix: string) => + [...kv.keys()] + .filter((key) => key.startsWith(`${namespace}/${prefix}`)) + .map((key) => ({ name: key.slice(namespace.length + 1) })), listWorkerDomains: async () => [], listWorkerNames: async () => [...workers.keys()], listWorkerRoutes: async () => [], listWorkerServiceRoutes: async () => [], publishWorkerCustomDomainsSafely: async () => {}, publishWorkerRoutesSafely: async () => {}, + putKvBulk: async ( + _account: string, + namespace: string, + entries: ReadonlyArray<{ key: string; value: string }>, + ) => { + for (const entry of entries) { + kv.set(`${namespace}/${entry.key}`, entry.value); + } + }, putKvValue: async (_account: string, namespace: string, key: string, value: string) => { kv.set(`${namespace}/${key}`, value); }, diff --git a/packages/void/test/unit/platform-installer.test.ts b/packages/void/test/unit/platform-installer.test.ts index 02c468ef2..a49ae3907 100644 --- a/packages/void/test/unit/platform-installer.test.ts +++ b/packages/void/test/unit/platform-installer.test.ts @@ -29,6 +29,7 @@ import { } from '@void/platform/installer'; import { toSlash } from 'pathslash'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; +import type { AiLoggingProjectionKv } from '../../src/cli/platform-ai-logging-projection.ts'; import { PlatformCloudflareApiError } from '../../src/cli/platform-cloudflare.ts'; import { hyperdriveOriginConfigHash, @@ -110,16 +111,19 @@ type InstallArguments = Parameters; type InstallClient = InstallArguments[3]['client']; type DefaultedClientMethods = | 'apiBaseUrl' + | 'deleteKvBulk' | 'deleteKvValue' | 'disableHyperdriveCaching' | 'getHyperdriveConfig' | 'getWorkerPlainTextBindings' + | 'listKvKeys' | 'listWorkerDomains' | 'listWorkerNames' | 'listWorkerRoutes' | 'listWorkerServiceRoutes' | 'publishWorkerCustomDomainsSafely' | 'publishWorkerRoutesSafely' + | 'putKvBulk' | 'request'; type TestInstallerDependencies = Omit & { client: Omit & @@ -144,8 +148,10 @@ function installPlatform( ...dependencies, client: { apiBaseUrl: resolvePinnedApiBaseUrl(), + deleteKvBulk: unexpectedCloudflareCall('deleteKvBulk'), deleteKvValue: async () => {}, getWorkerPlainTextBindings: unexpectedCloudflareCall('getWorkerPlainTextBindings'), + listKvKeys: unexpectedCloudflareCall('listKvKeys'), listWorkerDomains: unexpectedCloudflareCall('listWorkerDomains'), listWorkerNames: unexpectedCloudflareCall('listWorkerNames'), listWorkerRoutes: unexpectedCloudflareCall('listWorkerRoutes'), @@ -154,6 +160,7 @@ function installPlatform( 'publishWorkerCustomDomainsSafely', ), publishWorkerRoutesSafely: unexpectedCloudflareCall('publishWorkerRoutesSafely'), + putKvBulk: unexpectedCloudflareCall('putKvBulk'), request: unexpectedCloudflareCall('request'), ...dependencies.client, getHyperdriveConfig: @@ -837,6 +844,106 @@ describe('platform installer', () => { expect(events).toEqual(['lift fence', 'enable traffic']); }); + it('publishes AI logging settings after migrations, before the Workers upload, and again after it', async () => { + useRegistryDirectory(); + const plan = await createPlatformInstallPlan( + planningClient(), + { + accountId: 'account', + applicationDomain: '', + zoneName: '', + workersDev: true, + controlPlaneDomain: '', + dedicatedZone: false, + displayName: 'Logging', + installationSlug: 'logging', + }, + null, + ); + let index = 0; + const create = async (_account: string, name: string) => ({ + id: `resource-${index++}`, + name, + }); + const events: Array = []; + const kvCalls: Array = []; + const result = await installPlatform(plan, freshSecrets(), null, { + claimDatabase, + acquireDatabaseLifecycleLock: async () => + Object.assign(async () => {}, { + prepareSandboxDrain: async () => sandboxDrainPreparation('complete'), + publishAiLogging: async (kv: AiLoggingProjectionKv) => { + events.push('publish AI logging'); + await kv.list('ai-logging:'); + await kv.put([ + { key: 'ai-logging:p1', value: 'off', metadata: { mode: 'off', at: 1 } }, + ]); + await kv.delete(['ai-logging:p2']); + return { skipped: false as const, projects: 2, written: 1, deleted: 1 }; + }, + }), + client: { + createAiGateway: create, + createDnsRecord: async () => { + throw new Error('no DNS expected'); + }, + createZone: async () => { + throw new Error('no zone expected'); + }, + createKvNamespace: create, + createR2Bucket: create, + createQueue: create, + createDispatchNamespace: create, + createHyperdrive: create, + putKvValue: async () => {}, + putR2Object: async () => {}, + listKvKeys: async (...args) => { + kvCalls.push(['list', ...args]); + return []; + }, + putKvBulk: async (...args) => { + kvCalls.push(['put', ...args]); + }, + deleteKvBulk: async (...args) => { + kvCalls.push(['delete', ...args]); + }, + }, + deployWorker: async (config) => { + events.push(`deploy ${String(config.name)}`); + }, + prepareDatabase: async () => { + events.push('migrate'); + return prepareDatabase(); + }, + revalidateBeforeWorkerDeploy: async () => {}, + verifyHealth: async () => {}, + }); + expect(result.manifest.status).toBe('installed'); + const upload = ['api', 'proxy', 'email-gateway', 'tail', 'dispatch'].map( + (name) => `deploy void-logging-${name}`, + ); + // A fresh install uploads the Workers with traffic paused, then deploys them + // again to open traffic; the second pass runs between the two. + expect(events).toEqual([ + 'migrate', + 'publish AI logging', + ...upload, + 'publish AI logging', + ...upload, + ]); + const routing = result.manifest.resources.find((resource) => resource.key === 'routing-kv')!; + expect(kvCalls.slice(0, 3)).toEqual([ + ['list', 'account', routing.id, 'ai-logging:'], + [ + 'put', + 'account', + routing.id, + [{ key: 'ai-logging:p1', value: 'off', metadata: { mode: 'off', at: 1 } }], + ], + ['delete', 'account', routing.id, ['ai-logging:p2']], + ]); + }); + it('keeps traffic disabled and the verified Worker set when shared email bootstrap blocks', async () => { const directory = useRegistryDirectory(); const plan = await createPlatformInstallPlan( @@ -3558,6 +3665,16 @@ describe('platform installer', () => { expect( queries.find(({ sql }) => sql.startsWith('DELETE FROM "platform_settings"'))?.values, ).toEqual(['platform.uninstall']); + + // AI logging projection runs on this same session; this fake has no table. + await expect( + lock.publishAiLogging!({ + list: async () => [], + put: async () => {}, + delete: async () => {}, + }), + ).resolves.toEqual({ skipped: true }); + expect(queries.at(-1)?.sql).toContain("to_regclass('public.project_ai_logging')"); await lock(); }); diff --git a/packages/void/test/unit/platform-management-upgrade.test.ts b/packages/void/test/unit/platform-management-upgrade.test.ts index 36806cc34..0fac55263 100644 --- a/packages/void/test/unit/platform-management-upgrade.test.ts +++ b/packages/void/test/unit/platform-management-upgrade.test.ts @@ -33,6 +33,7 @@ const state = vi.hoisted(() => ({ events: [] as Array, manifest: undefined as PlatformInstallationManifest | undefined, prepareDatabase: vi.fn(), + publishAiLogging: vi.fn(), readAdministratorSetup: vi.fn(), readAuthenticationState: vi.fn(), readPlanZeroTrust: vi.fn(), @@ -145,6 +146,7 @@ vi.mock('../../src/cli/platform-installer.ts', async (importOriginal) => { authoritativeManifest: state.manifest, checkpoint: vi.fn(), prepareDatabase: state.prepareDatabase, + publishAiLogging: state.publishAiLogging, readAdministratorSetup: state.readAdministratorSetup, readAuthenticationState: state.readAuthenticationState, readProjectZeroTrust: state.readProjectZeroTrust, @@ -164,6 +166,8 @@ vi.mock('../../src/cli/platform-installer.ts', async (importOriginal) => { existing!.ownershipNonce, ); expect(borrowed.prepareDatabase).toBe(state.prepareDatabase); + // Every upgrade and repair republishes AI logging settings on the held connection. + expect(borrowed.publishAiLogging).toBe(state.publishAiLogging); expect(borrowed.readAuthenticationState).toBe(state.readAuthenticationState); await borrowed.readAuthenticationState!(); state.events.push('installer-start'); diff --git a/packages/void/test/unit/platform-plans-config.test.ts b/packages/void/test/unit/platform-plans-config.test.ts index 0e993fc4c..0d071029a 100644 --- a/packages/void/test/unit/platform-plans-config.test.ts +++ b/packages/void/test/unit/platform-plans-config.test.ts @@ -357,3 +357,228 @@ describe('platform config plans', () => { ); }); }); + +describe('platform config plans AI logging defaults', () => { + const catalog = { ...createDefaultPlanCatalog('free'), revision: 7 }; + const aiLogging = { modes: { pro: 'metadata' }, publish: null, remaining: 0 }; + + /** A platform that answers each request from `answer`, recording request bodies. */ + function platform(answer: (url: string, body?: Record) => unknown) { + const fetcher = vi.fn(async (input: string | URL | Request, init?: RequestInit) => { + const url = input.toString(); + const body = init?.body ? JSON.parse(init.body as string) : undefined; + calls.push({ url, body }); + return Response.json(answer(url, body)); + }); + vi.stubGlobal('fetch', fetcher); + return fetcher; + } + + function output() { + return vi + .mocked(console.log) + .mock.calls.map((call) => String(call[0])) + .join('\n'); + } + + async function planFile(content: unknown) { + const file = join(directory, 'plan.json'); + await writeFile(file, JSON.stringify(content)); + return file; + } + + it('refuses aiLogging before any request on a platform without plan defaults', async () => { + platform(() => ({ catalog, accounts: [] })); + const file = await planFile({ aiLogging: 'off' }); + await expect( + runPlatformPlansConfig( + parsePlatformPlansArgs(['plans', 'set', 'pro', '--file', file, '--yes']), + ), + ).rejects.toThrow('Upgrade the platform first'); + expect(calls.filter((call) => call.body)).toHaveLength(0); + }); + + it('rejects an unknown aiLogging mode in a plan file', async () => { + platform(() => ({ catalog, accounts: [], aiLogging })); + const file = await planFile({ aiLogging: 'everything' }); + await expect( + runPlatformPlansConfig( + parsePlatformPlansArgs(['plans', 'set', 'pro', '--file', file, '--yes']), + ), + ).rejects.toThrow('aiLogging must be one of inherit, off, metadata, full'); + expect(calls.filter((call) => call.body)).toHaveLength(0); + }); + + it('previews the AI Gateway logging change as a diff line with the project count', async () => { + platform((_url, body) => + body + ? { + dryRun: true, + action: 'plans.set', + target: 'pro', + expectedRevision: 7, + catalog: { ...catalog, revision: 8 }, + affectedAccounts: 3, + aiLogging: { modes: {}, planIds: ['pro'], includeUnknown: false }, + aiLoggingPublish: { complete: false, processed: 0, remaining: 12, expectedBy: null }, + } + : { catalog, accounts: [], aiLogging }, + ); + const file = await planFile({ aiLogging: 'inherit' }); + await runPlatformPlansConfig( + parsePlatformPlansArgs(['plans', 'set', 'pro', '--file', file, '--plan']), + ); + expect(calls.at(-1)?.body).toEqual({ aiLogging: 'inherit', dryRun: true }); + expect(output()).toContain('AI Gateway logging: metadata → inherit'); + expect(output()).toContain('AI logging settings to publish: 12 projects'); + }); + + it('shows the current default the dry run read, not the cached listing', async () => { + platform((_url, body) => + body + ? { + dryRun: true, + action: 'plans.set', + target: 'pro', + expectedRevision: 7, + catalog: { ...catalog, revision: 8 }, + affectedAccounts: 3, + aiLogging: { + modes: {}, + modesBefore: { pro: 'off' }, + planIds: ['pro'], + includeUnknown: false, + }, + } + : { catalog, accounts: [], aiLogging }, + ); + const file = await planFile({ aiLogging: 'inherit' }); + await runPlatformPlansConfig( + parsePlatformPlansArgs(['plans', 'set', 'pro', '--file', file, '--plan']), + ); + expect(output()).toContain('AI Gateway logging: off → inherit'); + }); + + it('offers the setting in the interactive picker', async () => { + vi.stubGlobal('process', { ...process, stdin: { ...process.stdin, isTTY: true } }); + platform((_url, body) => + body?.dryRun + ? { dryRun: true, expectedRevision: 7, catalog, affectedAccounts: 0, aiLogging } + : body + ? { + catalog, + reconciliation: { complete: true, processed: 0 }, + aiLoggingPublish: { complete: true, processed: 0, remaining: 0, expectedBy: null }, + } + : { catalog, accounts: [], aiLogging }, + ); + vi.mocked(select).mockResolvedValueOnce('aiLogging').mockResolvedValueOnce('off'); + vi.mocked(confirm).mockResolvedValueOnce(true); + await runPlatformPlansConfig(parsePlatformPlansArgs(['plans', 'set', 'pro'])); + expect(select).toHaveBeenNthCalledWith( + 1, + expect.objectContaining({ + options: expect.arrayContaining([ + { value: 'aiLogging', label: 'AI Gateway logging: metadata' }, + ]), + }), + ); + expect(select).toHaveBeenNthCalledWith( + 2, + expect.objectContaining({ initialValue: 'metadata' }), + ); + expect(calls.at(-1)?.body).toEqual({ aiLogging: 'off', expectedRevision: 7 }); + }); + + it('keeps syncing until the AI logging publish completes, then prints the expected time', async () => { + const pages = [ + { complete: false, processed: 100, remaining: 150, expectedBy: '2026-11-13T14:01:00.000Z' }, + { complete: false, processed: 100, remaining: 50, expectedBy: '2026-11-13T14:02:00.000Z' }, + { complete: true, processed: 50, remaining: 0, expectedBy: '2026-11-13T14:03:20.000Z' }, + ]; + platform((url, body) => { + if (!body) { + return { catalog, accounts: [], aiLogging }; + } + if (body.dryRun) { + return { + dryRun: true, + action: 'plans.set', + target: 'pro', + expectedRevision: 7, + catalog: { ...catalog, revision: 8 }, + affectedAccounts: 0, + aiLogging: { modes: { pro: 'off' }, planIds: ['pro'], includeUnknown: false }, + }; + } + return { + ...(url.endsWith('/sync') ? {} : { action: 'plans.set', target: 'pro' }), + catalog: { ...catalog, revision: 8 }, + reconciliation: { complete: true, processed: 0 }, + aiLoggingPublish: pages.shift(), + }; + }); + const file = await planFile({ aiLogging: 'off' }); + await runPlatformPlansConfig( + parsePlatformPlansArgs(['plans', 'set', 'pro', '--file', file, '--yes']), + ); + expect(calls.filter((call) => call.url.endsWith('/sync'))).toEqual([ + { + url: 'https://api.example.com/operator/v1/config/plans/sync', + body: { expectedRevision: 8 }, + }, + { + url: 'https://api.example.com/operator/v1/config/plans/sync', + body: { expectedRevision: 8 }, + }, + ]); + expect(output()).toContain( + 'AI logging published to 250 projects; expected by 14:03:20 UTC (normally within 2 minutes).', + ); + }); + + it('stops with a resumption command when the AI logging publish fails', async () => { + platform((_url, body) => + !body + ? { catalog, accounts: [], aiLogging } + : body.dryRun + ? { dryRun: true, expectedRevision: 7, catalog, affectedAccounts: 0 } + : { + action: 'plans.set', + target: 'pro', + catalog: { ...catalog, revision: 8 }, + reconciliation: { complete: true, processed: 0 }, + aiLoggingPublish: { complete: false, processed: 0, remaining: 3, error: 'KV failed' }, + // The API marks a failed publish page this way; the CLI must still name plans sync. + ok: false, + }, + ); + const file = await planFile({ aiLogging: 'off' }); + await expect( + runPlatformPlansConfig( + parsePlatformPlansArgs(['plans', 'set', 'pro', '--file', file, '--yes']), + ), + ).rejects.toMatchObject({ + code: 'plan_sync_pending', + message: expect.stringContaining('AI logging setting is not published to every project'), + }); + }); + + it('shows the plan default and a pending publish', async () => { + platform((url) => + url.endsWith('/config/plans') + ? { catalog, accounts: [], aiLogging } + : { + catalogRevision: 7, + default: false, + plan: catalog.plans.find((plan) => plan.id === 'pro'), + accounts: 2, + aiLogging: 'metadata', + aiLoggingPublish: { complete: false, remaining: 4, planIds: ['pro'] }, + }, + ); + await runPlatformPlansConfig(parsePlatformPlansArgs(['plans', 'show', 'pro'])); + expect(output()).toContain('AI Gateway logging: metadata'); + expect(output()).toContain('AI logging publish pending: 4 projects remaining'); + }); +}); diff --git a/platform/packages/api/test/integration/operator-cli-e2e.test.ts b/platform/packages/api/test/integration/operator-cli-e2e.test.ts index f80a97a9e..a2149de96 100644 --- a/platform/packages/api/test/integration/operator-cli-e2e.test.ts +++ b/platform/packages/api/test/integration/operator-cli-e2e.test.ts @@ -5,7 +5,8 @@ import { createServer, type Server } from 'node:http'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; -import { afterAll, beforeAll, beforeEach, expect, test, vi } from 'vite-plus/test'; +import { afterAll, beforeAll, beforeEach, expect, onTestFinished, test, vi } from 'vite-plus/test'; +import { aiLoggingKey } from '../../src/ai-logging-policy.ts'; import { getUser } from '../../src/db.ts'; import type { ApiEnv } from '../../src/env.ts'; import { app } from '../../src/index.ts'; @@ -139,6 +140,12 @@ test('built CLI configures the logging policy enforced by the actual AI proxy', const { default: proxy } = (await import(/* @vite-ignore */ proxyUrl)) as { default: { fetch(request: Request, env: unknown): Promise }; }; + // Hosted Void Cloud does not set the uncached auth-database flag. + const uncached = env.PLATFORM_AUTH_DATABASE_UNCACHED; + delete env.PLATFORM_AUTH_DATABASE_UNCACHED; + onTestFinished(() => { + env.PLATFORM_AUTH_DATABASE_UNCACHED = uncached; + }); const owner = await createTestUser(env.db, 'ai-customer'); const project = await createTestProject(env.db, owner.id, 'private-ai'); const command = ['project', 'ai-logging', project.id, 'metadata']; @@ -150,6 +157,8 @@ test('built CLI configures the logging policy enforced by the actual AI proxy', const saved = await run([...command, '--yes', '--json']); expect(saved.code, saved.stderr).toBe(0); expect(JSON.parse(saved.stdout)).toMatchObject({ mode: 'metadata' }); + // The proxy reads only the published ROUTING value, which the API wrote. + expect(await env.ROUTING.get(aiLoggingKey(project.id))).toBe('metadata'); const ai = { run: vi.fn(async () => ({ response: 'ok' })), @@ -191,10 +200,19 @@ test('built CLI configures the logging policy enforced by the actual AI proxy', extraHeaders: { 'cf-aig-collect-log-payload': 'false' }, }), ); - // The same isolate must enforce a new policy without a deploy or stale cache. + // The proxy reads the key on every call and keeps no copy of its own, so a new + // value applies without a deploy. This test KV ignores `cacheTtl`: in production a + // location that already read the old value may serve it until the cache time ends, + // which is why the command prints an expected-by time instead of "now". const changed = await run(['project', 'ai-logging', project.id, 'off', '--yes', '--json']); expect(changed.code, changed.stderr).toBe(0); + const reads = vi.spyOn(env.ROUTING, 'get'); expect((await proxy.fetch(request(), bindings)).status).toBe(200); + expect(reads).toHaveBeenCalledWith(aiLoggingKey(project.id), { cacheTtl: 30 }); + expect( + Date.parse((JSON.parse(changed.stdout) as { expectedBy: string }).expectedBy), + ).toBeGreaterThan(Date.now() + 30_000); + reads.mockRestore(); expect(ai.run).toHaveBeenLastCalledWith( 'test-model', { prompt: 'private' }, @@ -205,6 +223,19 @@ test('built CLI configures the logging policy enforced by the actual AI proxy', const audit = await run(['system', 'events', '--json']); expect(audit.code, audit.stderr).toBe(0); expect(JSON.stringify(JSON.parse(audit.stdout))).toContain(`projects/${project.id}/ai-logging`); + + // Human output names where the setting comes from and when new requests follow it. + const human = await run(['project', 'ai-logging', project.id, 'full', '--yes']); + expect(human.code, human.stderr).toBe(0); + expect(human.stdout).toContain( + `AI logging for ${project.id}: full (set on project; plan "free" default: inherit)`, + ); + expect(human.stdout).toContain('New AI requests are expected to follow it by '); + const shown = await run(['project', 'show', project.id]); + expect(shown.code, shown.stderr).toBe(0); + expect(shown.stdout).toContain( + 'AI Gateway logging: full (set on project; plan "free" default: inherit) — pending (expected by ', + ); }); test('built CLI authenticates, previews, changes access, and reads the actual database audit', async () => {