feat(cloudflare/hyperdrive): connect to private databases through Workers VPC (#2218)

Author: sam-goodwin

examples/cloudflare-hyperdrive-aws-vpc/README.md

@@ -0,0 +1,33 @@
+# Hyperdrive + Workers VPC + Aurora
+
+[Guide](https://alchemy.run/cloudflare/data/hyperdrive-private-database/)
+
+A Cloudflare Worker queries Aurora PostgreSQL in private AWS subnets through Hyperdrive. Nothing in the VPC accepts inbound traffic: `cloudflared` runs on ECS Fargate and dials out to Cloudflare.
+
+```
+Worker → Hyperdrive → VPC Service → Tunnel → cloudflared (ECS) → Aurora
+```
+
+- [src/Database.ts](./src/Database.ts) — VPC, security groups, Aurora
+- [src/Connector.ts](./src/Connector.ts) — Cloudflare Tunnel + `cloudflared` on ECS
+- [src/Hyperdrive.ts](./src/Hyperdrive.ts) — TCP VPC Service + Hyperdrive
+- [src/worker.ts](./src/worker.ts) — the Worker
+
+## Deploy
+
+From the repository root:
+
+```sh
+pnpm install
+cd examples/cloudflare-hyperdrive-aws-vpc
+pnpm run deploy --profile testing --stage hyperdrive-vpc
+curl "<url>"
+```
+
+Aurora incurs charges until destroyed.
+
+## Destroy
+
+```sh
+pnpm run destroy --profile testing --stage hyperdrive-vpc
+```

examples/cloudflare-hyperdrive-aws-vpc/alchemy.run.ts

@@ -0,0 +1,28 @@
+import * as Alchemy from "alchemy";
+import * as AWS from "alchemy/AWS";
+import * as Cloudflare from "alchemy/Cloudflare";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { Connector } from "./src/Connector.ts";
+import { Hyperdrive } from "./src/Hyperdrive.ts";
+
+export default Alchemy.Stack(
+  "CloudflareHyperdriveAwsVpc",
+  {
+    providers: Layer.mergeAll(AWS.providers(), Cloudflare.providers(), Alchemy.RandomProvider()),
+    state: Alchemy.localState(),
+  },
+  Effect.gen(function* () {
+    yield* Connector;
+    const hd = yield* Hyperdrive;
+    const worker = yield* Cloudflare.Worker("Api", {
+      main: "./src/worker.ts",
+      compatibility: { flags: ["nodejs_compat"] },
+      env: { DB: hd },
+    });
+    return {
+      url: worker.url,
+      hyperdriveId: hd.hyperdriveId,
+    };
+  }),
+);

examples/cloudflare-hyperdrive-aws-vpc/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "cloudflare-hyperdrive-aws-vpc",
+  "version": "0.0.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alchemy-run/alchemy.git",
+    "directory": "examples/cloudflare-hyperdrive-aws-vpc"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "deploy": "alchemy deploy",
+    "destroy": "alchemy destroy"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "catalog:",
+    "alchemy": "workspace:*",
+    "effect": "catalog:",
+    "pg": "catalog:"
+  },
+  "devDependencies": {
+    "@types/pg": "catalog:"
+  }
+}

examples/cloudflare-hyperdrive-aws-vpc/src/Connector.ts

@@ -0,0 +1,34 @@
+import * as AWS from "alchemy/AWS";
+import * as Cloudflare from "alchemy/Cloudflare";
+import * as Effect from "effect/Effect";
+import { ConnectorSecurityGroup, Network } from "./Database.ts";
+
+/** The Cloudflare Tunnel that carries Hyperdrive's traffic into the VPC. */
+export const Tunnel = Cloudflare.Tunnel.Tunnel("Tunnel", {
+  ingress: [{ service: "http_status:404" }],
+});
+
+/**
+ * Runs `cloudflared` inside the VPC on ECS Fargate. It dials out to
+ * Cloudflare, so the VPC needs no inbound rules. The tunnel token is kept in
+ * Secrets Manager and injected as `TUNNEL_TOKEN`.
+ */
+export const Connector = Effect.gen(function* () {
+  const network = yield* Network;
+  const securityGroup = yield* ConnectorSecurityGroup;
+  const tunnel = yield* Tunnel;
+  const token = yield* AWS.SecretsManager.Secret("TunnelToken", {
+    secretString: tunnel.token,
+  });
+  const cluster = yield* AWS.ECS.Cluster("Cluster", {});
+  return yield* AWS.ECS.Service("Cloudflared", {
+    cluster,
+    image: "cloudflare/cloudflared:latest",
+    command: ["tunnel", "--no-autoupdate", "run"],
+    secrets: { TUNNEL_TOKEN: token.secretArn },
+    vpcId: network.vpcId,
+    subnets: network.publicSubnetIds,
+    securityGroups: [securityGroup.groupId],
+    assignPublicIp: true,
+  });
+});

