@requence/service 0.8.2-edge.1155 → 0.8.2-edge.1157

package/build/index.js

@@ -178,13 +178,27 @@ function isClaimCheckObject(data) {
 
 // ../helpers/src/utils/requenceCallback.ts
 import { z as z5 } from "zod/v4";
-var callbackObjectSchema = z5.object({
-  sourceId: z5.string(),
-  outputName: z5.string().nullable(),
-  propertyPath: z5.array(z5.union([z5.string(), z5.int()])),
-  callbackId: z5.uuid(),
-  __REQUENCE_type: z5.literal("RequenceCallback")
-});
+var REQUENCE_CALLBACK_TAG = "RequenceCallback";
+var callbackPathSchema = z5.array(z5.union([z5.string(), z5.int()]));
+var callbackObjectSchema = z5.discriminatedUnion("lifetime", [
+  z5.object({
+    __REQUENCE_type: z5.literal(REQUENCE_CALLBACK_TAG),
+    lifetime: z5.literal("connection"),
+    outputName: z5.string().nullable(),
+    propertyPath: callbackPathSchema,
+    sourceId: z5.string(),
+    callbackId: z5.uuid()
+  }),
+  z5.object({
+    __REQUENCE_type: z5.literal(REQUENCE_CALLBACK_TAG),
+    lifetime: z5.literal("durable"),
+    outputName: z5.string().nullable(),
+    propertyPath: callbackPathSchema,
+    name: z5.string(),
+    nodeId: z5.string(),
+    bound: z5.unknown().optional()
+  })
+]);
 function isCallbackObject(data) {
   return callbackObjectSchema.safeParse(data).success;
 }
@@ -200,6 +214,43 @@ function createCallback(callback) {
     }
   });
 }
+var DURABLE_CALLBACK_BINDING = Symbol.for("requence.durableCallbackBinding");
+function createDurableCallbackReference(binding) {
+  const reference = () => {
+    throw new Error(`durable callback "${binding.name}" was called in the service that emitted it — a durable callback reference is a value to emit, and it runs only when the graph invokes it`);
+  };
+  Object.defineProperty(reference, "name", {
+    value: binding.name,
+    configurable: true
+  });
+  return Object.defineProperty(reference, DURABLE_CALLBACK_BINDING, {
+    value: binding,
+    enumerable: false
+  });
+}
+function readDurableCallbackBinding(value) {
+  if (typeof value !== "function") {
+    return;
+  }
+  const binding = value[DURABLE_CALLBACK_BINDING];
+  return typeof binding === "object" && binding !== null && typeof binding.name === "string" ? binding : undefined;
+}
+function serviceCallbackQueueName(dispatchQueue) {
+  return `${dispatchQueue}-callbacks`;
+}
+var DURABLE_CALLBACK_INVOCATION_TTL_MS = 60000;
+var DURABLE_CALLBACK_QUEUE_ARGUMENTS = {
+  messageTtl: DURABLE_CALLBACK_INVOCATION_TTL_MS,
+  deadLetterExchange: "error"
+};
+var durableCallbackInvocationSchema = z5.object({
+  taskId: z5.uuid(),
+  nodeId: z5.string(),
+  name: z5.string(),
+  bound: z5.unknown().optional(),
+  arg: z5.unknown().optional(),
+  configuration: z5.unknown().optional()
+});
 
 // ../helpers/src/utils/serviceRender.ts
 import { z as z6 } from "zod/v4";
