convex 1.36.0 → 1.37.0

package/src/react/use_query_object_options.test.ts

@@ -7,9 +7,10 @@ import { test, describe } from "vitest";
 import { anyApi } from "../server/api.js";
 
 import type { ApiFromModules, QueryBuilder } from "../server/index.js";
-import { useQuery as useQueryReal } from "./client.js";
+import { useQuery_experimental as useQuery_experimentalReal } from "./client.js";
 
-const useQuery = (() => {}) as unknown as typeof useQueryReal;
+const useQuery_experimental =
+  (() => {}) as unknown as typeof useQuery_experimentalReal;
 const query: QueryBuilder<any, "public"> = (() => {}) as any;
 
 const module = {
@@ -21,28 +22,28 @@ const api = anyApi as unknown as API;
 
 describe("useQuery object options", () => {
   test("supports object options and skip sentinel", () => {
-    useQuery({
+    useQuery_experimental({
       query: api.module.noArgs,
       args: {},
     });
 
-    useQuery({
+    useQuery_experimental({
       query: api.module.args,
       args: { _arg: "asdf" },
     });
 
     const _arg: string | undefined = undefined;
-    useQuery({
+    useQuery_experimental({
       query: api.module.args,
       args: _arg ? { _arg } : "skip",
     });
 
-    useQuery({
+    useQuery_experimental({
       query: api.module.args,
       args: { _arg: "asdf" },
     });
 
-    useQuery({
+    useQuery_experimental({
       query: api.module.noArgs,
       args: "skip",
     });

package/src/react/use_query_result.test.ts

@@ -7,9 +7,12 @@ import { test, describe, expectTypeOf } from "vitest";
 import { anyApi } from "../server/api.js";
 
 import type { ApiFromModules, QueryBuilder } from "../server/index.js";
-import { useQuery as useQueryReal, type UseQueryResult } from "./client.js";
+import {
+  useQuery_experimental as useQueryReal,
+  type UseQueryResult,
+} from "./client.js";
 
-const useQuery = (() => {}) as unknown as typeof useQueryReal;
+const useQuery_experimental = (() => {}) as unknown as typeof useQueryReal;
 const query: QueryBuilder<any, "public"> = (() => {}) as any;
 
 const module = {
@@ -19,24 +22,54 @@ const module = {
 type API = ApiFromModules<{ module: typeof module }>;
 const api = anyApi as unknown as API;
 
-describe("useQuery object-form result types", () => {
+describe("useQuery_experimental result types", () => {
   test("supports object-form result usage", () => {
-    useQuery({
+    useQuery_experimental({
       query: api.module.args,
       args: { _arg: "asdf" },
     });
 
-    useQuery({
+    const throwingResult = useQuery_experimental({
       query: api.module.args,
       args: { _arg: "asdf" },
       throwOnError: true,
     });
+    expectTypeOf(throwingResult).toEqualTypeOf<UseQueryResult<string, true>>();
 
     const _arg: string | undefined = undefined;
-    const conditionalResult = useQuery({
+    const conditionalResult = useQuery_experimental({
       query: api.module.args,
       args: _arg ? { _arg } : "skip",
     });
-    expectTypeOf(conditionalResult).toEqualTypeOf<UseQueryResult<string>>();
+    expectTypeOf(conditionalResult).toEqualTypeOf<
+      UseQueryResult<string, false>
+    >();
+  });
+
+  test("throwOnError:true omits error from result", () => {
+    // Never executed; exists only for type checking.
+    () => {
+      const throwingResult = useQuery_experimental({
+        query: api.module.args,
+        args: { _arg: "asdf" },
+        throwOnError: true,
+      });
+      expectTypeOf<(typeof throwingResult)["status"]>().toEqualTypeOf<
+        "pending" | "success"
+      >();
+    };
+  });
+
+  test("throwOnError ommitted includes error in result", () => {
+    // Never executed; exists only for type checking.
+    () => {
+      const throwingResult = useQuery_experimental({
+        query: api.module.args,
+        args: { _arg: "asdf" },
+      });
+      expectTypeOf<(typeof throwingResult)["status"]>().toEqualTypeOf<
+        "pending" | "success" | "error"
+      >();
+    };
   });
 });

package/src/server/api.intersect.test.ts

@@ -0,0 +1,109 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { assert, Equals } from "../test/type_testing.js";
+import { test } from "vitest";
+import {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+  FunctionReferenceFromExport,
+} from "./api.js";
+import {
+  EmptyObject,
+  RegisteredAction,
+  RegisteredMutation,
+  RegisteredQuery,
+} from "./registration.js";
+
+test("FunctionReferenceFromExport preserves visibility through intersections", () => {
+  type TaggedPublicMutation = RegisteredMutation<
+    "public",
+    EmptyObject,
+    string
+  > & { foo: "bar" };
+  type TaggedInternalMutation = RegisteredMutation<
+    "internal",
+    EmptyObject,
+    string
+  > & { foo: "bar" };
+  type TaggedInternalQuery = RegisteredQuery<
+    "internal",
+    { x: number },
+    string
+  > & { tag: true };
+  type TaggedPublicAction = RegisteredAction<"public", EmptyObject, number> & {
+    a: 1;
+  };
+
+  assert<
+    Equals<
+      FunctionReferenceFromExport<TaggedPublicMutation>,
+      FunctionReference<"mutation", "public", EmptyObject, string>
+    >
+  >();
+  assert<
+    Equals<
+      FunctionReferenceFromExport<TaggedInternalMutation>,
+      FunctionReference<"mutation", "internal", EmptyObject, string>
+    >
+  >();
+  assert<
+    Equals<
+      FunctionReferenceFromExport<TaggedInternalQuery>,
+      FunctionReference<"query", "internal", { x: number }, string>
+    >
+  >();
+  assert<
+    Equals<
+      FunctionReferenceFromExport<TaggedPublicAction>,
+      FunctionReference<"action", "public", EmptyObject, number>
+    >
+  >();
+});
+
+test("intersected functions show up in api / internal", () => {
+  type TaggedInternal = RegisteredMutation<"internal", EmptyObject, string> & {
+    foo: "bar";
+  };
+  type TaggedPublic = RegisteredMutation<"public", EmptyObject, number> & {
+    tag: true;
+  };
+
+  const myModule = {
+    taggedInternal: null as unknown as TaggedInternal,
+    taggedPublic: null as unknown as TaggedPublic,
+  };
+  type API = ApiFromModules<{ myModule: typeof myModule }>;
+  type Internal = FilterApi<API, FunctionReference<any, "internal">>;
+  type Public = FilterApi<API, FunctionReference<any, "public">>;
+
+  assert<
+    Equals<
+      Internal,
+      {
+        myModule: {
+          taggedInternal: FunctionReference<
+            "mutation",
+            "internal",
+            EmptyObject,
+            string
+          >;
+        };
+      }
+    >
+  >();
+  assert<
+    Equals<
+      Public,
+      {
+        myModule: {
+          taggedPublic: FunctionReference<
+            "mutation",
+            "public",
+            EmptyObject,
+            number
+          >;
+        };
+      }
+    >
+  >();
+});

package/src/server/audit_logging.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, test } from "vitest";
+import { AuditLogBody, cloneWithSentinels } from "./audit_logging.js";
+import { log } from "./log.js";
+
+describe("cloneWithSentinels", () => {
+  test("clones the body when there are no log vars", () => {
+    const input: AuditLogBody = {
+      foo: "bar",
+      count: 42,
+      flag: true,
+      empty: null,
+      nested: { inner: "value", arr: [1, 2, 3] },
+    };
+    const result = cloneWithSentinels(input);
+
+    expect(result).toEqual(input);
+    expect(result).not.toBe(input);
+    expect(result.nested).not.toBe(input.nested);
+  });
+
+  test("replaces log vars with sentinel objects", () => {
+    const input: AuditLogBody = {
+      userIp: log.vars.ip,
+      agent: log.vars.userAgent,
+      ts: log.vars.now,
+      reqId: log.vars.requestId,
+      note: "hello",
+    };
+    const result = cloneWithSentinels(input);
+
+    expect(result).toEqual({
+      userIp: { $var: "ip" },
+      agent: { $var: "userAgent" },
+      ts: { $var: "now" },
+      reqId: { $var: "requestId" },
+      note: "hello",
+    });
+  });
+
+  test("handles log vars nested inside an object", () => {
+    const input: AuditLogBody = {
+      outer: {
+        inner: {
+          userIp: log.vars.ip,
+          ts: log.vars.now,
+        },
+        label: "x",
+      },
+    };
+    const result = cloneWithSentinels(input);
+
+    expect(result).toEqual({
+      outer: {
+        inner: { userIp: { $var: "ip" }, ts: { $var: "now" } },
+        label: "x",
+      },
+    });
+  });
+
+  test("handles log vars inside arrays", () => {
+    const input: AuditLogBody = {
+      items: [log.vars.ip, log.vars.userAgent, log.vars.now, "literal"],
+    };
+    const result = cloneWithSentinels(input);
+
+    expect(result).toEqual({
+      items: [
+        { $var: "ip" },
+        { $var: "userAgent" },
+        { $var: "now" },
+        "literal",
+      ],
+    });
+  });
+
+  test("handles the same var used multiple times", () => {
+    const input: AuditLogBody = {
+      topIp: log.vars.ip,
+      nested: { anotherIp: log.vars.ip },
+      list: [log.vars.ip],
+    };
+    const result = cloneWithSentinels(input);
+
+    expect(result).toEqual({
+      topIp: { $var: "ip" },
+      nested: { anotherIp: { $var: "ip" } },
+      list: [{ $var: "ip" }],
+    });
+  });
+
+  test("handles log vars inside objects within an array", () => {
+    const input: AuditLogBody = {
+      records: [
+        { ip: log.vars.ip, name: "a" },
+        { ts: log.vars.now, name: "b" },
+        { agent: log.vars.userAgent, name: "c" },
+      ],
+    };
+    const result = cloneWithSentinels(input);
+
+    expect(result).toEqual({
+      records: [
+        { ip: { $var: "ip" }, name: "a" },
+        { ts: { $var: "now" }, name: "b" },
+        { agent: { $var: "userAgent" }, name: "c" },
+      ],
+    });
+  });
+
+  test("throws on keys starting with $", () => {
+    expect(() => cloneWithSentinels({ $var: "ip" })).toThrow(
+      'keys must not start with "$"',
+    );
+  });
+
+  test("throws on $ keys nested inside objects", () => {
+    expect(() => cloneWithSentinels({ outer: { $secret: "value" } })).toThrow(
+      'keys must not start with "$"',
+    );
+  });
+
+  test("throws on unknown symbol var", () => {
+    const fakeVar = Symbol("var.fake");
+    expect(() =>
+      // @ts-expect-error intentionally passing an invalid var symbol
+      cloneWithSentinels({ x: fakeVar }),
+    ).toThrow("Unknown audit var symbol");
+  });
+});

package/src/server/audit_logging.ts

@@ -0,0 +1,75 @@
+import { performAsyncSyscall } from "./impl/syscall.js";
+import { LogVar, varNames } from "./logVars.js";
+
+export type AuditLogBody = { [key: string]: AuditLogValue };
+export type AuditLogValue =
+  | null
+  | undefined
+  | boolean
+  | number
+  | string
+  | LogVar
+  | AuditLogValue[]
+  | { [key: string]: AuditLogValue };
+
+type JsonValue =
+  | null
+  | undefined
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+function validateKey(key: string) {
+  if (key.startsWith("$")) {
+    throw new Error(`Audit log body keys must not start with "$": "${key}"`);
+  }
+}
+
+function cloneValue(value: AuditLogValue): JsonValue {
+  if (typeof value === "symbol") {
+    if (!(value in varNames)) {
+      throw new Error(
+        `Unknown audit var symbol: ${String(value)}. Use one of log.var.requestId, log.var.ip, log.var.userAgent, or log.var.now.`,
+      );
+    }
+    return { $var: varNames[value] };
+  }
+  if (value === null || value === undefined || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(cloneValue);
+  }
+  const result: { [key: string]: JsonValue } = {};
+  for (const [key, val] of Object.entries(value)) {
+    validateKey(key);
+    result[key] = cloneValue(val);
+  }
+  return result;
+}
+
+/**
+ * Deep-clone the body, replacing audit var symbols with sentinel objects
+ * like `{ $var: "ip" }`.
+ */
+export function cloneWithSentinels(body: AuditLogBody): {
+  [key: string]: JsonValue;
+} {
+  const result: { [key: string]: JsonValue } = {};
+  for (const [key, val] of Object.entries(body)) {
+    validateKey(key);
+    result[key] = cloneValue(val);
+  }
+  return result;
+}
+
+/**
+ * @internal
+ */
+export const audit = async (body: AuditLogBody): Promise<void> => {
+  await performAsyncSyscall("1.0/auditLog", {
+    body: cloneWithSentinels(body),
+  });
+};

package/src/server/impl/meta_impl.ts

@@ -3,8 +3,10 @@ import {
   ActionMeta,
   MutationMeta,
   QueryMeta,
+  RequestMetadata,
   FunctionMetadata,
   TransactionMetrics,
+  DeploymentMetadata,
 } from "../meta.js";
 import { performAsyncSyscall } from "./syscall.js";
 
@@ -35,6 +37,27 @@ async function getFunctionMetadata(): Promise<{
   return { name, componentPath };
 }
 
+async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
+  const syscallJSON = await performAsyncSyscall(
+    "1.0/getDeploymentMetadata",
+    {},
+  );
+  const result = jsonToConvex(syscallJSON) as any;
+  return {
+    name: result.name,
+    region: result.region ?? null,
+    class: result.class,
+  };
+}
+
+async function getRequestMetadata(): Promise<RequestMetadata> {
+  const { ip, userAgent, requestId } = await performAsyncSyscall(
+    "1.0/getRequestMetadata",
+    {},
+  );
+  return { ip, userAgent, requestId };
+}
+
 export function setupQueryMeta(
   visibility: FunctionMetadata["visibility"],
 ): QueryMeta {
@@ -45,6 +68,7 @@ export function setupQueryMeta(
       visibility,
     }),
     getTransactionMetrics,
+    getDeploymentMetadata,
   };
 }
 
@@ -58,6 +82,8 @@ export function setupMutationMeta(
       visibility,
     }),
     getTransactionMetrics,
+    getDeploymentMetadata,
+    getRequestMetadata,
   };
 }
 
@@ -70,5 +96,7 @@ export function setupActionMeta(
       type: "action",
       visibility,
     }),
+    getDeploymentMetadata,
+    getRequestMetadata,
   };
 }

package/src/server/impl/registration_impl.ts

@@ -492,6 +492,7 @@ export const internalQueryGeneric: QueryBuilder<any, "internal"> = ((
 async function invokeAction<
   F extends (ctx: GenericActionCtx<GenericDataModel>, ...args: any) => any,
 >(func: F, requestId: string, argsStr: string, visibility: FunctionVisibility) {
+  (globalThis as any).Convex?.setupPerformance?.();
   const args = jsonToConvex(JSON.parse(argsStr));
   const calls = setupActionCalls(requestId);
   const ctx = {
@@ -673,6 +674,7 @@ export const internalActionGeneric: ActionBuilder<any, "internal"> = ((
 async function invokeHttpAction<
   F extends (ctx: GenericActionCtx<GenericDataModel>, request: Request) => any,
 >(func: F, request: Request) {
+  (globalThis as any).Convex?.setupPerformance?.();
   // TODO(presley): Change the function signature and propagate the requestId from Rust.
   // Ok, to mock it out for now, since http endpoints are only running in V8.
   const requestId = "";

package/src/server/index.ts

@@ -107,6 +107,8 @@ export type {
   TransactionMetric,
   TransactionMetrics,
   FunctionMetadata,
+  DeploymentMetadata,
+  RequestMetadata,
   QueryMeta,
   MutationMeta,
   ActionMeta,
@@ -177,6 +179,7 @@ export type {
   PartialApi,
   ArgsAndOptions,
   FunctionReturnType,
+  ValidatorTypeToReturnType,
 } from "./api.js";
 export {
   defineApp,
@@ -201,6 +204,15 @@ export type {
  */
 export type { Index, SearchIndex, VectorIndex } from "./schema.js";
 
+/**
+ * @internal
+ */
+export { log } from "./log.js";
+/**
+ * @internal
+ */
+export type { AuditLogBody, AuditLogValue } from "./audit_logging.js";
+
 export type {
   SearchIndexConfig,
   VectorIndexConfig,

package/src/server/log.ts

@@ -0,0 +1,16 @@
+import { audit } from "./audit_logging.js";
+import { vars } from "./logVars.js";
+
+// Type annotations are needed for the `unique symbol` types in `vars` to typecheck correctly
+interface Log {
+  audit: typeof audit;
+  vars: typeof vars;
+}
+
+/**
+ * @internal
+ */
+export const log: Log = {
+  audit,
+  vars,
+};

package/src/server/logVars.ts

@@ -0,0 +1,34 @@
+const REQUEST_ID = Symbol("var.requestId");
+const IP = Symbol("var.ip");
+const USER_AGENT = Symbol("var.userAgent");
+const NOW = Symbol("var.now");
+
+export type LogVar =
+  | typeof REQUEST_ID
+  | typeof IP
+  | typeof USER_AGENT
+  | typeof NOW;
+
+/**
+ * @internal
+ */
+export const varNames: Record<symbol, string> = {
+  [REQUEST_ID]: "requestId",
+  [IP]: "ip",
+  [USER_AGENT]: "userAgent",
+  [NOW]: "now",
+};
+
+export const vars = {
+  /** Resolved to the request ID. */
+  requestId: REQUEST_ID,
+  /** Resolved to the client's IP address. */
+  ip: IP,
+  /** Resolved to the client's User-Agent header. */
+  userAgent: USER_AGENT,
+  /**
+   * Resolved to the current server timestamp, as milliseconds from the
+   * Unix epoch.
+   */
+  now: NOW,
+} as const;

package/src/server/meta.ts

@@ -49,6 +49,46 @@ export type FunctionMetadata = {
   visibility: FunctionVisibility;
 };
 
+/**
+ * Metadata about the deployment this function is running on.
+ *
+ * @public
+ */
+export type DeploymentMetadata = {
+  /**
+   * The deployment name, e.g. `"tall-tiger-123"` for cloud deployments,
+   * `"local-my_team-my_project"` for local deployments, or
+   * `"anonymous-*"` for anonymous deployments.
+   */
+  name: string;
+  /**
+   * The deployment region, e.g. `"aws-us-east-1"`.
+   * `null` for local and self-hosted deployments.
+   */
+  region: string | null;
+  /**
+   * The deployment class, e.g. `"s16"`, `"s256"`, or `"d1024"`.
+   */
+  class: "s16" | "s256" | "d1024";
+};
+
+/**
+ * Metadata about the HTTP request that triggered the current function execution.
+ *
+ * `ip` and `userAgent` are `null` when the function was not triggered by an
+ * HTTP request (e.g. scheduled jobs or cron jobs).
+ *
+ * Functions called from within a function (i.e. using `runMutation` or
+ * `runAction`) will have the same request metadata as the parent function.
+ *
+ * @public
+ */
+export type RequestMetadata = {
+  ip: string | null;
+  userAgent: string | null;
+  requestId: string;
+};
+
 /**
  * Extra context available in Convex query functions.
  *
@@ -57,6 +97,7 @@ export type FunctionMetadata = {
 export interface QueryMeta {
   getFunctionMetadata(): Promise<FunctionMetadata>;
   getTransactionMetrics(): Promise<TransactionMetrics>;
+  getDeploymentMetadata(): Promise<DeploymentMetadata>;
 }
 
 /**
@@ -64,7 +105,12 @@ export interface QueryMeta {
  *
  * @public
  */
-export interface MutationMeta extends QueryMeta {}
+export interface MutationMeta extends QueryMeta {
+  /**
+   * @internal
+   */
+  getRequestMetadata(): Promise<RequestMetadata>;
+}
 
 /**
  * Extra context available in Convex action functions.
@@ -73,4 +119,10 @@ export interface MutationMeta extends QueryMeta {}
  */
 export interface ActionMeta {
   getFunctionMetadata(): Promise<FunctionMetadata>;
+  getDeploymentMetadata(): Promise<DeploymentMetadata>;
+
+  /**
+   * @internal
+   */
+  getRequestMetadata(): Promise<RequestMetadata>;
 }