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
3 changes: 2 additions & 1 deletion docs/guide/platform/installation/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ Inject the following values from protected CI secrets. Do not commit them in a w
| `VOID_PLATFORM_DATABASE_URL` | Dedicated PostgreSQL URL |
| `VOID_PLATFORM_HYPERDRIVE_ID` | Existing externally managed Hyperdrive ID, when applicable |
| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_HOST` | Origin host of that Hyperdrive; set with its ID and user |
| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_USER` | Runtime database user of that Hyperdrive; set with its ID and host |
| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_USER` | Runtime database user of that Hyperdrive; set with its ID and host (or service ID) |
| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_SERVICE_ID` | For a Workers VPC origin, set the service ID in place of the origin host |
| `VOID_PLATFORM_R2_ACCESS_KEY_ID` | R2 Access Key ID |
| `VOID_PLATFORM_R2_SECRET_ACCESS_KEY` | R2 Secret Access Key |
| `VOID_PLATFORM_JWT_SECRET` | Original JWT signing secret |
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/platform/installation/prerequisites.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ Save the printed URL in your password manager and paste it into Void's `PostgreS
The installer can create Hyperdrive for you or use one you manage separately. For an existing configuration:

1. Point it at the dedicated platform database using a runtime user, and disable SQL result caching.
2. Select it in the installer and review the database, host, port, and runtime user.
2. Select it in the installer and review the database, host and port (or Workers VPC service ID), and runtime user.
3. Supply a database owner connection at the PostgreSQL URL prompt so Void can apply migrations.

To create one first, choose **Set up a separately managed Hyperdrive** and follow the printed instructions or [Cloudflare’s setup guide](https://developers.cloudflare.com/hyperdrive/get-started/). Rerun the installer once it is ready. Void leaves its configuration under your control. For unattended setup, use the Hyperdrive variables in [Install from CI](/guide/platform/installation/ci).
35 changes: 27 additions & 8 deletions packages/void/src/cli/platform-auth-database.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@ import type { InstallationResource } from '@void/platform';
import {
hyperdriveOriginConfigHash,
hyperdriveOriginFromConnectionString,
hyperdriveOriginLocationMatches,
hyperdriveOriginMatches,
type CloudflareHyperdriveConfig,
type CloudflareHyperdriveOriginLocation,
type PlatformCloudflareClient,
} from './platform-cloudflare.ts';
import type { PlatformExternalHyperdrive } from './platform-plan.ts';
Expand All @@ -21,6 +23,10 @@ export function readPlatformHyperdriveSelection(
} catch {
throw new Error('platform: The saved Hyperdrive selection is invalid.');
}
return parsePlatformHyperdriveSelection(value);
}

