hobots 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -21,6 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Client: () => Client,
+  ManagerAgent: () => ManagerAgent,
+  ManagerApi: () => ManagerApi,
+  ManagerApiError: () => ManagerApiError,
   Scope: () => Scope,
   Span: () => Span,
   Transaction: () => Transaction,
@@ -33,12 +36,15 @@ __export(src_exports, {
   getClient: () => getClient,
   init: () => init,
   parseDsn: () => parseDsn,
+  register: () => register,
   setContext: () => setContext,
   setExtra: () => setExtra,
   setTag: () => setTag,
   setTags: () => setTags,
   setUser: () => setUser,
+  start: () => start,
   startTransaction: () => startTransaction,
+  stop: () => stop,
   withMonitor: () => withMonitor,
   withScope: () => withScope
 });
@@ -60,11 +66,13 @@ function parseDsnUrl(dsn, prefix) {
   return { key, path, origin: `${url.protocol}//${url.host}` };
 }
 function parseDsn(dsn) {
-  const { key, path, origin } = parseDsnUrl(dsn, "[hobots-monitor]");
+  const { key, path, origin } = parseDsnUrl(dsn, "[hobots]");
   return {
-    publicKey: key,
-    projectId: path,
-    endpoint: `${origin}/api/ingest/${key}`
+    key,
+    projectSlug: path,
+    origin,
+    ingestEndpoint: `${origin}/api/ingest`,
+    managerBaseUrl: `${origin}/api/manager`
   };
 }
 
