@gaganref/confect-server 10.3.1-fork.36 → 10.3.1-fork.39

package/src/RegisteredFunction.ts

@@ -11,6 +11,7 @@ import {
 import {
   type DefaultFunctionArgs,
   type FunctionVisibility,
+  type FunctionMetadata,
   type GenericActionCtx,
   type GenericDataModel,
   type StorageReader as ConvexStorageReader,
@@ -21,8 +22,12 @@ import {
 import type { Value } from "convex/values";
 import { ConvexError } from "convex/values";
 import { pipe } from "effect/Function";
+import * as Clock from "effect/Clock";
+import * as Cause from "effect/Cause";
 import * as Console from "effect/Console";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
 import * as Result from "effect/Result";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
@@ -43,9 +48,16 @@ import * as Storage from "./Storage.js";
 import * as StorageActionWriter from "./StorageActionWriter.js";
 import type * as StorageReader from "./StorageReader.js";
 import * as StorageWriter from "./StorageWriter.js";
+import * as Tracer from "effect/Tracer";
+import * as ObservabilityRuntime from "./internal/observability.js";
 import * as VectorSearch from "./VectorSearch.js";
 import type * as Handler from "./Handler.js";
 
+export const Observability = Context.Reference<Layer.Layer<never> | undefined>(
+  "@confect/server/Observability",
+  { defaultValue: () => undefined },
+);
+
 export type Any =
   | RegisteredQuery<FunctionVisibility, DefaultFunctionArgs, any>
   | RegisteredMutation<FunctionVisibility, DefaultFunctionArgs, any>
@@ -185,67 +197,125 @@ export const combineErrorSchemas = (
 };
 
 /**
- * Run the `Effect` as a `Promise`. The error schema acts as an allowlist of
- * failures that may be surfaced to the client as a `ConvexError`:
+ * Run the `Effect` as a `Promise`. Inspect the complete `Exit` before encoding
+ * a declared error so a typed failure cannot hide a defect.
  *
- * - With a schema: typed errors are schema-encoded and wrapped in a
- *   `ConvexError`, then thrown so Convex surfaces the data to the client.
- *   `Effect.either` escapes the failure channel before `runPromise` so the
- *   thrown `ConvexError` retains its `Symbol.for("ConvexError")` identity
- *   instead of being wrapped in Effect's `FiberFailure`.
- * - Without a schema: every failure is converted to a defect via `Effect.orDie`,
- *   so nothing—not even a `ConvexError` the handler placed in its error
- *   channel—reaches the client as a `ConvexError`. The fiber dies and
- *   `runPromise` rejects with a generic failure.
+ * Any `Die` reason takes the defect path. Without a `Die`, the first `Fail` in
+ * cause order is schema-encoded and thrown as a `ConvexError` outside the
+ * Effect runtime so Convex surfaces its data to the client. Other failures and
+ * interruptions alongside that `Fail` are ignored. Without an error schema, the
+ * selected failure is treated as a defect.
  *
- * Either way, a `ConvexError` _defect_—thrown imperatively rather than placed
- * in the error channel, e.g. the pagination protocol's `InvalidCursor` signal
- * from `QueryStream.paginate`—is rethrown bare so it retains its identity and
- * Convex serializes its `data` to the client, matching how a thrown
- * `ConvexError` behaves in a plain Convex handler.
+ * A lone `ConvexError` defect or a selected undeclared `ConvexError` failure is
+ * rethrown bare so it keeps Convex's meaning. Pagination and Workpool rely on
+ * its data for their control signals. Other causes with a `Die`, interrupt-only
+ * or empty causes, and error-encoding failures reject with a plain `Error`
+ * whose message renders the complete cause and whose `cause` holds it for
+ * server diagnostics.
  *
  * A `scheduler` in `runOptions` must be passed here as a run option rather than
  * provided via `Effect.provideService` inside `effect`: the run option lands in
  * the fiber's root context, while a service provided within `effect` pops
- * before the `orDie`/`catch`/`result` wrappers this function adds. The fiber's
- * op counter survives context pops, so a cooperative yield can fire inside
- * those wrappers—only a root-context scheduler covers them.
+ * before the exit/encoding wrappers this function adds. The fiber's op counter
+ * survives context pops, so a cooperative yield can fire inside those wrappers.
+ * Only a root-context scheduler covers them.
  */
 export const runHandlerPromise =
   (
     errorSchema: Schema.Codec<any, any> | undefined,
     runOptions?: {
       readonly scheduler?: EffectScheduler.Scheduler | undefined;
+      readonly clock?: Clock.Clock | undefined;
+      readonly invocation?: Effect.Effect<FunctionMetadata> | undefined;
+      readonly observability?: Layer.Layer<never> | undefined;
     },
   ) =>
   <A, E>(effect: Effect.Effect<A, E>): Promise<A> => {
-    // A `ConvexError` defect escapes into the (escaped) failure channel so
-    // the `throw` below rethrows it with its identity intact.
-    const rethrowConvexErrorDefects = Effect.catchDefect(
-      (defect: unknown): Effect.Effect<never, ConvexError<any>> =>
-        defect instanceof ConvexError
-          ? Effect.fail(defect)
-          : Effect.die(defect),
+    const { observability, invocation, clock } = runOptions ?? {};
+    let encodedError: Exit.Exit<any, any> | undefined;
+    const observed = Effect.tapCause(effect, (cause) =>
+      Effect.gen(function* () {
+        const reason =
+          cause.reasons.find(Cause.isDieReason) ??
+          cause.reasons.find(Cause.isFailReason);
+        if (reason?._tag === "Fail" && errorSchema !== undefined) {
+          encodedError = yield* Effect.exit(
+            Schema.encodeEffect(errorSchema)(reason.error),
+          );
+          if (Exit.isFailure(encodedError))
+            return yield* Effect.orDie(encodedError);
+        }
+      }),
     );
-
-    const withConvexError =
-      errorSchema === undefined
-        ? Effect.orDie(effect)
-        : effect.pipe(
-            Effect.catch((typedError) =>
-              pipe(
-                Schema.encodeEffect(errorSchema)(typedError),
-                Effect.catchTag("SchemaError", Effect.die),
-                Effect.andThen((encodedError) =>
-                  Effect.fail(new ConvexError(encodedError)),
+    const withConvexError: Effect.Effect<Result.Result<A, ConvexError<any>>> =
+      Effect.gen(function* () {
+        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),
                 ),
               ),
-            ),
+        );
+        if (Exit.isSuccess(exit)) {
+          return Result.succeed(exit.value);
+        }
+
+        const cause =
+          encodedError !== undefined && Exit.isFailure(encodedError)
+            ? encodedError.cause
+            : exit.cause;
+        const reason =
+          cause.reasons.find(Cause.isDieReason) ??
+          cause.reasons.find(Cause.isFailReason);
+        if (
+          encodedError === undefined &&
+          reason?._tag === "Die" &&
+          cause.reasons.length === 1 &&
+          reason.defect instanceof ConvexError
+        ) {
+          return Result.fail(reason.defect);
+        }
+
+        if (reason?._tag === "Fail") {
+          if (errorSchema === undefined) {
+            if (reason.error instanceof ConvexError) {
+              return Result.fail(reason.error);
+            }
+            return yield* Effect.die(reason.error);
+          }
+          const encoded =
+            encodedError ??
+            (yield* Effect.exit(
+              Schema.encodeEffect(errorSchema)(reason.error),
+            ));
+          if (Exit.isSuccess(encoded)) {
+            return Result.fail(new ConvexError(encoded.value));
+          }
+          return yield* Effect.die(
+            new Error(Cause.pretty(encoded.cause), { cause: encoded.cause }),
           );
+        }
+        return yield* Effect.die(new Error(Cause.pretty(cause), { cause }));
+      });
     return Effect.runPromise(
-      Effect.result(rethrowConvexErrorDefects(withConvexError)).pipe(
-        Effect.provide(ConvexLogger.layer),
+      withConvexError.pipe(
+        Effect.provide(
+          observability === undefined
+            ? ConvexLogger.layer
+            : ObservabilityRuntime.memoized(observability),
+        ),
         Effect.provideService(Console.Console, globalThis.console),
+        clock === undefined
+          ? (self) => self
+          : Effect.provideService(Clock.Clock, clock),
       ),
       runOptions,
     ).then(
@@ -276,6 +346,7 @@ export const actionFunctionBase = <
   resolvedMiddlewares = [],
   createLayer,
   scope = IdScope.app,
+  observability,
 }: {
   name: string;
   functionVisibility: FunctionVisibility;
@@ -288,6 +359,7 @@ export const actionFunctionBase = <
     ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
   ) => Layer.Layer<R>;
   scope?: IdScope.IdScope;
+  observability?: Layer.Layer<never> | undefined;
 }) => ({
   args: compileArgsSchema(args, scope),
   returns: compileReturnsSchema(returns, scope),
@@ -324,7 +396,12 @@ export const actionFunctionBase = <
         Schema.encodeEffect(returns),
         Effect.catchTag("SchemaError", Effect.die),
       );
-    }).pipe(runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares))),
+    }).pipe(
+      runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares), {
+        invocation: Effect.promise(() => ctx.meta.getFunctionMetadata()),
+        observability,
+      }),
+    ),
 });
 
 export type ActionServices<