examples/cloudflare-hyperdrive-aws-vpc/src/Database.ts

@@ -0,0 +1,62 @@
+import * as Alchemy from "alchemy";
+import * as AWS from "alchemy/AWS";
+import * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+
+export const DB_USER = "app";
+export const DB_NAME = "app";
+
+/**
+ * A VPC with public subnets (for the tunnel connector) and private subnets
+ * (for Aurora). Nothing in the private subnets is reachable from the internet.
+ */
+export const Network = AWS.EC2.Network("Network", {
+  cidrBlock: "10.63.0.0/16",
+  availabilityZones: 2,
+});
+
+/** Security group for the `cloudflared` connector — outbound only. */
+export const ConnectorSecurityGroup = Effect.gen(function* () {
+  const network = yield* Network;
+  return yield* AWS.EC2.SecurityGroup("ConnectorSecurityGroup", {
+    vpcId: network.vpcId,
+    description: "cloudflared connector; no inbound connections",
+  });
+});
+
+/** Database password, generated once and kept in state. */
+export const DbPassword = Alchemy.Random("DbPassword", { bytes: 24 });
+
+/** Private Aurora PostgreSQL that only admits the connector. */
+export const Database = Effect.gen(function* () {
+  const network = yield* Network;
+  const connector = yield* ConnectorSecurityGroup;
+  const password = yield* DbPassword;
+  const dbSecurityGroup = yield* AWS.EC2.SecurityGroup("DatabaseSecurityGroup", {
+    vpcId: network.vpcId,
+    description: "Postgres from the cloudflared connector only",
+    ingress: [
+      {
+        ipProtocol: "tcp",
+        fromPort: 5432,
+        toPort: 5432,
+        referencedGroupId: connector.groupId,
+      },
+    ],
+  });
+  const secret = yield* AWS.SecretsManager.Secret("DatabaseSecret", {
+    secretString: Output.map(password.text, (password) =>
+      Redacted.make(JSON.stringify({ username: DB_USER, password: Redacted.value(password) })),
+    ),
+  });
+  return yield* AWS.RDS.Aurora("Database", {
+    databaseName: DB_NAME,
+    engine: "aurora-postgresql",
+    engineVersion: "17.5",
+    subnetIds: network.privateSubnetIds,
+    securityGroupIds: [dbSecurityGroup.groupId],
+    secret: { resource: secret },
+    instance: { dbInstanceClass: "db.serverless", publiclyAccessible: false },
+  });
+});

examples/cloudflare-hyperdrive-aws-vpc/src/Hyperdrive.ts

@@ -0,0 +1,49 @@
+import * as Cloudflare from "alchemy/Cloudflare";
+import * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import { Connector, Tunnel } from "./Connector.ts";
+import { DB_NAME, DB_USER, Database, DbPassword } from "./Database.ts";
+
+/**
+ * A TCP VPC Service for the Aurora writer endpoint. `cloudflared` resolves
+ * the hostname with the VPC's DNS, so the private endpoint works as-is.
+ */
+export const AuroraService = Effect.gen(function* () {
+  const tunnel = yield* Tunnel;
+  const connector = yield* Connector;
+  const db = yield* Database;
+  // Hyperdrive connects to the database when it is created, so the path
+  // must be live first: wait for the writer instance and the connector.
+  const hostname = Output.map(
+    Output.all(db.cluster.endpoint, db.writer.dbInstanceArn, connector.serviceArn),
+    ([endpoint]) => endpoint!,
+  );
+  return yield* Cloudflare.Connectivity.DirectoryService("AuroraService", {
+    type: "tcp",
+    tcpPort: 5432,
+    appProtocol: "postgresql",
+    host: {
+      hostname,
+      resolverNetwork: { tunnelId: tunnel.tunnelId },
+    },
+    // Aurora's certificate is issued by the Amazon RDS CA, which Workers VPC
+    // does not trust yet (custom CAs are not supported). The connection is
+    // still TLS-encrypted.
+    tlsSettings: { certVerificationMode: "disabled" },
+  });
+});
+
+/** Hyperdrive egresses through the VPC Service to reach Aurora. */
+export const Hyperdrive = Effect.gen(function* () {
+  const service = yield* AuroraService;
+  const password = yield* DbPassword;
+  return yield* Cloudflare.Hyperdrive.Connection("Hyperdrive", {
+    origin: {
+      scheme: "postgres",
+      serviceId: service.serviceId,
+      database: DB_NAME,
+      user: DB_USER,
+      password: password.text,
+    },
+  });
+});

examples/cloudflare-hyperdrive-aws-vpc/src/worker.ts

