Queue mutations in ConvexHttpClient (#37818)

thomasballinger · Convex, Inc. · commit 734df16b4700 · 2025-06-12T18:04:51.000Z
Queue mutations in the ConvexHttpClient to match the behavior of ConvexClient and ConvexReactClient. This makes switching between these safer.

If you need unqueued mutations (you need to run multiple mutations concurrently), pass the `unqueued: true` option or create a separate ConvexHttpClient for each queue of mutations you need.

Also allow passing auth as an option in the constructor. This is appropriate for short-lived ConvexHttpClients and it more convenient for instantiating a client and using it in a single expression.

GitOrigin-RevId: fea037a6e10672648b0d71ddf1071b7ca5915eb7
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+- ConvexHttpClient mutations are now queued by default, making the
+  ConvexHttpClient match the behavior of ConvexClient and ConvexReactClient.
+  This makes switching between these safer.
+
+  If you need unqueued mutations (you need to run multiple mutations
+  concurrently), pass the unqueued: true option or create a separate
+  ConvexHttpClient for each queue of mutations you need.
+
+- Allow passing auth to ConvexHttpClient as an option in the constructor. This
+  is appropriate for short-lived ConvexHttpClients and it more convenient for
+  instantiating a client and using it in a single expression.
+
+- Restore check that Convex functions are not imported in the browser.
+
+  Convex functions run in a Convex deployment; including their source in a
+  frontend bundle is never necessary and can unintentionally reveal
+  implementation details (and even hardcoded secrets).
+
+  This check current causes a `console.warn()` warning, but in future versions
+  this will become an error. If you see the warning "Convex functions should not
+  be imported in the browser" you should address this by investigating where
+  this is being logged from; that's code you don't want in your frontend bundle.
+  If you really want your Convex functions in the browser it's possible to
+  disable this warning but this is not recommended.
+
+- TypeScript error when async callbacks are passed to
+  `mutation.withOptimisticUpdate()`: an optimistic update function is expected
+  to run synchronously.
+
 ## 1.24.8
 
 - Restore short retry timer for WebSocket reconnects initiated by an error on
diff --git a/src/browser/http_client.test.ts b/src/browser/http_client.test.ts
@@ -0,0 +1,174 @@
+import { test, expect, afterEach, vi } from "vitest";
+import { ConvexHttpClient, setFetch } from "./http_client.js";
+import { makeFunctionReference } from "../server/index.js";
+
+const apiMutationFunc = makeFunctionReference<
+  "mutation",
+  { value: string },
+  string
+>("test:mutation");
+
+afterEach(() => {
+  setFetch(globalThis.fetch);
+});
+
+test("mutation queue processes mutations sequentially", async () => {
+  const client = new ConvexHttpClient("http://test");
+
+  // Mock fetch to simulate network delays
+  const fetchMock = vi.fn();
+  let resolveFirst: (value: any) => void;
+  let resolveSecond: (value: any) => void;
+
+  fetchMock.mockImplementation((url, options) => {
+    const body = JSON.parse(options.body);
+    if (body.path === "test:mutation" && body.args[0].value === "first") {
+      return new Promise((resolve) => {
+        resolveFirst = resolve;
+      });
+    }
+    if (body.path === "test:mutation" && body.args[0].value === "second") {
+      return new Promise((resolve) => {
+        resolveSecond = resolve;
+      });
+    }
+    return Promise.reject(new Error("Unexpected mutation"));
+  });
+
+  setFetch(fetchMock);
+
+  // Start two queued mutations
+  const firstPromise = client.mutation(apiMutationFunc, { value: "first" });
+  const secondPromise = client.mutation(apiMutationFunc, { value: "second" });
+
+  // Verify first mutation started but second hasn't
+  expect(fetchMock).toHaveBeenCalledTimes(1);
+  expect(JSON.parse(fetchMock.mock.calls[0][1].body).args[0].value).toBe(
+    "first",
+  );
+
+  // Resolve first mutation
+  resolveFirst!({
+    ok: true,
+    json: () => Promise.resolve({ status: "success", value: "first result" }),
+  });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  // Verify second mutation started
+  expect(fetchMock).toHaveBeenCalledTimes(2);
+  expect(JSON.parse(fetchMock.mock.calls[1][1].body).args[0].value).toBe(
+    "second",
+  );
+
+  // Resolve second mutation
+  resolveSecond!({
+    ok: true,
+    json: () => Promise.resolve({ status: "success", value: "second result" }),
+  });
+
+  // Verify both promises resolve
+  await expect(firstPromise).resolves.toBe("first result");
+  await expect(secondPromise).resolves.toBe("second result");
+});
+
+test("unqueued mutations skip the queue", async () => {
+  const client = new ConvexHttpClient("http://test");
+
+  const fetchMock = vi.fn();
+  let resolveQueued: (value: any) => void;
+
+  fetchMock.mockImplementation((url, options) => {
+    const body = JSON.parse(options.body);
+    if (body.path === "test:mutation" && body.args[0].value === "queued") {
+      return new Promise((resolve) => {
+        resolveQueued = resolve;
+      });
+    }
+    if (body.path === "test:mutation" && body.args[0].value === "unqueued") {
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({ status: "success", value: "unqueued result" }),
+      });
+    }
+    return Promise.reject(new Error("Unexpected mutation"));
+  });
+
+  setFetch(fetchMock);
+
+  // Start a queued mutation
+  const queuedPromise = client.mutation(apiMutationFunc, { value: "queued" });
+  expect(fetchMock).toHaveBeenCalledTimes(1);
+
+  // Start an unqueued mutation while first is still running
+  const unqueuedPromise = client.mutation(
+    apiMutationFunc,
+    { value: "unqueued" },
+    { skipQueue: true },
+  );
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  // Verify both mutations started immediately
+  expect(fetchMock).toHaveBeenCalledTimes(2);
+
+  // Resolve the queued mutation
+  resolveQueued!({
+    ok: true,
+    json: () => Promise.resolve({ status: "success", value: "queued result" }),
+  });
+
+  // Verify both promises resolve
+  await expect(queuedPromise).resolves.toBe("queued result");
+  await expect(unqueuedPromise).resolves.toBe("unqueued result");
+});
+
+test("failed mutations don't block the queue", async () => {
+  const client = new ConvexHttpClient("http://test");
+
+  const fetchMock = vi.fn();
+  let resolveSecond: (value: any) => void;
+
+  fetchMock.mockImplementation((url, options) => {
+    const body = JSON.parse(options.body);
+    if (body.path === "test:mutation" && body.args[0].value === "first") {
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            status: "error",
+            errorMessage: "First mutation failed",
+          }),
+      });
+    }
+    if (body.path === "test:mutation" && body.args[0].value === "second") {
+      return new Promise((resolve) => {
+        resolveSecond = resolve;
+      });
+    }
+    return Promise.reject(new Error("Unexpected mutation"));
+  });
+
+  setFetch(fetchMock);
+
+  // Start two queued mutations
+  const firstPromise = client.mutation(apiMutationFunc, { value: "first" });
+  const secondPromise = client.mutation(apiMutationFunc, { value: "second" });
+
+  await expect(firstPromise).rejects.toThrow("First mutation failed");
+
+  // First mutation failed, second should start
+  expect(fetchMock).toHaveBeenCalledTimes(2);
+  expect(JSON.parse(fetchMock.mock.calls[1][1].body).args[0].value).toBe(
+    "second",
+  );
+
+  // Resolve second mutation
+  resolveSecond!({
+    ok: true,
+    json: () => Promise.resolve({ status: "success", value: "second result" }),
+  });
+
+  // Verify first promise rejects and second resolves
+  await expect(firstPromise).rejects.toThrow("First mutation failed");
+  await expect(secondPromise).resolves.toBe("second result");
+});
diff --git a/src/browser/http_client.ts b/src/browser/http_client.ts
@@ -18,7 +18,11 @@ import {
   logForFunction,
   Logger,
 } from "./logging.js";
