convex 1.40.0 → 1.41.0

package/src/cli/lib/localDeployment/dashboard.ts

@@ -1,20 +1,21 @@
 import { Context } from "../../../bundler/context.js";
 import {
   dashboardOutDir,
-  loadDashboardConfig,
+  loadProjectDashboardConfig,
   loadUuidForAnonymousUser,
-  saveDashboardConfig,
+  saveProjectDashboardConfig,
 } from "./filePaths.js";
 import { choosePorts } from "./utils.js";
 import { startServer } from "./serve.js";
-import { listExistingAnonymousDeployments } from "./anonymous.js";
 import { localDeploymentUrl, selfHostedEventTag } from "./run.js";
 import serveHandler from "serve-handler";
-import { ensureDashboardDownloaded } from "./download.js";
+import {
+  ensureBackendBinaryDownloaded,
+  ensureDashboardDownloaded,
+} from "./download.js";
 import { bigBrainAPIMaybeThrows } from "../utils/utils.js";
 
 export const DEFAULT_LOCAL_DASHBOARD_PORT = 6790;
-export const DEFAULT_LOCAL_DASHBOARD_API_PORT = 6791;
 
 /**
  * This runs the `dashboard-self-hosted` app locally.
@@ -22,32 +23,59 @@ export const DEFAULT_LOCAL_DASHBOARD_API_PORT = 6791;
  * uses `dashboard.convex.dev`, and some of the code below is written
  * assuming this is only used for `anonymous`.
  */
