Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/guide/platform/administration/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,17 @@ 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).

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.

## Using Scripts
Expand Down
29 changes: 29 additions & 0 deletions docs/guide/platform/installation/maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,35 @@ Keep the earlier runtime files if you need rollback. If the installed version is

:::

### Follow upgrade and rollback progress

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.

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 <id>` 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:
Expand Down
5 changes: 5 additions & 0 deletions docs/reference/cli/platform.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <installation-id>` 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.
Expand Down
2 changes: 2 additions & 0 deletions packages/platform/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ export {
createPlatformInstallationManifest,
parsePlatformResourceOwnershipMarker,
parsePlatformInstallationManifest,
parsePlatformLifecycleOperation,
recordInstallationResource,
recordInstallationStep,
setInstallationDesiredState,
Expand All @@ -73,6 +74,7 @@ export {
type InstallationStatus,
type InstallationStep,
type PlatformInstallationManifest,
type PlatformLifecycleOperation,
type PlatformInstallationEndpoints,
type PlatformRuntimeProvenance,
type PlatformResourceOwnershipMarker,
Expand Down
72 changes: 72 additions & 0 deletions packages/platform/src/installation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<{
Expand Down Expand Up @@ -99,6 +167,7 @@ export type PlatformInstallationManifest = Readonly<{
endpoints: PlatformInstallationEndpoints;
id: string;
ownershipNonce: string;
operation?: PlatformLifecycleOperation;
platformVersion: string;
resources: ReadonlyArray<InstallationResource>;
runtime: PlatformRuntimeProvenance | null;
Expand Down Expand Up @@ -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) }
Expand Down
2 changes: 2 additions & 0 deletions packages/void/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<installation-name>-<role>` 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.
Expand Down
48 changes: 45 additions & 3 deletions packages/void/src/cli/platform-cmd.ts
Original file line number Diff line number Diff line change
@@ -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 {
Expand All @@ -15,6 +15,7 @@ import {
normalizePlatformApiUrl,
savePlatformConnection,
selectPlatformConnection,
listInstallationManifests,
type PlatformConnection,
} from './platform-registry.ts';

Expand Down Expand Up @@ -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}`);
Expand All @@ -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`);
}
}
Loading
Loading