export function parsePlatformHyperdriveSelection(value: unknown): PlatformExternalHyperdrive {
const selected = value as Partial<PlatformExternalHyperdrive> | null;
const nonempty = (value: unknown): value is string =>
typeof value === 'string' && value.trim() !== '';
Expand All @@ -29,7 +35,9 @@ export function readPlatformHyperdriveSelection(
typeof selected !== 'object' ||
Array.isArray(selected) ||
!nonempty(selected.id) ||
!nonempty(selected.host) ||
(nonempty(selected.serviceId)
? selected.host !== undefined
: selected.serviceId !== undefined || !nonempty(selected.host)) ||
!nonempty(selected.user) ||
(selected.name !== undefined && (typeof selected.name !== 'string' || !selected.name)) ||
(selected.database !== undefined &&
Expand All @@ -39,7 +47,9 @@ export function readPlatformHyperdriveSelection(
}
return {
id: selected.id,
host: selected.host,
...(selected.serviceId !== undefined
? { serviceId: selected.serviceId }
: { host: selected.host! }),
user: selected.user,
...(selected.name ? { name: selected.name } : {}),
...(selected.database ? { database: selected.database } : {}),
Expand Down Expand Up @@ -67,19 +77,28 @@ export function platformDatabaseNameFromOwnerUrl(databaseUrl: string): string {
/** Pin an externally managed Hyperdrive without treating the owner URL as its runtime origin. */
export function verifyExternalPlatformHyperdrive(input: {
config: CloudflareHyperdriveConfig;
databaseUrl: string;
expected: { id: string; name: string; host: string; user: string };
databaseUrl?: string;
expected: CloudflareHyperdriveOriginLocation & {
id: string;
name?: string;
database?: string;
user: string;
};
recordedHash?: string;
}): string {
const { config, expected } = input;
const database = platformDatabaseNameFromOwnerUrl(input.databaseUrl);
const database =
input.databaseUrl === undefined
? undefined
: platformDatabaseNameFromOwnerUrl(input.databaseUrl);
const hash = hyperdriveOriginConfigHash(config.origin);
if (
config.id !== expected.id ||
config.name !== expected.name ||
config.origin.host !== expected.host.toLowerCase() ||
(expected.name !== undefined && config.name !== expected.name) ||
!hyperdriveOriginLocationMatches(config.origin, expected) ||
config.origin.user !== expected.user ||
config.origin.database !== database ||
(database !== undefined && config.origin.database !== database) ||
(expected.database !== undefined && config.origin.database !== expected.database) ||
(input.recordedHash && input.recordedHash !== hash)
) {
throw new Error(
Expand Down
100 changes: 70 additions & 30 deletions packages/void/src/cli/platform-cloudflare.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,15 +84,25 @@ export type CloudflareNamedResource = Readonly<{
id: string;
name: string;
}>;
export type CloudflareHyperdriveOrigin = Readonly<{
accessClientId?: string;
export type CloudflareHyperdriveOriginLocation = Readonly<
{ host: string; serviceId?: never } | { serviceId: string; host?: never }
>;
type CloudflareHyperdriveDatabase = Readonly<{
database: string;
host: string;
/** Tunnel-backed origins get their database port from the tunnel service. */
port: number | null;
scheme: 'postgresql';
user: string | null;
}>;
type CloudflareHyperdriveHostOrigin = CloudflareHyperdriveDatabase &
Readonly<{
accessClientId?: string;
host: string;
serviceId?: never;
/** Tunnel-backed origins get their database port from the tunnel service. */
port: number | null;
}>;
export type CloudflareHyperdriveOrigin =
| CloudflareHyperdriveHostOrigin
| (CloudflareHyperdriveDatabase & Readonly<{ serviceId: string; host?: never }>);
export type CloudflareHyperdriveConfig = CloudflareNamedResource &
Readonly<{ origin: CloudflareHyperdriveOrigin; cachingDisabled?: boolean }>;
export type CloudflareDnsRecord = CloudflareNamedResource &
Expand Down Expand Up @@ -1691,7 +1701,9 @@ export function parsePostgresConnectionString(value: string): {
};
}

export function hyperdriveOriginFromConnectionString(value: string): CloudflareHyperdriveOrigin {
export function hyperdriveOriginFromConnectionString(
value: string,
): CloudflareHyperdriveHostOrigin {
const parsed = parsePostgresConnectionString(value);
return {
database: parsed.database,
Expand All @@ -1707,21 +1719,34 @@ export function hyperdriveOriginConfigHash(origin: CloudflareHyperdriveOrigin):
.update(
JSON.stringify({
database: origin.database,
host: origin.host.toLowerCase(),
port: origin.port,
...(origin.serviceId !== undefined
? { serviceId: origin.serviceId.toLowerCase() }
: { host: origin.host.toLowerCase(), port: origin.port }),
scheme: 'postgresql',
user: origin.user,
...(origin.accessClientId ? { accessClientId: origin.accessClientId } : {}),
...(origin.serviceId === undefined && origin.accessClientId
? { accessClientId: origin.accessClientId }
: {}),
}),
)
.digest('hex');
}

export function hyperdriveOriginLocationMatches(
live: CloudflareHyperdriveOriginLocation,
expected: CloudflareHyperdriveOriginLocation,
): boolean {
return expected.serviceId !== undefined
? live.serviceId?.toLowerCase() === expected.serviceId.toLowerCase()
: live.host?.toLowerCase() === expected.host.toLowerCase();
}

export function hyperdriveOriginMatches(
live: CloudflareHyperdriveOrigin,
expected: CloudflareHyperdriveOrigin,
expected: CloudflareHyperdriveHostOrigin,
): boolean {
return (
live.serviceId === undefined &&
live.database === expected.database &&
live.host.toLowerCase() === expected.host.toLowerCase() &&
live.port === expected.port &&
Expand All @@ -1741,18 +1766,40 @@ function parseHyperdriveConfig(value: Record<string, unknown>): CloudflareHyperd
if (scheme !== 'postgres' && scheme !== 'postgresql') {
throw new Error(`platform: Unsupported Hyperdrive origin scheme ${JSON.stringify(scheme)}.`);
}
const accessClientId =
typeof record.access_client_id === 'string' && record.access_client_id
? record.access_client_id
: undefined;
const port =
accessClientId && record.port == null
? null
: typeof record.port === 'number' || typeof record.port === 'string'
? Number(record.port)
: NaN;
if (port !== null && (!Number.isInteger(port) || port <= 0 || port > 65_535)) {
throw new Error('platform: Cloudflare Hyperdrive config has an invalid origin port.');
const database: CloudflareHyperdriveDatabase = {
database: requiredString(record.database, 'Hyperdrive origin database'),
scheme: 'postgresql',
user: typeof record.user === 'string' && record.user ? record.user : null,
};
let parsedOrigin: CloudflareHyperdriveOrigin;
if (record.service_id != null) {
const serviceId = requiredString(record.service_id, 'Hyperdrive origin service ID');
if (record.host != null || record.port != null || record.access_client_id != null) {
throw new Error(
'platform: Cloudflare Hyperdrive config mixes Workers VPC and host origin fields.',
);
}
parsedOrigin = { ...database, serviceId };
} else {
const accessClientId =
typeof record.access_client_id === 'string' && record.access_client_id
? record.access_client_id
: undefined;
const port =
accessClientId && record.port == null
? null
: typeof record.port === 'number' || typeof record.port === 'string'
? Number(record.port)
: NaN;
if (port !== null && (!Number.isInteger(port) || port <= 0 || port > 65_535)) {
throw new Error('platform: Cloudflare Hyperdrive config has an invalid origin port.');
}
parsedOrigin = {
...database,
host: requiredString(record.host, 'Hyperdrive origin host').toLowerCase(),
port,
...(accessClientId ? { accessClientId } : {}),
};
}
return {
id: requiredString(value.id, 'Hyperdrive id'),
Expand All @@ -1762,13 +1809,6 @@ function parseHyperdriveConfig(value: Record<string, unknown>): CloudflareHyperd
typeof value.caching === 'object' &&
!Array.isArray(value.caching) &&
(value.caching as Record<string, unknown>).disabled === true,
origin: {
...(accessClientId ? { accessClientId } : {}),
database: requiredString(record.database, 'Hyperdrive origin database'),
host: requiredString(record.host, 'Hyperdrive origin host').toLowerCase(),
port,
scheme: 'postgresql',
user: typeof record.user === 'string' && record.user ? record.user : null,
},
origin: parsedOrigin,
};
}
2 changes: 1 addition & 1 deletion packages/void/src/cli/platform-installer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -301,9 +301,9 @@ export async function installPlatform(
config: live,
databaseUrl: secrets.databaseUrl,
expected: {
...(plan.externalHyperdrive ?? live.origin),
id: hyperdriveAction.id,
name: hyperdriveAction.name,
host: plan.externalHyperdrive?.host ?? live.origin.host,
user: plan.externalHyperdrive?.user ?? live.origin.user ?? '',
},
...(recordedHyperdrive ? { recordedHash: recordedHyperdrive.configHash } : {}),
Expand Down
Loading