@@ -188,6 +196,7 @@ var DEFAULT_MAX_BATCH_SIZE = 10;
 var DEFAULT_MAX_QUEUE_SIZE = 200;
 var Transport = class {
   endpoint;
+  key;
   logger;
   flushIntervalMs;
   maxBatchSize;
@@ -198,6 +207,7 @@ var Transport = class {
   closed = false;
   constructor(options) {
     this.endpoint = options.endpoint;
+    this.key = options.key;
     this.logger = options.logger;
     this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
     this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
@@ -250,7 +260,7 @@ var Transport = class {
       try {
         const response = await fetch(this.endpoint, {
           method: "POST",
-          headers: { "content-type": "application/json" },
+          headers: { "content-type": "application/json", authorization: `Bearer ${this.key}` },
           body: JSON.stringify(envelope)
         });
         if (response.ok) {
@@ -306,7 +316,8 @@ var Client = class {
     this.logger = makeLogger(!!options.debug);
     this.dsn = parseDsn(options.dsn);
     this.transport = new Transport({
-      endpoint: this.dsn.endpoint,
+      endpoint: this.dsn.ingestEndpoint,
+      key: this.dsn.key,
       logger: this.logger,
       flushIntervalMs: options.flushIntervalMs,
       maxBatchSize: options.maxBatchSize
@@ -341,7 +352,6 @@ var Client = class {
       level: hint?.level ?? event.level ?? scope2.level ?? "error",
       release: event.release ?? this.options.release,
       environment: event.environment ?? this.options.environment ?? "production",
-      server_name: event.server_name ?? this.options.serverName,
       tags: Object.keys(tags).length > 0 ? tags : void 0,
       extra: Object.keys(extra).length > 0 ? extra : void 0,
       user: event.user ?? scope2.user,
@@ -357,7 +367,6 @@ var Client = class {
         ...payload,
         release: payload.release ?? this.options.release,
         environment: payload.environment ?? this.options.environment ?? "production",
-        server_name: payload.server_name ?? this.options.serverName,
         tags: { ...this.options.tags, ...payload.tags }
       }
     });
@@ -367,12 +376,16 @@ var Client = class {
       type: "check_in",
       payload: {
         ...payload,
+        release: payload.release ?? this.options.release,
         environment: payload.environment ?? this.options.environment ?? "production"
       }
     });
   }
   sendHeartbeat(payload) {
-    this.transport.enqueue({ type: "heartbeat", payload });
+    this.transport.enqueue({
+      type: "heartbeat",
+      payload: { ...payload, release: payload.release ?? this.options.release }
+    });
   }
   flush(timeoutMs) {
     return this.transport.flush(timeoutMs);
@@ -384,19 +397,12 @@ var Client = class {
 
 // src/heartbeat.ts
 var DEFAULT_INTERVAL_MS = 3e4;
-function defaultInstanceId() {
-  if (isNode()) {
-    const host = process.env.HOSTNAME || process.env.COMPUTERNAME;
-    if (host) return host;
-  }
-  return `instance-${uuid4().slice(0, 8)}`;
-}
 var Heartbeat = class {
-  constructor(client2, options = {}, serverName) {
+  constructor(client2, options = {}, instanceId) {
     this.client = client2;
     this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
-    this.instanceId = options.instanceId ?? serverName ?? defaultInstanceId();
-    this.name = options.name ?? this.instanceId;
+    this.instanceId = instanceId;
+    this.name = options.name ?? instanceId;
     this.metadata = options.metadata;
   }
   intervalMs;
@@ -677,27 +683,437 @@ async function withMonitorImpl(client2, captureError, monitorSlug, fn, options)
   }
 }
 
+// src/manager/api.ts
+var RETRY_DELAYS_MS2 = [1e3, 4e3, 16e3];
+var ManagerApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ManagerApiError";
+  }
+};
+var ManagerApi = class {
+  baseUrl;
+  key;
+  logger;
+  constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.key = options.key;
+    this.logger = options.logger;
+  }
+  headers() {
+    return {
+      "content-type": "application/json",
+      authorization: `Bearer ${this.key}`
+    };
+  }
+  /** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
+  async poll(request, signal) {
+    const response = await fetch(`${this.baseUrl}/poll`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(request),
+      signal
+    });
+    if (!response.ok) {
+      throw new ManagerApiError(`poll falhou (HTTP ${response.status})`, response.status);
+    }
+    return await response.json();
+  }
+  /**
+   * PATCH de status/logs com retry em falha de rede/5xx/429.
+   * 4xx é definitivo e vira ManagerApiError imediato (409 = run cancelada/transição inválida).
+   */
+  async updateRun(runId, update) {
+    for (let attempt = 0; ; attempt++) {
+      let retriable;
+      try {
+        const response = await fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}`, {
+          method: "PATCH",
+          headers: this.headers(),
+          body: JSON.stringify(update)
+        });
+        if (response.ok) return;
+        if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+          throw new ManagerApiError(`update rejeitado (HTTP ${response.status})`, response.status);
+        }
+        retriable = new Error(`HTTP ${response.status}`);
+      } catch (error) {
+        if (error instanceof ManagerApiError) throw error;
+        retriable = error;
+      }
+      const delay = RETRY_DELAYS_MS2[attempt];
+      if (delay === void 0) {
+        throw new Error(`update da run ${runId} descartado ap\xF3s retries: ${String(retriable)}`);
+      }
+      this.logger.warn(`falha no update da run ${runId} (${String(retriable)}), retry em ${delay}ms`);
+      await sleep(delay);
+    }
+  }
+};
+
+// src/manager/context.ts
+var DEFAULT_LOG_FLUSH_INTERVAL_MS = 2e3;
+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) {
+    this.api = api;
+    this.runId = runId;
+    this.logger = logger;
+    this.flushIntervalMs = flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS;
+    this.context = {
+      runId,
+      task,
+      log: (level, message) => this.log(level, message),
+      signal: this.abortController.signal
+    };
+  }
+  context;
+  buffer = [];
+  loggedCount = 0;
+  droppedCount = 0;
+  dead = false;
+  chain = Promise.resolve();
+  timer;
+  abortController = new AbortController();
+  flushIntervalMs;
+  get isDead() {
+    return this.dead;
+  }
+  /** Aborta o ctx.signal sem matar o reporter (timeout/shutdown ainda reportam o terminal). */
+  abort() {
+    if (!this.abortController.signal.aborted) this.abortController.abort();
+  }
+  log(level, message) {
+    if (this.dead) return;
+    if (this.loggedCount >= MAX_LOGS_PER_RUN) {
+      this.droppedCount++;
+      return;
+    }
+    this.loggedCount++;
+    const truncated = message.length > MAX_LOG_MESSAGE_CHARS ? `${message.slice(0, MAX_LOG_MESSAGE_CHARS)}\u2026 [truncado]` : message;
+    this.buffer.push({ ts: nowISO(), level, message: truncated });
+    if (this.buffer.length >= FLUSH_AT_BUFFERED) {
+      this.flushLogs();
+    } else {
+      this.scheduleFlush();
+    }
+  }
+  scheduleFlush() {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = void 0;
+      this.flushLogs();
+    }, this.flushIntervalMs);
+    unrefTimer(this.timer);
+  }
+  clearFlushTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+  }
+  takeLogs() {
+    const logs = this.buffer.splice(0, this.buffer.length);
+    if (this.droppedCount > 0) {
+      logs.push({
+        ts: nowISO(),
+        level: "warning",
+        message: `${this.droppedCount} logs descartados (limite de ${MAX_LOGS_PER_RUN} por execu\xE7\xE3o)`
+      });
+      this.droppedCount = 0;
+    }
+    return logs;
+  }
+  /** Flush incremental: envia o buffer como status 'running' (em chunks). */
+  flushLogs() {
+    this.clearFlushTimer();
+    if (this.dead || this.buffer.length === 0) return;
+    const logs = this.buffer.splice(0, this.buffer.length);
+    for (let i = 0; i < logs.length; i += MAX_LOGS_PER_PATCH) {
+      this.enqueue({ status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) });
+    }
+  }
+  /** Primeiro PATCH (claimed → running). Retorna false se a run já morreu (cancelada). */
+  async reportRunning() {
+    this.enqueue({ status: "running" });
+    await this.chain;
+    return !this.dead;
+  }
+  reportSuccess() {
+    this.clearFlushTimer();
+    this.enqueue({ status: "succeeded", logs: this.takeLogs() });
+  }
+  reportFailure(error) {
+    this.clearFlushTimer();
+    this.enqueue({ status: "failed", error, logs: this.takeLogs() });
+  }
+  /** Aguarda a fila de PATCHes esvaziar (chame depois do terminal). */
+  finalize() {
+    return this.chain;
+  }
+  enqueue(update) {
+    if (this.dead) return;
+    this.chain = this.chain.then(async () => {
+      if (this.dead) return;
+      const payload = update.logs && update.logs.length === 0 ? { ...update, logs: void 0 } : update;
+      try {
+        await this.api.updateRun(this.runId, payload);
+      } catch (error) {
+        if (error instanceof ManagerApiError && (error.status === 409 || error.status === 404)) {
+          this.dead = true;
+          this.abort();
+          this.buffer = [];
+          this.logger.warn(`run ${this.runId} cancelada/removida no servidor \u2014 reporte suprimido`);
+          return;
+        }
+        this.logger.error(`update da run ${this.runId} perdido:`, error);
+      }
+    });
+  }
+};
+
+// src/manager/agent.ts
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+var MIN_POLL_INTERVAL_MS = 1e3;
+var MAX_CONCURRENCY = 5;
+var POLL_RETRY_DELAYS_MS = [1e3, 4e3, 16e3];
+var AUTH_FAILURE_INTERVAL_MS = 3e4;
+function hostname() {
+  if (!isNode()) return void 0;
+  return process.env.HOSTNAME || process.env.COMPUTERNAME || void 0;
+}
+var ManagerAgent = class {
+  constructor(options, registry2) {
+    this.options = options;
+    this.registry = registry2;
+    this.logger = makeLogger(options.debug ?? false, "[hobots-manager]");
+    const dsn = parseDsn(options.dsn);
+    this.api = new ManagerApi({ baseUrl: dsn.managerBaseUrl, key: dsn.key, logger: this.logger });
+    this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    this.concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, options.concurrency ?? 1));
+    this.instanceId = options.instanceId;
+    this.taskTimeoutMs = options.taskTimeoutMs;
+    this.logFlushIntervalMs = options.logFlushIntervalMs;
+    this.logger.debug("agente configurado", { baseUrl: dsn.managerBaseUrl, projectSlug: dsn.projectSlug });
+  }
+  logger;
+  api;
+  pollIntervalMs;
+  concurrency;
+  instanceId;
+  taskTimeoutMs;
+  logFlushIntervalMs;
+  state = "idle";
+  timer;
+  pollAbort;
+  consecutiveFailures = 0;
+  consecutiveAuthFailures = 0;
+  activeRuns = /* @__PURE__ */ new Set();
+  reporters = /* @__PURE__ */ new Set();
+  get activeCount() {
+    return this.activeRuns.size;
+  }
+  start() {
+    if (this.state === "started") return;
+    if (this.state === "stopping") {
+      throw new Error("[hobots-manager] start() chamado durante stop() \u2014 aguarde o stop terminar");
+    }
+    if (this.registry.size === 0) {
+      throw new Error("[hobots-manager] nenhuma task registrada \u2014 chame register() antes de start()");
+    }
+    this.state = "started";
+    this.logger.debug(`polling iniciado (tasks: ${[...this.registry.keys()].join(", ")})`);
+    this.schedule(0);
+  }
+  /** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
+  async stop(timeoutMs = 3e4) {
+    if (this.state === "idle") return true;
+    this.state = "stopping";
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+    this.pollAbort?.abort();
+    const all = Promise.allSettled([...this.activeRuns]).then(() => true);
+    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();
+    }
+    this.state = "idle";
+    return finished;
+  }
+  /** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
+  schedule(delayMs) {
+    if (this.state !== "started" || this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = void 0;
+      void this.tick();
+    }, delayMs);
+  }
+  async tick() {
+    if (this.state !== "started") return;
+    if (this.activeRuns.size >= this.concurrency) {
+      this.schedule(this.pollIntervalMs);
+      return;
+    }
+    this.pollAbort = new AbortController();
+    try {
+      const response = await this.api.poll(
+        {
+          agent: {
+            // identidade canônica do agente no painel — o mesmo instanceId do
+            // heartbeat do Monitor, então os dois canais convergem em um agente
+            instance_id: this.instanceId,
+            version: SDK_VERSION,
+            host: hostname(),
+            tasks: [...this.registry.keys()]
+          },
+          max: Math.min(MAX_CONCURRENCY, this.concurrency - this.activeRuns.size),
+          tasks: [...this.registry.keys()]
+        },
+        this.pollAbort.signal
+      );
+      this.consecutiveFailures = 0;
+      this.consecutiveAuthFailures = 0;
+      for (const run of response.runs) {
+        this.dispatch(run);
+      }
+      this.schedule(response.runs.length > 0 ? 0 : this.pollIntervalMs);
+    } catch (error) {
+      if (this.state !== "started") return;
+      this.schedule(this.delayAfterPollError(error));
+    } finally {
+      this.pollAbort = void 0;
+    }
+  }
+  delayAfterPollError(error) {
+    if (error instanceof ManagerApiError && error.status === 401) {
+      this.consecutiveAuthFailures++;
+      if (this.consecutiveAuthFailures === 1 || this.consecutiveAuthFailures % 10 === 0) {
+        this.logger.error("chave rejeitada (401) \u2014 verifique a DSN do projeto em Configura\xE7\xF5es \u2192 Agentes");
+      }
+      return Math.max(this.pollIntervalMs, AUTH_FAILURE_INTERVAL_MS);
+    }
+    this.consecutiveFailures++;
+    const ladder = POLL_RETRY_DELAYS_MS[Math.min(this.consecutiveFailures - 1, POLL_RETRY_DELAYS_MS.length - 1)];
+    const delay = Math.min(Math.max(ladder, 0), Math.max(this.pollIntervalMs, 16e3));
+    this.logger.warn(`poll falhou (${String(error)}), pr\xF3xima tentativa em ${delay}ms`);
+    return delay;
+  }
+  dispatch(run) {
+    const promise = this.executeRun(run).catch((error) => this.logger.error(`erro inesperado na run ${run.id}:`, error)).finally(() => {
+      this.activeRuns.delete(promise);
+      if (this.state === "started") this.schedule(0);
+    });
+    this.activeRuns.add(promise);
+  }
+  async executeRun(run) {
+    const reporter = new RunReporter(this.api, run.id, run.task, this.logger, this.logFlushIntervalMs);
+    this.reporters.add(reporter);
+    try {
+      const handler = this.registry.get(run.task);
+      if (!handler) {
+        reporter.reportFailure({
+          type: "HandlerNotFound",
+          message: `tarefa n\xE3o registrada no agente: ${run.task}`
+        });
+        await reporter.finalize();
+        return;
+      }
+      const ok = await reporter.reportRunning();
+      if (!ok) {
+        this.logger.debug(`run ${run.id} cancelada antes de iniciar \u2014 handler n\xE3o executado`);
+        return;
+      }
+      this.logger.debug(`executando run ${run.id} (${run.task})`);
+      try {
+        await this.invokeWithTimeout(handler, run, reporter);
+        reporter.reportSuccess();
+        this.logger.debug(`run ${run.id} conclu\xEDda`);
+      } catch (error) {
+        reporter.reportFailure(toRunError(error));
+        this.logger.debug(`run ${run.id} falhou: ${String(error)}`);
+      }
+      await reporter.finalize();
+    } finally {
+      this.reporters.delete(reporter);
+    }
+  }
+  async invokeWithTimeout(handler, run, reporter) {
+    const invocation = Promise.resolve().then(() => handler(run.params, reporter.context));
+    if (!this.taskTimeoutMs || this.taskTimeoutMs <= 0) {
+      await invocation;
+      return;
+    }
+    const timeoutMs = this.taskTimeoutMs;
+    const timeout = sleep(timeoutMs).then(() => TIMEOUT_SENTINEL);
+    const outcome = await Promise.race([invocation, timeout]);
+    if (outcome !== TIMEOUT_SENTINEL) return;
+    reporter.abort();
+    invocation.then(() => this.logger.warn(`run ${run.id} terminou depois do timeout de ${timeoutMs}ms`)).catch(() => this.logger.warn(`run ${run.id} falhou depois do timeout de ${timeoutMs}ms (erro descartado)`));
+    throw Object.assign(new Error(`timeout ap\xF3s ${timeoutMs}ms (o handler pode continuar em background)`), {
+      name: "TaskTimeout"
+    });
+  }
+};
+var TIMEOUT_SENTINEL = /* @__PURE__ */ Symbol("task-timeout");
+var MAX_ERROR_MESSAGE_CHARS = 1e4;
+var MAX_ERROR_STACK_CHARS = 2e4;
+function truncate(value, max) {
+  return value.length > max ? `${value.slice(0, max)}\u2026 [truncado]` : value;
+}
+function toRunError(error) {
+  if (error instanceof Error) {
+    return {
+      type: error.name,
+      message: truncate(error.message, MAX_ERROR_MESSAGE_CHARS),
+      stack: error.stack ? truncate(error.stack, MAX_ERROR_STACK_CHARS) : void 0
+    };
+  }
+  return { message: truncate(String(error), MAX_ERROR_MESSAGE_CHARS) };
+}
+
 // src/core.ts
 var DEFAULT_MAX_BREADCRUMBS = 100;
 var client;
 var scope = new Scope();
 var heartbeat;
+var agent;
+var registry = /* @__PURE__ */ new Map();
+var warnedManagerDisabled = false;
 function init(options) {
   if (client) {
     client.logger.warn("init() chamado mais de uma vez \u2014 substituindo o client anterior");
     heartbeat?.stop();
     heartbeat = void 0;
   }
+  if (agent) {
+    void agent.stop(0);
+    agent = void 0;
+  }
+  warnedManagerDisabled = false;
   client = new Client(options);
   if (options.captureUnhandled !== false) {
     installGlobalHandlers(client, () => scope);
   }
   if (options.heartbeat) {
     const heartbeatOptions = options.heartbeat === true ? {} : options.heartbeat;
-    heartbeat = new Heartbeat(client, heartbeatOptions, options.serverName);
+    heartbeat = new Heartbeat(client, heartbeatOptions, options.instanceId);
     heartbeat.start();
   }
-  client.logger.debug("inicializado", { endpoint: client.dsn.endpoint });
+  if (options.manager) {
+    const managerOptions = options.manager === true ? {} : options.manager;
+    agent = new ManagerAgent(
+      { ...managerOptions, dsn: options.dsn, instanceId: options.instanceId, debug: options.debug },
+      registry
+    );
+  }
+  client.logger.debug("inicializado", { endpoint: client.dsn.ingestEndpoint });
 }
 function getClient() {
   return client;
@@ -756,9 +1172,32 @@ async function withMonitor(monitorSlug, fn, options) {
 function flush(timeoutMs) {
   return client ? client.flush(timeoutMs) : Promise.resolve(true);
 }
-function close(timeoutMs) {
+function register(task, handler) {
+  if (registry.has(task)) {
+    (agent?.logger ?? client?.logger)?.warn(`register('${task}') sobrescreveu um handler existente`);
+  }
+  if (client && !agent && !warnedManagerDisabled) {
+    warnedManagerDisabled = true;
+    client.logger.warn(
+      `register('${task}') com o Manager desabilitado \u2014 passe manager: true (ou op\xE7\xF5es) no init()`
+    );
+  }
+  registry.set(task, handler);
+}
+function start() {
+  if (!agent) {
+    throw new Error("[hobots] Manager n\xE3o configurado \u2014 passe manager: true (ou op\xE7\xF5es) no init() antes de start()");
+  }
+  agent.start();
+}
+function stop(timeoutMs) {
+  return agent ? agent.stop(timeoutMs) : Promise.resolve(true);
+}
+async function close(timeoutMs) {
+  const agentStopped = agent ? await agent.stop(timeoutMs) : true;
   heartbeat?.stop();
   heartbeat = void 0;
-  return client ? client.close(timeoutMs) : Promise.resolve(true);
+  const clientClosed = client ? await client.close(timeoutMs) : true;
+  return agentStopped && clientClosed;
 }
 //# sourceMappingURL=index.cjs.map