-import { FunctionArgs, UserIdentityAttributes } from "../server/index.js";
+import {
+  ArgsAndOptions,
+  FunctionArgs,
+  UserIdentityAttributes,
+} from "../server/index.js";
 
 export const STATUS_CODE_OK = 200;
 export const STATUS_CODE_BAD_REQUEST = 400;
@@ -33,15 +37,25 @@ export function setFetch(f: typeof globalThis.fetch) {
   specifiedFetch = f;
 }
 
+export type HttpMutationOptions = {
+  /**
+   * Skip the default queue of mutations and run this immediately.
+   *
+   * This allows the same HttpConvexClient to be used to request multiple
+   * mutations in parallel, something not possible with WebSocket-based clients.
+   */
+  skipQueue: boolean;
+};
+
 /**
  * A Convex client that runs queries and mutations over HTTP.
  *
+ * This client is stateful (it has user credentials and queues mutations)
+ * so take care to avoid sharing it between requests in a server.
+ *
  * This is appropriate for server-side code (like Netlify Lambdas) or non-reactive
  * webapps.
  *
- * If you're building a React app, consider using
- * {@link react.ConvexReactClient} instead.
- *
  * @public
  */
 export class ConvexHttpClient {
@@ -52,6 +66,14 @@ export class ConvexHttpClient {
   private debug: boolean;
   private fetchOptions?: FetchOptions;
   private logger: Logger;
+  private mutationQueue: Array<{
+    mutation: FunctionReference<"mutation">;
+    args: FunctionArgs<any>;
+    resolve: (value: any) => void;
+    reject: (error: any) => void;
+  }> = [];
+  private isProcessingQueue: boolean = false;
+
   /**
    * Create a new {@link ConvexHttpClient}.
    *
@@ -61,15 +83,19 @@ export class ConvexHttpClient {
    * - `skipConvexDeploymentUrlCheck` - Skip validating that the Convex deployment URL looks like
    * `https://happy-animal-123.convex.cloud` or localhost. This can be useful if running a self-hosted
    * Convex backend that uses a different URL.
-   * - `logger` - A logger. If not provided, logs to the console.
+   * - `logger` - A logger or a boolean. If not provided, logs to the console.
    * You can construct your own logger to customize logging to log elsewhere
-   * or not log at all.
+   * or not log at all, or use `false` as a shorthand for a no-op logger.
+   * - `auth` - A JWT containing identity claims accessible in Convex functions.
+   * This identity may expire so it may be necessary to call `setAuth()` later,
+   * but for short-lived clients it's convenient to specify this value here.
    */
   constructor(
     address: string,
     options?: {
       skipConvexDeploymentUrlCheck?: boolean;
       logger?: Logger | boolean;
+      auth?: string;
     },
   ) {
     if (typeof options === "boolean") {
@@ -124,6 +150,9 @@ export class ConvexHttpClient {
   }
 
   /**
+   * Set admin auth token to allow calling internal queries, mutations, and actions
+   * and acting as an identity.
+   *
    * @internal
    */
   setAdminAuth(token: string, actingAsIdentity?: UserIdentityAttributes) {
@@ -299,19 +328,10 @@ export class ConvexHttpClient {
     }
   }
 
-  /**
-   * Execute a Convex mutation function.
-   *
-   * @param name - The name of the mutation.
-   * @param args - The arguments object for the mutation. If this is omitted,
-   * the arguments will be `{}`.
-   * @returns A promise of the mutation's result.
-   */
-  async mutation<Mutation extends FunctionReference<"mutation">>(
+  private async mutationInner<Mutation extends FunctionReference<"mutation">>(
     mutation: Mutation,
-    ...args: OptionalRestArgs<Mutation>
+    mutationArgs: FunctionArgs<Mutation>,
   ): Promise<FunctionReturnType<Mutation>> {
-    const mutationArgs = parseArgs(args[0]);
     const name = getFunctionName(mutation);
     const body = JSON.stringify({
       path: name,
@@ -359,8 +379,60 @@ export class ConvexHttpClient {
     }
   }
 
+  private async processMutationQueue() {
+    if (this.isProcessingQueue) {
+      return;
+    }
+
+    this.isProcessingQueue = true;
+    while (this.mutationQueue.length > 0) {
+      const { mutation, args, resolve, reject } = this.mutationQueue.shift()!;
+      try {
+        const result = await this.mutationInner(mutation, args);
+        resolve(result);
+      } catch (error) {
+        reject(error);
+      }
+    }
+    this.isProcessingQueue = false;
+  }
+
+  private enqueueMutation<Mutation extends FunctionReference<"mutation">>(
+    mutation: Mutation,
+    args: FunctionArgs<Mutation>,
+  ): Promise<FunctionReturnType<Mutation>> {
+    return new Promise((resolve, reject) => {
+      this.mutationQueue.push({ mutation, args, resolve, reject });
+      void this.processMutationQueue();
+    });
+  }
+
+  /**
+   * Execute a Convex mutation function. Mutations are queued by default.
+   *
+   * @param name - The name of the mutation.
+   * @param args - The arguments object for the mutation. If this is omitted,
+   * the arguments will be `{}`.
+   * @param options - An optional object containing
+   * @returns A promise of the mutation's result.
+   */
+  async mutation<Mutation extends FunctionReference<"mutation">>(
+    mutation: Mutation,
+    ...args: ArgsAndOptions<Mutation, HttpMutationOptions>
+  ): Promise<FunctionReturnType<Mutation>> {
+    const [fnArgs, options] = args;
+    const mutationArgs = parseArgs(fnArgs);
+    const queued = !options?.skipQueue;
+
+    if (queued) {
+      return await this.enqueueMutation(mutation, mutationArgs);
+    } else {
+      return await this.mutationInner(mutation, mutationArgs);
+    }
+  }
+
   /**
-   * Execute a Convex action function.
+   * Execute a Convex action function. Actions are not queued.
    *
    * @param name - The name of the action.
    * @param args - The arguments object for the action. If this is omitted,
@@ -420,7 +492,7 @@ export class ConvexHttpClient {
   }
 
   /**
-   * Execute a Convex function of an unknown type.
+   * Execute a Convex function of an unknown type. These function calls are not queued.
    *
    * @param name - The name of the function.
    * @param args - The arguments object for the function. If this is omitted,
