@neetru/pgbouncer-arithmetic 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# @neetru/coredb-pgbouncer-arithmetic
+
+Aritmética pura de **dimensionamento do pool do PgBouncer** para as VMs
+Postgres densas do Neetru Core DB. Função pura, determinística,
+**zero dependências de runtime**.
+
+## O problema — o teto de conexões (P0-4)
+
+Uma VM Postgres densa hospeda **N bancos logicos** atrás de um único PgBouncer.
+O `max_connections` do Postgres é um **teto rígido**: se o servidor recebe mais
+conexões que isso, elas começam a **falhar**.
+
+Se os tamanhos de pool do PgBouncer são cravados na mão, o problema é silencioso
+até crescer: o 1º, 2º, 3º produto cabem; o **5º–10º produto satura o teto** e a
+partir daí qualquer conexão nova falha — para todos os bancos da VM, não só o
+último.
+
+Este pacote remove o número mágico. Ele **deriva** o dimensionamento do
+PgBouncer a partir de duas grandezas reais — `max_connections` da VM e a
+**contagem viva de bancos** — de modo que a soma das conexões reais ao Postgres
+nunca estoure o teto.
+
+## API
+
+```ts
+import {
+  computePoolSizing,
+  assertConnectionInvariant,
+  type PoolSizing,
+} from '@neetru/coredb-pgbouncer-arithmetic';
+```
+
+### `computePoolSizing(nBancos, maxConnections?): PoolSizing`
+
+Dimensiona o pool do PgBouncer para uma VM.
+
+```ts
+computePoolSizing(4);        // 4 bancos, max_connections default 100
+// { defaultPoolSize: 23, reservePoolSize: 5, maxClientConn: 500 }
+
+computePoolSizing(10, 100);  // 10 bancos
+// { defaultPoolSize: 9, reservePoolSize: 2, maxClientConn: 500 }
+```
+
+| Campo | Significado |
+|---|---|
+| `defaultPoolSize` | `default_pool_size` — conexões de **servidor** por banco. |
+| `reservePoolSize` | `reserve_pool_size` — folga de burst (¼ do `defaultPoolSize`). |
+| `maxClientConn` | `max_client_conn` — conexões de **cliente** aceitas. Fixo em `500`. |
+
+A derivação:
+
+- `RESERVED_CONNECTIONS = 8` — superusuário + monitoring + sondas do agente,
+  tiradas do teto antes do rateio.
+- `usable = max(maxConnections - 8, nBancos)` — conexões disponíveis para os
+  pools dos produtos; nunca menos de 1 por banco.
+- `defaultPoolSize = max(2, floor(usable / nBancos))` — o `floor` garante a
+  **propriedade central de segurança**:
+
+  ```
+  nBancos × defaultPoolSize ≤ usable
+  ```
+
+  ou seja, a soma das conexões reais ao Postgres nunca estoura o teto. O
+  `max(2, …)` é um **floor de viabilidade** — um pool de tamanho 1 é inútil.
+- `reservePoolSize = max(1, floor(defaultPoolSize / 4))`.
+- `maxClientConn = 500`.
+
+**Sanitização (fail-safe):**
+
+- `maxConnections` — não-finito / `< 1` / ausente → cai para `100`.
+- `nBancos` — coagido a inteiro positivo (`floor`); NaN / `Infinity` / `≤ 0`
+  caem para `1`. O chamador **deve** passar a contagem viva real — o fallback
+  para 1 é a última linha de defesa contra lixo, não algo em que se apoiar.
+
+**Edge de over-densidade:** quando há bancos demais numa VM pequena,
+`floor(usable / nBancos)` pode dar 0 ou 1 e o **floor-de-2** entra. Nessa
+região `nBancos × 2` *pode* exceder `usable` — a propriedade de segurança é
+rompida. Isso não é um bug do cálculo: é o **sinal de uma VM genuinamente
+over-densa**. `computePoolSizing` ainda devolve `defaultPoolSize: 2` (o mínimo
+viável — um pool menor não funciona), mas o valor **não finge ser seguro**
+nessa região. A correção é operacional: hospedar menos bancos ou usar uma VM
+maior (mais `max_connections`). O chamador que opera VMs densas deve cruzar
+`nBancos × 2 ≤ usable` e alertar. `computePoolSizing` **não lança** — é
+aritmética pura.
+
+### `assertConnectionInvariant({ sdkPoolMax, maxInstances, defaultPoolSize }): void`
+
+Protege a invariante crítica de **autoscaling**:
+
+```
+sdkPoolMax × maxInstances ≤ defaultPoolSize
+```
+
+Cada instância do Cloud Run roda um `pg.Pool` com até `sdkPoolMax` conexões.
+Sob autoscaling até `maxInstances` instâncias sobem ao mesmo tempo. O total que
+o produto pode demandar do PgBouncer é `sdkPoolMax × maxInstances` — e isso não
+pode exceder o `default_pool_size`, ou o produto satura o pool e as conexões
+falham.
+
+```ts
+assertConnectionInvariant({ sdkPoolMax: 2, maxInstances: 4, defaultPoolSize: 8 });
+// ok — 2 × 4 = 8 ≤ 8
+
+assertConnectionInvariant({ sdkPoolMax: 2, maxInstances: 5, defaultPoolSize: 8 });
+// throws — 2 × 5 = 10 > 8
+```
+
+**Fail-closed:** qualquer um dos três valores que não seja inteiro positivo
+finito **lança** — uma entrada lixo nunca passa silenciosa. Se a invariante for
+violada, o erro nomeia os três números e diz o que fazer: reduzir `pg.Pool.max`,
+reduzir o `maxInstances` do Cloud Run, ou aumentar o `default_pool_size`
+hospedando menos bancos / usando uma VM maior.
+
+## Estado
+
+Implementado (M0 — P0-4). Suíte vitest cobrindo a derivação default, a
+propriedade de segurança no regime normal, a região do floor-de-2, sanitização
+de ambos os argumentos, determinismo e a invariante de autoscaling fail-closed.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @neetru/coredb-pgbouncer-arithmetic
+ *
+ * Aritmetica pura de dimensionamento do pool do PgBouncer. Uma VM Postgres
+ * densa hospeda N bancos logicos atras de um unico PgBouncer; `max_connections`
+ * e um teto rigido. Este pacote deriva o dimensionamento do PgBouncer a partir
+ * de `max_connections` e da contagem viva de bancos, e protege a invariante
+ * critica de autoscaling `sdkPoolMax * maxInstances <= defaultPoolSize`.
+ *
+ * Funcao pura, deterministica, zero dependencias de runtime. Fecha o teto de
+ * conexoes (P0-4).
+ */
+export { computePoolSizing, assertConnectionInvariant } from './sizing.js';
+export type { PoolSizing } from './types.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @neetru/coredb-pgbouncer-arithmetic
+ *
+ * Aritmetica pura de dimensionamento do pool do PgBouncer. Uma VM Postgres
+ * densa hospeda N bancos logicos atras de um unico PgBouncer; `max_connections`
+ * e um teto rigido. Este pacote deriva o dimensionamento do PgBouncer a partir
+ * de `max_connections` e da contagem viva de bancos, e protege a invariante
+ * critica de autoscaling `sdkPoolMax * maxInstances <= defaultPoolSize`.
+ *
+ * Funcao pura, deterministica, zero dependencias de runtime. Fecha o teto de
+ * conexoes (P0-4).
+ */
+export { computePoolSizing, assertConnectionInvariant } from './sizing.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC"}

