@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 592 lines 19.6 KB
Raw
1 import * as hyperdrive from "@distilled.cloud/cloudflare/hyperdrive";
2 import { deepEqual, isResolved } from "alchemy/Diff";
3 import * as ProviderLayer from "alchemy/Local/ProviderLayer";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { isResourceOfType, Resource } from "alchemy/Resource";
7 import * as Effect from "effect/Effect";
8 import * as Option from "effect/Option";
9 import * as Redacted from "effect/Redacted";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
13 import { localAccountId } from "../LocalAccount.ts";
14 import { generateLocalId } from "../LocalRuntime.ts";
15 import type { Providers } from "../Providers.ts";
16
17 export type Scheme = "postgres" | "postgresql" | "mysql";
18
19 /**
20 * Origin configuration for a public PostgreSQL or MySQL database.
21 */
22 export type PublicOrigin = {
23 scheme: Scheme;
24 host: string;
25 port?: number;
26 database: string;
27 user: string;
28 /**
29 * Database password.
30 */
31 password: Redacted.Redacted<string>;
32 };
33
34 /**
35 * Origin configuration for a database fronted by Cloudflare Access.
36 */
37 export type AccessOrigin = {
38 scheme: Scheme;
39 host: string;
40 database: string;
41 user: string;
42 password: Redacted.Redacted<string>;
43 accessClientId: Redacted.Redacted<string>;
44 accessClientSecret: Redacted.Redacted<string>;
45 };
46
47 /**
48 * Origin configuration for a private database reached through Workers VPC.
49 *
50 * Hyperdrive egresses through a TCP VPC Service
51 * ({@link https://developers.cloudflare.com/workers-vpc/ Workers VPC}), which
52 * routes over a Cloudflare Tunnel into the private network — e.g. an Aurora
53 * or RDS instance inside an AWS VPC. The host and port live on the VPC
54 * Service, so they are not repeated here. mTLS cannot be combined with a VPC
55 * origin; TLS is managed on the VPC Service.
56 */
57 export type VpcOrigin = {
58 scheme: Scheme;
59 /**
60 * Identifier of the TCP VPC Service to connect through, e.g.
61 * `service.serviceId` of a `Cloudflare.Connectivity.DirectoryService`
62 * with `type: "tcp"`.
63 */
64 serviceId: string;
65 database: string;
66 user: string;
67 /**
68 * Database password.
69 */
70 password: Redacted.Redacted<string>;
71 };
72
73 export type Origin = PublicOrigin | AccessOrigin | VpcOrigin;
74
75 export type Caching = {
76 /**
77 * Whether caching is disabled.
78 * @default false
79 */
80 disabled?: boolean;
81 /**
82 * Maximum duration items should persist in the cache, in seconds.
83 * @default 60
84 */
85 maxAge?: number;
86 /**
87 * Number of seconds the cache may serve a stale response while revalidating.
88 * @default 15
89 */
90 staleWhileRevalidate?: number;
91 };
92
93 export type Mtls = {
94 caCertificateId?: string;
95 mtlsCertificateId?: string;
96 /**
97 * @default "require"
98 */
99 sslmode?: "require" | "verify-ca" | "verify-full";
100 };
101
102 export type DevOrigin = PublicOrigin & {
103 /**
104 * @default "prefer"
105 */
106 sslmode?: "disable" | "prefer" | "require" | "verify-ca" | "verify-full";
107 };
108
109 export type Props = {
110 /**
111 * Name of the Hyperdrive configuration. If omitted, a unique name will be
112 * generated.
113 * @default ${app}-${stage}-${id}
114 */
115 name?: string;
116 /**
117 * Database connection origin. Hyperdrive supports public Postgres/MySQL
118 * databases, databases fronted by Cloudflare Access, and private databases
119 * reached through a Workers VPC Service.
120 */
121 origin: Origin;
122 /**
123 * Caching configuration.
124 */
125 caching?: Caching;
126 /**
127 * mTLS configuration.
128 */
129 mtls?: Mtls;
130 /**
131 * The (soft) maximum number of connections Hyperdrive is allowed to make to
132 * the origin database.
133 */
134 originConnectionLimit?: number;
135 /**
136 * Local development overrides. When the stack runs in dev mode
137 * connect to a locally running database
138 */
139 dev?: DevOrigin;
140 };
141
142 export type Connection = Resource<
143 "Cloudflare.Hyperdrive",
144 Props,
145 {
146 hyperdriveId: string;
147 name: string;
148 accountId: string;
149 origin: Origin;
150 mtls: Mtls;
151 dev: DevOrigin | undefined;
152 },
153 never,
154 Providers
155 >;
156
157 /**
158 * A Cloudflare Hyperdrive configuration.
159 *
160 * Hyperdrive accelerates and pools connections to existing PostgreSQL or
161 * MySQL databases, exposing them to Workers via a binding. Create a config
162 * as a resource, then bind it to a Worker to obtain a connection string.
163 * ### Creating a Hyperdrive
164 * **Example:** Public Postgres origin
165 * ```typescript
166 * const hd = yield* Cloudflare.Hyperdrive.Connection("my-pg", {
167 * origin: {
168 * scheme: "postgres",
169 * host: "db.example.com",
170 * port: 5432,
171 * database: "app",
172 * user: "app",
173 * password: yield* Config.Redacted("DB_PASSWORD"),
174 * },
175 * });
176 * ```
177 *
178 * ### Connecting to a private database
179 * A database inside a private network (e.g. Aurora or RDS in an AWS VPC) is
180 * reached through Workers VPC: run `cloudflared` inside the network with the
181 * Tunnel's token, expose the database as a TCP VPC Service, and point
182 * Hyperdrive at the service.
183 *
184 * **Example:** Aurora in an AWS VPC through Workers VPC
185 * ```typescript
186 * const tunnel = yield* Cloudflare.Tunnel.Tunnel("VpcTunnel");
187 * const service = yield* Cloudflare.Connectivity.DirectoryService("Aurora", {
188 * type: "tcp",
189 * tcpPort: 5432,
190 * appProtocol: "postgresql",
191 * host: {
192 * hostname: "my-cluster.cluster-abc123.us-east-1.rds.amazonaws.com",
193 * resolverNetwork: { tunnelId: tunnel.tunnelId },
194 * },
195 * });
196 * const hd = yield* Cloudflare.Hyperdrive.Connection("Aurora", {
197 * origin: {
198 * scheme: "postgres",
199 * serviceId: service.serviceId,
200 * database: "app",
201 * user: "app",
202 * password: yield* Config.Redacted("DB_PASSWORD"),
203 * },
204 * });
205 * ```
206 *
207 * ### Binding to a Worker
208 * **Example:** Using Hyperdrive inside a Worker
209 * ```typescript
210 * const hd = yield* Cloudflare.Hyperdrive.Connect(MyConnection);
211 * const url = yield* hd.connectionString;
212 * ```
213 *
214 * @resource
215 * @product Hyperdrive
216 * @category Storage & Databases
217 */
218 export const Connection = Resource<Connection>("Cloudflare.Hyperdrive");
219
220 export const isHyperdriveConnection = (value: unknown): value is Connection =>
221 isResourceOfType(value, "Cloudflare.Hyperdrive");
222
223 export const ProviderLive = () =>
224 Provider.succeed(Connection, {
225 // `hyperdriveId` is stable within live mode: `updateConfig` never changes
226 // it, and the dev→deploy transition (which DOES mint a new id) is a
227 // mode-switch the engine plans as a REPLACEMENT, so updates can rely on it.
228 stables: ["hyperdriveId", "accountId"],
229 list: Effect.fn(function* () {
230 const { accountId } = yield* yield* CloudflareEnvironment;
231 return yield* hyperdrive.listConfigs.pages({ accountId }).pipe(
232 Stream.runCollect,
233 Effect.map((chunk) =>
234 Array.from(chunk).flatMap((page) =>
235 (page.result ?? []).map((c) => ({
236 hyperdriveId: c.id,
237 name: c.name,
238 accountId,
239 // The connection-string password is write-only and never
240 // returned by the API, so it is absent here (matching `read`,
241 // which sources it from `olds`).
242 origin: { ...c.origin } as Origin,
243 mtls: {
244 caCertificateId: c.mtls?.caCertificateId ?? undefined,
245 mtlsCertificateId: c.mtls?.mtlsCertificateId ?? undefined,
246 sslmode: c.mtls?.sslmode ?? undefined,
247 } as Mtls,
248 dev: undefined,
249 })),
250 ),
251 ),
252 );
253 }),
254 diff: Effect.fn(function* ({ id, olds, news, output }) {
255 const { accountId } = yield* yield* CloudflareEnvironment;
256 if ((output?.accountId ?? accountId) !== accountId) {
257 return { action: "replace" } as const;
258 }
259 // Each replace-forcing field is checked on its own: an unresolved
260 // origin (e.g. another resource's output) must not hide a rename.
261 const newName = "name" in news ? news.name : undefined;
262 if (isResolved(newName)) {
263 const oldName = output?.name ?? (yield* createConfigName(id, olds.name));
264 // Auto-generated names are engine-owned: the deployed name stays
265 // authoritative even if the generator would name this id differently
266 // today. Only an explicit user-provided name can force a replace.
267 const name = newName ?? oldName;
268 if (oldName !== name) {
269 return { action: "replace" } as const;
270 }
271 }
272 // `updateConfig` preserves omitted mTLS settings and accepts no null
273 // certificate id, so a pinned certificate can only be dropped by
274 // creating a fresh config. An explicit name is unique per account, so
275 // the old config must go first.
276 const oldMtls = output?.mtls ?? olds?.mtls;
277 const mtls = "mtls" in news ? news.mtls : undefined;
278 if (isResolved(mtls)) {
279 const dropped = (key: "caCertificateId" | "mtlsCertificateId") =>
280 oldMtls?.[key] !== undefined && mtls?.[key] === undefined;
281 if (dropped("caCertificateId") || dropped("mtlsCertificateId")) {
282 return { action: "replace", deleteFirst: newName !== undefined } as const;
283 }
284 }
285 }),
286 read: Effect.fn(function* ({ id, output, olds }) {
287 const { accountId } = yield* yield* CloudflareEnvironment;
288 if (output?.hyperdriveId) {
289 return yield* hyperdrive
290 .getConfig({
291 accountId: output.accountId,
292 hyperdriveId: output.hyperdriveId,
293 })
294 .pipe(
295 Effect.map((c) => ({
296 hyperdriveId: c.id,
297 name: c.name,
298 accountId: output.accountId,
299 origin: {
300 ...c.origin,
301 password: olds?.origin?.password,
302 } as Origin,
303 mtls: {
304 caCertificateId: c.mtls?.caCertificateId ?? undefined,
305 mtlsCertificateId: c.mtls?.mtlsCertificateId ?? undefined,
306 sslmode: c.mtls?.sslmode ?? undefined,
307 } as Mtls,
308 dev: output?.dev,
309 })),
310 Effect.catchTag("HyperdriveConfigNotFound", () => Effect.undefined),
311 );
312 }
313 const name = yield* createConfigName(id, olds?.name);
314 const match = yield* findByName(name);
315 if (match) {
316 return {
317 hyperdriveId: match.id,
318 name: match.name,
319 accountId,
320 origin: {
321 ...match.origin,
322 password: olds?.origin?.password,
323 } as Origin,
324 mtls: {
325 caCertificateId: match.mtls?.caCertificateId ?? undefined,
326 mtlsCertificateId: match.mtls?.mtlsCertificateId ?? undefined,
327 sslmode: match.mtls?.sslmode ?? undefined,
328 } as Mtls,
329 dev: output?.dev,
330 };
331 }
332 return undefined;
333 }),
334 reconcile: Effect.fn(function* ({ id, news, olds, output }) {
335 const { accountId } = yield* yield* CloudflareEnvironment;
336 const name = output?.name ?? (yield* createConfigName(id, news.name));
337
338 const requestBody = toRequestBody(news);
339
340 // Observe the live config. `output` is only a cache of the id: a
341 // config deleted out of band falls through to create.
342 const observed = output?.hyperdriveId
343 ? yield* hyperdrive
344 .getConfig({ accountId: output.accountId, hyperdriveId: output.hyperdriveId })
345 .pipe(Effect.catchTag("HyperdriveConfigNotFound", () => Effect.undefined))
346 : undefined;
347
348 // Every `updateConfig` opens a new origin pool and leaves the old one
349 // connected until its idle timeout, so skip it unless something would
350 // change. The API never returns the password or Access client secret:
351 // readable fields are compared against the live config (so drift is
352 // corrected), and the write-only secrets against the last applied
353 // request in `olds`. Without `olds` (adoption) the secrets are unknown,
354 // so the config is updated.
355 if (
356 observed &&
357 olds !== undefined &&
358 deepEqual(requestBody, toRequestBody(olds)) &&
359 isInSync(observed, news.name ?? name, requestBody)
360 ) {
361 return {
362 hyperdriveId: observed.id,
363 name: observed.name,
364 accountId: output?.accountId ?? accountId,
365 origin: news.origin,
366 mtls: news.mtls ?? {},
367 dev: news.dev,
368 };
369 }
370
371 // Ensure + sync. With a live config we update it in place; otherwise
372 // we createConfig and fall back to "find by name then update" if
373 // Cloudflare reports the name is already in use (race or a cold-start
374 // adoption).
375 const synced = yield* (
376 observed
377 ? hyperdrive.updateConfig({
378 accountId: output?.accountId ?? accountId,
379 hyperdriveId: observed.id,
380 name: news.name ?? observed.name,
381 ...requestBody,
382 })
383 : hyperdrive.createConfig({ accountId, name, ...requestBody }).pipe(
384 Effect.catchTag("InvalidHyperdriveConfig", (originalError) =>
385 Effect.gen(function* () {
386 const match = yield* findByName(name);
387 if (!match) {
388 return yield* originalError;
389 }
390 return yield* hyperdrive.updateConfig({
391 accountId,
392 hyperdriveId: match.id,
393 name,
394 ...requestBody,
395 });
396 }),
397 ),
398 )
399 ).pipe(
400 // Cloudflare connects to the origin on create/update. A just-
401 // provisioned database, or a just-created Workers VPC Service that
402 // has not propagated yet (`destination_not_found`), is briefly
403 // unreachable.
404 Effect.retry({
405 while: (error) => error._tag === "HyperdriveOriginUnavailable",
406 schedule: Schedule.spaced("3 seconds"),
407 times: 20,
408 }),
409 );
410
411 return {
412 hyperdriveId: synced.id,
413 name: synced.name,
414 accountId: output?.accountId ?? accountId,
415 origin: news.origin,
416 mtls: news.mtls ?? {},
417 dev: news.dev,
418 };
419 }),
420 delete: Effect.fn(function* ({ output }) {
421 yield* hyperdrive
422 .deleteConfig({
423 accountId: output.accountId,
424 hyperdriveId: output.hyperdriveId,
425 })
426 .pipe(Effect.catchTag("HyperdriveConfigNotFound", () => Effect.void));
427 }),
428 });
429
430 /**
431 * Local (dev) provider — the config is purely virtual: reconcile mints a
432 * `dev:` id and echoes the desired props into attributes, with no cloud API
433 * calls. The actual local behavior lives in the Worker binding: the local
434 * runtime's Hyperdrive plugin is an origin passthrough driven by the
435 * `hyperdrives` record `ConnectBinding` lowers (the `dev` prop when set,
436 * otherwise the real `origin`).
437 */
438 export const ProviderLocal = () =>
439 Provider.succeed(Connection, {
440 stables: ["accountId"],
441 diff: Effect.fn(function* ({ news, output }) {
442 const accountId = yield* localAccountId;
443 if (!output?.hyperdriveId) return { action: "update" } as const;
444 if (!isResolved(news)) return undefined;
445 if (output.accountId !== accountId) {
446 return { action: "replace" } as const;
447 }
448 // Fall through to the engine's default prop diff (name/origin/dev
449 // changes update in place; reconcile re-echoes them).
450 }),
451 read: Effect.fn(function* ({ output }) {
452 // Purely virtual — the persisted state row is the source of truth.
453 return output ?? undefined;
454 }),
455 reconcile: Effect.fn(function* ({ id, news, output }) {
456 const accountId = yield* localAccountId;
457 return {
458 hyperdriveId: output?.hyperdriveId ?? generateLocalId(),
459 name: yield* createConfigName(id, news.name),
460 accountId: output?.accountId ?? accountId,
461 origin: news.origin,
462 mtls: news.mtls ?? {},
463 dev: news.dev,
464 };
465 }),
466 delete: Effect.fn(function* () {
467 // Purely virtual — dropping the state row is enough.
468 }),
469 });
470
471 export const ConnectionProvider = () =>
472 ProviderLayer.dual(Connection, {
473 local: () => ProviderLocal(),
474 live: () => ProviderLive(),
475 });
476
477 const createConfigName = (id: string, name: string | undefined) =>
478 Effect.gen(function* () {
479 if (name) return name;
480 return yield* createPhysicalName({ id, lowercase: true });
481 });
482
483 const findByName = (name: string) =>
484 Effect.gen(function* () {
485 const { accountId } = yield* yield* CloudflareEnvironment;
486 return yield* hyperdrive.listConfigs.items({ accountId }).pipe(
487 Stream.filter((c) => c.name === name),
488 Stream.runHead,
489 Effect.map(Option.getOrUndefined),
490 );
491 });
492
493 export const defaultPort = (scheme: Scheme): number => (scheme === "mysql" ? 3306 : 5432);
494
495 const unwrap = (v: string | Redacted.Redacted<string>): string =>
496 Redacted.isRedacted(v) ? Redacted.value(v) : v;
497
498 const toRequestBody = (props: Props) => ({
499 origin: toRequestOrigin(props.origin),
500 caching: props.caching,
501 mtls: props.mtls,
502 originConnectionLimit: props.originConnectionLimit,
503 });
504
505 const SECRET_ORIGIN_KEYS = new Set(["password", "accessClientSecret"]);
506 const DEFAULT_MAX_AGE = 60;
507 const DEFAULT_STALE_WHILE_REVALIDATE = 15;
508
509 /**
510 * Whether the live config already matches every readable field of the
511 * desired request. Secrets are write-only and are not compared here.
512 */
513 const isInSync = (
514 observed: hyperdrive.GetConfigResponse,
515 name: string,
516 desired: ReturnType<typeof toRequestBody>,
517 ): boolean => {
518 if (observed.name !== name) return false;
519
520 const live: Readonly<Record<string, unknown>> = { ...observed.origin };
521 if (
522 Object.entries(desired.origin).some(
523 ([key, value]) => !SECRET_ORIGIN_KEYS.has(key) && live[key] !== value,
524 )
525 ) {
526 return false;
527 }
528
529 const caching = desired.caching ?? {};
530 if ((caching.disabled ?? false) !== observed.caching.disabled) return false;
531 if (
532 !observed.caching.disabled &&
533 ((caching.maxAge ?? DEFAULT_MAX_AGE) !== (observed.caching.maxAge ?? DEFAULT_MAX_AGE) ||
534 (caching.staleWhileRevalidate ?? DEFAULT_STALE_WHILE_REVALIDATE) !==
535 (observed.caching.staleWhileRevalidate ?? DEFAULT_STALE_WHILE_REVALIDATE))
536 ) {
537 return false;
538 }
539
540 // `updateConfig` preserves omitted mTLS settings, so only the specified
541 // ones are compared.
542 const mtls = desired.mtls ?? {};
543 if (
544 (["caCertificateId", "mtlsCertificateId", "sslmode"] as const).some(
545 (key) => mtls[key] !== undefined && mtls[key] !== (observed.mtls?.[key] ?? undefined),
546 )
547 ) {
548 return false;
549 }
550
551 return (
552 desired.originConnectionLimit === undefined ||
553 desired.originConnectionLimit === (observed.originConnectionLimit ?? undefined)
554 );
555 };
556
557 /**
558 * Build the request body shape that the distilled `createConfig`/`updateConfig`
559 * methods accept. Secrets are unwrapped here because the distilled TS types
560 * declare `password`/`access_client_secret` as plain strings even though the
561 * runtime schema also accepts `Redacted<string>`.
562 */
563 const toRequestOrigin = (origin: Origin) => {
564 if ("serviceId" in origin) {
565 return {
566 database: origin.database,
567 password: unwrap(origin.password),
568 scheme: origin.scheme,
569 serviceId: origin.serviceId,
570 user: origin.user,
571 };
572 }
573 if ("accessClientId" in origin) {
574 return {
575 accessClientId: unwrap(origin.accessClientId),
576 accessClientSecret: unwrap(origin.accessClientSecret),
577 database: origin.database,
578 host: origin.host,
579 password: unwrap(origin.password),
580 scheme: origin.scheme,
581 user: origin.user,
582 };
583 }
584 return {
585 database: origin.database,
586 host: origin.host,
587 password: unwrap(origin.password),
588 port: origin.port ?? defaultPort(origin.scheme),
589 scheme: origin.scheme,
590 user: origin.user,
591 };
592 };