cloudbroker-sdk 0.9.0 → 0.9.1

package/README.md

@@ -349,6 +349,23 @@ await CloudBrokerCloud.trackExecution("job:fechamento-mensal", () => fecharMes()
   de um deploy pela versão que de fato rodou.
 - No shutdown: `await execucoes.flush(); execucoes.stop();`.
 
+#### Falhas e duração (0.9.1)
+
+Sem mudar nada no seu código, `expressMiddleware`, `trackExecution` e
+`CloudBroker.operation` passam a informar, junto com a contagem, quantas
+execuções **terminaram**, quantas **falharam** e a **duração** somada:
+
+- requisição: termina quando a resposta é enviada; status 5xx = falha. Uma
+  requisição abortada antes de responder conta como execução, mas não como
+  terminada;
+- `trackExecution`/`operation`: falha = o callback lançou ou a Promise rejeitou.
+  O retorno e o erro chegam intactos ao seu código.
+
+Por isso a taxa de falha e a duração média são calculadas sobre as execuções
+**terminadas**, não sobre o total. Duração por execução tem teto de 24 h.
+
+Para contar à mão: `const fim = execucoes.count({ label }); … fim({ failed })`.
+
 ### Custo por operação (0.9.0)
 
 Cada execução ganha um `operationId` (`op_` + UUID v7, gerado localmente). As chamadas de nuvem e de IA feitas durante a execução levam esse id, e o CloudBroker passa a somar o custo de **uma** execução (ex.: S3 + DynamoDB + OpenAI de um `POST /checkout`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudbroker-sdk",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
   "repository": {
     "type": "git",

package/src/client.js

@@ -48,7 +48,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.9.0",
+        sdkVersion: "0.9.1",
         sentAt: new Date().toISOString(),
       };
       if (this.#cloudQueue.length < MAX_QUEUE_SIZE) {
@@ -104,7 +104,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.9.0",
+        sdkVersion: "0.9.1",
         sentAt: new Date().toISOString(),
       };
 

package/src/cloud-wrapper.js

@@ -35,6 +35,7 @@ import {
   AZURE_COSMOS_ITEMS_OPS,
   AZURE_COSMOS_ITEMS_ITERATOR_OPS,
 } from "./pricing-cloud.js";
+import { runObserved } from "./observe.js";
 import { cbStore, childOperationIds, operationFields } from "./context.js";
 import { resolveVersion } from "./executions.js";
 
@@ -249,7 +250,14 @@ export class CloudBrokerCloud {
       // durante a requisição levam o mesmo operationId.
       const ctx = { label: safe(resolveLabel), product: safe(resolveProduct), team: safe(resolveTeam), ...childOperationIds() };
       try {
-        if (executions && typeof executions.count === "function") executions.count(ctx);
+        if (executions && typeof executions.count === "function") {
+          const fim = executions.count(ctx);
+          // Fim da requisição: resposta enviada. 5xx = falha. Abortada antes
+          // de responder não chega aqui — conta só em executions, não em completed.
+          if (typeof fim === "function" && typeof res?.once === "function") {
+            res.once("finish", () => { try { fim({ failed: res.statusCode >= 500 }); } catch { /* nunca lança */ } });
+          }
+        }
       } catch { /* contador nunca derruba a requisição */ }
       cbStore.run(ctx, () => next());
     };
@@ -270,10 +278,11 @@ export class CloudBrokerCloud {
   static trackExecution(label, fn, options = {}) {
     // Uma operação por execução (RFC-0026); dentro de outra operação, vira filha.
     const ctx = { label, product: options.product, team: options.team, ...childOperationIds() };
+    let fim = null;
     try {
-      if (options.executions && typeof options.executions.count === "function") options.executions.count(ctx);
+      if (options.executions && typeof options.executions.count === "function") fim = options.executions.count(ctx);
     } catch { /* contador nunca derruba a execução */ }
-    return cbStore.run(ctx, fn);
+    return runObserved(ctx, fn, fim);
   }
 
   /**

package/src/executions.js

@@ -20,6 +20,14 @@
  *   • contagem com mais de 7 dias sem conseguir enviar é descartada (o backend
  *     recusa, e reenviar para sempre seria inútil).
  *
+ * Falhas e duração (0.9.1, RFC-0026): `count()` devolve uma função de
+ * término. Chamada no fim (`fim({ failed })`), ela soma na MESMA combinação
+ * da hora de início: `completed`, `failures` e `durationMsSum` (relógio
+ * monotônico). Execução que nunca termina (requisição abortada, processo
+ * morto) conta em `count` e não em `completed` — por isso a taxa de falha e a
+ * duração média se calculam sobre `completed`. O expressMiddleware e o
+ * trackExecution chamam o término sozinhos.
+ *
  * Uso:
  *   const execucoes = new ExecutionCounter({ apiKey: "cb-key-xxx" }); // version ← CLOUDBROKER_VERSION
  *   app.use(CloudBrokerCloud.expressMiddleware({ label: ..., executions: execucoes }));
@@ -29,6 +37,8 @@
 const DEFAULT_EXECUTIONS_ENDPOINT = "https://api.cloudbroker.app.br/api/cloud/executions";
 const HOUR_MS = 3_600_000;
 const MAX_AGE_MS = 7 * 24 * HOUR_MS;
+const MAX_DURATION_MS = 24 * HOUR_MS;   // o backend recusa acima disso
+const NOOP = () => {};
 
 /** Versão do código do cliente: explícita > CLOUDBROKER_VERSION > null. */
 export function resolveVersion(explicit) {
@@ -48,10 +58,13 @@ export class ExecutionCounter {
   #debug;
   #maxKeys;
   #now;
+  #mono;
   #pending = new Map();
   #flushing = false;
   #timer = null;
   dropped = 0;
+  /** Términos que não couberam no teto de combinações (sem a execução perdida). */
+  droppedCompletions = 0;
 
   /**
    * @param {object} options
@@ -62,7 +75,7 @@ export class ExecutionCounter {
    * @param {number} [options.maxKeys=200] — o backend recusa lote com mais de 200
    * @param {boolean} [options.debug=false]
    */
-  constructor({ apiKey, version, endpoint = DEFAULT_EXECUTIONS_ENDPOINT, flushIntervalMs = 60_000, maxKeys = 200, debug = false, now } = {}) {
+  constructor({ apiKey, version, endpoint = DEFAULT_EXECUTIONS_ENDPOINT, flushIntervalMs = 60_000, maxKeys = 200, debug = false, now, monotonicNow } = {}) {
     if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
     this.#apiKey = apiKey;
     this.#endpoint = endpoint;
@@ -70,6 +83,7 @@ export class ExecutionCounter {
     this.#debug = debug;
     this.#maxKeys = Math.max(1, Math.min(200, Math.floor(maxKeys) || 200));
     this.#now = typeof now === "function" ? now : Date.now;
+    this.#mono = typeof monotonicNow === "function" ? monotonicNow : () => performance.now();
     if (flushIntervalMs > 0) {
       this.#timer = setInterval(() => { this.flush(); }, flushIntervalMs);
       if (typeof this.#timer?.unref === "function") this.#timer.unref();
@@ -85,21 +99,48 @@ export class ExecutionCounter {
   /**
    * Soma uma execução do trecho. Nunca lança.
    * @param {{label?: string, product?: string}} ctx
+   * @returns {(result?: {failed?: boolean}) => void} término da execução —
+   *   soma completed/failures/durationMsSum; só a 1ª chamada conta. Sem rótulo
+   *   (execução não contada), é uma função vazia.
    */
   count(ctx) {
     try {
       const label = ctx?.label, product = ctx?.product;
-      if (typeof label !== "string" || !label.trim()) return;
+      if (typeof label !== "string" || !label.trim()) return NOOP;
       const hour = hourStartIso(this.#now());
       const prod = typeof product === "string" && product.trim() ? product : null;
       const key = `${hour}\u0000${label}\u0000${prod || ""}`;
       const cur = this.#pending.get(key);
-      if (cur) { cur.count++; return; }
-      if (this.#pending.size >= this.#maxKeys) { this.dropped++; return; }
-      this.#pending.set(key, { label, product: prod, version: this.#version, hour, count: 1 });
+      if (cur) cur.count++;
+      else if (this.#pending.size >= this.#maxKeys) { this.dropped++; return NOOP; }
+      else this.#pending.set(key, { label, product: prod, version: this.#version, hour, count: 1 });
+      const start = this.#mono();
+      let done = false;
+      return (result) => {
+        if (done) return;
+        done = true;
+        try { this.#complete(key, { label, product: prod, hour }, start, result?.failed === true); }
+        catch (err) { if (this.#debug) console.warn("[CloudBroker] executions finish error:", err.message); }
+      };
     } catch (err) {
       if (this.#debug) console.warn("[CloudBroker] executions.count error:", err.message);
+      return NOOP;
+    }
+  }
+
+  #complete(key, base, start, failed) {
+    const d = this.#mono() - start;
+    const ms = Number.isFinite(d) && d > 0 ? Math.min(Math.round(d), MAX_DURATION_MS) : 0;
+    let it = this.#pending.get(key);
+    if (!it) {
+      // A combinação já foi enviada: o término vai num item só com fim (count 0).
+      if (this.#pending.size >= this.#maxKeys) { this.droppedCompletions++; return; }
+      it = { ...base, version: this.#version, count: 0 };
+      this.#pending.set(key, it);
     }
+    it.completed = (it.completed || 0) + 1;
+    it.failures = (it.failures || 0) + (failed ? 1 : 0);
+    it.durationMsSum = (it.durationMsSum || 0) + ms;
   }
 
   /** Envia o pendente. Nunca lança; em falha transitória, a contagem volta para a fila. */
@@ -138,8 +179,14 @@ export class ExecutionCounter {
       if (Date.parse(it.hour) < limite) { this.dropped += it.count; continue; }
       const key = `${it.hour}\u0000${it.label}\u0000${it.product || ""}`;
       const cur = this.#pending.get(key);
-      if (cur) cur.count += it.count;
-      else if (this.#pending.size < this.#maxKeys) this.#pending.set(key, it);
+      if (cur) {
+        cur.count += it.count;
+        if (it.completed) {
+          cur.completed = (cur.completed || 0) + it.completed;
+          cur.failures = (cur.failures || 0) + it.failures;
+          cur.durationMsSum = (cur.durationMsSum || 0) + it.durationMsSum;
+        }
+      } else if (this.#pending.size < this.#maxKeys) this.#pending.set(key, it);
       else this.dropped += it.count;
     }
   }

package/src/observe.js

@@ -0,0 +1,29 @@
+/**
+ * Roda `fn` no contexto `ctx` e avisa o término da execução (0.9.1, RFC-0026).
+ *
+ * `fim` é a função devolvida por ExecutionCounter.count(); null = sem contador.
+ * Garantias: o retorno de `fn` (inclusive a MESMA Promise) e o erro de `fn`
+ * chegam intactos ao chamador; a observação nunca lança nem cria rejeição
+ * não tratada nova (o ramo `.then` trata as duas saídas).
+ */
+import { cbStore } from "./context.js";
+
+export function runObserved(ctx, fn, fim) {
+  if (typeof fim !== "function") return cbStore.run(ctx, fn);
+  const end = (failed) => { try { fim({ failed }); } catch { /* nunca lança */ } };
+  let result;
+  try {
+    result = cbStore.run(ctx, fn);
+  } catch (err) {
+    end(true);
+    throw err;
+  }
+  let then = null;
+  try { then = result !== null && (typeof result === "object" || typeof result === "function") ? result.then : null; } catch { then = null; }
+  if (typeof then === "function") {
+    try { then.call(result, () => end(false), () => end(true)); } catch { end(false); }
+  } else {
+    end(false);
+  }
+  return result;
+}

package/src/operation.js

@@ -22,6 +22,7 @@
  * servidor), customerId e metadata (risco de dado pessoal — RFC-0026 §3).
  */
 import { cbStore, childOperationIds, operationFields } from "./context.js";
+import { runObserved } from "./observe.js";
 
 const OPERATION_TYPES = new Set(["http", "business", "job", "queue", "graphql", "database", "ai", "custom"]);
 
@@ -51,7 +52,7 @@ export class CloudBroker {
       throw new TypeError("[CloudBroker] operation(name, options, callback): callback deve ser uma função.");
     }
 
-    let ctx = null;
+    let ctx = null, fim = null;
     try {
       const parent = cbStore.getStore() || {};
       const o = options && typeof options === "object" ? options : {};
@@ -65,12 +66,12 @@ export class CloudBroker {
         ...childOperationIds(),
       };
       try {
-        if (o.executions && typeof o.executions.count === "function") o.executions.count(ctx);
+        if (o.executions && typeof o.executions.count === "function") fim = o.executions.count(ctx);
       } catch { /* contador nunca derruba a operação */ }
     } catch {
       ctx = null;
     }
-    return ctx ? cbStore.run(ctx, callback) : callback();
+    return ctx ? runObserved(ctx, callback, fim) : callback();
   }
 
   /**

package/src/test-executions.js

@@ -178,6 +178,99 @@ ok(resolveVersion("x".repeat(100)).length === 64, "versão com teto de 64");
   ok(sent.filter((s) => s.url.endsWith("/api/cloud/events")).at(-1)?.body.events[0].version === "v9", "versão explícita do wrapAWS vence o env");
 }
 
+// ─── falhas e duração (0.9.1, RFC-0026) ──────────────────────────────────────
+{
+  const { EventEmitter } = await import("node:events");
+  let mono = 1000;
+  const c = mk({ monotonicNow: () => mono });
+  const fim1 = c.count({ label: "checkout", product: "Loja" });
+  const fim2 = c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Loja" });            // em andamento: sem fim
+  mono += 120; fim1();
+  mono += 30; fim2({ failed: true });
+  fim1({ failed: true });                                      // 2ª chamada não conta
+  ok(typeof c.count({}) === "function", "count sem rótulo devolve término vazio (chamável)");
+  await c.flush();
+  let it = sent.at(-1).body.executions[0];
+  ok(it.count === 3 && it.completed === 2 && it.failures === 1 && it.durationMsSum === 270, `contagem 3, fim 2, 1 falha, duração somada (veio ${JSON.stringify(it)})`);
+
+  const fim3 = c.count({ label: "checkout", product: "Loja" });
+  await c.flush();                                             // início já enviado
+  mono += 50; fim3();
+  await c.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 0 && it.completed === 1 && it.durationMsSum === 50 && it.hour === "2026-10-12T15:00:00.000Z", "término depois do envio do início → item só com fim, na hora do INÍCIO");
+
+  const c0 = mk({ monotonicNow: () => mono });
+  c0.count({ label: "v1" });
+  await c0.flush();
+  ok(!("completed" in sent.at(-1).body.executions[0]), "sem término observado não manda completed (ausente ≠ 0)");
+
+  const cNeg = mk({ monotonicNow: () => NaN });
+  cNeg.count({ label: "n" })();
+  await cNeg.flush();
+  ok(sent.at(-1).body.executions[0].durationMsSum === 0, "relógio inválido → duração 0, nunca NaN");
+  let longa = 0; const cL = mk({ monotonicNow: () => longa });
+  const fimL = cL.count({ label: "longa" }); longa = 48 * 3_600_000; fimL();
+  await cL.flush();
+  ok(sent.at(-1).body.executions[0].durationMsSum === 24 * 3_600_000, "duração limitada a 24 h (teto do backend)");
+
+  const cR = mk({ monotonicNow: () => mono });
+  respond = () => ({ ok: false, status: 503 });
+  cR.count({ label: "r" })({ failed: true });
+  await cR.flush();
+  respond = () => ({ ok: true, status: 200 });
+  cR.count({ label: "r" })();
+  await cR.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 2 && it.completed === 2 && it.failures === 1, "falha transitória: fim volta à fila e soma com o seguinte");
+
+  // middleware: 'finish' com 5xx = falha; abortada (sem finish) não completa
+  const cm = mk({ monotonicNow: () => mono });
+  const mw = CloudBrokerCloud.expressMiddleware({ label: "mod", executions: cm });
+  const r1 = Object.assign(new EventEmitter(), { statusCode: 200 });
+  const r2 = Object.assign(new EventEmitter(), { statusCode: 503 });
+  const r3 = Object.assign(new EventEmitter(), { statusCode: 200 });
+  for (const r of [r1, r2, r3]) await new Promise((ok_) => mw({ method: "GET", path: "/" }, r, ok_));
+  r1.emit("finish"); r2.emit("finish"); r3.emit("close");
+  await cm.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 3 && it.completed === 2 && it.failures === 1, "middleware: 2xx ok, 5xx falha, abortada só em count");
+
+  // trackExecution e operation: sync, async, erro; retorno e erro intactos
+  const ct = mk({ monotonicNow: () => mono });
+  const p = Promise.resolve(9);
+  ok(CloudBrokerCloud.trackExecution("t", () => p, { executions: ct }) === p, "trackExecution devolve a MESMA Promise");
+  ok(CloudBrokerCloud.trackExecution("t", () => 1, { executions: ct }) === 1, "síncrono devolve o valor");
+  class E extends Error {}
+  let e1; try { CloudBrokerCloud.trackExecution("t", () => { throw new E("s"); }, { executions: ct }); } catch (e) { e1 = e; }
+  let e2; try { await CloudBrokerCloud.trackExecution("t", async () => { throw new E("a"); }, { executions: ct }); } catch (e) { e2 = e; }
+  ok(e1 instanceof E && e2 instanceof E, "erro síncrono e assíncrono propagam com o mesmo tipo");
+  const { CloudBroker } = await import("./operation.js");
+  await CloudBroker.operation("t", { executions: ct }, async () => 1);
+  let e3; try { await CloudBroker.operation("t", { executions: ct }, async () => { throw new E("o"); }); } catch (e) { e3 = e; }
+  ok(e3 instanceof E, "CloudBroker.operation propaga o erro");
+  await new Promise((r) => setTimeout(r, 10));
+  await ct.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 6 && it.completed === 6 && it.failures === 3, `trackExecution + operation: 6 execuções, 3 falhas (veio ${it.count}/${it.completed}/${it.failures})`);
+
+  // nenhuma rejeição não tratada nova
+  const unhandled = [];
+  const h = (r) => unhandled.push(r);
+  process.on("unhandledRejection", h);
+  const pr = CloudBrokerCloud.trackExecution("t", async () => { throw new E("x"); }, { executions: ct });
+  await pr.catch(() => {});
+  await new Promise((r) => setTimeout(r, 20));
+  process.off("unhandledRejection", h);
+  ok(unhandled.length === 0, "a observação não cria rejeição não tratada");
+
+  const quebrado = { count() { return () => { throw new Error("x"); }; } };
+  ok(CloudBrokerCloud.trackExecution("t", () => 5, { executions: quebrado }) === 5, "término que lança não derruba a execução");
+  const thenHostil = { get then() { throw new Error("x"); } };
+  ok(CloudBrokerCloud.trackExecution("t", () => thenHostil, { executions: ct }) === thenHostil, "retorno com 'then' hostil volta intacto");
+}
+
 // ─── versão do pacote ────────────────────────────────────────────────────────
 {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

package/src/test-operations.js

@@ -169,7 +169,7 @@ const ask = () => openai.chat.completions.create({ model: "gpt-4o-mini", message
 {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   const client = readFileSync(new URL("./client.js", import.meta.url), "utf8");
-  ok(pkg.version === "0.9.0" && [...client.matchAll(/sdkVersion:\s*"([^"]+)"/g)].every((m) => m[1] === pkg.version), "sdkVersion 0.9.0 nos eventos");
+  ok(pkg.version === "0.9.1" && [...client.matchAll(/sdkVersion:\s*"([^"]+)"/g)].every((m) => m[1] === pkg.version), "sdkVersion 0.9.1 nos eventos");
 }
 
 console.log(`\n${pass} asserções ok — custo por operação`);