package/dist/sizing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Aritmetica de dimensionamento do pool do PgBouncer.
+ *
+ * Uma VM Postgres densa hospeda N bancos logicos atras de um unico PgBouncer.
+ * `max_connections` do Postgres e um teto rigido. Se os tamanhos de pool sao
+ * cravados na mao, o 5o-10o produto satura o teto e conexoes comecam a falhar.
+ * Este modulo deriva o dimensionamento do PgBouncer a partir de
+ * `max_connections` e da contagem viva de bancos, e protege a invariante
+ * critica de autoscaling.
+ */
+import type { PoolSizing } from './types.js';
+/**
+ * Dimensiona o pool do PgBouncer para uma VM Postgres densa.
+ *
+ * @param nBancos        Contagem viva real de bancos logicos na VM. Precisa
+ *                       ser um inteiro 1..10000; lixo LANCA (nao ha fallback —
+ *                       cair para 1 seria fail-open e poderia estourar o teto).
+ * @param maxConnections `max_connections` do Postgres da VM. Default 100 se
+ *                       omitido; lixo (NaN/Infinity/<1) LANCA; fracionario
+ *                       sofre `Math.floor`.
+ * @returns Dimensionamento puro e deterministico do pool.
+ * @throws {Error} se `nBancos` ou `maxConnections` forem invalidos.
+ */
+export declare function computePoolSizing(nBancos: number, maxConnections?: number): PoolSizing;
+/**
+ * Protege a invariante critica de autoscaling:
+ *
+ *   sdkPoolMax * maxInstances <= defaultPoolSize
+ *
+ * Cada instancia do Cloud Run roda um `pg.Pool` com ate `sdkPoolMax` conexoes.
+ * Sob autoscaling ate `maxInstances` instancias podem subir ao mesmo tempo. O
+ * total de conexoes que o produto pode demandar do PgBouncer e
+ * `sdkPoolMax * maxInstances`, e isso NAO pode exceder `default_pool_size`, ou
+ * o produto satura o pool e conexoes comecam a falhar.
+ *
+ * FAIL-CLOSED: qualquer um dos tres valores que nao seja inteiro positivo
+ * finito faz LANCAR — uma entrada lixo nunca passa silenciosa.
+ *
+ * @throws {Error} se algum input for invalido, ou se a invariante for violada.
+ */
+export declare function assertConnectionInvariant(input: {
+    sdkPoolMax: number;
+    maxInstances: number;
+    defaultPoolSize: number;
+}): void;

