alchemy 0.57.2 → 0.59.0

package/src/cloudflare/hyperdrive.ts

@@ -1,6 +1,8 @@
+import { alchemy } from "../alchemy.ts";
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
-import type { Secret } from "../secret.ts";
+import { Scope } from "../scope.ts";
+import { Secret } from "../secret.ts";
 import { logger } from "../util/logger.ts";
 import { handleApiError } from "./api-error.ts";
 import { createCloudflareApi, type CloudflareApiOptions } from "./api.ts";
@@ -8,7 +10,7 @@ import { createCloudflareApi, type CloudflareApiOptions } from "./api.ts";
 /**
  * Origin configuration for a PostgreSQL or MySQL database connection
  */
-export interface HyperdriveOrigin {
+export interface HyperdrivePublicOrigin {
   /**
    * Database name
    */
@@ -23,7 +25,7 @@ export interface HyperdriveOrigin {
    * Database password
    * Use alchemy.secret() to securely store this value
    */
-  password: Secret;
+  password: string | Secret;
 
   /**
    * Database port
@@ -56,7 +58,7 @@ export interface HyperdriveOriginWithAccess {
    * Access client secret
    * Use alchemy.secret() to securely store this value
    */
-  access_client_secret: Secret;
+  access_client_secret: string | Secret;
 
   /**
    * Database host
@@ -118,6 +120,16 @@ export interface HyperdriveMtls {
   sslmode?: "verify-ca" | "verify-full";
 }
 
+export type HyperdriveOriginInput =
+  | string
+  | Secret
+  | HyperdrivePublicOrigin
+  | HyperdriveOriginWithAccess;
+
+export type HyperdriveOrigin =
+  | HyperdrivePublicOrigin
+  | HyperdriveOriginWithAccess;
+
 /**
  * Properties for creating or updating a Cloudflare Hyperdrive.
  */
@@ -130,7 +142,7 @@ export interface HyperdriveProps extends CloudflareApiOptions {
   /**
    * Database connection origin configuration
    */
-  origin: HyperdriveOrigin | HyperdriveOriginWithAccess;
+  origin: HyperdriveOriginInput;
 
   /**
    * Caching configuration
@@ -148,6 +160,14 @@ export interface HyperdriveProps extends CloudflareApiOptions {
    * @internal
    */
   hyperdriveId?: string;
+
+  dev?: {
+    /**
+     * The database connection origin configuration for local development
+     * @default origin
+     */
+    origin?: HyperdriveOriginInput;
+  };
 }
 
 /**
@@ -156,7 +176,7 @@ export interface HyperdriveProps extends CloudflareApiOptions {
  */
 export interface Hyperdrive
   extends Resource<"cloudflare::Hyperdrive">,
-    Omit<HyperdriveProps, "origin"> {
+    Omit<HyperdriveProps, "origin" | "dev"> {
   /**
    * The ID of the resource
    */
@@ -170,7 +190,18 @@ export interface Hyperdrive
   /**
    * Database connection origin configuration
    */
-  origin: HyperdriveOrigin | HyperdriveOriginWithAccess;
+  origin: HyperdrivePublicOrigin | HyperdriveOriginWithAccess;
+
+  /**
+   * Local development configuration
+   * @internal
+   */
+  dev: {
+    /**
+     * The connection string to use for local development
+     */
+    origin: Secret;
+  };
 
   /**
    * Resource type identifier for binding.
@@ -257,19 +288,66 @@ export interface Hyperdrive
  *   }
  * });
  */
-export const Hyperdrive = Resource(
+export async function Hyperdrive(
+  id: string,
+  props: HyperdriveProps,
+): Promise<Hyperdrive> {
+  const origin = normalizeHyperdriveOrigin(props.origin);
+  const dev = {
+    origin: toConnectionString(
+      normalizeHyperdriveOrigin(props.dev?.origin ?? origin),
+    ),
+    force: Scope.current.local,
+  };
+  return await _Hyperdrive(id, {
+    ...props,
+    origin,
+    dev,
+  });
+}
+
+/**
+ * Internal properties for creating or updating a Cloudflare Hyperdrive config.
+ * @internal
+ */
+interface InternalHyperdriveProps extends CloudflareApiOptions {
+  name: string;
+  hyperdriveId?: string;
+  origin: HyperdriveOrigin;
+  caching?: HyperdriveCaching;
+  mtls?: HyperdriveMtls;
+  dev: {
+    origin: Secret;
+    force?: boolean;
+  };
+}
+
+const _Hyperdrive = Resource(
   "cloudflare::Hyperdrive",
   async function (
     this: Context<Hyperdrive>,
     id: string,
-    props: HyperdriveProps,
+    props: InternalHyperdriveProps,
   ): Promise<Hyperdrive> {
+    const hyperdriveId = props.hyperdriveId || this.output?.hyperdriveId;
+
+    if (this.scope.local) {
+      return this({
+        id,
+        hyperdriveId: hyperdriveId || "",
+        name: props.name,
+        origin: props.origin,
+        caching: props.caching,
+        mtls: props.mtls,
+        dev: props.dev,
+        type: "hyperdrive",
+      });
+    }
     const api = await createCloudflareApi(props);
     const configsPath = `/accounts/${api.accountId}/hyperdrive/configs`;
 
     // For create operations, we don't have a hyperdriveId yet
     // For update/delete operations, we need to use the hyperdriveId from props or output
-    const hyperdriveId = props.hyperdriveId || this.output?.hyperdriveId;
     const configPath = hyperdriveId
       ? `${configsPath}/${hyperdriveId}`
       : `${configsPath}`;
@@ -353,9 +431,10 @@ export const Hyperdrive = Resource(
       id,
       hyperdriveId: apiResource.id, // Store the Cloudflare-assigned UUID
       name: apiResource.name,
-      origin: props.origin, // Keep the original origin with secrets
+      origin: props.origin,
       caching: apiResource.caching,
       mtls: apiResource.mtls,
+      dev: props.dev,
       type: "hyperdrive",
     });
   },
@@ -364,7 +443,7 @@ export const Hyperdrive = Resource(
 /**
  * Prepare the request body by unwrapping secret values
  */
-function prepareRequestBody(props: HyperdriveProps): any {
+function prepareRequestBody(props: InternalHyperdriveProps): any {
   const requestBody: any = { ...props };
 
   // Remove internal props
@@ -375,16 +454,93 @@ function prepareRequestBody(props: HyperdriveProps): any {
     // Regular origin with password
     requestBody.origin = {
       ...props.origin,
-      password: props.origin.password.unencrypted,
+      password: Secret.unwrap(props.origin.password),
       scheme: props.origin.scheme ?? "postgres",
     };
   } else if ("access_client_secret" in props.origin) {
     // Origin with access client secret
     requestBody.origin = {
       ...props.origin,
-      access_client_secret: props.origin.access_client_secret.unencrypted,
+      access_client_secret: Secret.unwrap(props.origin.access_client_secret),
     };
   }
 
   return requestBody;
 }
+
+/**
+ * Converts a HyperdriveOriginInput to a HyperdriveOrigin.
+ * This includes:
+ * - parsing the origin from a string
+ * - ensuring the scheme is "postgres" or "mysql"
+ * - normalizing the port to a number with default values
+ * - wrapping secrets in a Secret object
+ * @internal - Exported for testing
+ */
+export const normalizeHyperdriveOrigin = (
+  input: HyperdriveOriginInput,
+): Required<HyperdrivePublicOrigin> | Required<HyperdriveOriginWithAccess> => {
+  const origin = Secret.unwrap(input);
+  if (typeof origin === "string") {
+    const url = new URL(origin);
+    const scheme = normalizeScheme(url.protocol.slice(0, -1));
+    return {
+      scheme,
+      user: url.username,
+      password: alchemy.secret(url.password),
+      host: url.hostname,
+      port: normalizePort(scheme, url.port),
+      database: url.pathname.slice(1),
+    };
+  }
+  const scheme = normalizeScheme(origin.scheme);
+  return {
+    ...origin,
+    ...("password" in origin && {
+      password: Secret.wrap(origin.password),
+    }),
+    ...("access_client_secret" in origin && {
+      access_client_secret: Secret.wrap(origin.access_client_secret),
+    }),
+    scheme,
+    port: normalizePort(scheme, origin.port),
+  };
+};
+
+const normalizeScheme = (scheme: string | undefined) => {
+  if (!scheme || scheme === "postgres" || scheme === "postgresql") {
+    return "postgres";
+  }
+  if (scheme === "mysql" || scheme === "mysql2") {
+    return "mysql";
+  }
+  throw new Error(
+    `Unsupported database connection scheme "${scheme}" for Hyperdrive (expected "postgres" or "mysql")`,
+  );
+};
+
+const normalizePort = (
+  scheme: "postgres" | "mysql",
+  port: string | number | undefined,
+) => {
+  if (typeof port === "number") {
+    return port;
+  }
+  if (port) {
+    return Number.parseInt(port);
+  }
+  return scheme === "postgres" ? 5432 : 3306;
+};
+
+const toConnectionString = (
+  origin:
+    | Required<HyperdrivePublicOrigin>
+    | Required<HyperdriveOriginWithAccess>,
+) => {
+  const password = Secret.unwrap(
+    "password" in origin ? origin.password : origin.access_client_secret,
+  );
+  return new Secret(
+    `${origin.scheme}://${origin.user}:${password}@${origin.host}:${origin.port}/${origin.database}`,
+  );
+};

package/src/cloudflare/index.ts

@@ -50,6 +50,7 @@ export * from "./secrets-store.ts";
 export * from "./state.ts";
 export * from "./sveltekit/sveltekit.ts";
 export * from "./tanstack-start/tanstack-start.ts";
+export * from "./tunnel.ts";
 export * from "./vectorize-index.ts";
 export * from "./vectorize-metadata-index.ts";
 export * from "./version-metadata.ts";

package/src/cloudflare/kv-namespace.ts

@@ -1,13 +1,18 @@
 import type { Context } from "../context.ts";
 import { Resource, ResourceKind } from "../resource.ts";
-import { logger } from "../util/logger.ts";
+import { Scope } from "../scope.ts";
 import { withExponentialBackoff } from "../util/retry.ts";
-import { handleApiError } from "./api-error.ts";
+import { CloudflareApiError, handleApiError } from "./api-error.ts";
+import {
+  extractCloudflareResult,
+  type CloudflareApiErrorPayload,
+} from "./api-response.ts";
 import {
   createCloudflareApi,
   type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.ts";
+import { deleteMiniflareBinding } from "./miniflare/delete.ts";
 
 /**
  * Properties for creating or updating a KV Namespace
@@ -49,6 +54,12 @@ export interface KVNamespaceProps extends CloudflareApiOptions {
      * @default false
      */
     remote?: boolean;
+
+    /**
+     * Whether to force the KV namespace to be created or updated
+     * @default false
+     */
+    force?: boolean;
   };
 }
 
@@ -91,7 +102,7 @@ export function isKVNamespace(resource: Resource): resource is KVNamespace {
  */
 export interface KVNamespace
   extends Resource<"cloudflare::KVNamespace">,
-    Omit<KVNamespaceProps, "delete"> {
+    Omit<KVNamespaceProps, "delete" | "dev"> {
   type: "kv_namespace";
   /**
    * The ID of the namespace
@@ -107,6 +118,22 @@ export interface KVNamespace
    * Time at which the namespace was last modified
    */
   modifiedAt: number;
+
+  /**
+   * Development mode properties
+   * @internal
+   */
+  dev: {
+    /**
+     * The ID of the KV namespace in development mode
+     */
+    id: string;
+
+    /**
+     * Whether the KV namespace is running remotely
+     */
+    remote: boolean;
+  };
 }
 
 /**
@@ -163,84 +190,76 @@ export interface KVNamespace
  *   delete: false
  * });
  */
-export const KVNamespace = Resource(
+export async function KVNamespace(
+  id: string,
+  props: KVNamespaceProps = {},
+): Promise<KVNamespace> {
+  return await _KVNamespace(id, {
+    ...props,
+    dev: {
+      ...(props.dev ?? {}),
+      force: Scope.current.local,
+    },
+  });
+}
+
+const _KVNamespace = Resource(
   "cloudflare::KVNamespace",
   async function (
     this: Context<KVNamespace>,
     id: string,
     props: KVNamespaceProps,
   ): Promise<KVNamespace> {
-    // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi(props);
-
     const title = props.title ?? id;
+    const local = this.scope.local && !props.dev?.remote;
+    const dev = {
+      id: this.output?.dev?.id ?? this.output?.namespaceId ?? id,
+      remote: props.dev?.remote ?? false,
+    };
+
+    if (local) {
+      return this({
+        type: "kv_namespace",
+        namespaceId: this.output?.namespaceId ?? "",
+        title,
+        values: props.values,
+        dev,
+        createdAt: this.output?.createdAt ?? Date.now(),
+        modifiedAt: Date.now(),
+      });
+    }
+
+    const api = await createCloudflareApi(props);
 
     if (this.phase === "delete") {
-      // For delete operations, we need to check if the namespace ID exists in the output
-      const namespaceId = this.output?.namespaceId;
-      if (namespaceId && props.delete !== false) {
-        await deleteKVNamespace(api, namespaceId);
+      if (this.output.dev?.id) {
+        await deleteMiniflareBinding("kv", this.output.dev.id);
+      }
+      if (this.output.namespaceId && props.delete !== false) {
+        await deleteKVNamespace(api, this.output.namespaceId);
       }
-
-      // Return minimal output for deleted state
       return this.destroy();
     }
-    // For create or update operations
-    // If this.phase is "update", we expect this.output to exist
-    let namespaceId =
-      this.phase === "update" ? this.output?.namespaceId || "" : "";
-    let createdAt =
-      this.phase === "update"
-        ? this.output?.createdAt || Date.now()
-        : Date.now();
-
-    if (this.phase === "update" && namespaceId) {
-      // Can't update a KV namespace title directly, just work with existing ID
-    } else {
-      try {
-        // Try to create the KV namespace
-        const { id } = await createKVNamespace(api, {
-          ...props,
-          title,
-        });
-        createdAt = Date.now();
-        namespaceId = id;
-      } catch (error) {
-        // Check if this is a "namespace already exists" error and adopt is enabled
-        if (
-          props.adopt &&
-          error instanceof Error &&
-          error.message.includes("already exists")
-        ) {
-          logger.log(`Namespace '${title}' already exists, adopting it`);
-          // Find the existing namespace by title
-          const existingNamespace = await findKVNamespaceByTitle(api, title);
-
-          if (!existingNamespace) {
-            throw new Error(
-              `Failed to find existing namespace '${title}' for adoption`,
-            );
-          }
 
-          // Use the existing namespace ID
-          namespaceId = existingNamespace.id;
-          createdAt = existingNamespace.createdAt || Date.now();
-        } else {
-          // Re-throw the error if adopt is false or it's not a "namespace already exists" error
-          throw error;
-        }
-      }
+    let result: { namespaceId: string; createdAt: number };
+    if (this.phase === "create" || !this.output.namespaceId) {
+      result = await createKVNamespace(api, {
+        ...props,
+        title,
+      });
+    } else {
+      result = this.output;
     }
 
-    await insertKVRecords(api, namespaceId, props);
+    await insertKVRecords(api, result.namespaceId, props);
 
     return this({
       type: "kv_namespace",
-      namespaceId,
-      title: props.title,
+      namespaceId: result.namespaceId,
+      title,
       values: props.values,
-      dev: props.dev,
-      createdAt: createdAt,
+      dev,
+      createdAt: result.createdAt,
       modifiedAt: Date.now(),
     });
   },
@@ -251,19 +270,44 @@ export async function createKVNamespace(
   props: KVNamespaceProps & {
     title: string;
   },
-): Promise<{ id: string }> {
-  const createResponse = await api.post(
-    `/accounts/${api.accountId}/storage/kv/namespaces`,
-    {
-      title: props.title,
-    },
-  );
+): Promise<{ namespaceId: string; createdAt: number }> {
+  try {
+    const { id } = await extractCloudflareResult<{
+      id: string;
+      title: string;
+      beta?: boolean;
+      supports_url_encoding?: boolean;
+    }>(
+      `create kv namespace "${props.title}"`,
+      api.post(`/accounts/${api.accountId}/storage/kv/namespaces`, {
+        title: props.title,
+      }),
+    );
+    return { namespaceId: id, createdAt: Date.now() };
+  } catch (error) {
+    if (
+      error instanceof CloudflareApiError &&
+      (error.errorData as CloudflareApiErrorPayload[]).some(
+        (e) => e.code === 10014,
+      ) &&
+      props.adopt
+    ) {
+      const existingNamespace = await findKVNamespaceByTitle(api, props.title);
+
+      if (!existingNamespace) {
+        throw new Error(
+          `Failed to find existing namespace '${props.title}' for adoption`,
+        );
+      }
 
-  if (!createResponse.ok) {
-    await handleApiError(createResponse, "create", "kv_namespace", props.title);
+      return {
+        namespaceId: existingNamespace.id,
+        createdAt: existingNamespace.createdAt ?? Date.now(),
+      };
+    } else {
+      throw error;
+    }
   }
-
-  return { id: ((await createResponse.json()) as any).result.id };
 }
 
 export async function deleteKVNamespace(

package/src/cloudflare/miniflare/build-worker-options.ts

@@ -1,6 +1,7 @@
 import * as miniflare from "miniflare";
 import { assertNever } from "../../util/assert-never.ts";
 import type { HTTPServer } from "../../util/http.ts";
+import type { CloudflareApi } from "../api.ts";
 import {
   Self,
   type Binding,
@@ -14,6 +15,7 @@ import type { AssetsConfig } from "../worker.ts";
 import { createRemoteProxyWorker } from "./remote-binding-proxy.ts";
 
 export interface MiniflareWorkerInput {
+  api: CloudflareApi;
   id: string;
   name: string;
   compatibilityDate: string | undefined;
@@ -143,7 +145,7 @@ export const buildWorkerOptions = async (
             raw: true,
           });
         } else {
-          (options.d1Databases ??= {})[key] = binding.id;
+          (options.d1Databases ??= {})[key] = binding.dev.id;
         }
         break;
       }
@@ -165,7 +167,8 @@ export const buildWorkerOptions = async (
         break;
       }
       case "hyperdrive": {
-        throw new Error("Hyperdrive bindings are not supported in local mode");
+        (options.hyperdrives ??= {})[key] = binding.dev.origin.unencrypted;
+        break;
       }
       case "images": {
         if (isRemoteBinding(binding)) {
@@ -182,17 +185,17 @@ export const buildWorkerOptions = async (
         break;
       }
       case "kv_namespace": {
-        const namespaceId =
-          "namespaceId" in binding ? binding.namespaceId : binding.id;
         if (isRemoteBinding(binding)) {
           remoteBindings.push({
             type: "kv_namespace",
             name: key,
-            namespace_id: namespaceId,
+            namespace_id:
+              "namespaceId" in binding ? binding.namespaceId : binding.id,
             raw: true,
           });
         } else {
-          (options.kvNamespaces ??= {})[key] = namespaceId;
+          (options.kvNamespaces ??= {})[key] =
+            "dev" in binding ? binding.dev.id : binding.id;
         }
         break;
       }
@@ -217,7 +220,7 @@ export const buildWorkerOptions = async (
         break;
       }
       case "pipeline": {
-        (options.pipelines ??= {})[key] = binding.id;
+        (options.pipelines ??= {})[key] = binding.name;
         break;
       }
       case "ratelimit": {
@@ -249,7 +252,7 @@ export const buildWorkerOptions = async (
             raw: true,
           });
         } else {
-          (options.r2Buckets ??= {})[key] = binding.name;
+          (options.r2Buckets ??= {})[key] = binding.dev.id;
         }
         break;
       }
@@ -329,6 +332,7 @@ export const buildWorkerOptions = async (
   }
   if (remoteBindings.length > 0) {
     const remoteProxy = await createRemoteProxyWorker({
+      api: input.api,
       name: input.name,
       bindings: remoteBindings,
     });