hobots 1.3.2 → 1.3.4

package/README.md

@@ -48,7 +48,7 @@ Hobots.init({
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
-  ctx.log('info', 'começando…');
+  ctx.log.info('começando…');
   return { processadas: 12 };
 });
 
@@ -235,9 +235,9 @@ Hobots.init({
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
-  ctx.log('info', `processando lote ${params.lote}…`);
+  ctx.log.info(`processando lote ${params.lote}…`);
   if (ctx.signal.aborted) return;   // cancelamento cooperativo
-  ctx.log('info', '12 notas processadas');
+  ctx.log.info('12 notas processadas');
 });
 
 Hobots.start(); // começa o polling e MANTÉM O PROCESSO VIVO
@@ -277,7 +277,7 @@ interface RunContext {
 ```
 
 - **`params`** — os dados do formulário configurado no app (JSON validado). Tipável: `Hobots.register<{ lote: number }>(...)`.
-- **`ctx.log(level, message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run quase em tempo real.
+- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run quase em tempo real.
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**.
 - **Retorno** — **ignorado**: o SDK não captura nem envia o valor retornado pelo handler (resultados podem conter dados sensíveis e não são coletados).
 - **Erro lançado** — a run é reportada como `failed` (mensagem cap 10k, stack 20k).
@@ -292,7 +292,7 @@ Uma run cancelada no app **não mata** o handler — o SDK apenas dispara `ctx.s
 Hobots.register('processar-nfe', async (params, ctx) => {
   for (const nota of params.notas) {
     if (ctx.signal.aborted) {
-      ctx.log('warning', 'cancelamento detectado — parando');
+      ctx.log.warn('cancelamento detectado — parando');
       return;
     }
     await processar(nota);

package/dist/index.cjs

@@ -111,7 +111,7 @@ function parseStacktrace(stack) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.3.2" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.3.3" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -433,28 +433,61 @@ var Heartbeat = class {
   }
 };
 
+// src/internal-handlers.ts
+var INTERNAL = /* @__PURE__ */ Symbol.for("hobots.sdk.internalListener");
+function markInternal(listener) {
+  listener[INTERNAL] = true;
+  return listener;
+}
+function externalListenerCount(event) {
+  const listeners = process.listeners(event);
+  return listeners.filter((listener) => !listener[INTERNAL]).length;
+}
+var emergencyTasks = [];
+function addEmergencyTask(task) {
+  emergencyTasks.push(task);
+}
+async function awaitEmergencyTasks(capMs) {
+  if (emergencyTasks.length === 0) return;
+  await Promise.race([Promise.allSettled(emergencyTasks), sleep(capMs)]);
+}
+
 // src/instrument.ts
+var EMERGENCY_REPORT_CAP_MS = 3e3;
 var installed = false;
+function hasInstalledGlobalHandlers() {
+  return installed;
+}
 function installGlobalHandlers(client2, getScope) {
   if (installed) return;
   installed = true;
   if (isNode()) {
-    process.on("uncaughtException", (error) => {
-      client2.captureException(error, { level: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
-      void client2.flush(2e3).then(() => {
-        if (process.listenerCount("uncaughtException") <= 1) {
-          console.error(error);
-          process.exit(1);
-        }
-      });
-    });
-    process.on("unhandledRejection", (reason) => {
-      client2.captureException(reason, { level: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
-      void client2.flush(2e3);
-    });
-    process.on("beforeExit", () => {
-      void client2.flush(2e3);
-    });
+    process.on(
+      "uncaughtException",
+      markInternal((error) => {
+        client2.captureException(error, { level: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
+        void client2.flush(2e3).then(async () => {
+          if (externalListenerCount("uncaughtException") === 0) {
+            await awaitEmergencyTasks(EMERGENCY_REPORT_CAP_MS);
+            console.error(error);
+            process.exit(1);
+          }
+        });
+      })
+    );
+    process.on(
+      "unhandledRejection",
+      markInternal((reason) => {
+        client2.captureException(reason, { level: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
+        void client2.flush(2e3);
+      })
+    );
+    process.on(
+      "beforeExit",
+      markInternal(() => {
+        void client2.flush(2e3);
+      })
+    );
     return;
   }
   if (typeof window !== "undefined") {
@@ -750,25 +783,76 @@ var ManagerApi = class {
       await sleep(delay);
     }
   }
+  /**
+   * Um único PATCH com timeout curto — exit path (o processo está morrendo, o retry
+   * ladder do updateRun é proibido aqui). Status HTTP é ignorado: 409/404 significa
+   * que a run já foi cancelada/finalizada, o que é aceitável nesse caminho.
+   */
+  async updateRunOnce(runId, update, timeoutMs = 2e3) {
+    await fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+      method: "PATCH",
+      headers: this.headers(),
+      body: JSON.stringify(update),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  }
 };
 
 // src/manager/context.ts
+function runCanceledError() {
+  return Object.assign(new Error("execu\xE7\xE3o cancelada"), { name: "RunCanceled" });
+}
+function cancelableSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(runCanceledError());
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(runCanceledError());
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 var DEFAULT_LOG_FLUSH_INTERVAL_MS = 2e3;
+var DEFAULT_CANCEL_CHECK_INTERVAL_MS = 5e3;
+var MIN_CANCEL_CHECK_INTERVAL_MS = 1e3;
+var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
 var MAX_LOG_MESSAGE_CHARS = 1e4;
 var MAX_LOGS_PER_RUN = 500;
 var MAX_LOGS_PER_PATCH = 100;
 var FLUSH_AT_BUFFERED = 20;
 var RunReporter = class {
-  constructor(api, runId, task, logger, flushIntervalMs) {
+  constructor(api, runId, task, logger, flushIntervalMs, cancelCheckIntervalMs) {
     this.api = api;
     this.runId = runId;
     this.logger = logger;
     this.flushIntervalMs = flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS;
+    this.cancelCheckIntervalMs = Math.min(
+      MAX_CANCEL_CHECK_INTERVAL_MS,
+      Math.max(MIN_CANCEL_CHECK_INTERVAL_MS, cancelCheckIntervalMs ?? DEFAULT_CANCEL_CHECK_INTERVAL_MS)
+    );
+    const log = {
+      debug: (message) => this.log("debug", message),
+      info: (message) => this.log("info", message),
+      warn: (message) => this.log("warning", message),
+      error: (message) => this.log("error", message)
+    };
+    const signal = this.abortController.signal;
     this.context = {
       runId,
       task,
-      log: (level, message) => this.log(level, message),
-      signal: this.abortController.signal
+      log,
+      signal,
+      throwIfCanceled: () => {
+        if (signal.aborted) throw runCanceledError();
+      },
+      sleep: (ms) => cancelableSleep(ms, signal)
     };
   }
   context;
@@ -777,16 +861,31 @@ var RunReporter = class {
   droppedCount = 0;
   dead = false;
   chain = Promise.resolve();
+  pendingUpdates = 0;
   timer;
+  watchTimer;
   abortController = new AbortController();
   flushIntervalMs;
+  cancelCheckIntervalMs;
   get isDead() {
     return this.dead;
   }
   /** Aborta o ctx.signal sem matar o reporter (timeout/shutdown ainda reportam o terminal). */
   abort() {
+    this.stopCancelWatch();
     if (!this.abortController.signal.aborted) this.abortController.abort();
   }
+  /**
+   * Mata o reporter de vez: aborta o signal e suprime todo reporte futuro.
+   * Usado no exit path — depois que o agente reportou AgentTerminated por fora
+   * da fila, um handler zumbi não pode reenviar status por cima.
+   */
+  kill() {
+    this.abort();
+    this.dead = true;
+    this.clearFlushTimer();
+    this.buffer = [];
+  }
   log(level, message) {
     if (this.dead) return;
     if (this.loggedCount >= MAX_LOGS_PER_RUN) {
@@ -841,22 +940,45 @@ var RunReporter = class {
   async reportRunning() {
     this.enqueue({ status: "running" });
     await this.chain;
+    if (!this.dead) this.startCancelWatch();
     return !this.dead;
   }
   reportSuccess() {
+    this.stopCancelWatch();
     this.clearFlushTimer();
     this.enqueue({ status: "succeeded", logs: this.takeLogs() });
   }
   reportFailure(error) {
+    this.stopCancelWatch();
     this.clearFlushTimer();
     this.enqueue({ status: "failed", error, logs: this.takeLogs() });
   }
+  /**
+   * Heartbeat de cancelamento: enquanto o handler roda, um PATCH 'running' vazio
+   * periódico faz o servidor responder 409 se a run foi cancelada no app — o que
+   * mata o reporter e dispara ctx.signal, mesmo em handlers que nunca logam.
+   */
+  startCancelWatch() {
+    if (this.watchTimer) return;
+    this.watchTimer = setInterval(() => {
+      if (this.dead || this.pendingUpdates > 0 || this.buffer.length > 0) return;
+      this.enqueue({ status: "running" });
+    }, this.cancelCheckIntervalMs);
+    unrefTimer(this.watchTimer);
+  }
+  stopCancelWatch() {
+    if (this.watchTimer) {
+      clearInterval(this.watchTimer);
+      this.watchTimer = void 0;
+    }
+  }
   /** Aguarda a fila de PATCHes esvaziar (chame depois do terminal). */
   finalize() {
     return this.chain;
   }
   enqueue(update) {
     if (this.dead) return;
+    this.pendingUpdates++;
     this.chain = this.chain.then(async () => {
       if (this.dead) return;
       const payload = update.logs && update.logs.length === 0 ? { ...update, logs: void 0 } : update;
@@ -865,6 +987,7 @@ var RunReporter = class {
       } catch (error) {
         if (error instanceof ManagerApiError && (error.status === 409 || error.status === 404)) {
           this.dead = true;
+          this.stopCancelWatch();
           this.abort();
           this.buffer = [];
           this.logger.warn(`run ${this.runId} cancelada/removida no servidor \u2014 reporte suprimido`);
@@ -872,10 +995,56 @@ var RunReporter = class {
         }
         this.logger.error(`update da run ${this.runId} perdido:`, error);
       }
+    }).finally(() => {
+      this.pendingUpdates--;
     });
   }
 };
 
+// src/manager/shutdown.ts
+var WATCHED_SIGNALS = ["SIGINT", "SIGTERM"];
+function installShutdownHandlers(agent2) {
+  if (!isNode()) return () => {
+  };
+  let signaled = false;
+  const signalHandlers = /* @__PURE__ */ new Map();
+  for (const signal of WATCHED_SIGNALS) {
+    const handler = markInternal(() => {
+      if (externalListenerCount(signal) > 0) return;
+      if (signaled) return;
+      signaled = true;
+      const reraise = () => {
+        process.removeListener(signal, handler);
+        process.kill(process.pid, signal);
+      };
+      if (agent2.activeCount === 0) {
+        reraise();
+        return;
+      }
+      const report = agent2.reportAgentTerminated(`o processo do agente recebeu ${signal} durante a execu\xE7\xE3o`);
+      addEmergencyTask(report);
+      void report.finally(reraise);
+    });
+    process.on(signal, handler);
+    signalHandlers.set(signal, handler);
+  }
+  const onFatal = markInternal((error) => {
+    const report = agent2.activeCount > 0 ? agent2.reportAgentTerminated("o processo do agente morreu com um erro n\xE3o tratado durante a execu\xE7\xE3o") : Promise.resolve();
+    addEmergencyTask(report);
+    if (!hasInstalledGlobalHandlers() && externalListenerCount("uncaughtException") === 0) {
+      void report.finally(() => {
+        console.error(error);
+        process.exit(1);
+      });
+    }
+  });
+  process.on("uncaughtException", onFatal);
+  return () => {
+    for (const [signal, handler] of signalHandlers) process.removeListener(signal, handler);
+    process.removeListener("uncaughtException", onFatal);
+  };
+}
+
 // src/manager/agent.ts
 var DEFAULT_POLL_INTERVAL_MS = 5e3;
 var MIN_POLL_INTERVAL_MS = 1e3;
@@ -898,6 +1067,7 @@ var ManagerAgent = class {
     this.instanceId = options.instanceId;
     this.taskTimeoutMs = options.taskTimeoutMs;
     this.logFlushIntervalMs = options.logFlushIntervalMs;
+    this.cancelCheckIntervalMs = options.cancelCheckIntervalMs;
     this.logger.debug("agente configurado", { baseUrl: config.managerBaseUrl });
   }
   logger;
@@ -907,6 +1077,7 @@ var ManagerAgent = class {
   instanceId;
   taskTimeoutMs;
   logFlushIntervalMs;
+  cancelCheckIntervalMs;
   state = "idle";
   timer;
   pollAbort;
@@ -914,6 +1085,7 @@ var ManagerAgent = class {
   consecutiveAuthFailures = 0;
   activeRuns = /* @__PURE__ */ new Set();
   reporters = /* @__PURE__ */ new Set();
+  uninstallShutdown;
   get activeCount() {
     return this.activeRuns.size;
   }
@@ -926,6 +1098,9 @@ var ManagerAgent = class {
       throw new Error("[hobots-manager] nenhuma task registrada \u2014 chame register() antes de start()");
     }
     this.state = "started";
+    if (this.options.installExitHandlers !== false && !this.uninstallShutdown) {
+      this.uninstallShutdown = installShutdownHandlers(this);
+    }
     this.logger.debug(`polling iniciado (tasks: ${[...this.registry.keys()].join(", ")})`);
     this.schedule(0);
   }
@@ -942,11 +1117,32 @@ var ManagerAgent = class {
     const finished = timeoutMs > 0 ? await Promise.race([all, sleep(timeoutMs).then(() => false)]) : false;
     if (!finished && this.activeRuns.size > 0) {
       this.logger.warn(`${this.activeRuns.size} run(s) ainda em execu\xE7\xE3o ap\xF3s ${timeoutMs}ms \u2014 abandonando a espera`);
-      for (const reporter of this.reporters) reporter.abort();
+      await this.reportAgentTerminated("agente encerrado durante a execu\xE7\xE3o (shutdown excedeu o tempo de espera)");
     }
+    this.uninstallShutdown?.();
+    this.uninstallShutdown = void 0;
     this.state = "idle";
     return finished;
   }
+  /**
+   * Best-effort do exit path: reporta 'failed'/AgentTerminated para as runs ativas
+   * antes do processo morrer, fora da fila do reporter e com timeout curto. Runs já
+   * canceladas no app (reporter morto) são puladas; erros de rede são engolidos —
+   * o sweep server-side é o backstop.
+   */
+  async reportAgentTerminated(message, timeoutMs = 2500) {
+    const pending = [];
+    for (const reporter of this.reporters) {
+      if (reporter.isDead) continue;
+      reporter.kill();
+      pending.push(
+        this.api.updateRunOnce(reporter.context.runId, { status: "failed", error: { type: "AgentTerminated", message } }, timeoutMs).catch(() => {
+        })
+      );
+    }
+    if (pending.length === 0) return;
+    await Promise.race([Promise.allSettled(pending), sleep(timeoutMs)]);
+  }
   /** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
   schedule(delayMs) {
     if (this.state !== "started" || this.timer) return;
@@ -1013,7 +1209,7 @@ var ManagerAgent = class {
     this.activeRuns.add(promise);
   }
   async executeRun(run) {
-    const reporter = new RunReporter(this.api, run.id, run.task, this.logger, this.logFlushIntervalMs);
+    const reporter = new RunReporter(this.api, run.id, run.task, this.logger, this.logFlushIntervalMs, this.cancelCheckIntervalMs);
     this.reporters.add(reporter);
     try {
       const handler = this.registry.get(run.task);