@gaganref/confect-server 10.3.1-fork.41 → 10.3.1-fork.43

package/src/ActionRunner.ts

@@ -1,4 +1,5 @@
-import * as Ref from "@confect/core/Ref";
+import * as ReservedArgument from "./internal/reservedArgument.js";
+import type * as Ref from "@confect/core/Ref";
 import { type GenericActionCtx } from "convex/server";
 import * as Effect from "effect/Effect";
 import * as Context from "effect/Context";
@@ -18,7 +19,7 @@ const make = (runAction: GenericActionCtx<any>["runAction"]) => ({
     Ref.Error<Action> | Schema.SchemaError
   > =>
     run(
-      Ref.runWithCodec(
+      ReservedArgument.runWithCodec(
         action,
         (args[0] ?? {}) as Ref.Args<Action>,
         (functionReference, encodedArgs) =>

package/src/FunctionRegistryItem.ts

@@ -29,6 +29,7 @@ export interface ConfectFunctionRegistryItem {
   readonly [TypeId]: TypeId;
   readonly _tag: "Confect";
   readonly name: string;
+  readonly reservedArgument?: string;
   readonly functionVisibility: FunctionVisibility;
   readonly functionType: FunctionType;
   readonly args: Schema.Codec<any, any>;
@@ -64,6 +65,9 @@ export const make = ({
       const item = Object.assign(Object.create(FunctionRegistryItemProto), {
         _tag: "Confect" as const,
         name: functionSpec.name,
+        ...(functionSpec.reservedArgument === undefined
+          ? {}
+          : { reservedArgument: functionSpec.reservedArgument }),
         functionVisibility: functionSpec.functionVisibility,
         functionType: functionSpec.runtimeAndFunctionType.functionType,
         middlewareAttachments: [

package/src/MutationRunner.ts

@@ -1,4 +1,5 @@
-import * as Ref from "@confect/core/Ref";
+import * as ReservedArgument from "./internal/reservedArgument.js";
+import type * as Ref from "@confect/core/Ref";
 import type { GenericActionCtx } from "convex/server";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
@@ -46,7 +47,7 @@ const make = (nativeRunMutation: GenericActionCtx<any>["runMutation"]) => {
             yield* MutationTransactionContext.MutationTransactionContext;
           return yield* controls.runMutation(mutation, actualArgs, options);
         }
-        return yield* Ref.runWithCodec(
+        return yield* ReservedArgument.runWithCodec(
           mutation,
           actualArgs,
           (ref, encodedArgs) => nativeRunMutation(ref, encodedArgs),

package/src/MutationTransactionContext.ts

@@ -1,3 +1,4 @@
+import * as ReservedArgument from "./internal/reservedArgument.js";
 import * as Ref from "@confect/core/Ref";
 import type {
   AdvancedRunQueryOptions,
@@ -32,7 +33,7 @@ const make = (
       args: Ref.Args<Mutation>,
       options: MutationOptions,
     ) =>
-      Ref.runWithCodec(mutation, args, (ref, encodedArgs) =>
+      ReservedArgument.runWithCodec(mutation, args, (ref, encodedArgs) =>
         ctx.runMutation(ref, encodedArgs, options),
       ),
   ),

package/src/RegisteredConvexFunction.ts

@@ -86,6 +86,7 @@ export const prepare = (
       const definition = mutationFunction({
         databaseSchema,
         name: item.name,
+        reservedArgument: item.reservedArgument,
         observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
@@ -103,6 +104,7 @@ export const prepare = (
     Match.when("action", () => {
       const definition = convexActionFunction(databaseSchema, {
         name: item.name,
+        reservedArgument: item.reservedArgument,
         observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
@@ -324,9 +326,11 @@ const mutationFunction = <
   handler,
   resolvedMiddlewares,
   observability,
+  reservedArgument,
 }: {
   databaseSchema: DatabaseSchema_;
   name: string;
+  reservedArgument?: string | undefined;
   functionVisibility: FunctionVisibility;
   args: Schema.Codec<Args, ConvexArgs>;
   returns: Schema.Codec<Returns, ConvexReturns>;
@@ -337,7 +341,12 @@ const mutationFunction = <
   resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
   observability?: Layer.Layer<never> | undefined;
 }) => ({
-  args: compileArgsSchema(args, databaseSchema.target.scope),
+  args: compileArgsSchema(
+    args,
+    databaseSchema.target.scope,
+    reservedArgument,
+    name,
+  ),
   returns: compileReturnsSchema(returns, databaseSchema.target.scope),
   handler: (
     ctx: GenericMutationCtx<
@@ -347,7 +356,7 @@ const mutationFunction = <
   ): Promise<ConvexReturns> =>
     Effect.gen(function* () {
       const decodedArgs = yield* pipe(
-        actualArgs,
+        RegisteredFunction.domainArgs(actualArgs, reservedArgument),
         Schema.decodeUnknownEffect(args),
         Effect.catchTag("SchemaError", Effect.die),
       );
@@ -372,7 +381,11 @@ const mutationFunction = <
         RegisteredFunction.combineErrorSchemas(error, resolvedMiddlewares),
         {
           scheduler: new EffectScheduler.MixedScheduler("sync"),
-          invocation: Effect.promise(() => ctx.meta.getFunctionMetadata()),
+          invocation: RegisteredFunction.invocationMetadata(
+            ctx.meta,
+            actualArgs,
+            reservedArgument,
+          ),
           observability,
         },
       ),
@@ -397,8 +410,10 @@ const convexActionFunction = <
     handler,
     resolvedMiddlewares,
     observability,
+    reservedArgument,
   }: {
     name: string;
+    reservedArgument?: string | undefined;
     functionVisibility: FunctionVisibility;
     args: Schema.Codec<Args, ConvexArgs>;
     returns: Schema.Codec<Returns, ConvexReturns>;
@@ -424,6 +439,7 @@ const convexActionFunction = <
     handler,
     resolvedMiddlewares,
     observability,
+    reservedArgument,
     createLayer: (ctx) =>
       Layer.mergeAll(
         RegisteredFunction.actionLayer(schema, ctx),

package/src/RegisteredFunction.ts

@@ -1,3 +1,4 @@
+export { Forward } from "./internal/reservedArgument.js";
 import * as ActionCallSpec from "@confect/core/ActionCall";
 import * as ActionCall from "./ActionCall.js";
 import type { FunctionSpec, RuntimeAndFunctionType } from "@confect/core";
@@ -12,6 +13,7 @@ import {
   type DefaultFunctionArgs,
   type FunctionVisibility,
   type FunctionMetadata,
+  type MutationMeta,
   type GenericActionCtx,
   type GenericDataModel,
   type StorageReader as ConvexStorageReader,
@@ -22,6 +24,9 @@ import {
 import type { Value } from "convex/values";
 import { ConvexError } from "convex/values";
 import { pipe } from "effect/Function";
+import * as Config from "effect/Config";
+import * as Option from "effect/Option";
+import * as ConvexConfigProvider from "./ConvexConfigProvider.js";
 import * as Clock from "effect/Clock";
 import * as Cause from "effect/Cause";
 import * as Console from "effect/Console";
@@ -53,6 +58,40 @@ import * as ObservabilityRuntime from "./internal/observability.js";
 import * as VectorSearch from "./VectorSearch.js";
 import type * as Handler from "./Handler.js";
 
+export interface ReceivedValue {
+  readonly value: unknown;
+  readonly requestId: string;
+  readonly deployment: string | undefined;
+}
+
+export const Received = Context.Reference<ReceivedValue | undefined>(
+  "@confect/server/RegisteredFunction/Received",
+  { defaultValue: () => undefined },
+);
+
+export const invocationMetadata = (
+  meta: Pick<MutationMeta, "getFunctionMetadata" | "getRequestMetadata">,
+  args: DefaultFunctionArgs,
+  reservedArgument?: string,
+): Effect.Effect<FunctionMetadata & { readonly received?: ReceivedValue }> =>
+  Effect.gen(function* () {
+    const metadata = yield* Effect.promise(() => meta.getFunctionMetadata());
+    if (reservedArgument === undefined) return metadata;
+    const { requestId } = yield* Effect.promise(() =>
+      meta.getRequestMetadata(),
+    );
+    const deployment = yield* Config.String("CONVEX_CLOUD_URL").pipe(
+      Config.option,
+      Effect.map(Option.getOrUndefined),
+      Effect.provide(ConvexConfigProvider.layer),
+      Effect.orDie,
+    );
+    return {
+      ...metadata,
+      received: { value: args[reservedArgument], requestId, deployment },
+    };
+  });
+
 export const Observability = Context.Reference<Layer.Layer<never> | undefined>(
   "@confect/server/Observability",
   { defaultValue: () => undefined },
@@ -226,7 +265,11 @@ export const runHandlerPromise =
     runOptions?: {
       readonly scheduler?: EffectScheduler.Scheduler | undefined;
       readonly clock?: Clock.Clock | undefined;
-      readonly invocation?: Effect.Effect<FunctionMetadata> | undefined;
+      readonly invocation?:
+        | Effect.Effect<
+            FunctionMetadata & { readonly received?: ReceivedValue }
+          >
+        | undefined;
       readonly observability?: Layer.Layer<never> | undefined;
     },
   ) =>
@@ -269,16 +312,18 @@ export const runHandlerPromise =
         const exit = yield* Effect.exit(
           observability === undefined || invocation === undefined
             ? effect
-            : Effect.flatMap(invocation, ({ name, type, componentPath }) =>
-                Effect.useSpan(
-                  name,
-                  {
-                    root: true,
-                    attributes: { kind: type, componentPath },
-                  },
-                  (span) =>
-                    Effect.provideService(observed, Tracer.ParentSpan, span),
-                ),
+            : Effect.flatMap(
+                invocation,
+                ({ name, type, componentPath, received }) =>
+                  Effect.useSpan(
+                    name,
+                    {
+                      root: true,
+                      attributes: { kind: type, componentPath },
+                    },
+                    (span) =>
+                      Effect.provideService(observed, Tracer.ParentSpan, span),
+                  ).pipe(Effect.provideService(Received, received)),
               ),
         );
         if (Exit.isSuccess(exit)) {
@@ -347,6 +392,16 @@ export const runHandlerPromise =
     );
   };
 
+export const domainArgs = (
+  args: DefaultFunctionArgs,
+  reservedArgument?: string,
+): DefaultFunctionArgs =>
+  reservedArgument === undefined
+    ? args
+    : Object.fromEntries(
+        Object.entries(args).filter(([key]) => key !== reservedArgument),
+      );
+
 export const actionFunctionBase = <
   Schema extends DatabaseSchema.AnyWithProps,
   Args,
@@ -366,8 +421,10 @@ export const actionFunctionBase = <
   createLayer,
   scope = IdScope.app,
   observability,
+  reservedArgument,
 }: {
   name: string;
+  reservedArgument?: string | undefined;
   functionVisibility: FunctionVisibility;
   args: Schema.Codec<Args, ConvexArgs>;
   returns: Schema.Codec<Returns, ConvexReturns>;
@@ -380,7 +437,7 @@ export const actionFunctionBase = <
   scope?: IdScope.IdScope;
   observability?: Layer.Layer<never> | undefined;
 }) => ({
-  args: compileArgsSchema(args, scope),
+  args: compileArgsSchema(args, scope, reservedArgument, name),
   returns: compileReturnsSchema(returns, scope),
   handler: (
     ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
@@ -388,7 +445,7 @@ export const actionFunctionBase = <
   ): Promise<ConvexReturns> =>
     Effect.gen(function* () {
       const decodedArgs = yield* pipe(
-        actualArgs,
+        domainArgs(actualArgs, reservedArgument),
         Schema.decodeUnknownEffect(args),
         Effect.catchTag("SchemaError", Effect.die),
       );
@@ -417,7 +474,7 @@ export const actionFunctionBase = <
       );
     }).pipe(
       runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares), {
-        invocation: Effect.promise(() => ctx.meta.getFunctionMetadata()),
+        invocation: invocationMetadata(ctx.meta, actualArgs, reservedArgument),
         observability,
       }),
     ),

package/src/RegisteredNodeFunction.ts

@@ -61,6 +61,7 @@ export const make = (
   return genericFunction(
     nodeActionFunction(databaseSchema, {
       name: item.name,
+      reservedArgument: item.reservedArgument,
       observability,
       functionVisibility: item.functionVisibility,
       args: item.args,
@@ -90,8 +91,10 @@ const nodeActionFunction = <
     handler,
     resolvedMiddlewares,
     observability,
+    reservedArgument,
   }: {
     name: string;
+    reservedArgument?: string | undefined;
     functionVisibility: FunctionVisibility;
     args: Schema.Codec<Args, ConvexArgs>;
     returns: Schema.Codec<Returns, ConvexReturns>;
@@ -118,6 +121,7 @@ const nodeActionFunction = <
     handler,
     resolvedMiddlewares,
     observability,
+    reservedArgument,
     createLayer: (ctx) =>
       Layer.mergeAll(
         RegisteredFunction.actionLayer(databaseSchema, ctx),

package/src/Scheduler.ts

@@ -1,3 +1,4 @@
+import * as ReservedArgument from "./internal/reservedArgument.js";
 import type * as IdScope from "@confect/core/IdScope";
 import { Ref } from "@confect/core";
 import type { GenericId } from "@confect/core/GenericId";
@@ -12,38 +13,34 @@ import * as Layer from "effect/Layer";
 const make = (scheduler: ConvexScheduler) => ({
   cancel: (id: ConvexGenericId<"_scheduled_functions">) =>
     Effect.promise(() => scheduler.cancel(id)),
-  runAfter: <Ref_ extends Ref.AnyMutation | Ref.AnyAction>(
-    delay: Duration.Duration,
-    ref: Ref_,
-    ...args: Ref.OptionalArgs<Ref_>
-  ) => {
+  runAfter: Effect.fn("Scheduler.runAfter")(function* <
+    Ref_ extends Ref.AnyMutation | Ref.AnyAction,
+  >(delay: Duration.Duration, ref: Ref_, ...args: Ref.OptionalArgs<Ref_>) {
     const delayMs = Duration.toMillis(delay);
     const functionReference = Ref.getFunctionReference(ref);
-    const encodedArgs = Ref.encodeArgsSync(
+    const encodedArgs = yield* ReservedArgument.encodeArgs(
       ref,
       (args[0] ?? {}) as Ref.Args<Ref_>,
     );
 
-    return Effect.promise(() =>
+    return yield* Effect.promise(() =>
       scheduler.runAfter(delayMs, functionReference, encodedArgs),
     );
-  },
-  runAt: <Ref_ extends Ref.AnyMutation | Ref.AnyAction>(
-    dateTime: DateTime.DateTime,
-    ref: Ref_,
-    ...args: Ref.OptionalArgs<Ref_>
-  ) => {
+  }),
+  runAt: Effect.fn("Scheduler.runAt")(function* <
+    Ref_ extends Ref.AnyMutation | Ref.AnyAction,
+  >(dateTime: DateTime.DateTime, ref: Ref_, ...args: Ref.OptionalArgs<Ref_>) {
     const timestamp = DateTime.toEpochMillis(dateTime);
     const functionReference = Ref.getFunctionReference(ref);
-    const encodedArgs = Ref.encodeArgsSync(
+    const encodedArgs = yield* ReservedArgument.encodeArgs(
       ref,
       (args[0] ?? {}) as Ref.Args<Ref_>,
     );
 
-    return Effect.promise(() =>
+    return yield* Effect.promise(() =>
       scheduler.runAt(timestamp, functionReference, encodedArgs),
     );
-  },
+  }),
 });
 
 export const Scheduler = Context.Service<ReturnType<typeof make>>(

package/src/internal/reservedArgument.ts

@@ -0,0 +1,56 @@
+import { convexToJson, type Value } from "convex/values";
+import * as Ref from "@confect/core/Ref";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Tracer from "effect/Tracer";
+
+export const Forward = Context.Reference<
+  ((span: Tracer.Span) => unknown) | undefined
+>("@confect/server/RegisteredFunction/Forward", {
+  defaultValue: () => undefined,
+});
+
+const inject = (
+  ref: Ref.Any,
+  encoded: unknown,
+  context: Context.Context<never>,
+): unknown => {
+  if (ref.reservedArgument === undefined || ref.functionType === "query")
+    return encoded;
+  const forward = Context.get(context, Forward);
+  const span = Context.getOrUndefined(context, Tracer.ParentSpan);
+  if (forward === undefined || span?._tag !== "Span") return encoded;
+  try {
+    const value = forward(span);
+    if (value === undefined) return encoded;
+    convexToJson(value as Value);
+    return {
+      ...(encoded as Record<string, unknown>),
+      [ref.reservedArgument]: value,
+    };
+  } catch {
+    return encoded;
+  }
+};
+
+export const runWithCodec = <Ref_ extends Ref.Any>(
+  ref: Ref_,
+  args: Ref.Args<Ref_>,
+  call: (
+    native: Ref.FunctionReference<Ref_>,
+    encoded: unknown,
+  ) => PromiseLike<unknown>,
+) =>
+  Effect.withFiber((fiber) =>
+    Ref.runWithCodec(ref, args, (native, encoded) =>
+      call(native, inject(ref, encoded, fiber.context)),
+    ),
+  );
+
+export const encodeArgs = <Ref_ extends Ref.Any>(
+  ref: Ref_,
+  args: Ref.Args<Ref_>,
+) =>
+  Effect.withFiberSucceed((fiber) =>
+    inject(ref, Ref.encodeArgsSync(ref, args), fiber.context),
+  );