package/dist/sizing.js

@@ -0,0 +1,157 @@
+/**
+ * Aritmetica de dimensionamento do pool do PgBouncer.
+ *
+ * Uma VM Postgres densa hospeda N bancos logicos atras de um unico PgBouncer.
+ * `max_connections` do Postgres e um teto rigido. Se os tamanhos de pool sao
+ * cravados na mao, o 5o-10o produto satura o teto e conexoes comecam a falhar.
+ * Este modulo deriva o dimensionamento do PgBouncer a partir de
+ * `max_connections` e da contagem viva de bancos, e protege a invariante
+ * critica de autoscaling.
+ */
+/**
+ * Conexoes que NUNCA pertencem aos pools dos produtos: superusuario,
+ * monitoring, sondas (probes) do agente. Subtraidas do teto antes do rateio.
+ */
+const RESERVED_CONNECTIONS = 8;
+/**
+ * Teto fixo de conexoes de CLIENTE que o PgBouncer aceita. Conexoes de cliente
+ * sao baratas (nao consomem conexao de servidor enquanto ociosas no pooling
+ * em modo transaction), por isso o valor e generoso e constante.
+ */
+const MAX_CLIENT_CONN = 500;
+/** Default de `max_connections` quando o chamador nao informa um valor. */
+const DEFAULT_MAX_CONNECTIONS = 100;
+/**
+ * Teto sano para a contagem de bancos numa VM. Acima disso a entrada e
+ * quase certamente lixo (nenhuma VM Postgres hospeda 10 mil bancos logicos
+ * atras de um unico PgBouncer) — melhor falhar alto do que dimensionar.
+ */
+const MAX_N_BANCOS = 10000;
+/**
+ * Valida e saneia `maxConnections`.
+ *
+ * - `undefined` → default 100.
+ * - Numero finito >= 1 → aceito. Fracionario sofre `Math.floor` (um
+ *   `max_connections` fracionario nao faz sentido; truncar e inofensivo e
+ *   leniente). Um inteiro pequeno legitimo (ex.: 20) e aceito — e um Postgres
+ *   pequeno, nao lixo.
+ * - Qualquer outra coisa (NaN, Infinity, negativo, zero, nao-numero) →
+ *   LANCA. Uma config de Postgres lixo nunca passa silenciosa (fail-loud).
+ *
+ * @throws {Error} se `maxConnections` for fornecido e nao for finito ou < 1.
+ */
+function sanitizeMaxConnections(maxConnections) {
+    if (maxConnections === undefined) {
+        return DEFAULT_MAX_CONNECTIONS;
+    }
+    if (typeof maxConnections !== 'number' || !Number.isFinite(maxConnections) || maxConnections < 1) {
+        throw new Error(`computePoolSizing: maxConnections invalido — precisa ser um numero finito >= 1 ` +
+            `(o max_connections real do Postgres), recebeu ${String(maxConnections)}.`);
+    }
+    return Math.floor(maxConnections);
+}
+/**
+ * Valida `nBancos`. NAO ha fallback: dimensionar um pool de conexao sem a
+ * contagem real de bancos e fail-OPEN — cair para 1 produz o MAIOR pool por
+ * banco e, se a VM hospeda muitos bancos, o total estoura o `max_connections`
+ * do Postgres. Por isso uma contagem lixo LANCA.
+ *
+ * `nBancos` precisa ser um inteiro finito no intervalo `1 <= nBancos <= 10000`.
+ *
+ * @throws {Error} se `nBancos` nao for um inteiro positivo no intervalo sano.
+ */
+function validateNBancos(nBancos) {
+    if (typeof nBancos !== 'number' ||
+        !Number.isInteger(nBancos) ||
+        nBancos < 1 ||
+        nBancos > MAX_N_BANCOS) {
+        throw new Error(`computePoolSizing: nBancos invalido — precisa ser um inteiro 1..${MAX_N_BANCOS} ` +
+            `(a contagem real de bancos na VM); nao da pra dimensionar um pool sem a ` +
+            `contagem real, recebeu ${String(nBancos)}.`);
+    }
+    return nBancos;
+}
+/**
+ * Dimensiona o pool do PgBouncer para uma VM Postgres densa.
+ *
+ * @param nBancos        Contagem viva real de bancos logicos na VM. Precisa
+ *                       ser um inteiro 1..10000; lixo LANCA (nao ha fallback —
+ *                       cair para 1 seria fail-open e poderia estourar o teto).
+ * @param maxConnections `max_connections` do Postgres da VM. Default 100 se
+ *                       omitido; lixo (NaN/Infinity/<1) LANCA; fracionario
+ *                       sofre `Math.floor`.
+ * @returns Dimensionamento puro e deterministico do pool.
+ * @throws {Error} se `nBancos` ou `maxConnections` forem invalidos.
+ */
+export function computePoolSizing(nBancos, maxConnections) {
+    const safeMaxConn = sanitizeMaxConnections(maxConnections);
+    const safeNBancos = validateNBancos(nBancos);
+    // `usable` = conexoes disponiveis para os pools dos produtos, depois de
+    // tirar as reservadas. O `Math.max` com `safeNBancos` garante ao menos 1
+    // conexao por banco mesmo numa VM minuscula (floor(usable/nBancos) >= 1).
+    const usable = Math.max(safeMaxConn - RESERVED_CONNECTIONS, safeNBancos);
+    // `floor(usable / nBancos)` garante a propriedade central de seguranca:
+    //   nBancos * defaultPoolSize <= usable
+    // ou seja, a soma das conexoes reais ao Postgres NUNCA estoura o teto.
+    //
+    // EDGE DE OVER-DENSIDADE: o `Math.max(2, ...)` impoe um floor de viabilidade
+    // — um pool com tamanho 1 e inutil. Quando ha bancos demais numa VM pequena,
+    // `floor(usable/nBancos)` pode dar 0 ou 1 e o floor-de-2 entra. Nesse caso
+    // `nBancos * 2` PODE exceder `usable` — a propriedade de seguranca e
+    // ROMPIDA. Isso NAO e silenciado por capricho: e o sinal de uma VM
+    // genuinamente over-densa. A correcao real e operacional — hospedar menos
+    // bancos ou subir para uma VM maior (mais `max_connections`). `computePoolSizing`
+    // ainda devolve `defaultPoolSize: 2` (o minimo viavel) porque um pool menor
+    // que 2 nao funciona; mas o valor NAO finge ser seguro nessa regiao. O
+    // chamador que opera VMs densas deve cruzar `nBancos * 2 <= usable` e alertar.
+    const defaultPoolSize = Math.max(2, Math.floor(usable / safeNBancos));
+    // Folga de burst — um quarto do pool base, no minimo 1.
+    const reservePoolSize = Math.max(1, Math.floor(defaultPoolSize / 4));
+    return {
+        defaultPoolSize,
+        reservePoolSize,
+        maxClientConn: MAX_CLIENT_CONN,
+    };
+}
+/** Verdadeiro sse `n` e um inteiro finito estritamente positivo. */
+function isPositiveInteger(n) {
+    return typeof n === 'number' && Number.isInteger(n) && n > 0;
+}
+/**
+ * Protege a invariante critica de autoscaling:
+ *
+ *   sdkPoolMax * maxInstances <= defaultPoolSize
+ *
+ * Cada instancia do Cloud Run roda um `pg.Pool` com ate `sdkPoolMax` conexoes.
+ * Sob autoscaling ate `maxInstances` instancias podem subir ao mesmo tempo. O
+ * total de conexoes que o produto pode demandar do PgBouncer e
+ * `sdkPoolMax * maxInstances`, e isso NAO pode exceder `default_pool_size`, ou
+ * o produto satura o pool e conexoes comecam a falhar.
+ *
+ * FAIL-CLOSED: qualquer um dos tres valores que nao seja inteiro positivo
+ * finito faz LANCAR — uma entrada lixo nunca passa silenciosa.
+ *
+ * @throws {Error} se algum input for invalido, ou se a invariante for violada.
+ */
+export function assertConnectionInvariant(input) {
+    const { sdkPoolMax, maxInstances, defaultPoolSize } = input;
+    if (!isPositiveInteger(sdkPoolMax)) {
+        throw new Error(`assertConnectionInvariant: sdkPoolMax deve ser um inteiro positivo, recebeu ${String(sdkPoolMax)}.`);
+    }
+    if (!isPositiveInteger(maxInstances)) {
+        throw new Error(`assertConnectionInvariant: maxInstances deve ser um inteiro positivo, recebeu ${String(maxInstances)}.`);
+    }
+    if (!isPositiveInteger(defaultPoolSize)) {
+        throw new Error(`assertConnectionInvariant: defaultPoolSize deve ser um inteiro positivo, recebeu ${String(defaultPoolSize)}.`);
+    }
+    const demanded = sdkPoolMax * maxInstances;
+    if (demanded > defaultPoolSize) {
+        throw new Error(`Invariante de conexao violada: sdkPoolMax (${sdkPoolMax}) x maxInstances ` +
+            `(${maxInstances}) = ${demanded}, que excede defaultPoolSize (${defaultPoolSize}). ` +
+            `Sob autoscaling esse produto satura o pool do PgBouncer e conexoes vao ` +
+            `falhar. Corrija de uma destas formas: reduza pg.Pool.max (sdkPoolMax), ` +
+            `reduza o maxInstances do Cloud Run, ou aumente o default_pool_size ` +
+            `hospedando menos bancos na VM / usando uma VM maior (mais max_connections).`);
+    }
+}
+//# sourceMappingURL=sizing.js.map

