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
2 changes: 1 addition & 1 deletion docs/guide/platform/installation/prerequisites.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Void does not require a particular database provider. Use an existing PostgreSQL

1. Create a fresh database or project dedicated to the platform, with no existing application tables. Use a database role that can create and manage its tables and schemas.
2. Open the provider's connection details and select the primary database. Use a direct connection or a session-mode pooler, not transaction pooling. The connection must work from both your computer and Cloudflare.
3. Copy the PostgreSQL connection URL, including the password and SSL settings, into your password manager. Paste only the URL—not a surrounding `psql` command—into Void's `PostgreSQL DATABASE_URL` prompt.
3. Copy the PostgreSQL connection URL, including the password and SSL settings, into your password manager. Paste only the URL—not a surrounding `psql` command—into Void's `PostgreSQL DATABASE_URL` prompt, as the provider gives it, including SSL settings such as `sslmode=verify-full`. A Hyperdrive that Void creates trusts only public certificate authorities, so if your database uses a private certificate authority, use a separately managed Hyperdrive, as described below.

| Provider | Connection setup |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down
17 changes: 15 additions & 2 deletions docs/guide/platform/installation/uninstall.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,28 @@ void platform uninstall [id] --plan
void platform uninstall [id]
```

Uninstall blocks platform traffic, removes transient Queues, and records the resources left for you to review. By default, Workers, KV, R2, Hyperdrive, the dispatch namespace, and AI Gateway remain in your account. Adopted resources, external PostgreSQL, zones, DNS records, routes, custom domains, and Cloudflare Access resources are always retained.
Uninstall blocks platform traffic, removes Queues that no remaining platform Worker uses, and records the resources left for you to review. By default, Workers, the Queues they use, KV, R2, Hyperdrive, the dispatch namespace, and AI Gateway remain in your account. Adopted resources, external PostgreSQL, zones, DNS records, routes, custom domains, and Cloudflare Access resources are always retained.

To also remove eligible data resources owned by the installer:

```sh
void platform uninstall [id] --purge-data
```

Even with `--purge-data`, Void retains Workers, R2, AI Gateway, DNS records, routes, custom domains, Access resources, adopted resources, external PostgreSQL, and zones. Review those in the Cloudflare dashboard if you want to remove them.
Even with `--purge-data`, Void retains Workers, the Queues they use, R2, AI Gateway, DNS records, routes, custom domains, Access resources, adopted resources, external PostgreSQL, and zones. Review those in the Cloudflare dashboard if you want to remove them.

### Remove retained resources

Cloudflare refuses to delete a resource while a platform Worker still uses it. In the Cloudflare dashboard, remove what is left in this order, skipping anything already gone:

1. Delete the platform DNS record, Worker routes, and custom domains.
2. Open each platform Queue and remove the platform API Worker from its consumers.
3. Delete the platform Workers.
4. Delete the platform Queues.
5. Delete the application Workers in the dispatch namespace, then delete the namespace.
6. Delete the platform KV namespaces and Hyperdrive configuration.
7. Empty the R2 bucket, then delete it.
8. Delete the AI Gateway.

If installation configured Cloudflare Access, the uninstall plan lists its recorded applications and service tokens with their ownership and IDs. Review them in Zero Trust after uninstall. Remove installer-created resources only when nothing else uses them; resources connected from an existing company setup remain under their owner's control.

Expand Down
4 changes: 2 additions & 2 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -866,11 +866,11 @@ An upgrade completes after the new Workers pass health checks. If rollout fails,

`platform rollback` restores a compatible earlier runtime without reversing database migrations. Pass its files with `--runtime`. If the installed version is a custom build, also supply that version with `--from-runtime`. Void refuses targets that are incompatible with the current database or predate installed authentication, sandbox-drain, or ownership-aware usage protocols. A later `upgrade` can move forward again.

Uninstall verifies remote ownership before removing anything. Data resources are retained unless you pass `--purge-data`. Workers, R2, AI Gateway, DNS records, routes, custom domains, adopted resources, external PostgreSQL, and zones are always retained for manual review.
Uninstall verifies remote ownership before removing anything. Data resources are retained unless you pass `--purge-data`. Workers, the Queues they use, R2, AI Gateway, DNS records, routes, custom domains, adopted resources, external PostgreSQL, and zones are always retained for manual review.

Resources that may have been shared or repurposed are retained for manual review. Platform traffic stays blocked. External PostgreSQL and its data are never deleted.

See [Disable and Uninstall](../guide/platform/installation/uninstall.md) for the full removal policy.
See [Disable and Uninstall](../guide/platform/installation/uninstall.md#remove-retained-resources) for the full removal policy and the cleanup order.

## Deploy

Expand Down
9 changes: 6 additions & 3 deletions packages/void/src/cli/platform-cloudflare.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1128,7 +1128,7 @@ function parseDnsRecord(value: Record<string, unknown>): CloudflareDnsRecord {
export function parsePostgresConnectionString(value: string): {
database: string;
host: string;
mtls?: Readonly<{ sslmode: 'require' | 'verify-ca' | 'verify-full' }>;
mtls?: Readonly<{ sslmode: 'require' }>;
password: string;
port: number;
user: string;
Expand All @@ -1151,14 +1151,17 @@ export function parsePostgresConnectionString(value: string): {
throw new Error('platform: DATABASE_URL has an invalid PostgreSQL port.');
}
const sslmode = url.searchParams.get('sslmode');
let mtls: Readonly<{ sslmode: 'require' | 'verify-ca' | 'verify-full' }> | undefined;
let mtls: Readonly<{ sslmode: 'require' }> | undefined;
if (sslmode) {
if (sslmode !== 'require' && sslmode !== 'verify-ca' && sslmode !== 'verify-full') {
throw new Error(
'platform: Unsupported sslmode. Cloudflare Hyperdrive supports "require", "verify-ca", or "verify-full".',
);
}
mtls = { sslmode };
// Hyperdrive accepts its verify modes only with an uploaded CA certificate ID, which a
// connection URL cannot carry. `require` is Hyperdrive's TLS mode that validates the server
// certificate against public CAs; Void's own database connections still use the URL's mode.
mtls = { sslmode: 'require' };
}
return {
database,
Expand Down
72 changes: 67 additions & 5 deletions packages/void/src/cli/platform-installer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ import {
import {
hyperdriveOriginConfigHash,
hyperdriveOriginFromConnectionString,
parsePostgresConnectionString,
PlatformWorkerCustomDomainsChangedError,
PlatformWorkerRoutesChangedError,
type CloudflareNamedResource,
Expand Down Expand Up @@ -1405,6 +1406,11 @@ export async function installPlatform(
writeInstallationManifest(manifest);
}
assertRequiredPlatformSecrets(plan, manifest, secrets, !!dependencies.prepareAuthentication);
if (hyperdriveAction?.action === 'create') {
// Reject a URL Hyperdrive can never accept before the claim binds it to this installation.
parsePostgresConnectionString(secrets.databaseUrl);
assertVoidCreatedHyperdriveTrustsDatabase(secrets.databaseUrl);
}
const pendingSecrets = secretCheckpoint(secrets, workerSecretUpdateIntent);
writePendingInstallationSecrets(manifest, {
...pendingSecrets,
Expand Down Expand Up @@ -2646,6 +2652,9 @@ export async function installPlatform(
PLATFORM_DISABLED_VALUE,
);
},
// Traffic opens only after every Worker in this generation is
// verified against its own staged checkpoint, so none may be reused.
reuseMatchingVersion: false,
runner: runPinnedPlatformWrangler,
workerExisted: true,
});
Expand Down Expand Up @@ -3482,6 +3491,20 @@ export function assertRequiredPlatformSecrets(
}
}

/**
* A Hyperdrive that Void creates validates the server against public certificate authorities
* only, so it cannot honor a private CA that the local database client would trust.
*/
function assertVoidCreatedHyperdriveTrustsDatabase(databaseUrl: string): void {
// Same last-value-wins rule as the local client; pg ignores an empty value.
const sslrootcert = new URL(databaseUrl).searchParams.getAll('sslrootcert').at(-1);
if (sslrootcert && sslrootcert !== 'system') {
throw new Error(
'platform: A Hyperdrive created by Void trusts only public certificate authorities, so it cannot use the certificate authority in DATABASE_URL sslrootcert. If the database certificate comes from a public certificate authority, use sslrootcert=system. Otherwise create a separately managed Hyperdrive that trusts it, then select it with "Use an existing Hyperdrive" when you start a new installation, or set VOID_PLATFORM_HYPERDRIVE_ID, VOID_PLATFORM_HYPERDRIVE_ORIGIN_HOST, and VOID_PLATFORM_HYPERDRIVE_ORIGIN_USER.',
);
}
}

/** Make pg's current strict TLS behavior explicit without rewriting saved connection details. */
export function platformDatabaseClientUrl(databaseUrl: string): string {
let url: URL;
Expand All @@ -3490,9 +3513,19 @@ export function platformDatabaseClientUrl(databaseUrl: string): string {
} catch {
return databaseUrl;
}
// Match pg's last-value-wins query parsing and respect explicit libpq compatibility.
if (url.protocol !== 'postgres:' && url.protocol !== 'postgresql:') {
return databaseUrl;
}
// Match pg's last-value-wins query parsing. libpq reads `sslrootcert=system` as the system
// trust store and requires verify-full with it, while pg would open it as a file path. Node's
// default CAs with hostname verification give pg the same policy.
if (url.searchParams.getAll('sslrootcert').at(-1) === 'system') {
url.searchParams.delete('sslrootcert');
url.searchParams.set('sslmode', 'verify-full');
return url.toString();
}
// Respect explicit libpq compatibility.
if (
(url.protocol !== 'postgres:' && url.protocol !== 'postgresql:') ||
url.searchParams.getAll('sslmode').at(-1) !== 'require' ||
url.searchParams.getAll('uselibpqcompat').at(-1) === 'true'
) {
Expand Down Expand Up @@ -4283,6 +4316,8 @@ type PlatformWorkerDeploymentOptions = Readonly<{
publishRoutes: (workerName: string, patterns: ReadonlyArray<string>) => Promise<void>;
removeCustomDomains: () => Promise<void>;
retainNewWorker: () => Promise<void>;
/** False uploads a new version even when the active one has identical input. */
reuseMatchingVersion?: boolean;
runner: typeof runPlatformWrangler;
workerExisted: boolean;
}>;
Expand Down Expand Up @@ -4508,6 +4543,7 @@ export async function deployPlatformWorker(
const nextTriggers = readTriggerConfigFromObject(nextTraffic.wranglerConfig);
const contentHash =
secrets === null ? platformWorkerUploadFingerprint(config, options.managedRoutes) : null;
const reuseMatchingVersion = options.reuseMatchingVersion !== false;
let previousTriggers = readTriggerConfigFromObject(previousTraffic.wranglerConfig);
try {
const configPath = join(directory, 'wrangler.json');
Expand Down Expand Up @@ -4606,7 +4642,7 @@ export async function deployPlatformWorker(
);
}
};
if (options.workerExisted && contentHash && options.readCloudflare) {
if (options.workerExisted && contentHash && reuseMatchingVersion && options.readCloudflare) {
let candidate:
| {
deploymentId: string;
Expand Down Expand Up @@ -4703,6 +4739,7 @@ export async function deployPlatformWorker(
previousDeploymentId = previousDeployment.id;
if (
contentHash &&
reuseMatchingVersion &&
previous.contentHash === contentHash &&
platformWorkerUploadFingerprint(config, options.managedRoutes) === contentHash
) {
Expand Down Expand Up @@ -5225,6 +5262,7 @@ async function runPlatformWranglerAtApiBase(
}

type ConditionalWorkerCreateState = {
assetSessionStarted: boolean;
attempted: boolean;
conflictStatus: number | null;
created: boolean;
Expand Down Expand Up @@ -5278,8 +5316,11 @@ async function startConditionalWorkerCreateProxy(
throw new Error('platform: Cloudflare API base URL must use HTTP or HTTPS.');
}
const basePath = upstreamBase.pathname.replace(/\/+$/, '');
const expectedPath = `${basePath}/accounts/${encodeURIComponent(accountId)}/workers/scripts/${encodeURIComponent(workerName)}`;
const accountPath = `${basePath}/accounts/${encodeURIComponent(accountId)}`;
const expectedPath = `${accountPath}/workers/scripts/${encodeURIComponent(workerName)}`;
const assetUploadPath = `${accountPath}/workers/assets/upload`;
const state: ConditionalWorkerCreateState = {
assetSessionStarted: false,
attempted: false,
conflictStatus: null,
created: false,
Expand Down Expand Up @@ -5313,9 +5354,27 @@ async function startConditionalWorkerCreateProxy(
).test(incomingUrl.pathname);
const isReadOnly =
incoming.method === 'GET' || incoming.method === 'HEAD' || incoming.method === 'OPTIONS';
// A Worker with static assets must register its asset manifest and upload
// the missing files before the script PUT that references them. Neither
// step attaches anything to a Worker; only the guarded create does.
const isAssetUploadSession =
incoming.method === 'POST' &&
incomingUrl.pathname === `${expectedPath}/assets-upload-session` &&
incomingUrl.search === '';
const isAssetUpload =
incoming.method === 'POST' &&
state.assetSessionStarted &&
((incomingUrl.pathname === assetUploadPath && incomingUrl.search === '?base64=true') ||
(incomingUrl.search === '' &&
incomingUrl.pathname.startsWith(`${assetUploadPath}/`) &&
/^[0-9a-f]{32}$/.test(incomingUrl.pathname.slice(assetUploadPath.length + 1))));
if (
(isTopLevelWorkerUpload && !isConditionalCreate) ||
(!isReadOnly && !isConditionalCreate && !state.created)
(!isReadOnly &&
!isConditionalCreate &&
!isAssetUploadSession &&
!isAssetUpload &&
!state.created)
) {
state.rejectedMutation = `${incoming.method ?? 'UNKNOWN'} ${incomingUrl.pathname}${
incomingUrl.pathname === expectedPath && !supportedCreateQuery
Expand All @@ -5335,6 +5394,9 @@ async function startConditionalWorkerCreateProxy(
state.attempted = true;
headers['if-none-match'] = '*';
}
if (isAssetUploadSession) {
state.assetSessionStarted = true;
}
const upstreamUrl = new URL(
`${incomingUrl.pathname}${incomingUrl.search}`,
upstreamBase.origin,
Expand Down
33 changes: 31 additions & 2 deletions packages/void/src/cli/platform-management.ts
Original file line number Diff line number Diff line change
Expand Up @@ -798,7 +798,7 @@ export async function uninstallPlatform(
? 'Delete safely identifiable installer-owned data (--purge-data); retain Workers, R2, AI Gateway, and external PostgreSQL for manual cleanup.'
: 'Retain installer-owned data; external PostgreSQL is never deleted.';
note(
`Disable all platform traffic through installation-owned routing storage.\nRetain DNS records, routes, and custom domains for explicit dashboard cleanup.\nDelete installer-owned Queues.\n${dataMessage}\n${
`Disable all platform traffic through installation-owned routing storage.\nRetain DNS records, routes, and custom domains for explicit dashboard cleanup.\nDelete installer-owned Queues unless a retained Worker still uses them.\n${dataMessage}\n${
createdZone
? `Keep zone ${createdZone.name} for explicit manual cleanup.`
: 'Never delete the adopted application zone.'
Expand Down Expand Up @@ -930,6 +930,15 @@ export async function uninstallPlatform(
resourceDeletionPriority(left, deletionPriority) -
resourceDeletionPriority(right, deletionPriority),
);
// Uninstall retains Workers, and Cloudflare refuses to delete a Queue that
// a Worker still binds. Delete Queues only once none of this installation's
// Workers exist, so a retained Worker keeps its bindings intact.
const queuesInUse =
hasRoutingCheckpoint &&
resources.some(
(resource) => resource.kind === 'queue' && shouldDeleteResource(resource, retainData),
) &&
(await hasLiveInstallationWorker(client, next));
for (const resource of resources) {
if (resource.state !== 'ready') {
continue;
Expand All @@ -944,7 +953,7 @@ export async function uninstallPlatform(
await writeLifecycleCheckpoint(client, next);
continue;
}
if (resource.kind === 'dns-record' && !zone) {
if ((resource.kind === 'dns-record' && !zone) || (resource.kind === 'queue' && queuesInUse)) {
next = updateResourceState(next, resource.key, 'retained');
await writeLifecycleCheckpoint(client, next);
continue;
Expand Down Expand Up @@ -1116,6 +1125,26 @@ function shouldDeleteResource(resource: InstallationResource, retainData: boolea
return !(retainData && DATA_RESOURCE_KINDS.has(resource.kind));
}

async function hasLiveInstallationWorker(
client: Pick<PlatformManagementClient, 'listWorkerNames'>,
manifest: PlatformInstallationManifest,
): Promise<boolean> {
const names = manifest.deployment.resources;
const installationWorkers = new Set([
names.apiWorker,
names.proxyWorker,
names.emailGatewayWorker,
names.tailWorker,
names.dispatchWorker,
...manifest.resources
.filter((resource) => resource.kind === 'worker')
.map((resource) => resource.name),
]);
return (await client.listWorkerNames(manifest.account.id)).some((name) =>
installationWorkers.has(name),
);
}

function resourceDeletionPriority(
resource: InstallationResource,
priorities: Readonly<Record<string, number>>,
Expand Down
Loading
Loading