package/src/RegisteredNodeFunction.ts

@@ -23,7 +23,7 @@ export const buildForGroup = <Group extends GroupSpec.AnyWithProps>(
   databaseSchema: DatabaseSchema.AnyWithProps,
   groupLayer: Layer.Layer<GroupImpl.GroupImpl<"Finalized">>,
 ): RegisteredFunctions.RegisteredFunctionsForGroupSpec<Group> => {
-  const { functionRegistryItems, middlewareRegistryItems } =
+  const { functionRegistryItems, middlewareRegistryItems, observability } =
     GroupRegistry.make(groupLayer);
   return mapLeaves<FunctionRegistryItem.AnyWithProps, RegisteredFunction.Any>(
     functionRegistryItems as {
@@ -38,6 +38,7 @@ export const buildForGroup = <Group extends GroupSpec.AnyWithProps>(
             databaseSchema,
             confect,
             ResolvedMiddleware.resolve(confect, middlewareRegistryItems),
+            observability,
           ),
         ),
         Match.exhaustive,
@@ -49,6 +50,7 @@ export const make = (
   databaseSchema: DatabaseSchema.AnyWithProps,
   item: FunctionRegistryItem.ConfectFunctionRegistryItem,
   resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware> = [],
+  observability?: Layer.Layer<never>,
 ): RegisteredFunction.Any => {
   const genericFunction = Match.value(item.functionVisibility).pipe(
     Match.when("public", () => actionGeneric),
@@ -59,6 +61,7 @@ export const make = (
   return genericFunction(
     nodeActionFunction(databaseSchema, {
       name: item.name,
+      observability,
       functionVisibility: item.functionVisibility,
       args: item.args,
       returns: item.returns,
@@ -86,6 +89,7 @@ const nodeActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
   }: {
     name: string;
     functionVisibility: FunctionVisibility;
@@ -101,6 +105,7 @@ const nodeActionFunction = <
       | NodeServices.NodeServices
     >;
     resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+    observability?: Layer.Layer<never> | undefined;
   },
 ) =>
   RegisteredFunction.actionFunctionBase({
@@ -112,6 +117,7 @@ const nodeActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
     createLayer: (ctx) =>
       Layer.mergeAll(
         RegisteredFunction.actionLayer(databaseSchema, ctx),

package/src/internal/observability.ts

@@ -0,0 +1,27 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+import * as ConvexConfigProvider from "../ConvexConfigProvider.js";
+
+const memoMap = Layer.makeMemoMapUnsafe();
+export const scope = Scope.makeUnsafe();
+const layers = new WeakMap<Layer.Layer<never>, Layer.Layer<never>>();
+
+export const memoized = (layer: Layer.Layer<never>): Layer.Layer<never> => {
+  const cached = layers.get(layer);
+  if (cached !== undefined) return cached;
+  const built = Layer.buildWithMemoMap(layer, memoMap, scope).pipe(
+    Effect.provide(ConvexConfigProvider.layer),
+    // A failed first build is retried on the next invocation instead of failing every later one.
+    Effect.cachedWithTTL((exit) =>
+      Exit.isSuccess(exit) ? Duration.infinity : Duration.zero,
+    ),
+    Effect.runSync,
+    Effect.uninterruptible,
+    Layer.effectContext,
+  );
+  layers.set(layer, built);
+  return built;
+};