package/dist/sizing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sizing.js","sourceRoot":"","sources":["../src/sizing.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tipos canonicos do `@neetru/coredb-pgbouncer-arithmetic`.
+ */
+/**
+ * Dimensionamento do pool do PgBouncer derivado do `max_connections` do
+ * Postgres e da contagem viva de bancos da VM.
+ */
+export interface PoolSizing {
+    /**
+     * `default_pool_size` do PgBouncer — quantas conexoes de servidor o pool
+     * abre por banco.
+     *
+     * No regime normal vale a propriedade de seguranca
+     * `nBancos * defaultPoolSize <= usable` — a soma das conexoes reais ao
+     * Postgres nao estoura o teto.
+     *
+     * EXCECAO — VM over-densa: quando `floor(usable/nBancos) < 2`, entra o floor
+     * de viabilidade `defaultPoolSize: 2` (um pool menor que 2 nao funciona).
+     * Nessa regiao `nBancos * 2` PODE exceder `usable` — o `2` e um valor de
+     * viabilidade MINIMA, NAO um valor seguro. E o sinal de que a VM tem bancos
+     * demais: a correcao e operacional (hospedar menos bancos ou subir
+     * `max_connections`).
+     */
+    defaultPoolSize: number;
+    /**
+     * `reserve_pool_size` do PgBouncer — folga de burst acima do
+     * `default_pool_size`. Derivado como um quarto do `defaultPoolSize`.
+     */
+    reservePoolSize: number;
+    /**
+     * `max_client_conn` do PgBouncer — quantas conexoes de CLIENTE o PgBouncer
+     * aceita. E barato (conexao de cliente nao consome conexao de servidor) e
+     * fixo em 500.
+     */
+    maxClientConn: number;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Tipos canonicos do `@neetru/coredb-pgbouncer-arithmetic`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name":  "@neetru/pgbouncer-arithmetic",
+    "version":  "0.1.0",
+    "description":  "Dimensionamento aritmetico do pool do PgBouncer derivado do max_connections do Postgres e da contagem viva de bancos. Garante que a VM Postgres densa nunca estoure o teto de conexoes sob autoscaling. Funcao pura, zero dependencias.",
+    "license":  "UNLICENSED",
+    "type":  "module",
+    "main":  "./dist/index.js",
+    "types":  "./dist/index.d.ts",
+    "exports":  {
+                    ".":  {
+                              "types":  "./dist/index.d.ts",
+                              "default":  "./dist/index.js"
+                          }
+                },
+    "files":  [
+                  "dist"
+              ],
+    "scripts":  {
+                    "build":  "tsc",
+                    "test":  "vitest run"
+                },
+    "dependencies":  {
+
+                     },
+    "devDependencies":  {
+                            "typescript":  "^5.6.0",
+                            "vitest":  "^2.1.0"
+                        },
+    "engines":  {
+                    "node":  "\u003e=20"
+                }
+}