From f3b51312207e2d7c70286c4f58853a9616790fc6 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 5 Oct 2026 13:26:51 +0800 Subject: [PATCH 1/2] Polish platform upgrade and rollback UX --- .../platform/administration/operations.md | 8 + .../platform/installation/maintenance.md | 25 ++ docs/reference/cli/platform.md | 5 + packages/platform/src/index.ts | 2 + packages/platform/src/installation.ts | 72 +++++ packages/void/AGENTS.md | 2 + packages/void/src/cli/platform-cmd.ts | 48 ++- packages/void/src/cli/platform-installer.ts | 60 +++- packages/void/src/cli/platform-management.ts | 74 ++++- .../void/test/unit/installed-void.test.ts | 21 +- .../void/test/unit/platform-connect.test.ts | 61 +++- .../unit/platform-installation-state.test.ts | 30 ++ .../void/test/unit/platform-installer.test.ts | 10 + .../unit/platform-management-upgrade.test.ts | 66 +++- platform/packages/api/README.md | 1 + .../packages/api/src/admin/platform-status.ts | 50 ++++ .../admin/react/AdminNavigationFallback.tsx | 1 + .../packages/api/src/admin/react/pages.ts | 6 + .../packages/api/src/admin/react/styles.css | 83 +++++ .../api/src/admin/react/views/Layout.tsx | 7 + .../admin/react/views/PlatformStatusPage.tsx | 249 +++++++++++++++ .../packages/api/src/admin/routes/system.tsx | 21 ++ platform/packages/api/src/env.ts | 1 + platform/packages/api/src/index.ts | 53 +++- .../src/middleware/platform-maintenance.ts | 46 +++ .../platform-access-protection.test.ts | 32 +- .../test/integration/platform-status.test.ts | 283 ++++++++++++++++++ platform/packages/dispatch/src/error-page.ts | 33 +- platform/packages/dispatch/src/index.ts | 6 +- .../dispatch/test/unit/error-page.test.ts | 45 ++- 30 files changed, 1373 insertions(+), 28 deletions(-) create mode 100644 platform/packages/api/src/admin/platform-status.ts create mode 100644 platform/packages/api/src/admin/react/views/PlatformStatusPage.tsx create mode 100644 platform/packages/api/src/middleware/platform-maintenance.ts create mode 100644 platform/packages/api/test/integration/platform-status.test.ts diff --git a/docs/guide/platform/administration/operations.md b/docs/guide/platform/administration/operations.md index f0c934dad..4a418fadc 100644 --- a/docs/guide/platform/administration/operations.md +++ b/docs/guide/platform/administration/operations.md @@ -66,6 +66,14 @@ The dashboard’s **System Status** page refreshes health checks every 30 second Use `void platform upgrade`, `repair`, `disable`, and `enable` to maintain your platform. See [platform maintenance](/guide/platform/installation/maintenance#resume-repair-recover-and-upgrade). +For upgrade and rollback progress, open `/admin/status` on the API origin. +Administrators can follow saved progress and the API's traffic state during +maintenance while the API and authentication database remain reachable. If a +status refresh fails, the last confirmed snapshot is marked as stale. Normal +administrator changes stay paused during maintenance. +Follow the CLI's recovery instructions to resume an operation. See +[Follow upgrade and rollback progress](/guide/platform/installation/maintenance#follow-upgrade-and-rollback-progress). + For disaster recovery, keep a matching PostgreSQL backup, provider data backups, installation identity and complete project-encryption keyring, and immutable runtime artifacts. Keep traffic disabled while restoring data, run `discover` to reconstruct verified local metadata, and review `repair --plan` before recreating missing installer-owned infrastructure. Neither command restores backed-up data. See [Prepare for disaster recovery](/guide/platform/installation/maintenance#prepare-for-disaster-recovery) for the full sequence. ## Using Scripts diff --git a/docs/guide/platform/installation/maintenance.md b/docs/guide/platform/installation/maintenance.md index 1bd619e83..d23e4deb1 100644 --- a/docs/guide/platform/installation/maintenance.md +++ b/docs/guide/platform/installation/maintenance.md @@ -98,6 +98,31 @@ Keep the earlier runtime files if you need rollback. If the installed version is ::: +### Follow upgrade and rollback progress + +Open `/admin/status` on your platform API origin and sign in as an administrator. +The page shows the saved operation, source and target versions, and the traffic +state reported by the API. It refreshes every five seconds while visible. If +updates fail, it keeps the last confirmed snapshot and marks it as out of date. + +During maintenance, administrator navigation leads to this read-only page; +normal administrator changes remain paused. Sign-in and status remain available +while the API and authentication database are reachable. An operation completing +does not confirm every project's health. A disabled installation keeps traffic +paused after an upgrade or rollback. + +The CLI reports when an operation completes, fails, or waits for DNS or Sandbox +drain work, and prints the command needed to resume. Resolve the reported problem, +then resume with the same runtime files. For a custom rollback, retain the source +runtime files too. `void platform status ` also prints locally saved progress +before checking the live API; this local checkpoint can be out of date if another +administrator changed the installation. + +When application traffic is paused, visitors receive a temporary-unavailability +page with a **Try again** link. API requests and form submissions still receive +HTTP 503 responses. Void does not automatically replay requests; visitors who +submitted a form should check its result before submitting it again. + ### Manage an installation from another machine Use `discover` to restore the administrator's local installation records: diff --git a/docs/reference/cli/platform.md b/docs/reference/cli/platform.md index 536ab94ce..753391739 100644 --- a/docs/reference/cli/platform.md +++ b/docs/reference/cli/platform.md @@ -16,6 +16,11 @@ void platform status [id] `use` and `status` auto-select the only configured platform; with multiple platforms they show a picker interactively and require an id or URL in non-interactive use. A project with a recorded platform URL keeps using that platform when the global default changes. +For a self-hosted installation, `status ` prints locally saved +lifecycle progress before checking the live API. The saved checkpoint may be out +of date. If live discovery fails during maintenance, the command still shows that +checkpoint and exits with an error; it does not confirm current availability. + ## Operator commands {#operator-commands} Use `void platform` to administer the users and apps on your selected platform. Start with the [Platform Administration guide](../../guide/platform-administration.md) for signing in, giving people access, and investigating deployments. diff --git a/packages/platform/src/index.ts b/packages/platform/src/index.ts index 7f7f1a227..c71a5fddf 100644 --- a/packages/platform/src/index.ts +++ b/packages/platform/src/index.ts @@ -63,6 +63,7 @@ export { createPlatformInstallationManifest, parsePlatformResourceOwnershipMarker, parsePlatformInstallationManifest, + parsePlatformLifecycleOperation, recordInstallationResource, recordInstallationStep, setInstallationDesiredState, @@ -73,6 +74,7 @@ export { type InstallationStatus, type InstallationStep, type PlatformInstallationManifest, + type PlatformLifecycleOperation, type PlatformInstallationEndpoints, type PlatformRuntimeProvenance, type PlatformResourceOwnershipMarker, diff --git a/packages/platform/src/installation.ts b/packages/platform/src/installation.ts index 20e6cd1eb..5aa5093ee 100644 --- a/packages/platform/src/installation.ts +++ b/packages/platform/src/installation.ts @@ -72,6 +72,74 @@ export type PlatformRuntimeProvenance = Readonly<{ sourceRevision: string | null; }>; +/** Saved operator progress; this does not attest application availability. */ +export type PlatformLifecycleOperation = Readonly<{ + id: string; + action: 'install' | 'upgrade' | 'rollback' | 'repair' | 'enable'; + fromVersion: string | null; + toVersion: string; + runtimeManifestSha256?: string; + phase: + | 'preparing' + | 'deploying' + | 'verifying' + | 'enabling' + | 'waiting-for-dns' + | 'waiting-for-sandbox-drain' + | 'complete' + | 'failed'; + startedAt: string; + updatedAt: string; +}>; + +export function parsePlatformLifecycleOperation(value: unknown): PlatformLifecycleOperation { + assertRecord(value, 'operation'); + const actions = ['install', 'upgrade', 'rollback', 'repair', 'enable'] as const; + const phases = [ + 'preparing', + 'deploying', + 'verifying', + 'enabling', + 'waiting-for-dns', + 'waiting-for-sandbox-drain', + 'complete', + 'failed', + ] as const; + const action = actions.find((action) => action === value.action); + const phase = phases.find((phase) => phase === value.phase); + if (!action || !phase) { + throw new Error('Invalid platform operation action or phase.'); + } + if ( + value.runtimeManifestSha256 !== undefined && + (typeof value.runtimeManifestSha256 !== 'string' || + !/^[0-9a-f]{64}$/.test(value.runtimeManifestSha256)) + ) { + throw new Error('Invalid platform operation runtime digest.'); + } + return { + id: requiredString(value.id, 'operation.id'), + action, + fromVersion: + value.fromVersion === null + ? null + : requiredString(value.fromVersion, 'operation.fromVersion'), + toVersion: requiredString(value.toVersion, 'operation.toVersion'), + ...(typeof value.runtimeManifestSha256 === 'string' + ? { runtimeManifestSha256: value.runtimeManifestSha256 } + : {}), + phase, + startedAt: assertTimestamp( + requiredString(value.startedAt, 'operation.startedAt'), + 'operation.startedAt', + ), + updatedAt: assertTimestamp( + requiredString(value.updatedAt, 'operation.updatedAt'), + 'operation.updatedAt', + ), + }; +} + export type PlatformInstallationManifest = Readonly<{ authenticationResources?: ReadonlyArray< Readonly<{ @@ -99,6 +167,7 @@ export type PlatformInstallationManifest = Readonly<{ endpoints: PlatformInstallationEndpoints; id: string; ownershipNonce: string; + operation?: PlatformLifecycleOperation; platformVersion: string; resources: ReadonlyArray; runtime: PlatformRuntimeProvenance | null; @@ -446,6 +515,9 @@ export function parsePlatformInstallationManifest(value: unknown): PlatformInsta : 'enabled', status: value.status, runtime, + ...(value.operation !== undefined + ? { operation: parsePlatformLifecycleOperation(value.operation) } + : {}), ...(pendingDomain ? { pendingDomain } : {}), ...(value.authenticationResources !== undefined ? { authenticationResources: parseAuthenticationResources(value.authenticationResources) } diff --git a/packages/void/AGENTS.md b/packages/void/AGENTS.md index 7c899735e..a8b20e596 100644 --- a/packages/void/AGENTS.md +++ b/packages/void/AGENTS.md @@ -67,6 +67,8 @@ generated entries must preserve the module-boundary rules below. ### Key Design Decisions +- **Lifecycle progress**: Save operation phases under the installer database lock. Resume an operation ID only for the same action and target runtime digest. Progress describes the saved operation, not project availability; preserve traffic guards and report disabled installations separately from completed upgrades or rollbacks. + - **Platform resource identity**: New installations use `void--` names, without random suffixes. Conflicts fail closed; only matching ownership records/markers authorize reuse or resume. Externally managed Hyperdrive is an exception: users select it by ID, its name may differ from the generated name, and the selected name and origin are pinned for recovery. Keep recorded names and recovery behavior for older suffixed installations, and keep installation IDs/ownership nonces in metadata. Do not change application/user naming when changing platform infrastructure naming. - **Platform test origins**: Domain installations remain the default recommendation. Explicit `platform install --workers-dev` uses schema-v2 application routing and a forwarding Worker per project; normal domain platforms keep schema v1. `platform domain set` checkpoints pending DNS separately, verifies the live runtime token and HTTPS, then hands activation to the authenticated platform API. The service durably prepares Zero Trust destinations and project routing before publishing `PLATFORM_APPLICATION_KEY`; the CLI never publishes that key directly. API and dispatch resolve that configuration into a request-local environment copy. Preserve the original workers.dev identity and API origin. Forwarders share the main slug routing entry, validate its project ID, and honor suspension/disablement. They remain for manual cleanup, and their unpurgeable workers.dev edge-cache layer is bypassed while shared ISR remains enabled. diff --git a/packages/void/src/cli/platform-cmd.ts b/packages/void/src/cli/platform-cmd.ts index 7444a9aea..2d6c310ca 100644 --- a/packages/void/src/cli/platform-cmd.ts +++ b/packages/void/src/cli/platform-cmd.ts @@ -1,4 +1,4 @@ -import type { PlatformDiscoveryDocument } from '@void/platform'; +import type { PlatformDiscoveryDocument, PlatformInstallationManifest } from '@void/platform'; import { isCancel, log, select, text } from '@voidzero-dev/vite-plus-prompts'; import { cfAccessHeaders } from '../shared/cf-access.ts'; import { @@ -15,6 +15,7 @@ import { normalizePlatformApiUrl, savePlatformConnection, selectPlatformConnection, + listInstallationManifests, type PlatformConnection, } from './platform-registry.ts'; @@ -171,8 +172,36 @@ export async function runPlatformCommand(_root: string, args: PlatformArgs): Pro } if (args.subcommand === 'status') { - const connection = await resolveConnection(args.selector); - const discovery = await discoverPlatform(connection.apiUrl); + const local = args.selector + ? listInstallationManifests().find( + (manifest) => manifest.id === args.selector && manifest.status !== 'uninstalled', + ) + : undefined; + const connection = local ? null : await resolveConnection(args.selector); + const saved = + local ?? + (connection?.installationId + ? listInstallationManifests().find((manifest) => manifest.id === connection.installationId) + : undefined); + if (saved) { + showSavedInstallationStatus(saved); + } + const apiUrl = local?.endpoints.apiUrl ?? connection?.apiUrl; + if (!apiUrl) { + log.info('No verified API endpoint is saved yet. Live traffic availability is unknown.'); + return; + } + let discovery: PlatformDiscoveryDocument; + try { + discovery = await discoverPlatform(apiUrl); + } catch (error) { + if (saved) { + log.info( + 'Live availability could not be confirmed. The saved checkpoint above may be out of date.', + ); + } + throw error; + } log.success(`${discovery.displayName} is reachable.`); console.log(`API: ${discovery.apiUrl}`); console.log(`Proxy: ${discovery.proxyUrl}`); @@ -195,3 +224,16 @@ export async function runPlatformCommand(_root: string, args: PlatformArgs): Pro const { runPlatformLifecycleCommand } = await import('./platform-lifecycle.ts'); await runPlatformLifecycleCommand(args); } + +function showSavedInstallationStatus(manifest: PlatformInstallationManifest): void { + console.log(`Saved installation: ${manifest.id} (${manifest.status})`); + console.log(`Checkpoint: ${manifest.updatedAt}`); + if (manifest.operation) { + const operation = manifest.operation; + console.log(`Saved operation: ${operation.action} — ${operation.phase}`); + console.log(`Runtime: ${operation.fromVersion ?? 'new installation'} → ${operation.toVersion}`); + } + if (manifest.endpoints.apiUrl) { + console.log(`Administrator status: ${manifest.endpoints.apiUrl}/admin/status`); + } +} diff --git a/packages/void/src/cli/platform-installer.ts b/packages/void/src/cli/platform-installer.ts index 0e2daf660..9760c0d26 100644 --- a/packages/void/src/cli/platform-installer.ts +++ b/packages/void/src/cli/platform-installer.ts @@ -52,6 +52,7 @@ import { transitionInstallation, type InstallationResource, type PlatformInstallationManifest, + type PlatformLifecycleOperation, parsePlatformAuthenticationSetup, parsePlatformAccessProtection, type PlatformAccessProtection, @@ -367,6 +368,7 @@ export type PlatformInstallerDependencies = Readonly<{ migrateDatabase?: (databaseUrl: string, migrationsFolder: string) => Promise; now?: () => string; onProgress?: (message: string) => void; + operation?: PlatformLifecycleOperation['action']; prepareDatabase?: ( runtimeDirectory: string, database: PlatformRuntimeDatabaseManifest, @@ -1232,6 +1234,7 @@ async function recoverFailedPlatformInstallation( authenticationProtocolTransition: boolean, workerCutoverGeneration: number, previousPublicEndpoints: boolean, + operationStarted: boolean, now: () => string, writeRemoteInstallationCheckpoint: InstallationCheckpointWriter, ): Promise { @@ -1295,9 +1298,16 @@ async function recoverFailedPlatformInstallation( // Traffic remains closed and retry resumes toward a fully compatible Worker set. workerRollbacks = []; } - if (manifest.status !== 'failed' && manifest.status !== 'uninstalled') { + if (manifest.status !== 'uninstalled' && (manifest.status !== 'failed' || operationStarted)) { try { - manifest = transitionInstallation(manifest, 'failed', now()); + const updatedAt = now(); + manifest = transitionInstallation(manifest, 'failed', updatedAt); + if (operationStarted && manifest.operation) { + manifest = { + ...manifest, + operation: { ...manifest.operation, phase: 'failed', updatedAt }, + }; + } writeInstallationManifest(manifest); await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); } catch { @@ -1546,6 +1556,18 @@ export async function installPlatform( ) { workerSecretUpdateIntent = null; } + // Progress is checkpointed under the same lifecycle lock as mutations. Do not + // update it from parallel Worker upload callbacks. + const checkpointOperation = async (phase: PlatformLifecycleOperation['phase']) => { + if (!manifest?.operation) { + return; + } + const updatedAt = now(); + manifest = { ...manifest, operation: { ...manifest.operation, phase, updatedAt }, updatedAt }; + writeInstallationManifest(manifest); + await releaseDatabaseLock.checkpoint?.(manifest); + }; + let operationStarted = false; try { assertPlatformRuntimeSafety( runtime, @@ -1558,7 +1580,30 @@ export async function installPlatform( authoritative !== null && authoritative !== undefined, ); } - + const action = dependencies.operation ?? (existing ? 'upgrade' : 'install'); + const previousOperation = manifest.operation; + const resuming = + previousOperation?.action === action && + previousOperation.toVersion === version && + previousOperation.runtimeManifestSha256 === resolvedRuntime.manifestSha256 && + previousOperation.phase !== 'complete'; + const startedAt = now(); + operationStarted = true; + manifest = { + ...manifest, + operation: { + id: resuming ? previousOperation.id : randomUUID(), + action, + fromVersion: resuming ? previousOperation.fromVersion : sourcePlatformVersion, + toVersion: version, + runtimeManifestSha256: resolvedRuntime.manifestSha256, + phase: 'preparing', + startedAt: resuming ? previousOperation.startedAt : startedAt, + updatedAt: startedAt, + }, + updatedAt: startedAt, + }; + await checkpointOperation('preparing'); const liveAuthentication = await releaseDatabaseLock.readAuthenticationState?.(); if (liveAuthentication) { authenticationEnforcementActive = liveAuthentication.sessionsRequired; @@ -1910,6 +1955,7 @@ export async function installPlatform( await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); if (zone.status !== 'active') { manifest = transitionInstallation(manifest, 'waiting-for-dns', now()); + await checkpointOperation('waiting-for-dns'); writeInstallationManifest(manifest); await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); return { @@ -2004,6 +2050,7 @@ export async function installPlatform( } manifest = transitionInstallation(manifest, 'deploying', now()); + await checkpointOperation('deploying'); writeInstallationManifest(manifest); const ids = Object.fromEntries( manifest.resources.map((resource) => [resource.key, resource.id]), @@ -2082,6 +2129,7 @@ export async function installPlatform( PLATFORM_DISABLED_VALUE, ); workerTrafficGuarded = true; + dependencies.onProgress?.('Application traffic paused for a safe platform cutover'); } if (!preserveDisabled) { const trafficGeneration = nextTrafficGeneration(manifest); @@ -2523,6 +2571,7 @@ export async function installPlatform( usageProtocolVersion: targetUsageProtocolVersion, }; manifest = transitionInstallation(manifest, 'disabled', now()); + await checkpointOperation('complete'); writeInstallationManifest(manifest); await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); writePendingInstallationSecrets(manifest, secretCheckpoint(secrets)); @@ -2556,6 +2605,7 @@ export async function installPlatform( : ''; let setupPending = false; manifest = transitionInstallation(manifest, 'verifying', now()); + await checkpointOperation('verifying'); writeInstallationManifest(manifest); if (plan.deployment.authentication.configurable && authenticationStep) { if (!secrets.authenticationSetupJson || !secrets.authSetupToken) { @@ -2696,6 +2746,7 @@ export async function installPlatform( }, now(), ); + await checkpointOperation('waiting-for-sandbox-drain'); writeInstallationManifest(manifest); await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); workerRollbacks = []; @@ -2715,6 +2766,7 @@ export async function installPlatform( ); } } + await checkpointOperation('enabling'); if (requiresStagedCommit) { if (!authenticationCutoverCommitted) { manifest = recordWorkerCutoverResolution( @@ -2988,6 +3040,7 @@ export async function installPlatform( usageProtocolVersion: targetUsageProtocolVersion, }; manifest = transitionInstallation(manifest, 'installed', now()); + await checkpointOperation('complete'); writeInstallationManifest(manifest); await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); workerTrafficGuarded = false; @@ -3015,6 +3068,7 @@ export async function installPlatform( authenticationProtocolTransition, workerCutoverGeneration, previousPublicEndpoints, + operationStarted, now, writeRemoteInstallationCheckpoint, ); diff --git a/packages/void/src/cli/platform-management.ts b/packages/void/src/cli/platform-management.ts index f2e0b9a20..df258299a 100644 --- a/packages/void/src/cli/platform-management.ts +++ b/packages/void/src/cli/platform-management.ts @@ -176,6 +176,33 @@ export function selectAuthoritativePlatformManifest( return authoritative; } +function commandArgument(value: string): string { + return /^[a-zA-Z0-9_./:@-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`; +} + +export function platformLifecycleResumeCommand( + args: Extract< + PlatformArgs, + { subcommand: 'upgrade' | 'rollback' | 'repair' | 'disable' | 'enable' } + >, + installationId: string, +): string { + const command = ['void', 'platform', args.subcommand, commandArgument(installationId)]; + if (args.runtime) { + command.push('--runtime', commandArgument(args.runtime)); + } + if (args.subcommand === 'rollback' && args.fromRuntime) { + command.push('--from-runtime', commandArgument(args.fromRuntime)); + } + if ('dashboardUrl' in args && args.dashboardUrl) { + command.push('--dashboard-url', commandArgument(args.dashboardUrl)); + } + if (args.yes) { + command.push('--yes'); + } + return command.join(' '); +} + export async function runInstalledPlatformCommand(args: PlatformArgs): Promise { if ( args.subcommand !== 'upgrade' && @@ -303,13 +330,23 @@ export async function runInstalledPlatformCommand(args: PlatformArgs): Promise ( await createPlatformInstallPlan(client, planInput, recoveryManifest, { @@ -462,23 +500,35 @@ export async function runInstalledPlatformCommand(args: PlatformArgs): Promise'`. Then apply with `void platform system sandbox-drain --yes` and rerun until it reports DB-backed `complete: true`. Rerun this lifecycle command afterward to enable traffic.", + [ + 'Application traffic is paused. Saved progress is ready to resume.', + '1. Review remaining Sandbox work: void platform system sandbox-drain --plan', + "2. Apply: void platform system sandbox-drain --yes (follow nextCursor with --cursor '' until complete: true).", + `3. Resume: ${platformLifecycleResumeCommand(args, manifest.id)}`, + `Administrator status: ${plan.apiUrl}/admin/status`, + ].join('\n'), 'Waiting for managed Sandbox drain', ); return; } log.success( - args.subcommand === 'rollback' - ? `${deployment.displayName} is running compatible runtime ${runtime!.manifest.platformVersion}; PostgreSQL remains at schema ${rollbackSourceRuntime!.manifest.database.schemaDigest}.` - : `${deployment.displayName} is healthy at ${plan.apiUrl}.`, + `${deployment.displayName}: runtime ${runtime!.manifest.platformVersion} ${args.subcommand === 'rollback' ? 'restored' : 'ready'}.`, ); + log.info( + result.manifest.desiredState === 'disabled' + ? 'Application traffic remains paused. Enable the installation when you are ready.' + : `Platform verification passed. Traffic is enabled at ${plan.apiUrl}.`, + ); + if (args.subcommand === 'rollback') { + log.info('PostgreSQL migrations were retained; rollback changes the runtime only.'); + } if (result.emailOperationId) { log.info(`Shared email routing ready (operation ${result.emailOperationId}).`); } @@ -532,8 +582,20 @@ export async function runInstalledPlatformCommand(args: PlatformArgs): Promise { it('reports a declared but uninstalled project package', () => { project(); - expect(() => assertInstalledVoidMatchesCli(root)).toThrow('installed Vite plugin is missing'); + // Vitest resolves missing bare imports through the workspace. Check the + // missing-package case with Node's actual project-relative resolver. + const source = new URL('../../src/cli/installed-void.ts', import.meta.url).href; + const result = spawnSync( + process.execPath, + [ + '--input-type=module', + '--eval', + `import { assertInstalledVoidMatchesCli } from ${JSON.stringify(source)}; assertInstalledVoidMatchesCli(process.argv[1]);`, + root, + ], + { + encoding: 'utf8', + env: { ...process.env, NODE_OPTIONS: '', NODE_PATH: '' }, + timeout: 10000, + }, + ); + expect(result.status).toBe(1); + expect(result.stderr).toContain('installed Vite plugin is missing'); }); }); diff --git a/packages/void/test/unit/platform-connect.test.ts b/packages/void/test/unit/platform-connect.test.ts index 11b6e0413..e19d8d2da 100644 --- a/packages/void/test/unit/platform-connect.test.ts +++ b/packages/void/test/unit/platform-connect.test.ts @@ -1,5 +1,13 @@ -import { afterEach, describe, expect, it } from 'vite-plus/test'; -import { discoverPlatform } from '../../src/cli/platform-cmd.ts'; +import { mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { + createPlatformDeploymentManifest, + createPlatformInstallationManifest, +} from '@void/platform'; +import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; +import { discoverPlatform, runPlatformCommand } from '../../src/cli/platform-cmd.ts'; +import { writeInstallationManifest } from '../../src/cli/platform-registry.ts'; const document = { apiUrl: 'https://api.example.com', @@ -30,6 +38,55 @@ afterEach(() => { }); describe('platform discovery', () => { + it('shows saved lifecycle progress when live discovery is blocked by maintenance', async () => { + const directory = mkdtempSync(join(tmpdir(), 'void-status-')); + vi.stubEnv('VOID_PLATFORM_REGISTRY_DIR', directory); + const output = vi.spyOn(console, 'log').mockImplementation(() => {}); + vi.stubGlobal( + 'fetch', + vi.fn(async () => new Response('Platform disabled', { status: 503 })), + ); + try { + const timestamp = '2026-10-05T00:00:00.000Z'; + const manifest = createPlatformInstallationManifest({ + account: { id: 'account', name: 'Account' }, + createdAt: timestamp, + deployment: createPlatformDeploymentManifest({ + application: { baseDomain: 'apps.example.com', zoneName: 'example.com' }, + displayName: 'Example', + installationSlug: 'example', + }), + id: 'status-installation', + ownershipNonce: '0123456789abcdef0123456789abcdef', + platformVersion: '1.0.0', + }); + writeInstallationManifest({ + ...manifest, + status: 'verifying', + endpoints: { apiUrl: 'https://api.example.com', dashboardUrl: null, proxyUrl: null }, + operation: { + id: 'upgrade', + action: 'upgrade', + fromVersion: '1.0.0', + toVersion: '2.0.0', + phase: 'verifying', + startedAt: timestamp, + updatedAt: timestamp, + }, + }); + await expect( + runPlatformCommand('.', { subcommand: 'status', selector: manifest.id }), + ).rejects.toThrow('503'); + expect(output).toHaveBeenCalledWith('Saved operation: upgrade — verifying'); + expect(output).toHaveBeenCalledWith('Runtime: 1.0.0 → 2.0.0'); + expect(output).not.toHaveBeenCalledWith(expect.stringContaining('is reachable')); + } finally { + vi.restoreAllMocks(); + vi.unstubAllGlobals(); + vi.unstubAllEnvs(); + rmSync(directory, { recursive: true, force: true }); + } + }); it('accepts a valid document from its declared origin', async () => { const response = new Response(JSON.stringify(document)); Object.defineProperty(response, 'url', { diff --git a/packages/void/test/unit/platform-installation-state.test.ts b/packages/void/test/unit/platform-installation-state.test.ts index 9eba5dbc5..192b6b93b 100644 --- a/packages/void/test/unit/platform-installation-state.test.ts +++ b/packages/void/test/unit/platform-installation-state.test.ts @@ -1,6 +1,7 @@ import { createPlatformDeploymentManifest, createPlatformInstallationManifest, + parsePlatformInstallationManifest, transitionInstallation, } from '@void/platform'; import { describe, expect, it } from 'vite-plus/test'; @@ -28,6 +29,35 @@ function manifestAt(status: 'deploying' | 'verifying') { } describe('platform installation resume states', () => { + it('preserves validated lifecycle progress across recovery and accepts older checkpoints', () => { + const manifest = manifestAt('verifying'); + expect(parsePlatformInstallationManifest(manifest).operation).toBeUndefined(); + const operation = { + id: 'operation-1', + action: 'rollback' as const, + fromVersion: '2.0.0', + toVersion: '1.0.0', + phase: 'waiting-for-sandbox-drain' as const, + startedAt: manifest.createdAt, + updatedAt: manifest.updatedAt, + }; + const recovered = parsePlatformInstallationManifest( + JSON.parse(JSON.stringify({ ...manifest, operation })), + ); + expect(recovered.operation).toEqual(operation); + expect(() => + parsePlatformInstallationManifest({ + ...manifest, + operation: { ...operation, phase: 'online' }, + }), + ).toThrow('operation'); + expect(() => + parsePlatformInstallationManifest({ + ...manifest, + operation: { ...operation, updatedAt: 'invalid' }, + }), + ).toThrow('timestamp'); + }); it.each(['deploying', 'verifying'] as const)( 're-enters provisioning from an interrupted %s checkpoint', (status) => { diff --git a/packages/void/test/unit/platform-installer.test.ts b/packages/void/test/unit/platform-installer.test.ts index 252381b06..7d0e593bb 100644 --- a/packages/void/test/unit/platform-installer.test.ts +++ b/packages/void/test/unit/platform-installer.test.ts @@ -5750,6 +5750,7 @@ describe('platform installer', () => { ); expect(waitingForSandboxDrain.waitingForSandboxDrain).toBe(true); expect(waitingForSandboxDrain.manifest).toMatchObject({ + operation: { action: 'upgrade', phase: 'waiting-for-sandbox-drain' }, platformVersion: '0.10.13', safetyProtocols: { sandboxDrain: 3 }, status: 'verifying', @@ -5813,6 +5814,11 @@ describe('platform installer', () => { }, }, ); + expect(resumedAfterSandboxDrain.manifest.operation).toMatchObject({ + id: waitingForSandboxDrain.manifest.operation!.id, + startedAt: waitingForSandboxDrain.manifest.operation!.startedAt, + phase: 'complete', + }); expect(resumedAfterSandboxDrain.waitingForSandboxDrain).toBe(false); expect(resumedAfterSandboxDrain.manifest).toMatchObject({ safetyProtocols: { sandboxDrain: 3 }, @@ -5860,6 +5866,10 @@ describe('platform installer', () => { ).rejects.toThrow('upgrade health failed'); expect(verifiedTargetVersion).toBe(readPlatformRuntimeManifest().platformVersion); expect(listInstallationManifests(directory)[0]?.platformVersion).toBe('0.10.13'); + expect(listInstallationManifests(directory)[0]?.operation).toMatchObject({ + action: 'upgrade', + phase: 'failed', + }); const upgraded = await installPlatform(upgradedPlan, secrets, sourceManifest, { acquireDatabaseLifecycleLock, diff --git a/packages/void/test/unit/platform-management-upgrade.test.ts b/packages/void/test/unit/platform-management-upgrade.test.ts index bf77cac9d..0a9713f2a 100644 --- a/packages/void/test/unit/platform-management-upgrade.test.ts +++ b/packages/void/test/unit/platform-management-upgrade.test.ts @@ -203,11 +203,31 @@ import { acquirePlatformDatabaseLifecycleLock, installPlatform, } from '../../src/cli/platform-installer.ts'; -import { runInstalledPlatformCommand } from '../../src/cli/platform-management.ts'; +import { + platformLifecycleResumeCommand, + runInstalledPlatformCommand, +} from '../../src/cli/platform-management.ts'; import { createPlatformInstallPlan } from '../../src/cli/platform-plan.ts'; import { readInstallationRecoverySecrets } from '../../src/cli/platform-registry.ts'; describe('installed platform upgrade', () => { + it('prints an exact rollback resume command with quoted custom runtime paths', () => { + expect( + platformLifecycleResumeCommand( + { + subcommand: 'rollback', + selector: '', + plan: false, + yes: true, + runtime: '/tmp/earlier runtime', + fromRuntime: "/tmp/current's runtime", + }, + 'installation', + ), + ).toBe( + "void platform rollback installation --runtime '/tmp/earlier runtime' --from-runtime '/tmp/current'\\''s runtime' --yes", + ); + }); beforeEach(() => { vi.clearAllMocks(); vi.stubEnv('CLOUDFLARE_API_TOKEN', 'token'); @@ -468,6 +488,10 @@ describe('installed platform upgrade', () => { 'local-release', ]); expect(state.progress.error).toHaveBeenCalledExactlyOnceWith('Platform upgrade failed.'); + expect(note).toHaveBeenCalledWith( + expect.stringContaining(`void platform upgrade ${state.manifest!.id} --yes`), + 'Recovery', + ); expect(state.progress.stop).not.toHaveBeenCalled(); }); @@ -584,6 +608,46 @@ describe('installed platform upgrade', () => { expect(exit).toHaveBeenCalledWith(130); }); + it('reports a completed operation on a disabled installation without claiming enabled traffic', async () => { + vi.mocked(installPlatform).mockResolvedValueOnce({ + manifest: { ...state.manifest!, desiredState: 'disabled', status: 'disabled' }, + waitingForDns: false, + waitingForSandboxDrain: false, + zoneNameServers: [], + }); + await runInstalledPlatformCommand({ + subcommand: 'upgrade', + selector: state.manifest!.id, + plan: false, + runtime: '', + yes: true, + }); + expect(log.info).toHaveBeenCalledWith( + 'Application traffic remains paused. Enable the installation when you are ready.', + ); + expect(log.info).not.toHaveBeenCalledWith(expect.stringContaining('Traffic is enabled')); + expect(log.success).not.toHaveBeenCalledWith(expect.stringContaining('healthy')); + }); + + it('previews enabling a disabled installation without promising it will stay paused', async () => { + state.manifest = { ...state.manifest!, desiredState: 'disabled', status: 'disabled' }; + await runInstalledPlatformCommand({ + subcommand: 'enable', + selector: state.manifest.id, + plan: true, + runtime: '', + yes: true, + }); + expect(note).toHaveBeenCalledWith( + expect.stringContaining('Traffic resumes after verification.'), + 'Availability and progress', + ); + expect(note).not.toHaveBeenCalledWith( + expect.stringContaining('Application traffic will stay paused'), + 'Availability and progress', + ); + }); + describe('uninstall with project Zero Trust', () => { const enabled = { active: true, diff --git a/platform/packages/api/README.md b/platform/packages/api/README.md index e547cbbf5..2d62ebecc 100644 --- a/platform/packages/api/README.md +++ b/platform/packages/api/README.md @@ -10,6 +10,7 @@ It owns platform auth, projects, deployments, domains, secrets, provisioning, ro - **Public API**: CLI and dashboard-facing JSON routes - **Internal API**: resource resolution and revalidation used by other platform workers - **Admin UI**: React pages under `/admin/*`, server-rendered for first load and backed by a private Fate endpoint +- **Lifecycle status**: `/admin/status` and its GET JSON endpoint project display fields from the installer-owned PostgreSQL checkpoint. Maintenance admits these routes and administrator sign-in through normal Access and admin authentication. Keep the exception narrow, retain existing Sandbox drain operator access, and keep the Fate POST endpoint and administrator writes gated. - **Self-hosted owner setup**: dashboard OAuth and normal signup share the first-user transaction and configured GitHub identity check. Dashboard login can create the first owner without a CLI login; it never promotes existing users. Void Cloud keeps its existing admin-only login behavior. - **Background work**: - `scheduled()` for periodic usage enforcement and rollover checks diff --git a/platform/packages/api/src/admin/platform-status.ts b/platform/packages/api/src/admin/platform-status.ts new file mode 100644 index 000000000..23ac0d4b1 --- /dev/null +++ b/platform/packages/api/src/admin/platform-status.ts @@ -0,0 +1,50 @@ +import { + parsePlatformInstallationManifest, + type InstallationStatus, + type PlatformLifecycleOperation, +} from '@void/platform'; +import { sql } from 'drizzle-orm'; +import type { Context } from 'hono'; +import type { ApiEnv } from '../env.ts'; + +export type PlatformStatusSnapshot = Readonly<{ + checkedAt: string; + traffic: 'paused' | 'enabled'; + checkpoint: Readonly<{ + status: InstallationStatus; + platformVersion: string; + updatedAt: string; + operation: PlatformLifecycleOperation | null; + }> | null; +}>; + +/** Project only display fields from the installer-owned authoritative checkpoint. */ +export async function readPlatformStatus( + context: Context, +): Promise { + let checkpoint: PlatformStatusSnapshot['checkpoint'] = null; + if (context.env.PLATFORM_INSTALLATION_ID) { + const rows = await context.get('db').execute<{ lifecycle_manifest: unknown }>(sql` + SELECT lifecycle_manifest FROM public.__void_platform_installation + WHERE singleton = true AND installation_id = ${context.env.PLATFORM_INSTALLATION_ID} + `); + if (!rows.rows[0]) { + throw new Error('Installation checkpoint unavailable.'); + } + const manifest = parsePlatformInstallationManifest(rows.rows[0].lifecycle_manifest); + if (manifest.id !== context.env.PLATFORM_INSTALLATION_ID) { + throw new Error('Installation checkpoint identity mismatch.'); + } + checkpoint = { + status: manifest.status, + platformVersion: manifest.platformVersion, + updatedAt: manifest.updatedAt, + operation: manifest.operation ?? null, + }; + } + return { + checkedAt: new Date().toISOString(), + traffic: context.get('platformTrafficPaused') ? 'paused' : 'enabled', + checkpoint, + }; +} diff --git a/platform/packages/api/src/admin/react/AdminNavigationFallback.tsx b/platform/packages/api/src/admin/react/AdminNavigationFallback.tsx index 8bcbba6ec..9c21c25ba 100644 --- a/platform/packages/api/src/admin/react/AdminNavigationFallback.tsx +++ b/platform/packages/api/src/admin/react/AdminNavigationFallback.tsx @@ -9,6 +9,7 @@ import { matchAdminRoute, type AdminPageId } from './pages.ts'; import { Layout } from './views/Layout.tsx'; const TITLES: Partial> = { + platformStatus: 'Platform status', dashboard: 'Dashboard', plans: 'Plans', planEdit: 'Edit plan', diff --git a/platform/packages/api/src/admin/react/pages.ts b/platform/packages/api/src/admin/react/pages.ts index 00f40a584..a5506a510 100644 --- a/platform/packages/api/src/admin/react/pages.ts +++ b/platform/packages/api/src/admin/react/pages.ts @@ -1,4 +1,7 @@ export const adminComponents = { + platformStatus: async () => ({ + default: (await import('./views/PlatformStatusPage.tsx')).PlatformStatusPage, + }), adminLayout: async () => ({ default: (await import('./AdminProviders.tsx')).AdminProviders }), dashboard: async () => ({ default: (await import('./views/DashboardPage.tsx')).DashboardPage }), adminLogin: async () => ({ @@ -76,6 +79,9 @@ export function matchAdminRoute(url: string): AdminPageId | null { if (path === '/admin/') { return 'dashboard'; } + if (path === '/admin/status') { + return 'platformStatus'; + } if (path === '/admin/login') { return 'adminLogin'; } diff --git a/platform/packages/api/src/admin/react/styles.css b/platform/packages/api/src/admin/react/styles.css index 08a11eebe..c640cc037 100644 --- a/platform/packages/api/src/admin/react/styles.css +++ b/platform/packages/api/src/admin/react/styles.css @@ -52,6 +52,89 @@ body { width: 100%; } +.void-platform-status { + display: grid; + gap: var(--spacing-6); + max-width: 1120px; +} +.void-platform-status-heading { + display: flex; + align-items: start; + justify-content: space-between; + gap: var(--spacing-4); + flex-wrap: wrap; +} +.void-platform-status-heading h1 { + margin: 0; +} +.void-platform-status p { + line-height: 1.6; +} +.void-platform-status-refresh { + font: inherit; + color: var(--color-text-primary); + background: var(--color-background-body); + border: 1px solid var(--color-border); + border-radius: var(--radius-element); + padding: 10px 16px; + cursor: pointer; +} +.void-platform-status-refresh:focus-visible { + outline: 2px solid var(--color-text-accent); + outline-offset: 3px; +} +.void-platform-status-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: var(--spacing-6); +} +.void-platform-status-card { + padding: var(--spacing-6); + border: 1px solid var(--color-border); + border-radius: var(--radius-container); + background: var(--color-background-body); + min-width: 0; +} +.void-platform-status-card h2 { + margin-block: var(--spacing-3); +} +.void-platform-status-eyebrow { + font-size: 0.8rem; + font-weight: 600; + letter-spacing: 0.04em; + color: var(--color-text-secondary); +} +.void-platform-status-version { + font-size: 1.5rem; + overflow-wrap: anywhere; +} +.void-platform-status-card dl { + display: grid; + grid-template-columns: auto 1fr; + gap: var(--spacing-3) var(--spacing-4); + font-size: 0.875rem; +} +.void-platform-status-card dt, +.void-platform-status-timestamp { + color: var(--color-text-secondary); +} +.void-platform-status-card dd { + margin: 0; + overflow-wrap: anywhere; +} +.void-platform-status-notice { + border-inline-start: 3px solid var(--color-text-accent); + padding-inline-start: var(--spacing-4); +} +.void-platform-status-notice p { + margin: 0; +} +@media (max-width: 700px) { + .void-platform-status-grid { + grid-template-columns: 1fr; + } +} + .void-admin-owner-transfer { display: grid; gap: var(--spacing-4); diff --git a/platform/packages/api/src/admin/react/views/Layout.tsx b/platform/packages/api/src/admin/react/views/Layout.tsx index 8f539dbcc..6be307c4b 100644 --- a/platform/packages/api/src/admin/react/views/Layout.tsx +++ b/platform/packages/api/src/admin/react/views/Layout.tsx @@ -6,6 +6,7 @@ import { TopNav, TopNavHeading } from '@astryxdesign/core/TopNav'; import { useNavigation, useRouter } from '@void/react'; import { FolderKanban, + Activity, LayoutDashboard, LockKeyhole, LogOut, @@ -130,6 +131,12 @@ export function Layout({ /> + = { + preparing: 'Preparing the platform', + deploying: 'Deploying services', + verifying: 'Verifying the platform', + enabling: 'Enabling traffic and verifying cutover', + 'waiting-for-dns': 'Waiting for DNS', + 'waiting-for-sandbox-drain': 'Waiting for Sandbox drain', + complete: 'Operation complete', + failed: 'Operation needs attention', +}; +const ACTION_LABELS: Record = { + install: 'Installation', + upgrade: 'Upgrade', + rollback: 'Rollback', + repair: 'Repair', + enable: 'Enable', +}; + +export function PlatformStatusPage({ + platformName, + username, + snapshot, +}: { + platformName: string; + username?: string; + snapshot: PlatformStatusSnapshot | null; +}) { + const [current, setCurrent] = useState(snapshot); + const [connection, setConnection] = useState<'current' | 'unavailable' | 'expired'>( + snapshot ? 'current' : 'unavailable', + ); + const [refresh, setRefresh] = useState(0); + useEffect(() => { + let stopped = false; + let timer: ReturnType; + const controller = new AbortController(); + const poll = async () => { + if (document.visibilityState === 'hidden') { + timer = setTimeout(poll, 5000); + return; + } + try { + const response = await fetch('/admin/status.json', { + cache: 'no-store', + credentials: 'same-origin', + headers: { Accept: 'application/json' }, + signal: AbortSignal.any([controller.signal, AbortSignal.timeout(10000)]), + }); + if (stopped) { + return; + } + if (response.redirected || response.status === 401 || response.status === 403) { + setConnection('expired'); + return; + } + if (!response.ok || !response.headers.get('Content-Type')?.includes('application/json')) { + throw new Error('Status unavailable'); + } + const next: PlatformStatusSnapshot = await response.json(); + if (stopped) { + return; + } + setCurrent(next); + setConnection('current'); + } catch { + if (stopped) { + return; + } + setConnection('unavailable'); + } + if (!stopped) { + timer = setTimeout(poll, 5000); + } + }; + void poll(); + return () => { + stopped = true; + controller.abort(); + clearTimeout(timer); + }; + }, [refresh]); + + const operation = current?.checkpoint?.operation; + const waiting = + operation?.phase === 'waiting-for-dns' || operation?.phase === 'waiting-for-sandbox-drain'; + const failed = + operation?.phase === 'failed' || + (current?.checkpoint?.status === 'failed' && (!operation || operation.phase === 'complete')); + const needsAttention = failed || waiting; + const trafficLabel = !current + ? 'Unknown' + : current.traffic === 'paused' + ? 'Traffic paused' + : 'Traffic enabled'; + const phaseLabel = failed + ? 'Operation needs attention' + : operation + ? PHASE_LABELS[operation.phase] + : current?.checkpoint + ? `Saved installation state: ${current.checkpoint.status}` + : 'No saved operation'; + + return ( + +
+
+
+ Platform status +

Follow upgrade and rollback progress. This page is read-only during maintenance.

+
+ +
+ +
+ {connection === 'expired' ? ( +

+ Your administrator session needs attention. Sign in again{' '} + to confirm the current status. +

+ ) : connection === 'unavailable' ? ( +

+ Live status is unavailable.{' '} + {current + ? 'Showing the last confirmed snapshot; it may be out of date.' + : 'The current operation and traffic state could not be confirmed.'}{' '} + Progress is saved independently of this page. +

+ ) : ( +

+ Updates every 5 seconds while this page is visible. A saved checkpoint may remain + unchanged while a phase runs. +

+ )} +
+ +
+
+ + {operation ? ACTION_LABELS[operation.action] : 'Lifecycle'} + + + {phaseLabel} + + {operation ? ( + <> +

+ {operation.fromVersion ?? 'New installation'} →{' '} + {operation.toVersion} +

+
+
Started
+
{formatDateTime(operation.startedAt)}
+
Progress saved
+
{formatDateTime(operation.updatedAt)}
+
Installation state
+
{current?.checkpoint?.status}
+
+ + ) : ( +

+ {current?.checkpoint + ? `Saved runtime: ${current.checkpoint.platformVersion}. This operation has no detailed progress record.` + : 'Detailed progress is available for installations managed by the Void lifecycle CLI.'} +

+ )} + {operation?.phase === 'complete' && !failed && ( +

+ The lifecycle operation completed. Use the traffic state alongside health checks to + assess availability. +

+ )} + {operation && !needsAttention && operation.phase !== 'complete' && ( +

+ Keep the lifecycle command running. Refreshing this page does not interrupt the + operation. +

+ )} +
+ +
+ Traffic state reported by the API + + {trafficLabel} + {current && connection !== 'current' ? ' (last confirmed)' : ''} + +

+ {!current + ? 'Traffic state is not currently available.' + : current.traffic === 'paused' + ? 'Application requests may receive a temporary-unavailability response. Platform changes stay paused for administrators except for sign-in and this status page.' + : 'The API traffic gate is open. Individual projects and other services may still be affected while Workers roll out.'} +

+ {current && ( +

+ Confirmed {formatDateTime(current.checkedAt)} +

+ )} +

This state does not replace service or project health checks.

+
+
+ + {needsAttention && ( +
+ + Next step + +

+ {operation?.phase === 'waiting-for-dns' + ? 'Wait for the zone to become active, then rerun the lifecycle command.' + : operation?.phase === 'waiting-for-sandbox-drain' + ? 'Complete the remaining Sandbox drain work using the CLI, then rerun the lifecycle command. Traffic stays paused until the cutover is verified.' + : 'Review the CLI error and saved installation state. Resolve the error before resuming the same lifecycle command.'} +

+

+ Use the recovery commands printed by the CLI and keep the same runtime files + {operation?.action === 'rollback' ? ', including the rollback source runtime' : ''}. + Reloading this page does not resume an operation. +

+
+ )} + {current?.traffic === 'enabled' && connection === 'current' && ( +

+ Return to dashboard +

+ )} +
+
+ ); +} diff --git a/platform/packages/api/src/admin/routes/system.tsx b/platform/packages/api/src/admin/routes/system.tsx index 66e94c1a7..6e14eb36d 100644 --- a/platform/packages/api/src/admin/routes/system.tsx +++ b/platform/packages/api/src/admin/routes/system.tsx @@ -4,10 +4,31 @@ import type { ApiEnv } from '../../env.ts'; import { executeAuditedMutation, operatorAuditIntent } from '../../operator/audit.ts'; import { backfillPlatformQueueTokens, systemHealth } from '../../operator/system-operations.ts'; export type { HealthCheck, HealthResult } from '../../operator/system-operations.ts'; +import { getPlatformDisplayName } from '../../platform-identity.ts'; import { renderDashboardFatePage, renderFateListPage } from '../fate/render.ts'; +import { readPlatformStatus } from '../platform-status.ts'; +import { renderAdminPage } from '../react/server.ts'; export const adminSystem = new Hono(); +adminSystem.get('/status.json', async (context) => { + context.header('Cache-Control', 'private, no-store'); + try { + return context.json(await readPlatformStatus(context)); + } catch { + return context.json({ error: 'Platform status is temporarily unavailable' }, 503); + } +}); + +adminSystem.get('/status', async (context) => { + const snapshot = await readPlatformStatus(context).catch(() => null); + return renderAdminPage(context, 'platformStatus', 'Platform status', { + platformName: getPlatformDisplayName(context.env, context.req.url), + username: context.get('user').login, + snapshot, + }); +}); + adminSystem.get('/cli-versions', (context) => renderFateListPage(context, 'cliVersions')); adminSystem.get('/health', async (context) => diff --git a/platform/packages/api/src/env.ts b/platform/packages/api/src/env.ts index 332c02009..a017e8f38 100644 --- a/platform/packages/api/src/env.ts +++ b/platform/packages/api/src/env.ts @@ -194,6 +194,7 @@ export type ApiEnv = Env & { DEPLOY_HEARTBEAT_INTERVAL_MS?: number; }; Variables: { + platformTrafficPaused: boolean; user: User; db: Db; operatorSession: { id: string; expiresAt: string }; diff --git a/platform/packages/api/src/index.ts b/platform/packages/api/src/index.ts index b3fe5a7fa..222b42c7c 100644 --- a/platform/packages/api/src/index.ts +++ b/platform/packages/api/src/index.ts @@ -69,6 +69,11 @@ import { ErrorAlertMonitor } from './error-alert-monitor.ts'; import { cancelContainerBuildDos } from './github/cancel-builds.ts'; import { authMiddleware } from './middleware/auth.ts'; import { platformAccessProtection } from './middleware/platform-access.ts'; +import { + isMaintenanceReadRequest, + isMaintenanceLoginCallback, + isAdministratorCallback, +} from './middleware/platform-maintenance.ts'; import { operatorApi } from './operator/index.ts'; import { sandboxDrainStatus } from './operator/sandbox-operations.ts'; import { platformAppAccess } from './platform-app-access.ts'; @@ -223,15 +228,39 @@ const app = new Hono() context.req.header('X-Void-Auth-Setup') && context.req.method === 'POST' && context.req.path === '/internal/platform/auth-initialize'; + const trafficPaused = + context.env.PLATFORM_TRAFFIC_STATE === 'staging' || + context.env.PLATFORM_TRAFFIC_STATE === 'sandbox-drain' || + !!( + !authenticationSetup && + !installerProbe && + !maintenanceSandboxDrain && + context.env.PLATFORM_INSTALLATION_ID && + (await context.env.ROUTING.get(PLATFORM_DISABLED_KEY)) === PLATFORM_DISABLED_VALUE + ); + context.set('platformTrafficPaused', trafficPaused); + if (context.req.path === '/admin/status' || context.req.path === '/admin/status.json') { + context.header('Cache-Control', 'private, no-store'); + } if ( !authenticationSetup && !installerProbe && !maintenanceSandboxDrain && - (context.env.PLATFORM_TRAFFIC_STATE === 'staging' || - context.env.PLATFORM_TRAFFIC_STATE === 'sandbox-drain' || - (context.env.PLATFORM_INSTALLATION_ID && - (await context.env.ROUTING.get(PLATFORM_DISABLED_KEY)) === PLATFORM_DISABLED_VALUE)) + !isMaintenanceReadRequest(context) && + !isMaintenanceLoginCallback(context) && + trafficPaused ) { + if ( + context.req.method === 'GET' && + (context.req.path === '/admin' || context.req.path.startsWith('/admin/')) && + (context.req.header('Accept')?.includes('text/html') || + context.req.header('X-VoidPages') === 'true') + ) { + context.header('Cache-Control', 'private, no-store'); + return context.redirect('/admin/status', 302); + } + context.header('Cache-Control', 'no-store'); + context.header('Retry-After', '30'); return context.json({ error: 'Platform disabled' }, 503); } await next(); @@ -245,6 +274,22 @@ const app = new Hono() .use('*', platformAccessProtection) + .use('*', async (context, next) => { + if ( + context.get('platformTrafficPaused') && + isMaintenanceLoginCallback(context) && + !( + context.env.PLATFORM_TRAFFIC_STATE === 'sandbox-drain' && + isSandboxDrainMaintenanceRequest(context.req.raw) + ) && + !(await isAdministratorCallback(context)) + ) { + context.header('Cache-Control', 'no-store'); + return context.json({ error: 'Platform disabled' }, 503); + } + await next(); + }) + .get('/health', async (context) => { try { // Provision the trusted queue key before an installer enables traffic. diff --git a/platform/packages/api/src/middleware/platform-maintenance.ts b/platform/packages/api/src/middleware/platform-maintenance.ts new file mode 100644 index 000000000..4e8bd65b9 --- /dev/null +++ b/platform/packages/api/src/middleware/platform-maintenance.ts @@ -0,0 +1,46 @@ +import { and, eq, gt } from 'drizzle-orm'; +import type { Context } from 'hono'; +import { isAdminOAuthState } from '../admin/routes/login.ts'; +import type { ApiEnv } from '../env.ts'; +import { platformAuthAttempts } from '../schema.ts'; + +export function isMaintenanceReadRequest(context: Context): boolean { + if (context.req.method !== 'GET' && context.req.method !== 'HEAD') { + return false; + } + return ( + context.req.path === '/admin/status' || + context.req.path === '/admin/status.json' || + context.req.path === '/admin/login' || + /^\/admin\/login\/[^/]+$/.test(context.req.path) || + context.req.path === '/admin/logout' + ); +} + +export function isMaintenanceLoginCallback(context: Context): boolean { + return context.req.method === 'GET' && context.req.path === '/auth/callback'; +} + +/** Only administrator login may complete while the traffic gate is closed. */ +export async function isAdministratorCallback(context: Context): Promise { + const state = context.req.query('state'); + if (!state) { + return false; + } + if (!state.startsWith('platform.')) { + return isAdminOAuthState(state); + } + const [attempt] = await context + .get('db') + .select({ purpose: platformAuthAttempts.purpose }) + .from(platformAuthAttempts) + .where( + and( + eq(platformAuthAttempts.id, state), + gt(platformAuthAttempts.expires_at, new Date().toISOString()), + ), + ) + .limit(1); + // The callback still verifies browser proof, identity, role and session. + return attempt?.purpose === 'admin'; +} diff --git a/platform/packages/api/test/integration/platform-access-protection.test.ts b/platform/packages/api/test/integration/platform-access-protection.test.ts index 24fbd7dca..79f70e85c 100644 --- a/platform/packages/api/test/integration/platform-access-protection.test.ts +++ b/platform/packages/api/test/integration/platform-access-protection.test.ts @@ -18,7 +18,7 @@ import { createHumanSession } from '../../src/auth/sessions.ts'; import { emailReceipts } from '../../src/email/admission-schema.ts'; import { createGitHubWebhookIngressProof } from '../../src/github/webhook-ingress-auth.ts'; import { app } from '../../src/index.ts'; -import { platformAuthSettings, users } from '../../src/schema.ts'; +import { platformAuthSettings, platformHumanSessions, users } from '../../src/schema.ts'; import { clearTables, createTestBuild, @@ -150,6 +150,36 @@ async function githubSignature(body: string): Promise { } describe('Access-protected platform requests', () => { + it('keeps maintenance status behind human Access and a matching, revocable administrator session', async () => { + const session = await createHumanSession(env.db, env.JWT_SECRET, { + userId: user.id, + connectionId: 'github', + revision: 1, + generation: 1, + audience: 'admin', + companyIdentity, + }); + const call = (access?: string) => + app.fetch( + new Request(`${origin}/admin/status.json`, { + headers: { + Cookie: `admin_token=${session.token}`, + ...(access ? { 'Cf-Access-Jwt-Assertion': access } : {}), + }, + }), + { ...env, PLATFORM_TRAFFIC_STATE: 'staging' }, + ); + expect((await call()).status).toBe(403); + expect((await call(await assertion({ service: true }))).status).toBe(403); + expect((await call(await assertion({ subject: 'employee-2' }))).status).toBe(302); + const access = await assertion(); + expect((await call(access)).status).toBe(200); + await env.db + .update(platformHumanSessions) + .set({ revoked_at: new Date().toISOString() }) + .where(eq(platformHumanSessions.id, session.session.id)); + expect((await call(access)).status).toBe(302); + }); it('admits only the token-authenticated confirmation route without an Access assertion', async () => { const confirmation = await request('/email/destinations/confirm?token=invalid.signature'); expect(confirmation.status).toBe(400); diff --git a/platform/packages/api/test/integration/platform-status.test.ts b/platform/packages/api/test/integration/platform-status.test.ts new file mode 100644 index 000000000..3cf0b8c9d --- /dev/null +++ b/platform/packages/api/test/integration/platform-status.test.ts @@ -0,0 +1,283 @@ +import { readFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { + createPlatformDeploymentManifest, + createPlatformInstallationManifest, + PLATFORM_DISABLED_KEY, + type PlatformInstallationManifest, +} from '@void/platform'; +import { + getPlatformRuntimeDirectory, + PLATFORM_ADMIN_CLIENT_ASSET_PATH, + PLATFORM_ADMIN_STYLE_ASSET_PATH, +} from '@void/platform/installer'; +import { eq, sql } from 'drizzle-orm'; +import { chromium } from 'playwright'; +import { afterAll, beforeAll, beforeEach, expect, it } from 'vite-plus/test'; +import { importLegacyAuthentication } from '../../src/auth/configuration.ts'; +import { app } from '../../src/index.ts'; +import { users } from '../../src/schema.ts'; +import { clearTables, createTestUser, setupEnv, teardownEnv, type TestEnv } from './helpers.ts'; + +let env: TestEnv; +let admin: Awaited>; +let manifest: PlatformInstallationManifest; +const installationId = 'status-fixture'; +beforeAll(async () => { + env = await setupEnv(); + await env.db.execute(sql`CREATE TABLE __void_platform_installation ( + singleton boolean PRIMARY KEY, installation_id text NOT NULL, ownership_nonce text NOT NULL DEFAULT 'status-owner', lifecycle_manifest jsonb NOT NULL + )`); +}); +afterAll(teardownEnv); +beforeEach(async () => { + await clearTables(env.db); + await env.db.execute(sql`DELETE FROM __void_platform_installation`); + await env.ROUTING.delete(PLATFORM_DISABLED_KEY); + admin = await createTestUser(env.db, 'status-admin', 'github', undefined, 'free', 'admin'); + const timestamp = '2026-10-05T00:00:00.000Z'; + manifest = { + ...createPlatformInstallationManifest({ + account: { id: 'account', name: 'Account' }, + createdAt: timestamp, + deployment: createPlatformDeploymentManifest({ + application: { baseDomain: 'apps.example.com', zoneName: 'example.com' }, + displayName: 'Example', + installationSlug: 'example', + }), + id: installationId, + ownershipNonce: 'private-owner-nonce-0123456789abcdef', + platformVersion: '1.0.0', + }), + status: 'verifying', + operation: { + id: 'operation', + action: 'rollback', + fromVersion: '2.0.0', + toVersion: '1.0.0', + phase: 'waiting-for-sandbox-drain', + startedAt: timestamp, + updatedAt: timestamp, + }, + }; + await save(); +}); + +async function save() { + await env.db + .execute(sql`INSERT INTO __void_platform_installation (singleton, installation_id, lifecycle_manifest) VALUES + (true, ${installationId}, ${JSON.stringify(manifest)}::jsonb) + ON CONFLICT (singleton) DO UPDATE SET lifecycle_manifest = excluded.lifecycle_manifest`); +} +function request( + path: string, + token: string | undefined = admin.adminJwt, + init: RequestInit = {}, + trafficState = 'staging', +) { + const headers = new Headers(init.headers); + if (token) { + headers.set('Cookie', `admin_token=${token}`); + } + return app.fetch(new Request(`http://localhost${path}`, { ...init, headers }), { + ...env, + PLATFORM_INSTALLATION_ID: installationId, + PLATFORM_TRAFFIC_STATE: trafficState, + }); +} + +it.each(['staging', 'sandbox-drain'])( + 'serves private saved status to an admin during %s maintenance', + async (trafficState) => { + const response = await request('/admin/status.json', admin.adminJwt, {}, trafficState); + expect(response.status).toBe(200); + expect(response.headers.get('Cache-Control')).toBe('private, no-store'); + const body = await response.text(); + expect(JSON.parse(body)).toMatchObject({ + traffic: 'paused', + checkpoint: { operation: { action: 'rollback', phase: 'waiting-for-sandbox-drain' } }, + }); + expect(body).not.toContain('private-owner-nonce'); + expect(body).not.toContain('resources'); + const html = await request('/admin/status', admin.adminJwt, {}, trafficState); + expect(html.status).toBe(200); + expect(await html.text()).toContain('Waiting for Sandbox drain'); + }, +); + +it('observes the disabled KV gate even when the saved operation is complete', async () => { + manifest = { + ...manifest, + status: 'installed', + operation: { ...manifest.operation!, phase: 'complete' }, + }; + await save(); + await env.ROUTING.put(PLATFORM_DISABLED_KEY, 'disabled'); + expect(await (await request('/admin/status.json', admin.adminJwt, {}, '')).json()).toMatchObject({ + traffic: 'paused', + checkpoint: { operation: { phase: 'complete' } }, + }); + await env.ROUTING.delete(PLATFORM_DISABLED_KEY); + expect(await (await request('/admin/status.json', admin.adminJwt, {}, '')).json()).toMatchObject({ + traffic: 'enabled', + }); +}); + +it('requires a current administrator identity during maintenance', async () => { + const anonymous = await request('/admin/status.json', '', {}); + expect(anonymous.status).toBe(302); + expect(anonymous.headers.get('Location')).toBe('/admin/login'); + const regular = await createTestUser(env.db, 'status-member'); + expect((await request('/admin/status.json', regular.adminJwt)).status).toBe(403); + await env.db.update(users).set({ suspended_reason: 'admin' }).where(eq(users.id, admin.id)); + expect((await request('/admin/status.json')).status).toBe(403); +}); + +it('keeps writes and other API routes gated while redirecting admin navigation to status', async () => { + const response = await request('/admin/projects', admin.adminJwt, { + headers: { Accept: 'text/html' }, + }); + expect(response.status).toBe(302); + expect(response.headers.get('Location')).toBe('/admin/status'); + for (const path of [ + '/admin/status.json', + '/admin/status', + '/admin/fate', + '/admin/backfill-queue-tokens', + '/projects', + ]) { + const write = await request(path, admin.adminJwt, { + method: 'POST', + headers: { Origin: 'http://localhost' }, + }); + expect(write.status).toBe(503); + expect(await write.json()).toEqual({ error: 'Platform disabled' }); + } + expect((await request('/admin/health')).status).toBe(503); + expect((await request('/auth/callback?state=not-admin&code=fixture')).status).toBe(503); + expect((await request('/auth/callback?state=platform.unknown&code=fixture')).status).toBe(503); + expect((await request('/admin/login', '')).status).toBe(200); +}); + +it('reports unavailable checkpoints without exposing database errors or inventing progress', async () => { + await env.db.execute(sql`DELETE FROM __void_platform_installation`); + const response = await request('/admin/status.json'); + expect(response.status).toBe(503); + expect(await response.json()).toEqual({ error: 'Platform status is temporarily unavailable' }); + const html = await (await request('/admin/status')).text(); + expect(html).toContain('Live status is unavailable'); + expect(html).toContain('Unknown'); + expect(html).not.toContain('waiting-for-sandbox-drain'); +}); + +it('shows installation failure even when the last recorded operation completed', async () => { + manifest = { + ...manifest, + status: 'failed', + operation: { ...manifest.operation!, phase: 'complete' }, + }; + await save(); + const html = await (await request('/admin/status')).text(); + expect(html).toContain('Operation needs attention'); + expect(html).toContain('Next step'); + expect(html).not.toContain('The lifecycle operation completed.'); +}); + +it('allows administrator sign-in callbacks without allowing other login attempts', async () => { + await importLegacyAuthentication(env.db, env); + const login = await request('/admin/login/github', ''); + expect(login.status).toBe(302); + const state = new URL(login.headers.get('Location')!).searchParams.get('state')!; + // Missing browser proof is still rejected by normal authentication after the gate. + expect( + (await request(`/auth/callback?state=${encodeURIComponent(state)}&code=fixture`, '')).status, + ).toBe(400); + const memberLogin = await request( + `/auth/login?redirect=${encodeURIComponent('http://localhost:1234/callback?state=fixture')}&provider=github&code_challenge=${'a'.repeat(43)}&code_challenge_method=S256`, + '', + {}, + '', + ); + expect(memberLogin.status).toBe(302); + const memberState = new URL(memberLogin.headers.get('Location')!).searchParams.get('state')!; + expect( + (await request(`/auth/callback?state=${encodeURIComponent(memberState)}&code=fixture`, '')) + .status, + ).toBe(503); +}); + +it('retains the last confirmed snapshot when polling fails and refreshes without a write', async () => { + const browser = await chromium.launch(); + let unavailable = true; + const methods: Array = []; + const errors: Array = []; + try { + const context = await browser.newContext({ viewport: { width: 390, height: 844 } }); + await context.addCookies([ + { name: 'admin_token', value: admin.adminJwt, url: 'http://localhost' }, + ]); + const page = await context.newPage(); + page.on('pageerror', (error) => errors.push(error.message)); + await page.route('**/*', async (route) => { + const incoming = route.request(); + const url = new URL(incoming.url()); + if (url.origin !== 'http://localhost') { + await route.abort(); + return; + } + methods.push(incoming.method()); + if (url.pathname === '/admin/client.js' || url.pathname === '/admin/style.css') { + const asset = url.pathname.endsWith('.js') + ? PLATFORM_ADMIN_CLIENT_ASSET_PATH + : PLATFORM_ADMIN_STYLE_ASSET_PATH; + await route.fulfill({ + status: 200, + contentType: url.pathname.endsWith('.js') ? 'text/javascript' : 'text/css', + body: await readFile(join(getPlatformRuntimeDirectory(), asset)), + }); + return; + } + if (url.pathname === '/admin/status.json' && unavailable) { + await route.fulfill({ + status: 503, + contentType: 'application/json', + body: '{"error":"unavailable"}', + }); + return; + } + const response = await request(url.pathname + url.search, admin.adminJwt, { + headers: await incoming.allHeaders(), + }); + await route.fulfill({ + status: response.status, + headers: Object.fromEntries(response.headers), + body: Buffer.from(await response.arrayBuffer()), + }); + }); + await page.goto('http://localhost/admin/status'); + await page.getByText('Showing the last confirmed snapshot', { exact: false }).waitFor(); + expect(await page.getByRole('heading', { name: 'Waiting for Sandbox drain' }).count()).toBe(1); + expect( + await page.getByRole('heading', { name: 'Traffic paused (last confirmed)' }).count(), + ).toBe(1); + manifest = { + ...manifest, + status: 'installed', + operation: { ...manifest.operation!, phase: 'complete' }, + }; + await save(); + unavailable = false; + await page.getByRole('button', { name: 'Refresh status' }).click(); + await page.getByRole('heading', { name: 'Operation complete' }).waitFor(); + expect(await page.getByRole('heading', { name: 'Traffic paused', exact: true }).count()).toBe( + 1, + ); + expect( + await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth), + ).toBe(true); + expect(methods.every((method) => method === 'GET')).toBe(true); + expect(errors).toEqual([]); + } finally { + await browser.close(); + } +}); diff --git a/platform/packages/dispatch/src/error-page.ts b/platform/packages/dispatch/src/error-page.ts index 07fd6ca2b..d07b32714 100644 --- a/platform/packages/dispatch/src/error-page.ts +++ b/platform/packages/dispatch/src/error-page.ts @@ -9,7 +9,7 @@ function escapeHtml(value: string): string { .replaceAll('"', '"'); } -function renderDefaultErrorPage(status: number, title: string): string { +function renderDefaultErrorPage(status: number, title: string, maintenance = false): string { const heading = `${status}: ${title}`; const prefix = `${status}: `; @@ -63,16 +63,45 @@ function renderDefaultErrorPage(status: number, title: string): string { strong { font-weight: 600; } + p { color: #52525b; margin: 20px 0; } + a { display: inline-block; padding: 10px 20px; border-radius: 12px; background: #171717; color: #fff; text-decoration: none; } + a:focus-visible { outline: 3px solid #52525b; outline-offset: 4px; } + small { display: block; margin-top: 24px; color: #71717a; }
-

${escapeHtml(prefix)}${escapeHtml(title)}

+ ${ + maintenance + ? `

Temporarily unavailable

+

This service is undergoing maintenance. Please try again in a moment.

+ Try again + If you submitted a form, check whether it succeeded before submitting it again.` + : `

${escapeHtml(prefix)}${escapeHtml(title)}

` + }
`; } +export function createMaintenanceResponse(request: Request): Response { + const headers = new Headers({ 'Cache-Control': 'no-store', 'Retry-After': '30' }); + if (!shouldServeHtmlErrorPage(request)) { + return new Response(request.method === 'HEAD' ? null : 'Platform disabled', { + status: 503, + headers, + }); + } + headers.set('Content-Type', 'text/html; charset=utf-8'); + return new Response( + request.method === 'HEAD' ? null : renderDefaultErrorPage(503, 'Temporarily unavailable', true), + { + status: 503, + headers, + }, + ); +} + export function shouldServeHtmlErrorPage(request: Request): boolean { if (request.method !== 'GET' && request.method !== 'HEAD') { return false; diff --git a/platform/packages/dispatch/src/index.ts b/platform/packages/dispatch/src/index.ts index 7d1a4759d..dc0db3351 100644 --- a/platform/packages/dispatch/src/index.ts +++ b/platform/packages/dispatch/src/index.ts @@ -7,7 +7,7 @@ import { } from '@void/platform'; import { projectAccessVerifier } from './access.ts'; import type { Env } from './env.ts'; -import { createErrorResponse } from './error-page.ts'; +import { createErrorResponse, createMaintenanceResponse } from './error-page.ts'; import { applyHeaderRules, type HeaderRule } from './headers.ts'; import { readIsrCache, @@ -686,9 +686,7 @@ export default { (env.PLATFORM_INSTALLATION_ID && (await env.ROUTING.get(PLATFORM_DISABLED_KEY)) === PLATFORM_DISABLED_VALUE) ) { - return createErrorResponse(request, 503, 'Platform disabled', { - 'Cache-Control': 'no-store', - }); + return createMaintenanceResponse(request); } const startTime = Date.now(); // Budget for the bounded hot paths (static-asset reads, primary dispatch). diff --git a/platform/packages/dispatch/test/unit/error-page.test.ts b/platform/packages/dispatch/test/unit/error-page.test.ts index bc9884067..f12dccf13 100644 --- a/platform/packages/dispatch/test/unit/error-page.test.ts +++ b/platform/packages/dispatch/test/unit/error-page.test.ts @@ -1,7 +1,50 @@ import { describe, expect, it } from 'vite-plus/test'; -import { createErrorResponse, shouldServeHtmlErrorPage } from '../../src/error-page.ts'; +import { + createErrorResponse, + createMaintenanceResponse, + shouldServeHtmlErrorPage, +} from '../../src/error-page.ts'; describe('dispatch default error pages', () => { + it('offers a manual retry on an uncached maintenance document', async () => { + const response = createMaintenanceResponse( + new Request('https://example.com/account?secret=private', { + headers: { Accept: 'text/html' }, + }), + ); + expect(response.status).toBe(503); + expect(response.headers.get('Cache-Control')).toBe('no-store'); + expect(response.headers.get('Retry-After')).toBe('30'); + const html = await response.text(); + expect(html).toContain('Temporarily unavailable'); + expect(html).toContain('Try again'); + expect(html).not.toContain('private'); + expect(html).not.toContain(' { + const response = createMaintenanceResponse( + new Request(`https://example.com${path}`, { method, headers: { Accept: accept } }), + ); + expect(response.status).toBe(503); + expect(response.headers.get('Content-Type')).not.toContain('text/html'); + expect(await response.text()).toBe('Platform disabled'); + }); + + it.each(['/page', '/api/health'])('returns a bodyless maintenance HEAD for %s', async (path) => { + const response = createMaintenanceResponse( + new Request(`https://example.com${path}`, { method: 'HEAD' }), + ); + expect(response.status).toBe(503); + expect(response.headers.get('Cache-Control')).toBe('no-store'); + expect(await response.text()).toBe(''); + }); it('serves self-contained HTML for document 404s', async () => { const request = new Request('https://example.com/missing-page'); const response = createErrorResponse(request, 404, 'Not Found'); From 72684173f94cce93bea131a5f771ebe297c7b653 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 5 Oct 2026 14:42:11 +0800 Subject: [PATCH 2/2] Clarify automatic maintenance status and manual recovery --- .../platform/administration/operations.md | 15 ++++++---- .../platform/installation/maintenance.md | 28 +++++++++++-------- 2 files changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/guide/platform/administration/operations.md b/docs/guide/platform/administration/operations.md index 4a418fadc..2522678a3 100644 --- a/docs/guide/platform/administration/operations.md +++ b/docs/guide/platform/administration/operations.md @@ -66,12 +66,15 @@ The dashboard’s **System Status** page refreshes health checks every 30 second Use `void platform upgrade`, `repair`, `disable`, and `enable` to maintain your platform. See [platform maintenance](/guide/platform/installation/maintenance#resume-repair-recover-and-upgrade). -For upgrade and rollback progress, open `/admin/status` on the API origin. -Administrators can follow saved progress and the API's traffic state during -maintenance while the API and authentication database remain reachable. If a -status refresh fails, the last confirmed snapshot is marked as stale. Normal -administrator changes stay paused during maintenance. -Follow the CLI's recovery instructions to resume an operation. See +Upgrades and rollbacks run through the CLI; watching their progress is optional. +During maintenance, navigating the admin UI automatically redirects to +`/admin/status`. You can also open that page directly on the API origin. It +refreshes automatically and shows saved progress and the API's traffic state +while the API and authentication database remain reachable. If a status refresh +fails, the last confirmed snapshot is marked as stale. Normal administrator +changes stay paused during maintenance. +If the CLI reports an error or a waiting state, follow its recovery instructions +to resume the operation. See [Follow upgrade and rollback progress](/guide/platform/installation/maintenance#follow-upgrade-and-rollback-progress). For disaster recovery, keep a matching PostgreSQL backup, provider data backups, installation identity and complete project-encryption keyring, and immutable runtime artifacts. Keep traffic disabled while restoring data, run `discover` to reconstruct verified local metadata, and review `repair --plan` before recreating missing installer-owned infrastructure. Neither command restores backed-up data. See [Prepare for disaster recovery](/guide/platform/installation/maintenance#prepare-for-disaster-recovery) for the full sequence. diff --git a/docs/guide/platform/installation/maintenance.md b/docs/guide/platform/installation/maintenance.md index d23e4deb1..9d028e647 100644 --- a/docs/guide/platform/installation/maintenance.md +++ b/docs/guide/platform/installation/maintenance.md @@ -100,21 +100,25 @@ Keep the earlier runtime files if you need rollback. If the installed version is ### Follow upgrade and rollback progress -Open `/admin/status` on your platform API origin and sign in as an administrator. -The page shows the saved operation, source and target versions, and the traffic -state reported by the API. It refreshes every five seconds while visible. If -updates fail, it keeps the last confirmed snapshot and marks it as out of date. - -During maintenance, administrator navigation leads to this read-only page; -normal administrator changes remain paused. Sign-in and status remain available -while the API and authentication database are reachable. An operation completing +Watching progress is optional: a running upgrade or rollback proceeds through +the CLI without action on the status page. During maintenance, navigating the +admin UI automatically redirects to `/admin/status`. You can also open it +directly on your platform API origin and sign in as an administrator. + +The read-only page shows the saved operation, source and target versions, and +the traffic state reported by the API. It refreshes automatically every five +seconds while visible. If updates fail, it keeps the last confirmed snapshot +and marks it as out of date. Normal administrator changes remain paused. + +Sign-in and status remain available while the API and authentication database +are reachable. An operation completing does not confirm every project's health. A disabled installation keeps traffic paused after an upgrade or rollback. -The CLI reports when an operation completes, fails, or waits for DNS or Sandbox -drain work, and prints the command needed to resume. Resolve the reported problem, -then resume with the same runtime files. For a custom rollback, retain the source -runtime files too. `void platform status ` also prints locally saved progress +If an operation fails or waits for DNS or Sandbox drain work, the CLI prints +the recovery instructions and command needed to resume. Resolve the reported +problem, then resume with the same runtime files. For a custom rollback, retain +the source runtime files too. `void platform status ` also prints locally saved progress before checking the live API; this local checkpoint can be out of date if another administrator changed the installation.