@gaganref/confect-server 10.3.1-fork.6 → 10.3.1-fork.61

package/src/RegisteredConvexFunction.ts

@@ -61,12 +61,14 @@ export const prepare = (
   databaseSchema: DatabaseSchema.AnyWithProps,
   item: FunctionRegistryItem.ConfectFunctionRegistryItem,
   resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware> = [],
+  observability?: Layer.Layer<never>,
 ) =>
   Match.value(item.functionType).pipe(
     Match.when("query", () => {
       const definition = queryFunction({
         databaseSchema,
         name: item.name,
+        observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
         returns: item.returns,
@@ -84,6 +86,8 @@ export const prepare = (
       const definition = mutationFunction({
         databaseSchema,
         name: item.name,
+        reservedArgument: item.reservedArgument,
+        observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
         returns: item.returns,
@@ -100,6 +104,8 @@ export const prepare = (
     Match.when("action", () => {
       const definition = convexActionFunction(databaseSchema, {
         name: item.name,
+        reservedArgument: item.reservedArgument,
+        observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
         returns: item.returns,
@@ -188,6 +194,7 @@ const queryFunction = <
   error,
   handler,
   resolvedMiddlewares,
+  observability,
 }: {
   databaseSchema: DatabaseSchema_;
   name: string;
@@ -199,6 +206,7 @@ const queryFunction = <
     a: Args,
   ) => Effect.Effect<Returns, E, Handler.QueryServices<DatabaseSchema_>>;
   resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+  observability?: Layer.Layer<never> | undefined;
 }) => ({
   args: compileArgsSchema(args, databaseSchema.target.scope),
   returns: compileReturnsSchema(returns, databaseSchema.target.scope),
@@ -258,6 +266,9 @@ const queryFunction = <
         RegisteredFunction.combineErrorSchemas(error, resolvedMiddlewares),
         {
           scheduler: new EffectScheduler.MixedScheduler("sync"),
+          invocation: Effect.promise(() => ctx.meta.getFunctionMetadata()),
+          clock: observability === undefined ? undefined : queryClock,
+          observability,
         },
       ),
     ),
@@ -274,6 +285,7 @@ export const mutationLayer = <Schema extends DatabaseSchema.AnyWithProps>(
     RequestMetadata.layer(ctx.meta),
     TransactionMetadata.layer(ctx.meta),
     Auth.layerForTarget<Schema["target"]>(schema.target, ctx.auth),
+    Auth.mutationLayer(ctx.auth),
     Scheduler.layer<DatabaseSchema.Scope<Schema>>(
       ctx.scheduler,
       schema.target.scope,
@@ -313,9 +325,12 @@ const mutationFunction = <
   error,
   handler,
   resolvedMiddlewares,
+  observability,
+  reservedArgument,
 }: {
   databaseSchema: DatabaseSchema_;
   name: string;
+  reservedArgument?: string | undefined;
   functionVisibility: FunctionVisibility;
   args: Schema.Codec<Args, ConvexArgs>;
   returns: Schema.Codec<Returns, ConvexReturns>;
@@ -324,8 +339,14 @@ const mutationFunction = <
     a: Args,
   ) => Effect.Effect<Returns, E, MutationServices<DatabaseSchema_>>;
   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<
@@ -335,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),
       );
@@ -360,6 +381,12 @@ const mutationFunction = <
         RegisteredFunction.combineErrorSchemas(error, resolvedMiddlewares),
         {
           scheduler: new EffectScheduler.MixedScheduler("sync"),
+          invocation: RegisteredFunction.invocationMetadata(
+            ctx.meta,
+            actualArgs,
+            reservedArgument,
+          ),
+          observability,
         },
       ),
     ),
@@ -382,8 +409,11 @@ const convexActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
+    reservedArgument,
   }: {
     name: string;
+    reservedArgument?: string | undefined;
     functionVisibility: FunctionVisibility;
     args: Schema.Codec<Args, ConvexArgs>;
     returns: Schema.Codec<Returns, ConvexReturns>;
@@ -396,6 +426,7 @@ const convexActionFunction = <
       RegisteredFunction.ActionServices<DatabaseSchema_>
     >;
     resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+    observability?: Layer.Layer<never> | undefined;
   },
 ) =>
   RegisteredFunction.actionFunctionBase({
@@ -407,6 +438,8 @@ const convexActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
+    reservedArgument,
     createLayer: (ctx) =>
       Layer.mergeAll(
         RegisteredFunction.actionLayer(schema, ctx),

package/src/RegisteredFunction.ts

@@ -1,3 +1,6 @@
+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";
 import * as IdScope from "@confect/core/IdScope";
 import type * as FunctionProvenance from "@confect/core/FunctionProvenance";
@@ -9,6 +12,8 @@ import {
 import {
   type DefaultFunctionArgs,
   type FunctionVisibility,
+  type FunctionMetadata,
+  type MutationMeta,
   type GenericActionCtx,
   type GenericDataModel,
   type StorageReader as ConvexStorageReader,
@@ -19,8 +24,15 @@ 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";
+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";
@@ -41,9 +53,50 @@ 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 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 },
+);
+
 export type Any =
   | RegisteredQuery<FunctionVisibility, DefaultFunctionArgs, any>
   | RegisteredMutation<FunctionVisibility, DefaultFunctionArgs, any>
@@ -183,67 +236,150 @@ 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 & { readonly received?: ReceivedValue }
+          >
+        | 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;
+    let undeclared: { readonly error: unknown } | 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),
+          );
+          // An encoding failure is a defect, even when it dies with a ConvexError.
+          if (Exit.isFailure(encodedError)) {
+            const encoding = encodedError.cause;
+            return yield* Cause.squash(encoding) instanceof ConvexError
+              ? Effect.die(
+                  new Error(Cause.pretty(encoding), { cause: encoding }),
+                )
+              : Effect.orDie(encodedError);
+          }
+        }
+        // With no error schema a failure is a defect, so the root span ends as one.
+        if (
+          reason?._tag === "Fail" &&
+          errorSchema === undefined &&
+          !(reason.error instanceof ConvexError)
+        ) {
+          undeclared = { error: reason.error };
+          return yield* Effect.die(reason.error);
+        }
+      }),
     );
-
-    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, 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)) {
+          return Result.succeed(exit.value);
+        }
+        if (undeclared !== undefined)
+          return yield* Effect.die(undeclared.error);
+
+        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(
@@ -256,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,
@@ -274,8 +420,11 @@ export const actionFunctionBase = <
   resolvedMiddlewares = [],
   createLayer,
   scope = IdScope.app,
+  observability,
+  reservedArgument,
 }: {
   name: string;
+  reservedArgument?: string | undefined;
   functionVisibility: FunctionVisibility;
   args: Schema.Codec<Args, ConvexArgs>;
   returns: Schema.Codec<Returns, ConvexReturns>;
@@ -286,8 +435,9 @@ 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),
+  args: compileArgsSchema(args, scope, reservedArgument, name),
   returns: compileReturnsSchema(returns, scope),
   handler: (
     ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
@@ -295,10 +445,16 @@ export const actionFunctionBase = <
   ): Promise<ConvexReturns> =>
     Effect.gen(function* () {
       const decodedArgs = yield* pipe(
-        actualArgs,
+        domainArgs(actualArgs, reservedArgument),
         Schema.decodeUnknownEffect(args),
         Effect.catchTag("SchemaError", Effect.die),
       );
+      const restricted = resolvedMiddlewares.some(
+        ({ middlewareSpec }) =>
+          middlewareSpec.key === ActionCallSpec.Middleware.key,
+      )
+        ? restrict(ctx)
+        : undefined;
       // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context -- Middleware errors are intentionally erased here and validated by runHandlerPromise against the combined error schema below.
       const decodedReturns = yield* applyMiddleware(
         handler(decodedArgs),
@@ -309,13 +465,19 @@ export const actionFunctionBase = <
           functionVisibility,
           args: decodedArgs,
         },
-      ).pipe(Effect.provide(createLayer(ctx)));
+      ).pipe(Effect.provide(createLayer(restricted?.ctx ?? ctx)));
+      if (restricted !== undefined) yield* restricted.check;
       return yield* pipe(
         decodedReturns,
         Schema.encodeEffect(returns),
         Effect.catchTag("SchemaError", Effect.die),
       );
