@neetru/sdk 3.2.2 → 3.3.0

package/dist/db.cjs

@@ -20,12 +20,22 @@ var init_errors = __esm({
       code;
       status;
       requestId;
-      constructor(code, message, status, requestId) {
+      /**
+       * Motivo semântico opcional propagado pelo Core no corpo do erro (campo
+       * `reason` no TOPO do body, fora de `error`). Usado principalmente pelo 503
+       * de lease de DB, onde `reason` discrimina o estado do ambiente
+       * (`suspended` | `archived` | `revoked` | `provisioning` | `degraded` |
+       * `no_route` | `expired`). Camadas superiores (ex.: `db/sql`) mapeiam isso
+       * para um `NeetruDbErrorCode` mais específico (recuperável vs não).
+       */
+      reason;
+      constructor(code, message, status, requestId, reason) {
         super(message);
         this.name = "NeetruError";
         this.code = code;
         this.status = status;
         this.requestId = requestId;
+        this.reason = reason;
         Object.setPrototypeOf(this, _NeetruError.prototype);
       }
     };
@@ -231,16 +241,22 @@ async function httpRequest(config, opts) {
     const body = await safeJson(res);
     let code = statusToCode(res.status);
     let message = `HTTP ${res.status}`;
-    if (body && typeof body === "object" && "error" in body) {
+    let reason;
+    if (body && typeof body === "object") {
       const errField = body.error;
       if (typeof errField === "string") {
         message = errField;
       } else if (errField && typeof errField === "object") {
         if (typeof errField.code === "string") code = errField.code;
         if (typeof errField.message === "string") message = errField.message;
+        if (typeof errField.reason === "string") reason = errField.reason;
+      } else {
+        if (typeof body.code === "string") code = body.code;
+        if (typeof body.message === "string") message = body.message;
       }
+      if (typeof body.reason === "string") reason = body.reason;
     }
-    const err = new NeetruError(code, message, res.status, requestId);
+    const err = new NeetruError(code, message, res.status, requestId, reason);
     lastError = err;
     const isRetryable = RETRYABLE_CODES2.has(code);
     if (isRetryable && attempt < maxRetries) {
@@ -276,8 +292,98 @@ var init_http = __esm({
   }
 });
 
+// src/db/sql/resilient-pool.ts
+function isResilientPool(x) {
+  return typeof x === "object" && x !== null && x[RESILIENT_POOL_BRAND] === true;
+}
+function isConnectionEstablishmentError(err) {
+  const code = err && typeof err === "object" && "code" in err ? err.code : void 0;
+  if (code === "ECONNREFUSED" || code === "ETIMEDOUT" || code === "ENOTFOUND" || code === "EHOSTUNREACH" || code === "EAI_AGAIN") {
+    return true;
+  }
+  if (typeof code === "string") {
+    const upper = code.toUpperCase();
+    if (upper === "CERT_HAS_EXPIRED" || upper.startsWith("ERR_SSL") || upper.startsWith("ERR_TLS") || upper.includes("CERTIFICATE_EXPIRED")) {
+      return true;
+    }
+  }
+  const rawMessage = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  const message = rawMessage.toLowerCase();
+  if (message.length === 0) return false;
+  if (message.includes("certificate expired") || message.includes("certificate has expired") || message.includes("cert_has_expired") || message.includes("alert certificate expired") || message.includes("err_ssl") || message.includes("sslv3 alert") || message.includes("tlsv1 alert")) {
+    return true;
+  }
+  if (message.includes("econnrefused") || message.includes("etimedout") || message.includes("enotfound") || message.includes("ehostunreach") || message.includes("getaddrinfo")) {
+    return true;
+  }
+  return false;
+}
+function createResilientPool(initialInner) {
+  const state = { current: initialInner };
+  let reLease = null;
+  const controls = {
+    __neetruSwapInner(newInner) {
+      const old = state.current;
+      state.current = newInner;
+      return old;
+    },
+    __neetruGetInner() {
+      return state.current;
+    },
+    __neetruSetReLease(fn) {
+      reLease = fn;
+    }
+  };
+  const invokeQuery = (pool, args) => pool.query(...args);
+  const wrappedQuery = (...args) => {
+    if (args.length > 0 && typeof args[args.length - 1] === "function") {
+      return invokeQuery(state.current, args);
+    }
+    return (async () => {
+      try {
+        return await invokeQuery(state.current, args);
+      } catch (err) {
+        const fn = reLease;
+        if (fn === null || !isConnectionEstablishmentError(err)) {
+          throw err;
+        }
+        try {
+          await fn();
+        } catch {
+          throw err;
+        }
+        return await invokeQuery(state.current, args);
+      }
+    })();
+  };
+  const target = Object.create(Object.getPrototypeOf(initialInner));
+  const proxy = new Proxy(target, {
+    get(_t, prop) {
+      if (prop === RESILIENT_POOL_BRAND) return true;
+      if (prop === "__neetruSwapInner") return controls.__neetruSwapInner;
+      if (prop === "__neetruGetInner") return controls.__neetruGetInner;
+      if (prop === "__neetruSetReLease") return controls.__neetruSetReLease;
+      if (prop === "query") return wrappedQuery;
+      if (prop === "constructor") {
+        return state.current.constructor;
+      }
+      const current = state.current;
+      const value = Reflect.get(current, prop, current);
+      return typeof value === "function" ? value.bind(current) : value;
+    }
+  });
+  return proxy;
+}
+var RESILIENT_POOL_BRAND;
+var init_resilient_pool = __esm({
+  "src/db/sql/resilient-pool.ts"() {
+    RESILIENT_POOL_BRAND = /* @__PURE__ */ Symbol.for("neetru.sdk.resilientPool");
+  }
+});
+
 // src/db/sql/lease.ts
 function hasConnectionChanged(oldLease, newLease) {
+  if (!oldLease) return true;
   return oldLease.leaseId !== newLease.leaseId || oldLease.credentialVersion !== newLease.credentialVersion || oldLease.host !== newLease.host || oldLease.port !== newLease.port || oldLease.dbName !== newLease.dbName || oldLease.user !== newLease.user || oldLease.password !== newLease.password || oldLease.sslca !== newLease.sslca || oldLease.clientCert !== newLease.clientCert || oldLease.clientKey !== newLease.clientKey;
 }
 function mapPoolError(err) {
@@ -305,14 +411,31 @@ var RENEWAL_THRESHOLD, MIN_RENEWAL_DELAY_MS, SqlLeaseManager;
 var init_lease = __esm({
   "src/db/sql/lease.ts"() {
     init_db_errors();
+    init_resilient_pool();
     RENEWAL_THRESHOLD = 0.8;
     MIN_RENEWAL_DELAY_MS = 3e4;
     SqlLeaseManager = class {
+      /**
+       * Lease atual. `null` no modo LAZY antes da 1ª query (o 1º lease é adiado —
+       * ver `_ensureInitialLease`). Após a 1ª aquisição, sempre não-nulo.
+       */
       _lease;
       _pool;
       _orm;
       _renewalTimer = null;
       _closed = false;
+      /**
+       * Promessa de re-lease REATIVO em voo — coalesce chamadas concorrentes
+       * (N queries falhando ao mesmo tempo disparam UM único re-lease). Ver
+       * `_reactiveReLease`.
+       */
+      _reLeaseInFlight = null;
+      /**
+       * Promessa da aquisição do LEASE INICIAL em voo (modo lazy) — coalesce as
+       * N primeiras queries concorrentes num único fetch. `null` quando não há
+       * aquisição inicial pendente. Ver `_ensureInitialLease`.
+       */
+      _initInFlight = null;
       _deps;
       constructor(lease, pool, orm, deps) {
         this._lease = lease;
@@ -322,7 +445,7 @@ var init_lease = __esm({
           ...deps,
           now: deps.now ?? (() => Date.now())
         };
-        this._scheduleRenewal();
+        if (this._lease) this._scheduleRenewal();
       }
       // ─── Superfície pública (NeetruSqlClient) ──────────────────────────────────
       get orm() {
@@ -360,6 +483,7 @@ var init_lease = __esm({
        * usa `MIN_RENEWAL_DELAY_MS` como fallback seguro.
        */
       _calcRenewalDelayMs() {
+        if (!this._lease) return MIN_RENEWAL_DELAY_MS;
         const expiresAtMs = Date.parse(this._lease.expiresAt);
         if (!Number.isFinite(expiresAtMs)) return MIN_RENEWAL_DELAY_MS;
         const now = this._deps.now();
@@ -383,6 +507,8 @@ var init_lease = __esm({
       }
       async _doRenew() {
         if (this._closed) return;
+        const currentLease = this._lease;
+        if (!currentLease) return;
         try {
           const withDb = (o) => {
             if (this._deps.database !== void 0) o.database = this._deps.database;
@@ -390,7 +516,7 @@ var init_lease = __esm({
           };
           let newLease;
           try {
-            newLease = await this._deps.fetchLease(withDb({ leaseId: this._lease.leaseId }));
+            newLease = await this._deps.fetchLease(withDb({ leaseId: currentLease.leaseId }));
           } catch (renewErr) {
             newLease = await this._deps.fetchLease(withDb({}));
           }
@@ -407,6 +533,114 @@ var init_lease = __esm({
         }
         this._scheduleRenewal();
       }
+      // ─── Re-lease REATIVO (P1.5) ───────────────────────────────────────────────
+      /**
+       * Recuperação REATIVA: chamado pelo wrapper resiliente (`resilient-pool.ts`)
+       * quando uma query plana falha num erro de ESTABELECIMENTO de conexão (cert
+       * mTLS expirado no meio de uma request, ou timer de renovação que não
+       * disparou). Emite um lease NOVO e faz o swap do pool interno do wrapper com
+       * o certificado fresco; o wrapper então re-tenta a query 1x no pool novo.
+       *
+       * Vai DIRETO ao lease novo (sem `leaseId`) — a conexão falhou porque o
+       * certificado do lease atual está ruim, então `renew` (que depende do lease
+       * antigo estar vivo) não é o caminho mais robusto. Emitir do zero é o que já
+       * cura o death-spiral no caminho proativo (ver `_doRenew`).
+       *
+       * Coalesce concorrência: N queries falhando ao mesmo tempo compartilham UM
+       * único re-lease (não N leases). Após o swap, cada query re-tenta no pool
+       * vigente.
+       *
+       * NÃO engole erro: se o re-lease falhar, propaga — o wrapper então relança o
+       * erro ORIGINAL da query pro consumer.
+       */
+      async _reactiveReLease() {
+        if (this._closed) {
+          throw new exports.NeetruDbError(
+            "db_unavailable",
+            "SqlLeaseManager foi fechado \u2014 re-lease reativo abortado."
+          );
+        }
+        if (this._reLeaseInFlight !== null) return this._reLeaseInFlight;
+        const run = (async () => {
+          const withDb = (o) => {
+            if (this._deps.database !== void 0) o.database = this._deps.database;
+            return o;
+          };
+          const fresh = await this._deps.fetchLease(withDb({}));
+          await this._swapPool(fresh);
+        })();
+        this._reLeaseInFlight = run;
+        try {
+          await run;
+        } finally {
+          this._reLeaseInFlight = null;
+        }
+      }
+      // ─── Lease INICIAL lazy (motor de ambientes suspenso) ──────────────────────
+      /**
+       * Adquire o LEASE INICIAL sob demanda (modo lazy). Chamado pelo pool "adiado"
+       * (`createDeferredPool`) na 1ª query/transação — nunca no boot do módulo.
+       *
+       * Fluxo:
+       *   1. Se já há lease (`_lease != null`), devolve o pool REAL interno vigente
+       *      (idempotente — chamadas após a 1ª aquisição são no-op de fetch).
+       *   2. Busca o 1º lease no Core (com `database` se houver — contrato C-H).
+       *   3. Cria o pool REAL e faz o swap no wrapper resiliente (`__neetruSwapInner`)
+       *      pra que as queries seguintes passem direto pelo pool real.
+       *   4. Agenda a renovação proativa (só a partir daqui — antes não havia lease).
+       *
+       * Coalesce concorrência: N primeiras queries compartilham UM único fetch
+       * (`_initInFlight`). Se a aquisição FALHA (ex.: ambiente suspenso →
+       * `db_suspended`, ou Core fora → `db_unavailable`), o erro propaga pra query
+       * que a disparou e `_initInFlight` é limpo — a PRÓXIMA query re-tenta (o
+       * ambiente pode ter voltado). NÃO derruba o processo nem o import do módulo.
+       */
+      async _ensureInitialLease() {
+        if (this._closed) {
+          throw new exports.NeetruDbError(
+            "db_unavailable",
+            "SqlLeaseManager foi fechado \u2014 aquisi\xE7\xE3o de lease inicial abortada."
+          );
+        }
+        if (this._lease) {
+          return isResilientPool(this._pool) ? this._pool.__neetruGetInner() : this._pool;
+        }
+        if (this._initInFlight !== null) return this._initInFlight;
+        const run = (async () => {
+          let lease;
+          try {
+            lease = this._deps.database !== void 0 ? await this._deps.fetchLease({ database: this._deps.database }) : await this._deps.fetchLease();
+          } catch (err) {
+            if (err instanceof exports.NeetruDbError) throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new exports.NeetruDbError("db_unavailable", `Falha ao obter lease inicial: ${msg}`);
+          }
+          let realPool;
+          try {
+            realPool = this._deps.createPool(lease);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new exports.NeetruDbError("db_unavailable", `Falha ao abrir pool: ${msg}`);
+          }
+          if (isResilientPool(this._pool)) {
+            const old = this._pool.__neetruSwapInner(realPool);
+            void old.end().catch(() => {
+            });
+          } else {
+            this._pool = realPool;
+          }
+          this._lease = lease;
+          this._scheduleRenewal();
+          return realPool;
+        })();
+        this._initInFlight = run;
+        try {
+          return await run;
+        } catch (err) {
+          this._initInFlight = null;
+          throw err;
+        }
+      }
       /**
        * Hot-swap do pool: cria pool novo, atualiza ponteiros, drena pool antigo.
        *
@@ -418,6 +652,13 @@ var init_lease = __esm({
           return;
         }
         const newPool = this._deps.createPool(newLease);
+        if (isResilientPool(this._pool)) {
+          const oldInner = this._pool.__neetruSwapInner(newPool);
+          this._lease = newLease;
+          void oldInner.end().catch(() => {
+          });
+          return;
+        }
         const newOrm = this._deps.createDrizzle(newPool, this._deps.schema);
         const oldPool = this._pool;
         this._lease = newLease;
@@ -483,10 +724,19 @@ function createHttpLeaseFetcher(config) {
         retries: 2
       });
     } catch (err) {
+      const verb = isRenewal ? "renovar" : "obter";
       const msg = err instanceof Error ? err.message : String(err);
+      const reason = err instanceof NeetruError ? err.reason : void 0;
+      if (reason === "suspended" || reason === "archived" || reason === "revoked") {
+        const human = reason === "suspended" ? "ambiente suspenso \u2014 a m\xE1quina que o servia parou; ser\xE1 religado quando o ambiente voltar" : reason === "archived" ? "ambiente arquivado \u2014 este banco foi arquivado e n\xE3o aceita mais conex\xF5es" : "lease revogado \u2014 as credenciais deste ambiente foram revogadas pelo Core";
+        throw new exports.NeetruDbError(
+          "db_suspended",
+          `Falha ao ${verb} lease SQL: ${human} (reason=${reason}).`
+        );
+      }
       throw new exports.NeetruDbError(
         "db_unavailable",
-        `Falha ao ${isRenewal ? "renovar" : "obter"} lease SQL: ${msg}`
+        `Falha ao ${verb} lease SQL: ${msg}`
       );
     }
     return parseLease(raw);
@@ -558,8 +808,64 @@ async function createDrizzleHandle(pool, schema) {
   );
   return drizzle(pool, { schema });
 }
+function createDeferredPool(poolPrototype, ensureRealPool) {
+  let real = null;
+  let inflight = null;
+  const getReal = () => {
+    if (real) return Promise.resolve(real);
+    if (!inflight) {
+      inflight = ensureRealPool().then((p) => {
+        real = p;
+        inflight = null;
+        return p;
+      }).catch((e) => {
+        inflight = null;
+        throw e;
+      });
+    }
+    return inflight;
+  };
+  const deferred = {
+    async query(...args) {
+      const p = await getReal();
+      return p.query(...args);
+    },
+    async connect(...args) {
+      const p = await getReal();
+      return p.connect(...args);
+    },
+    async end() {
+      if (real) await real.end();
+    }
+  };
+  if (poolPrototype) {
+    Object.setPrototypeOf(deferred, poolPrototype);
+  }
+  return deferred;
+}
 async function createSqlClientWithDeps(deps, options) {
   const depsWithDb = options?.database !== void 0 ? { ...deps, database: options.database } : deps;
+  if (depsWithDb.lazy) {
+    let managerRef = null;
+    const deferred = createDeferredPool(depsWithDb.poolPrototype ?? null, () => {
+      if (!managerRef) {
+        throw new exports.NeetruDbError("db_unavailable", "SQL client n\xE3o inicializado (manager ausente).");
+      }
+      return managerRef._ensureInitialLease();
+    });
+    const pool2 = createResilientPool(deferred);
+    let orm2;
+    try {
+      orm2 = depsWithDb.createDrizzle(pool2, depsWithDb.schema);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new exports.NeetruDbError("db_unavailable", `Falha ao criar handle Drizzle: ${msg}`);
+    }
+    const manager2 = new SqlLeaseManager(null, pool2, orm2, depsWithDb);
+    managerRef = manager2;
+    pool2.__neetruSetReLease(() => manager2._reactiveReLease());
+    return manager2;
+  }
   let lease;
   try {
     if (options?.database !== void 0) {
@@ -572,23 +878,26 @@ async function createSqlClientWithDeps(deps, options) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new exports.NeetruDbError("db_unavailable", `Falha ao obter lease inicial: ${msg}`);
   }
-  let pool;
+  let innerPool;
   try {
-    pool = depsWithDb.createPool(lease);
+    innerPool = depsWithDb.createPool(lease);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new exports.NeetruDbError("db_unavailable", `Falha ao abrir pool: ${msg}`);
   }
+  const pool = createResilientPool(innerPool);
   let orm;
   try {
     orm = depsWithDb.createDrizzle(pool, depsWithDb.schema);
   } catch (err) {
-    await pool.end().catch(() => {
+    await innerPool.end().catch(() => {
     });
     const msg = err instanceof Error ? err.message : String(err);
     throw new exports.NeetruDbError("db_unavailable", `Falha ao criar handle Drizzle: ${msg}`);
   }
-  return new SqlLeaseManager(lease, pool, orm, depsWithDb);
+  const manager = new SqlLeaseManager(lease, pool, orm, depsWithDb);
+  pool.__neetruSetReLease(() => manager._reactiveReLease());
+  return manager;
 }
 async function createSqlClientFromConfig(config, schema, options) {
   const fetchLease = createHttpLeaseFetcher(config);
@@ -609,8 +918,8 @@ async function createSqlClientFromConfig(config, schema, options) {
       `[client.db.sql] requer pg + drizzle-orm como peerDependencies do servidor. Instale: npm install pg drizzle-orm. (${err.message})`
     );
   }
+  const Pool = pgMod.Pool ?? pgMod.default?.Pool;
   const createPool = (lease) => {
-    const Pool = pgMod.Pool ?? pgMod.default?.Pool;
     const ssl = lease.sslca ? {
       ca: lease.sslca,
       cert: lease.clientCert ?? void 0,
@@ -637,7 +946,14 @@ async function createSqlClientFromConfig(config, schema, options) {
       fetchLease,
       createPool,
       createDrizzle,
-      schema
+      schema,
+      // Lease inicial LAZY (motor de ambientes suspenso): `client.db.sql()` não
+      // pode explodir o `import` do módulo do produto quando o ambiente está
+      // suspenso/arquivado no boot. O 1º lease é adiado pra 1ª query.
+      lazy: true,
+      // Placeholder pré-1ª-query herda `pg.Pool.prototype` pra `instanceof Pool`
+      // valer no wrapper resiliente (transações Drizzle PASS-THROUGH seguras).
+      poolPrototype: Pool?.prototype ?? null
     },
     options
   );
@@ -646,7 +962,9 @@ var LEASE_ENDPOINT, LEASE_RENEW_ENDPOINT;
 var init_sql_client = __esm({
   "src/db/sql/sql-client.ts"() {
     init_db_errors();
+    init_errors();
     init_lease();
+    init_resilient_pool();
     LEASE_ENDPOINT = "/api/sdk/v1/db/lease";
     LEASE_RENEW_ENDPOINT = "/api/sdk/v1/db/lease/renew";
   }