@@ -995,17 +1046,33 @@ function sanitizeLogData(data) {
 // ../callbacks/src/handler.ts
 function createRequenceCallbackHandler() {
   return {
-    tag: "RequenceCallback",
+    tag: REQUENCE_CALLBACK_TAG,
     canHandle: (value) => typeof value === "function",
     serialize(callback, ctx, path) {
+      const binding = readDurableCallbackBinding(callback);
+      if (binding) {
+        if (!ctx.nodeId) {
+          throw new Error(`durable callback "${binding.name}" cannot be emitted on this boundary (no ctx.nodeId) at path "${path.join(".")}"`);
+        }
+        return {
+          __REQUENCE_type: REQUENCE_CALLBACK_TAG,
+          lifetime: "durable",
+          name: binding.name,
+          nodeId: ctx.nodeId,
+          bound: binding.bound,
+          outputName: ctx.outputName ?? null,
+          propertyPath: [...path]
+        };
+      }
       if (!ctx.onCallback) {
         throw new Error(`functions are not serializable on this boundary (no ctx.onCallback) at path "${path.join(".")}"`);
       }
       return {
-        ...ctx.onCallback(callback),
+        ...ctx.onCallback(callback, path),
+        lifetime: "connection",
         outputName: ctx.outputName ?? null,
         propertyPath: [...path],
-        __REQUENCE_type: "RequenceCallback"
+        __REQUENCE_type: REQUENCE_CALLBACK_TAG
       };
     },
     isReference: (value) => isCallbackObject(value),
@@ -1189,6 +1256,10 @@ function createSurfaceHandlerValueHandler() {
     tag: SURFACE_HANDLER_TAG,
     canHandle: (value) => typeof value === "function",
     serialize(handler, ctx, path) {
+      const binding = readDurableCallbackBinding(handler);
+      if (binding) {
+        throw new Error(`durable callback "${binding.name}" was put in a surface's props at "${path.join(".") || "<root>"}" — a callback addresses a position in the node's output schema, so it cannot be a UI prop; write the prop's handler in the UI's defaults instead`);
+      }
       return ctx.onSurfaceHandler(handler, path);
     },
     isReference: (value) => isSurfaceHandlerObject(value),
@@ -1240,6 +1311,7 @@ function createOutboundBoundary(base) {
         maxFileSize: base.maxFileSize,
         measure,
         outputName: opts.outputName ?? null,
+        nodeId: base.nodeId,
         onCallback: opts.onCallback,
         inlineKeys: opts.inlineKeys,
         ...opts.bestEffort ? {
@@ -1292,6 +1364,114 @@ function createInboundBoundary(base = {}) {
   };
 }
 
+// src/callbackGrowth.ts
+var DEV_OVERLAY_FIRST_WARNING = 100;
+var DEPLOYED_FIRST_WARNING = 1000;
+var TOP_PATHS = 3;
+function advance(from, count) {
+  let next = from;
+  while (next <= count) {
+    next *= 10;
+  }
+  return next;
+}
+function formatWarning(params) {
+  const worst = [...params.perPath.entries()].sort(([, a], [, b]) => b - a).slice(0, TOP_PATHS).map(([path, count]) => `${path} (${count})`).join(", ");
+  return [
+    `Requence: the functions you yield are piling up in memory and nothing frees them.`,
+    ``,
+    `Each one is kept for as long as the task runs, and it holds on to everything it`,
+    `used from the code around it — including the whole value you were handling at`,
+    `the time. On a task that runs for days, this service runs out of memory.`,
+    ``,
+    `If a function only needs data, and not a live connection or an open stream,`,
+    `write it once at the top of your file and hand it the data each time:`,
+    ``,
+    `  const removeItem = createDurableCallback('removeItem', (arg, { id }) => ...)`,
+    ``,
+    `  yield { remove: removeItem.for({ id: item.id }) }`,
+    ``,
+    `Then there is one function, however many times you yield.`,
+    ``,
+    `  service:  ${params.service}`,
+    `  task:     ${params.taskId}`,
+    `  holding:  ${params.delivery} from this task, ${params.connection} in this service`,
+    `  worst:    ${worst}`
+  ].join(`
+`);
+}
+function createCallbackGrowthWatch({
+  service,
+  devOverlay,
+  connectionCount,
+  warn
+}) {
+  const first = devOverlay ? DEV_OVERLAY_FIRST_WARNING : DEPLOYED_FIRST_WARNING;
+  let nextConnection = first;
+  return {
+    forDelivery({ taskId }) {
+      let delivery = 0;
+      let nextDelivery = first;
+      const perPath = new Map;
+      return {
+        record(path) {
+          delivery += 1;
+          const key = formatPath(path);
+          perPath.set(key, (perPath.get(key) ?? 0) + 1);
+          const connection = connectionCount();
+          const crossedDelivery = delivery >= nextDelivery;
+          const crossedConnection = connection >= nextConnection;
+          if (!crossedDelivery && !crossedConnection) {
+            return;
+          }
+          if (crossedDelivery) {
+            nextDelivery = advance(nextDelivery, delivery);
+          }
+          if (crossedConnection) {
+            nextConnection = advance(nextConnection, connection);
+          }
+          warn(formatWarning({ service, taskId, delivery, connection, perPath }));
+        }
+      };
+    }
+  };
+}
+
+// src/durableCallback.ts
+var RESERVED_CONTEXT_KEY = "configuration";
+function assertBindable(name, bound) {
+  if (bound === undefined || bound === null) {
+    return;
+  }
+  if (typeof bound !== "object") {
+    throw new Error(`durable callback "${name}" bound a ${typeof bound} — the bound data IS the callback's context, so it has to be an object`);
+  }
+  if (Object.hasOwn(bound, RESERVED_CONTEXT_KEY)) {
+    throw new Error(`durable callback "${name}" bound a "${RESERVED_CONTEXT_KEY}" key — the bound data IS the callback's context, and that name is taken by the node's configuration`);
+  }
+}
+var durableCallbacks = new Map;
+function createDurableCallback(name, handler) {
+  if (durableCallbacks.has(name)) {
+    throw new Error(`two durable callbacks share the name "${name}" — the name is the whole address of a durable callback, so pick a distinct one`);
+  }
+  durableCallbacks.set(name, { handler });
+  const handle = createDurableCallbackReference({ name, bound: undefined });
+  return Object.assign(handle, {
+    for: (bound) => {
+      assertBindable(name, bound);
+      return createDurableCallbackReference({ name, bound });
+    }
+  });
+}
+function findDurableCallback(name) {
+  return durableCallbacks.get(name);
+}
+function durableCallbackContext(name, bound, configuration) {
+  assertBindable(name, bound);
+  return { ...bound, configuration };
+}
+
 // src/helpers.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 class RetryError extends Error {
@@ -1488,7 +1668,8 @@ var messageKeySchema = z9.string().transform((str) => deobfuscate(str)).pipe(z9.
   uploadUrl: arr[2] || undefined,
   streamUrl: arr[3] || undefined,
   maxPayloadSize: arr[4] && Number.isFinite(Number(arr[4])) ? Number(arr[4]) : undefined,
-  maxFileSize: arr[5] && Number.isFinite(Number(arr[5])) ? Number(arr[5]) : undefined
+  maxFileSize: arr[5] && Number.isFinite(Number(arr[5])) ? Number(arr[5]) : undefined,
+  nodeId: arr[6] || undefined
 }));
 var headerSchema = z9.object({
   properties: z9.object({
@@ -1509,6 +1690,7 @@ var payloadSchema = z9.object({
 }).transform((msg) => decodeWireBody(msg.content, msg.properties.contentType)).pipe(z9.object({
   input: z9.unknown().optional(),
   configuration: z9.unknown().optional(),
+  nodeId: z9.string().optional(),
   options: z9.object({
     uploadUrl: z9.url().optional(),
     streamUrl: z9.url().optional(),
@@ -1581,6 +1763,15 @@ function safeAck(channel, message) {
     }
   }
 }
+function invocationHeaders(payload, invokingNodeId) {
+  return {
+    ...invokingNodeId ? { invokingNodeId } : {},
+    ...payload.lifetime === "connection" ? { connectionId: payload.sourceId, callbackId: payload.callbackId } : { callbackName: payload.name, callbackNodeId: payload.nodeId }
+  };
+}
+function invocationPayload(payload, arg) {
+  return payload.lifetime === "connection" ? arg : { arg, bound: payload.bound };
+}
 function safeNack(channel, message) {
   try {
     channel.nack(message);
@@ -1615,7 +1806,7 @@ function createConnection({
       clientProperties: {
         ...connectionOptions?.clientProperties,
         ...buildServiceClientProperties({
-          libVersion: "javascript@0.8.2-edge.1155",
+          libVersion: "javascript@0.8.2-edge.1157",
           serviceVersion: version,
           name,
           devOverlay: Boolean(devOverlay)
@@ -1670,6 +1861,12 @@ function createConnection({
   const sentComponents = new Set;
   const generatorTerminators = new Map;
   const callbacks = new Map;
+  const callbackGrowth = createCallbackGrowthWatch({
+    service: baseQueue,
+    devOverlay: Boolean(devOverlay),
+    connectionCount: () => callbacks.size,
+    warn: (text) => simple_default.warn(text)
+  });
   const backchannelInbound = createInboundBoundary(passthroughByteReferences ? { transformer: passthroughInboundTransformer } : {});
   const channelWrapper = connection.createChannel({
     async setup(channel) {
@@ -1824,6 +2021,43 @@ function createConnection({
       });
     }
   });
+  async function runDurableCallbackInvocation(payload) {
+    const parsed = durableCallbackInvocationSchema.safeParse(payload);
+    if (!parsed.success) {
+      simple_default.error("Requence: dropped a malformed durable callback invocation — it does not name a callback this build can run");
+      return;
+    }
+    const { name: name2, bound, arg, configuration, taskId, nodeId } = parsed.data;
+    const registration = findDurableCallback(name2);
+    if (!registration) {
+      throw new Error(`no durable callback registered as "${name2}" — a reference naming it was emitted by node ${nodeId} of task ${taskId}, and this version declares none`);
+    }
+    await registration.handler(arg, durableCallbackContext(name2, bound, configuration));
+  }
+  const callbackQueue = serviceCallbackQueueName(queue);
+  const callbackChannelWrapper = connection.createChannel({
+    async setup(channel) {
+      await channel.assertQueue(callbackQueue, DURABLE_CALLBACK_QUEUE_ARGUMENTS);
+      await channel.bindQueue(callbackQueue, "service", callbackQueue);
+      await channel.prefetch(prefetch);
+      await channel.consume(callbackQueue, async (message) => {
+        if (!message) {
+          return;
+        }
+        try {
+          await runDurableCallbackInvocation(JSON.parse(message.content.toString()));
+        } catch (error) {
+          simple_default.error("Requence: durable callback threw:", error instanceof Error ? error.stack ?? error.message : error);
+        }
+        safeAck(channel, message);
+      });
+    }
+  });
+  callbackChannelWrapper.on("error", (err) => {
+    if (!silent) {
+      simple_default.error("Requence AMQP callback channel error:", err.message);
+    }
+  });
   handlerChannelWrapper.on("error", (err) => {
     if (!silent) {
       simple_default.error("Requence AMQP handler channel error:", err.message);
@@ -1917,7 +2151,7 @@ function createConnection({
       if (layer !== "props") {
         throw new Error(`a function in a render payload is only a handler under props or defaults (found at "${payloadPath.join(".")}")`);
       }
-      const { sourceId, callbackId } = deps.registerCallback(handler);
+      const { sourceId, callbackId } = deps.registerCallback(handler, payloadPath);
       return {
         __REQUENCE_type: SURFACE_HANDLER_TAG,
         lifetime: "connection",
@@ -2001,13 +2235,15 @@ function createConnection({
         };
         const payload = payloadSchema.parse(message);
         const abortController = new AbortController;
-        const registerCallback = (callback) => {
+        const growth = callbackGrowth.forDelivery({ taskId });
+        const registerCallback = (callback, path2) => {
           const callbackId = crypto.randomUUID();
           registeredCallbackIds.add(callbackId);
           callbacks.set(callbackId, {
             callback,
             onCallbackInvoke: dispatchInvocation
           });
+          growth.record(path2);
           return { sourceId: connectionId, callbackId };
         };
         const outbound = createOutboundBoundary({
@@ -2015,24 +2251,24 @@ function createConnection({
           streamUrl: payload.options.streamUrl,
           maxPayloadSize: payload.options.maxPayloadSize,
           maxFileSize: payload.options.maxFileSize,
+          nodeId: payload.nodeId,
           wireCodec: dispatchCodec,
           signal: abortController.signal,
           warn: (msg, error) => simple_default.warn(`${msg} (task ${taskId})`, error instanceof Error ? error.message : error ?? "")
         });
-        const dispatchInvocation = (params) => {
-          outbound.track(outbound.send(params.arg, {
-            outputName: params.outputName,
+        const dispatchInvocation = (invocation) => {
+          outbound.track(outbound.send(invocation.arg, {
+            outputName: invocation.outputName,
             onCallback: registerCallback
           }).then((data) => publish({
             index: 0,
             version,
             taskId,
             messageId,
-            data,
-            outputName: params.outputName,
-            connectionId: params.sourceId,
-            callbackId: params.callbackId,
-            propertyPath: params.propertyPath,
+            data: invocationPayload(invocation, data),
+            outputName: invocation.outputName,
+            propertyPath: invocation.propertyPath,
+            ...invocationHeaders(invocation, payload.nodeId),
             epoch
           })));
         };
@@ -2059,13 +2295,7 @@ function createConnection({
           passthroughByteReferences,
           sends: {
             ...buildSendApi(publishDeps),
-            invokeCallback: (ref, arg) => dispatchInvocation({
-              sourceId: ref.sourceId,
-              callbackId: ref.callbackId,
-              outputName: ref.outputName,
-              propertyPath: ref.propertyPath,
-              arg
-            }),
+            invokeCallback: (ref, arg) => dispatchInvocation({ ...ref, arg }),
             options: payload.options
           },
           onLog(debugMethod, data) {
@@ -2090,7 +2320,7 @@ function createConnection({
           onDefer(reason) {
             deferred = true;
             deferredReason = reason || null;
-            return obfuscate(taskId, messageId, payload.options.uploadUrl ?? "", payload.options.streamUrl ?? "", payload.options.maxPayloadSize?.toString() ?? "", payload.options.maxFileSize?.toString() ?? "");
+            return obfuscate(taskId, messageId, payload.options.uploadUrl ?? "", payload.options.streamUrl ?? "", payload.options.maxPayloadSize?.toString() ?? "", payload.options.maxFileSize?.toString() ?? "", payload.nodeId ?? "");
           },
           onCallback: dispatchInvocation
         });
@@ -2103,7 +2333,7 @@ function createConnection({
           begin: true,
           epoch,
           ...buildServiceIdentityHeaders({
-            libVersion: "javascript@0.8.2-edge.1155",
+            libVersion: "javascript@0.8.2-edge.1157",
             name
           })
         });
@@ -2327,6 +2557,7 @@ function createConnection({
   const api = {
     close: async () => {
       stopUIWatch?.();
+      await callbackChannelWrapper.close();
       await handlerChannelWrapper.close();
       await channelWrapper.close();
       await connection.close();
@@ -2346,29 +2577,30 @@ function createConnection({
       };
       const registeredCallbackIds = new Set;
       const outbound = createOutboundBoundary(options);
-      const registerCallback = (callback) => {
+      const growth = callbackGrowth.forDelivery({ taskId });
+      const registerCallback = (callback, path2) => {
         const callbackId = crypto.randomUUID();
         registeredCallbackIds.add(callbackId);
         callbacks.set(callbackId, {
           callback,
           onCallbackInvoke: dispatchInvocation
         });
+        growth.record(path2);
         return { sourceId: connectionId, callbackId };
       };
-      const dispatchInvocation = (params) => {
-        outbound.track(outbound.send(params.arg, {
-          outputName: params.outputName,
+      const dispatchInvocation = (invocation) => {
+        outbound.track(outbound.send(invocation.arg, {
+          outputName: invocation.outputName,
           onCallback: registerCallback
         }).then((data) => publish({
           index: 0,
           version,
           taskId,
           messageId,
-          data,
-          outputName: params.outputName,
-          connectionId: params.sourceId,
-          callbackId: params.callbackId,
-          propertyPath: params.propertyPath
+          data: invocationPayload(invocation, data),
+          outputName: invocation.outputName,
+          propertyPath: invocation.propertyPath,
+          ...invocationHeaders(invocation, options.nodeId)
         })));
       };
       const publishDeps = {
@@ -2517,30 +2749,36 @@ function asyncEventEmitter(initial = []) {
   context?.terminated.then(() => {
     terminated = true;
   });
-  let resolve2;
-  const initialValues = structuredClone(initial);
+  const queue = structuredClone(initial);
+  let waiting = null;
   return {
     push: (value) => {
-      if (resolve2) {
+      if (waiting) {
+        const resolve2 = waiting;
+        waiting = null;
         resolve2(value);
-      } else {
-        initialValues.push(value);
+        return;
       }
+      queue.push(value);
     },
     [Symbol.asyncIterator]() {
       return {
         async next() {
-          if (initialValues.length > 0) {
-            return { value: initialValues.shift(), done: false };
+          if (queue.length > 0) {
+            return { value: queue.shift(), done: false };
           }
           const defer = Promise.withResolvers();
-          resolve2 = defer.resolve;
+          waiting = defer.resolve;
           if (context) {
             const value = await Promise.race([
               defer.promise,
               context.terminated
             ]);
-            return terminated ? { done: true, value: undefined } : { done: false, value };
+            if (terminated) {
+              waiting = null;
+              return { done: true, value: undefined };
+            }
+            return { done: false, value };
           }
           return { value: await defer.promise, done: false };
         }
@@ -2643,6 +2881,7 @@ export {
   isUnreachableStatus,
   createUI,
   createService,
+  createDurableCallback,
   createCallback,
   asyncEventEmitter,
   assertReachable,
@@ -2655,5 +2894,5 @@ export {
   PayloadTooLargeError
 };
 
-//# debugId=D7A7D1B5373F4AAA64756E2164756E21
+//# debugId=B9ACB95FA979832B64756E2164756E21
 //# sourceMappingURL=index.js.map