-    }).pipe(runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares))),
+    }).pipe(
+      runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares), {
+        invocation: invocationMetadata(ctx.meta, actualArgs, reservedArgument),
+        observability,
+      }),
+    ),
 });
 
 export type ActionServices<
@@ -389,3 +551,47 @@ export const storageLayer = <Scope extends IdScope.IdScope>(
   Storage.layer(reader) as Layer.Layer<
     Storage.Storage | StorageReader.ForScope<Scope>
   >;
+
+/**
+ * Shares one dispatch budget across the entire middleware chain.
+ */
+const restrict = <Model extends GenericDataModel>(
+  ctx: GenericActionCtx<Model>,
+) => {
+  let dispatched = false;
+  const claim = () => {
+    if (dispatched) throw new ActionCall.ActionCallAlreadyUsed();
+    dispatched = true;
+  };
+  const restricted: GenericActionCtx<Model> = {
+    ...ctx,
+    scheduler: {
+      runAfter: () => {
+        throw new ActionCall.SchedulingNotAllowed();
+      },
+      runAt: () => {
+        throw new ActionCall.SchedulingNotAllowed();
+      },
+      cancel: () => {
+        throw new ActionCall.SchedulingNotAllowed();
+      },
+    },
+    runQuery: (...args) => {
+      claim();
+      return ctx.runQuery(...args);
+    },
+    runMutation: (...args) => {
+      claim();
+      return ctx.runMutation(...args);
+    },
+    runAction: () => {
+      throw new ActionCall.NestedActionNotAllowed();
+    },
+  };
+  return {
+    ctx: restricted,
+    check: Effect.suspend(() =>
+      dispatched ? Effect.void : Effect.die(new ActionCall.ActionCallNotUsed()),
+    ),
+  };
+};

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,8 @@ export const make = (
   return genericFunction(
     nodeActionFunction(databaseSchema, {
       name: item.name,
+      reservedArgument: item.reservedArgument,
+      observability,
       functionVisibility: item.functionVisibility,
       args: item.args,
       returns: item.returns,
@@ -86,8 +90,11 @@ const nodeActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
+    reservedArgument,
   }: {
     name: string;
+    reservedArgument?: string | undefined;
     functionVisibility: FunctionVisibility;
     args: Schema.Codec<Args, ConvexArgs>;
     returns: Schema.Codec<Returns, ConvexReturns>;
@@ -101,6 +108,7 @@ const nodeActionFunction = <
       | NodeServices.NodeServices
     >;
     resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+    observability?: Layer.Layer<never> | undefined;
   },
 ) =>
   RegisteredFunction.actionFunctionBase({
@@ -112,6 +120,8 @@ const nodeActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
+    reservedArgument,
     createLayer: (ctx) =>
       Layer.mergeAll(
         RegisteredFunction.actionLayer(databaseSchema, ctx),

package/src/RegistryItems.ts

@@ -38,3 +38,34 @@ export const middlewareKeys = (items: RegistryItems): ReadonlyArray<string> =>
     Array.filter(MiddlewareRegistryItem.isMiddlewareRegistryItem),
     Array.map((item) => item.middlewareSpec.key),
   );
+
+export interface MissingMiddleware {
+  readonly functionName: string;
+  readonly middlewareKey: string;
+}
+
+export const missingRequired = (
+  items: RegistryItems,
+  required: ReadonlyArray<{ readonly key: string }>,
+  groupPath = "",
+): ReadonlyArray<MissingMiddleware> =>
+  Object.entries(items)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .flatMap(([functionName, value]) =>
+      FunctionRegistryItem.isFunctionRegistryItem(value)
+        ? required.flatMap(({ key }) =>
+            value._tag === "Confect" &&
+            value.middlewareAttachments.some(({ spec }) => spec.key === key)
+              ? []
+              : [
+                  {
+                    functionName:
+                      groupPath === ""
+                        ? functionName
+                        : `${groupPath}.${functionName}`,
+                    middlewareKey: key,
+                  },
+                ],
+          )
+        : [],
+    );