@@ -0,0 +1,18 @@
+import type { Hyperdrive } from "@cloudflare/workers-types";
+import { Client } from "pg";
+
+/** Queries the private Aurora database through Hyperdrive. */
+export default {
+  async fetch(_request: Request, env: { DB: Hyperdrive }): Promise<Response> {
+    const client = new Client({ connectionString: env.DB.connectionString });
+    try {
+      await client.connect();
+      const result = await client.query("select version()");
+      return Response.json(result.rows[0]);
+    } catch (error) {
+      return new Response(String(error), { status: 500 });
+    } finally {
+      await client.end().catch(() => {});
+    }
+  },
+};

examples/cloudflare-hyperdrive-aws-vpc/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["alchemy.run.ts", "src/**/*.ts"],
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".",
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "target": "ESNext"
+  },
+  "references": [{ "path": "../../packages/alchemy/tsconfig.json" }]
+}

packages/alchemy/src/Cloudflare/Hyperdrive/ConnectBinding.ts

@@ -1,4 +1,5 @@
 import type * as runtime from "@cloudflare/workers-types";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
@@ -7,7 +8,7 @@ import { defaultProviderMode, type ProviderMode } from "../../ProviderMode.ts";
 import { Worker, WorkerEnvironment } from "../Workers/Worker.ts";
 import { Connect, type ConnectClient } from "./Connect.ts";
 import type { Connection } from "./Connection.ts";
-import { defaultPort, type DevOrigin } from "./Connection.ts";
+import { defaultPort, type DevOrigin, type Mtls, type Origin } from "./Connection.ts";
 
 export const ConnectBinding = Layer.effect(
   Connect,
@@ -63,38 +64,63 @@ export const getHyperdriveDevOriginForHost = Effect.fn(function* (
   return mode === "local" ? getHyperdriveDevOrigin(connection) : undefined;
 });
 
+/**
+ * A Hyperdrive origin that `alchemy dev` cannot reach from the local
+ * machine, bound without a `dev` override.
+ */
+export class HyperdriveDevOriginUnsupported extends Data.TaggedError(
+  "HyperdriveDevOriginUnsupported",
+)<{
+  message: string;
+  logicalId: string;
+  origin: "access" | "vpc";
+}> {}
+
 export const getHyperdriveDevOrigin = (connection: Connection) => {
-  const origin = Output.map(
-    Output.all(connection.dev, connection.origin, connection.mtls),
-    ([dev, origin, mtls]): Required<DevOrigin> => {
-      if (dev) {
-        return {
-          scheme: dev.scheme,
-          host: dev.host,
-          port: dev.port ?? defaultPort(dev.scheme),
-          user: dev.user,
-          database: dev.database,
-          password: dev.password,
-          sslmode: dev.sslmode ?? "prefer",
-        };
-      }
-      if ("accessClientId" in origin) {
-        throw new Error(
-          `Hyperdrive instance ${connection.LogicalId} has an origin that requires Cloudflare Access. This is not supported in development mode. ` +
+  const origin = Output.mapEffect(([dev, origin, mtls]: [DevOrigin | undefined, Origin, Mtls]) => {
+    if (dev) {
+      return Effect.succeed<Required<DevOrigin>>({
+        scheme: dev.scheme,
+        host: dev.host,
+        port: dev.port ?? defaultPort(dev.scheme),
+        user: dev.user,
+        database: dev.database,
+        password: dev.password,
+        sslmode: dev.sslmode ?? "prefer",
+      });
+    }
+    if ("accessClientId" in origin) {
+      return Effect.die(
+        new HyperdriveDevOriginUnsupported({
+          logicalId: connection.LogicalId,
+          origin: "access",
+          message:
+            `Hyperdrive instance ${connection.LogicalId} has an origin that requires Cloudflare Access. This is not supported in development mode. ` +
             "Select a different origin or set the `dev` property to an origin that does not require Cloudflare Access.",
-        );
-      }
-      return {
-        scheme: origin.scheme,
-        host: origin.host,
-        port: origin.port ?? defaultPort(origin.scheme),
-        user: origin.user,
-        database: origin.database,
-        password: origin.password,
-        sslmode: mtls?.sslmode ?? "require",
-      };
-    },
-  );
+        }),
+      );
+    }
+    if ("serviceId" in origin) {
+      return Effect.die(
+        new HyperdriveDevOriginUnsupported({
+          logicalId: connection.LogicalId,
+          origin: "vpc",
+          message:
+            `Hyperdrive instance ${connection.LogicalId} has an origin that is reached through a Workers VPC Service. This is not supported in development mode. ` +
+            "Set the `dev` property to an origin reachable from your machine.",
+        }),
+      );
+    }
+    return Effect.succeed<Required<DevOrigin>>({
+      scheme: origin.scheme,
+      host: origin.host,
+      port: origin.port ?? defaultPort(origin.scheme),
+      user: origin.user,
+      database: origin.database,
+      password: origin.password,
+      sslmode: mtls?.sslmode ?? "require",
+    });
+  })(Output.all(connection.dev, connection.origin, connection.mtls));
   return Output.map(
     Output.all(connection.hyperdriveId, Output.asOutput(origin)),
     ([id, origin]) => ({