-export async function handleDashboard(ctx: Context, version: string) {
+export async function handleDashboard(
+  ctx: Context,
+  deployment: { name: string; cloudPort: number; adminKey: string },
+  options: {
+    /** The backend version to use if the user overrides the default version with the --local-backend-version flag */
+    backendVersion: string | undefined;
+  },
+) {
+  // We call `ensureBackendBinaryDownloaded` here to get the version,
+  // but `handleAnonymousDeployment` has already downloaded it.
+  const { version } = await ensureBackendBinaryDownloaded(
+    ctx,
+    options.backendVersion === undefined
+      ? { kind: "latest" }
+      : { kind: "version", version: options.backendVersion },
+  );
   const anonymousId = loadUuidForAnonymousUser(ctx) ?? undefined;
-  const isRunning = await checkIfDashboardIsRunning(ctx);
-  if (isRunning) {
-    // It's possible this is running with a different version, but
-    // let's not worry about that for now.
-    return;
-  }
   await ensureDashboardDownloaded(ctx, version);
-  const [dashboardPort, apiPort] = await choosePorts(ctx, {
-    count: 2,
+  const [dashboardPort] = await choosePorts(ctx, {
+    count: 1,
     startPort: DEFAULT_LOCAL_DASHBOARD_PORT,
     requestedPorts: [null, null],
   });
-  await saveDashboardConfig(ctx, {
+  saveProjectDashboardConfig(ctx, deployment.name, {
     port: dashboardPort,
-    apiPort,
-    version,
   });
 
   let hasReportedSelfHostedEvent = false;
 
+  const serverOptions = { cors: false } as const;
   const { cleanupHandle } = await startServer(
     ctx,
     dashboardPort,
     async (request, response) => {
+      const pathname = new URL(
+        request.url ?? "/",
+        // We only want to extract the pathname so the base doesn’t matter
+        "http://localhost",
+      ).pathname;
+
+      if (pathname === "/api/current_deployment") {
+        serverOptions satisfies { cors: false };
+        response.setHeader("Content-Type", "application/json");
+        response.end(
+          JSON.stringify({
+            name: deployment.name,
+            url: localDeploymentUrl(deployment.cloudPort),
+            adminKey: deployment.adminKey,
+          }),
+        );
+        return;
+      }
+
       if (!hasReportedSelfHostedEvent) {
         hasReportedSelfHostedEvent = true;
         void reportSelfHostedEvent(ctx, {
@@ -60,9 +88,8 @@ export async function handleDashboard(ctx: Context, version: string) {
         public: dashboardOutDir(),
       });
     },
-    {},
+    serverOptions,
   );
-  await startServingListDeploymentsApi(ctx, apiPort);
   return {
     dashboardPort,
     cleanupHandle,
@@ -100,70 +127,11 @@ async function reportSelfHostedEvent(
   }
 }
 
-/**
- * This serves a really basic API that just returns a JSON blob with the deployments
- * and their credentials.
- * The locally running dashboard can hit this API.
- */
-async function startServingListDeploymentsApi(ctx: Context, port: number) {
-  await startServer(
-    ctx,
-    port,
-    async (request, response) => {
-      const deployments = await listExistingAnonymousDeployments(ctx);
-      const deploymentsJson = deployments.map((d) => ({
-        name: d.deploymentName,
-        url: localDeploymentUrl(d.config.ports.cloud),
-        adminKey: d.config.adminKey,
-      }));
-      response.setHeader("Content-Type", "application/json");
-      response.end(JSON.stringify({ deployments: deploymentsJson }));
-    },
-    {
-      cors: true,
-    },
-  );
-}
-
-export async function checkIfDashboardIsRunning(ctx: Context) {
-  const dashboardConfig = loadDashboardConfig(ctx);
-  if (dashboardConfig === null) {
-    return false;
-  }
-  // We're checking if the mini API server is running and has a response that
-  // looks like a list of deployments, since it's easier than checking the
-  // dashboard UI + won't trigger the event for the developer opening the dashboard.
-  let resp: Response;
-  try {
-    resp = await fetch(`http://127.0.0.1:${dashboardConfig.apiPort}`);
-  } catch {
-    return false;
-  }
-  if (!resp.ok) {
-    return false;
-  }
-  let data: { deployments: { name: string; url: string; adminKey: string }[] };
-  try {
-    data = await resp.json();
-  } catch {
-    return false;
-  }
-  return Array.isArray(data.deployments);
-}
-
 export function dashboardUrl(ctx: Context, deploymentName: string) {
-  const dashboardConfig = loadDashboardConfig(ctx);
+  const dashboardConfig = loadProjectDashboardConfig(ctx, deploymentName);
   if (dashboardConfig === null) {
     return null;
   }
 
-  const queryParams = new URLSearchParams();
-  if (dashboardConfig.apiPort !== DEFAULT_LOCAL_DASHBOARD_API_PORT) {
-    queryParams.set("a", dashboardConfig.apiPort.toString());
-  }
-  queryParams.set("d", deploymentName);
-  const queryString = queryParams.toString();
-  const url = new URL(`http://127.0.0.1:${dashboardConfig.port}`);
-  url.search = queryString;
-  return url.href;
+  return `http://127.0.0.1:${dashboardConfig.port}/`;
 }

package/src/cli/lib/localDeployment/download.ts

@@ -15,7 +15,8 @@ import {
   versionedBinaryDir,
   dashboardOutDir,
   resetDashboardDir,
-  loadDashboardConfig,
+  loadGlobalDashboardConfig,
+  saveGlobalDashboardConfig,
   executableName,
 } from "./filePaths.js";
 import child_process from "child_process";
@@ -79,11 +80,38 @@ async function _ensureBackendBinaryDownloaded(
   return { version, binaryPath };
 }
 
+let cachedLatestVersion: string | null = null;
+
+/**
+ * Finds the latest version of the Convex local backend through
+ * version.convex.dev, caching the resolved version for the lifetime of the
+ * process so repeated lookups hit the network at most once.
+ *
+ * Wraps {@link _findLatestVersionWithBinary}. Only successful (non-null)
+ * results are cached, so a failed `requireSuccess: false` lookup can be retried
+ * by a later call.
+ */
+export async function findLatestVersionWithBinary<
+  RequireSuccess extends boolean,
+>(
+  ctx: Context,
+  requireSuccess: RequireSuccess,
+): Promise<RequireSuccess extends true ? string : string | null> {
+  if (cachedLatestVersion !== null) {
+    return cachedLatestVersion;
+  }
+  const result = await _findLatestVersionWithBinary(ctx, requireSuccess);
+  if (result !== null) {
+    cachedLatestVersion = result;
+  }
+  return result;
+}
+
 /**
  * Finds the latest version of the Convex local backend
  * through version.convex.dev
  */
-export async function findLatestVersionWithBinary<
+export async function _findLatestVersionWithBinary<
   RequireSuccess extends boolean,
 >(
   ctx: Context,
@@ -298,12 +326,15 @@ async function downloadZipFile(
 }
 
 export async function ensureDashboardDownloaded(ctx: Context, version: string) {
-  const config = loadDashboardConfig(ctx);
+  const config = loadGlobalDashboardConfig(ctx);
   if (config !== null && config.version === version) {
     return;
   }
   await resetDashboardDir(ctx);
   await _ensureDashboardDownloaded(ctx, version);
+  // Record which version is now in `dashboardOutDir()`
+  // so we can skip the download next time.
+  saveGlobalDashboardConfig(ctx, { version });
 }
 async function _ensureDashboardDownloaded(ctx: Context, version: string) {
   const zipLocation = dashboardZip();

package/src/cli/lib/localDeployment/filePaths.ts

@@ -6,7 +6,7 @@
     0.0.2
       convex-local-backend[.exe]
   dashboard
-    config.json
+    config.json // `GlobalDashboardConfig`
     out
     // if present, output files from building the self-hosted dashboard which can
     // be served using `npx serve`
@@ -24,6 +24,10 @@ Legacy (home directory) - used for backward compatibility if data already exists
   - For "local" deployments: ~/.convex/convex-backend-state/local-{team}-{project}/
   - For "anonymous" deployments: ~/.convex/anonymous-convex-backend-state/{anonymous-deployment-name}/
 
+For anonymous deployments, the locally running dashboard's `{ port }`
+is stored as `dashboard.json` next to that deployment's `config.json` (see
+`ProjectDashboardConfig`), wherever the deployment lives.
+
 
 ~/.convex
   convex-backend-state
@@ -331,12 +335,19 @@ export function dashboardOutDir() {
   return path.join(dashboardDir(), "out");
 }
 
-export type DashboardConfig = {
-  port: number;
-  apiPort: number;
+/**
+ * Global dashboard config in ~/.cache/convex/dashboard/config.json.
+ */
+export type GlobalDashboardConfig = {
   version: string;
+
+  // Previous versions of the Convex CLI would also store
+  // fields here for ports. They are now in ProjectDashboardConfig.
 };
-export function loadDashboardConfig(ctx: Context) {
+
+export function loadGlobalDashboardConfig(
+  ctx: Context,
+): GlobalDashboardConfig | null {
   const configFile = path.join(dashboardDir(), "config.json");
   if (!ctx.fs.exists(configFile)) {
     return null;
@@ -350,7 +361,10 @@ export function loadDashboardConfig(ctx: Context) {
   }
 }
 
-export function saveDashboardConfig(ctx: Context, config: DashboardConfig) {
+export function saveGlobalDashboardConfig(
+  ctx: Context,
+  config: GlobalDashboardConfig,
+) {
   const configFile = path.join(dashboardDir(), "config.json");
   if (!ctx.fs.exists(dashboardDir())) {
     ctx.fs.mkdir(dashboardDir(), { recursive: true });
@@ -358,6 +372,52 @@ export function saveDashboardConfig(ctx: Context, config: DashboardConfig) {
   ctx.fs.writeUtf8File(configFile, JSON.stringify(config));
 }
 
+/**
+ * Project-scoped dashboard config (for anonymous dev) in
+ * project/.convex/local/default/dashboard.json
+ * (or legacyDeploymentStateDir/dashboard.json)
+ */
+export type ProjectDashboardConfig = {
+  port: number;
+};
+
+function dashboardConfigPath(ctx: Context, deploymentName: string) {
+  return path.join(
+    deploymentStateDir(ctx, "anonymous", deploymentName),
+    "dashboard.json",
+  );
+}
+
+export function loadProjectDashboardConfig(
+  ctx: Context,
+  deploymentName: string,
+): ProjectDashboardConfig | null {
+  const configFile = dashboardConfigPath(ctx, deploymentName);
+  if (!ctx.fs.exists(configFile)) {
+    return null;
+  }
+  const content = ctx.fs.readUtf8File(configFile);
+  try {
+    return JSON.parse(content);
+  } catch (e) {
+    logVerbose(`Failed to parse project dashboard config: ${e as any}`);
+    return null;
+  }
+}
+
+export function saveProjectDashboardConfig(
+  ctx: Context,
+  deploymentName: string,
+  config: ProjectDashboardConfig,
+) {
+  const configPath = dashboardConfigPath(ctx, deploymentName);
+  const directoryPath = path.dirname(configPath);
+  if (!ctx.fs.exists(directoryPath)) {
+    ctx.fs.mkdir(directoryPath, { recursive: true });
+  }
+  ctx.fs.writeUtf8File(configPath, JSON.stringify(config));
+}
+
 export function loadUuidForAnonymousUser(ctx: Context) {
   const configFile = path.join(
     rootDeploymentStateDir("anonymous"),

package/src/cli/lib/localDeployment/localDeployment.ts

@@ -19,38 +19,24 @@ import {
   loadProjectLocalConfig,
   legacyDeploymentStateDir,
   rootDeploymentStateDir,
-  saveDeploymentConfig,
 } from "./filePaths.js";
 import {
-  ensureBackendRunning,
   ensureBackendStopped,
   localDeploymentUrl,
-  runLocalBackend,
   withRunningBackend,
 } from "./run.js";
-import { handlePotentialUpgrade } from "./upgrade.js";
-import { OnDeploymentActivityFunc } from "../deployment.js";
-import { promptSearch } from "../utils/prompts.js";
+import { handlePotentialUpgradeAndStart } from "./upgrade.js";
 import { LocalDeploymentError, printLocalDeploymentOnError } from "./errors.js";
 import {
   chooseLocalBackendPorts,
   printLocalDeploymentWelcomeMessage,
-  isOffline,
-  LOCAL_BACKEND_INSTANCE_SECRET,
 } from "./utils.js";
 import { ensureBackendBinaryDownloaded } from "./download.js";
 import { defaultEnvBackend } from "../defaultEnv.js";
 import { deploymentEnvBackend, EnvVar } from "../env.js";
 import { getProjectDetails } from "../deploymentSelection.js";
-
-export type DeploymentDetails = {
-  deploymentName: string;
-  deploymentUrl: string;
-  adminKey: string;
-  reference: string | null;
-  isDefault: boolean;
-  onActivity: OnDeploymentActivityFunc;
-};
+import { DeploymentDetails } from "../deployment.js";
+import { LEGACY_LOCAL_BACKEND_INSTANCE_SECRET } from "./secrets.js";
 
 export async function handleLocalDeployment(
   ctx: Context,
@@ -65,10 +51,6 @@ export async function handleLocalDeployment(
     forceUpgrade: boolean;
   },
 ): Promise<DeploymentDetails> {
-  if (await isOffline()) {
-    return handleOffline(ctx, options);
-  }
-
   const existingDeploymentForProject = await getExistingDeployment(ctx, {
     projectSlug: options.projectSlug,
     teamSlug: options.teamSlug,
@@ -110,38 +92,34 @@ export async function handleLocalDeployment(
     requestedPorts: options.ports,
     suggestedPorts: existingDeploymentForProject?.config.ports,
   });
-  const { deploymentName, adminKey, projectId } = await bigBrainStart(ctx, {
+  const { deploymentName, projectId } = await bigBrainStart(ctx, {
     port: cloudPort,
     projectSlug: options.projectSlug,
     teamSlug: options.teamSlug,
     instanceName: existingDeploymentForProject?.deploymentName ?? null,
   });
-  const onActivity = async (isOffline: boolean, _wasOffline: boolean) => {
-    await ensureBackendRunning(ctx, {
-      cloudPort,
-      deploymentName,
-      maxTimeSecs: 5,
-    });
-    if (isOffline) {
-      return;
-    }
-    await bigBrainRecordActivity(ctx, {
-      instanceName: deploymentName,
-    });
-  };
 
-  const { cleanupHandle } = await handlePotentialUpgrade(ctx, {
-    deploymentKind: "local",
-    deploymentName,
-    oldVersion: existingDeploymentForProject?.config.backendVersion ?? null,
-    newBinaryPath: binaryPath,
-    newVersion: version,
-    ports: { cloud: cloudPort, site: sitePort },
-    adminKey,
-    instanceSecret: LOCAL_BACKEND_INSTANCE_SECRET,
-    forceUpgrade: options.forceUpgrade,
-    cloudProjectId: projectId,
-  });
+  const { cleanupHandle, adminKey } = await handlePotentialUpgradeAndStart(
+    ctx,
+    {
+      deploymentKind: "local",
+      deploymentName,
+      oldVersion: existingDeploymentForProject?.config.backendVersion ?? null,
+      newBinaryPath: binaryPath,
+      newVersion: version,
+      ports: { cloud: cloudPort, site: sitePort },
+      existingCredentials: existingDeploymentForProject?.config
+        ? {
+            adminKey: existingDeploymentForProject?.config.adminKey,
+            instanceSecret:
+              existingDeploymentForProject?.config.instanceSecret ??
+              LEGACY_LOCAL_BACKEND_INSTANCE_SECRET,
+          }
+        : null,
+      forceUpgrade: options.forceUpgrade,
+      cloudProjectId: projectId,
+    },
+  );
 
   if (isFirstTime) {
     await importDefaultEnvVars(ctx, {
@@ -156,22 +134,32 @@ export async function handleLocalDeployment(
   // Periodically report activity to BigBrain every 60 seconds.
   // Uses self-scheduling setTimeout to avoid overlapping requests.
   let activityTimeout: ReturnType<typeof setTimeout> | null = null;
-  const scheduleActivityPing = () => {
+  let activityPingStopped = false;
+  async function activityPing() {
+    if (activityPingStopped) {
+      return;
+    }
+    try {
+      await bigBrainRecordActivity(ctx, {
+        instanceName: deploymentName,
+        adminKey,
+      });
+    } catch {
+      // Best-effort: don't crash on failed pings
+    }
+
+    if (activityPingStopped) {
+      return;
+    }
     activityTimeout = setTimeout(async () => {
-      try {
-        await bigBrainRecordActivity(ctx, {
-          instanceName: deploymentName,
-        });
-      } catch {
-        // Best-effort: don't crash on failed pings
-      }
-      scheduleActivityPing();
+      void activityPing();
     }, 60_000);
-  };
-  scheduleActivityPing();
+  }
+  void activityPing();
 
   const cleanupFunc = ctx.removeCleanup(cleanupHandle);
   ctx.registerCleanup(async (exitCode, err) => {
+    activityPingStopped = true;
     if (activityTimeout !== null) {
       clearTimeout(activityTimeout);
     }
@@ -190,7 +178,6 @@ export async function handleLocalDeployment(
     deploymentUrl: localDeploymentUrl(cloudPort),
     reference: null,
     isDefault: false,
-    onActivity,
   };
 }
 
@@ -218,64 +205,6 @@ export async function loadLocalDeploymentCredentials(
   };
 }
 
-async function handleOffline(
-  ctx: Context,
-  options: {
-    teamSlug: string;
-    projectSlug: string;
-    ports: { cloud: number | undefined; site: number | undefined };
-  },
-): Promise<DeploymentDetails> {
-  const { deploymentName, config } =
-    await chooseFromExistingLocalDeployments(ctx);
-  const { binaryPath } = await ensureBackendBinaryDownloaded(ctx, {
-    kind: "version",
-    version: config.backendVersion,
-  });
-  const { cloudPort, sitePort } = await chooseLocalBackendPorts(ctx, {
-    requestedPorts: options.ports,
-    // FIXME: This doesn’t try to reuse the ports already assigned in the config.
-    // Please update this if we ever support offline mode (currently this is dead code).
-  });
-  saveDeploymentConfig(ctx, "local", deploymentName, config);
-  await runLocalBackend(ctx, {
-    binaryPath,
-    ports: { cloud: cloudPort, site: sitePort },
-    deploymentName,
-    deploymentKind: "local",
-    instanceSecret: LOCAL_BACKEND_INSTANCE_SECRET,
-    isLatestVersion: false,
-  });
-  return {
-    adminKey: config.adminKey,
-    deploymentName,
-    deploymentUrl: localDeploymentUrl(cloudPort),
-    reference: null,
-    isDefault: false,
-    onActivity: async (isOffline: boolean, wasOffline: boolean) => {
-      await ensureBackendRunning(ctx, {
-        cloudPort,
-        deploymentName,
-        maxTimeSecs: 5,
-      });
-      if (isOffline) {
-        return;
-      }
-      if (wasOffline) {
-        await bigBrainStart(ctx, {
-          port: cloudPort,
-          projectSlug: options.projectSlug,
-          teamSlug: options.teamSlug,
-          instanceName: deploymentName,
-        });
-      }
-      await bigBrainRecordActivity(ctx, {
-        instanceName: deploymentName,
-      });
-    },
-  };
-}
-
 async function getExistingDeployment(
   ctx: Context,
   options: {
@@ -341,73 +270,6 @@ async function getLegacyLocalDeployments(ctx: Context): Promise<
   });
 }
 
-/**
- * Get all local deployments from both project-local and legacy locations.
- */
-async function getLocalDeployments(ctx: Context): Promise<
-  Array<{
-    deploymentName: string;
-    config: LocalDeploymentConfig;
-  }>
-> {
-  const deployments: Array<{
-    deploymentName: string;
-    config: LocalDeploymentConfig;
-  }> = [];
-
-  // Check project-local storage
-  const projectLocal = loadProjectLocalConfig(ctx);
-  if (
-    projectLocal !== null &&
-    projectLocal.deploymentName.startsWith("local-")
-  ) {
-    deployments.push(projectLocal);
-  }
-
-  // Also include legacy deployments (but avoid duplicates)
-  const legacyDeployments = await getLegacyLocalDeployments(ctx);
-  for (const legacy of legacyDeployments) {
-    if (!deployments.some((d) => d.deploymentName === legacy.deploymentName)) {
-      deployments.push(legacy);
-    }
-  }
-
-  return deployments;
-}
-
-async function chooseFromExistingLocalDeployments(ctx: Context): Promise<{
-  deploymentName: string;
-  config: LocalDeploymentConfig;
-}> {
-  const localDeployments = await getLocalDeployments(ctx);
-
-  if (localDeployments.length === 0) {
-    return ctx.crash({
-      exitCode: 1,
-      errorType: "fatal",
-      printedMessage:
-        "No local deployments found. Please run `npx convex dev` while online first.",
-    });
-  }
-
-  // Auto-select if there's only one deployment
-  if (localDeployments.length === 1) {
-    logVerbose(
-      `Auto-selecting the only local deployment: ${localDeployments[0].deploymentName}`,
-    );
-    return localDeployments[0];
-  }
-
-  // Multiple deployments (legacy) - prompt user to choose
-  return promptSearch(ctx, {
-    message: "Choose from an existing local deployment:",
-    choices: localDeployments.map((d) => ({
-      name: d.deploymentName,
-      value: d,
-    })),
-  });
-}
-
 /** Copies the default dev env vars from big brain the first time the local dev backend is started */
 export async function importDefaultEnvVars(
   ctx: Context,