@xeplr/utils 1.0.1 → 1.0.3

package/index.js

@@ -1,9 +1,11 @@
-const { sendEmail, configureEmail, emailConfigFromEnv, configureFromEnv } = require('./lib/email');
+const { sendEmail, configureEmail, emailConfigFromEnv, smtpFromEnv, configureFromEnv } = require('./lib/email');
 const { configureLogger, createSession, log, closeSession, getSessionLogs } = require('./lib/logger');
 const { generateId, formatDbDateTime, mysqlDateTime } = require('./lib/helpers');
 const { respond, sanitizeError } = require('./lib/response');
 const cache = require('./lib/cache');
 const Queue = require('./lib/queue');
+// Which SQL failures are worth trying again — see lib/sql-error.js.
+const { classifySqlError, isRetryableSqlError } = require('./lib/sql-error');
 const FileUploader = require('./lib/fileUploader');
 const RateLimiter = require('./lib/rateLimiter');
 const sms = require('./lib/sms');
@@ -14,6 +16,7 @@ module.exports = {
   sendEmail,
   configureEmail,
   emailConfigFromEnv,
+  smtpFromEnv,
   configureFromEnv,
 
   // Logger client
@@ -38,6 +41,10 @@ module.exports = {
   // Queue
   Queue,
 
+  // SQL error classification (retry decisions, and the code a log line carries)
+  classifySqlError,
+  isRetryableSqlError,
+
   // File Uploader
   FileUploader,
 

package/lib/email.js

@@ -25,7 +25,7 @@ let _deadLetterQueue = null;
  * Configure the email service.
  * @param {object} config
  * @param {string} config.provider - 'smtp' | 'aws' | 'azure' | 'brevo'
- * @param {object} [config.smtp] - { host, port, user, pass, from }
+ * @param {object} [config.smtp] - { host, port, user, pass, from, secure }
  * @param {object} [config.aws] - { region, accessKeyId, secretAccessKey, from }
  * @param {object} [config.azure] - { connectionString, from }
  * @param {object} [config.brevo] - { apiKey, fromEmail, fromName }
@@ -116,19 +116,62 @@ function buildAttachments(attachments) {
 }
 
 async function sendViaSMTP(to, subject, html, cc, attachments) {
-  var cfg = getConfig().smtp;
-  var transporter = loadNodemailer().createTransport({
+  var cfg = getConfig().smtp || {};
+  var port = _num(cfg.port, 587);
+  // 465 is implicit TLS from the first byte; 587 and 25 start in the clear and
+  // negotiate STARTTLS. A hardcoded false made every 465 relay fail on the
+  // handshake, so infer from the port unless it is stated.
+  var secure = cfg.secure === undefined || cfg.secure === null ? port === 465 : !!cfg.secure;
+
+  // Everything the caller set is forwarded; everything it did not is absent,
+  // so nodemailer's defaults stand. Same shape as the email-send action's
+  // connection object, so one SMTP server is described identically whether it
+  // is configured on a workflow step or in this install's env.
+  var transport = _compact({
     host: cfg.host,
-    port: cfg.port,
-    secure: false,
-    auth: { user: cfg.user, pass: cfg.pass }
+    port: port,
+    secure: secure,
+    requireTLS: cfg.requireTLS,
+    ignoreTLS: cfg.ignoreTLS,
+    name: cfg.name,
+    authMethod: cfg.authMethod,
+    connectionTimeout: cfg.connectionTimeout,
+    greetingTimeout: cfg.greetingTimeout,
+    socketTimeout: cfg.socketTimeout,
+    pool: cfg.pool,
+    maxConnections: cfg.maxConnections,
+    maxMessages: cfg.maxMessages,
+    logger: cfg.debug ? undefined : false,
+    debug: cfg.debug,
+    tls: cfg.tls && Object.keys(cfg.tls).length ? cfg.tls : undefined
   });
+  if (cfg.user || cfg.pass) transport.auth = _compact({ user: cfg.user, pass: cfg.pass });
+
+  // Unrecognised options last, so a server that needs something this library
+  // does not name is still reachable without editing this library. `tls` is
+  // merged a level deeper instead of replaced — SMTP_TLS_* and a tls block in
+  // SMTP_OPTIONS are both ways of saying the same thing, and dropping one
+  // because the other was set would be a silent downgrade.
+  if (cfg.options) {
+    var extraTls = cfg.options.tls;
+    Object.keys(cfg.options).forEach(function (k) {
+      if (k !== 'tls') transport[k] = cfg.options[k];
+    });
+    if (extraTls) transport.tls = Object.assign({}, transport.tls, extraTls);
+  }
+
+  var transporter = loadNodemailer().createTransport(transport);
 
   var mailOptions = { from: cfg.from, to, subject, html };
   if (cc && cc.length) mailOptions.cc = cc;
   if (attachments && attachments.length) mailOptions.attachments = buildAttachments(attachments);
 
-  await transporter.sendMail(mailOptions);
+  try {
+    await transporter.sendMail(mailOptions);
+  } finally {
+    // A pooled transport holds sockets open and would keep the process alive.
+    if (typeof transporter.close === 'function') transporter.close();
+  }
 }
 
 async function sendViaAWS(to, subject, html, cc, attachments) {
@@ -315,6 +358,93 @@ async function replayDeadLetters() {
   return items.length;
 }
 
+// ── SMTP from env ───────────────────────────────────────────────────────
+//
+// The same knobs the email-send ACTION already exposes on its connection
+// object (see @xeplr/actions lib/drivers/email/smtp.js), read from env instead
+// of from a workflow step. Kept deliberately open-ended rather than curated
+// per provider: "which SMTP server is this" is not a question this library can
+// answer, and every provider-specific list eventually meets a server that
+// needs one more option. Anything left unset is left OUT of the transport, so
+// nodemailer's own defaults apply.
+
+function _num(v, fallback) {
+  if (v === undefined || v === null || v === '') return fallback;
+  var n = Number(v);
+  return isFinite(n) ? n : fallback;
+}
+
+function _bool(v, fallback) {
+  if (v === undefined || v === null || v === '') return fallback;
+  var t = String(v).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].indexOf(t) !== -1) return true;
+  if (['0', 'false', 'no', 'off'].indexOf(t) !== -1) return false;
+  return fallback;
+}
+
+function _compact(obj) {
+  var out = {};
+  Object.keys(obj || {}).forEach(function (k) {
+    if (obj[k] !== undefined) out[k] = obj[k];
+  });
+  return out;
+}
+
+function smtpFromEnv() {
+  var env = process.env;
+
+  var tls = _compact({
+    rejectUnauthorized: _bool(env.SMTP_TLS_REJECT_UNAUTHORIZED, undefined),
+    servername: env.SMTP_TLS_SERVERNAME || undefined
+  });
+
+  return _compact({
+    host: env.SMTP_HOST,
+    port: _num(env.SMTP_PORT, 587),
+    user: env.SMTP_USER,
+    pass: env.SMTP_PASS,
+    from: env.SMTP_FROM,
+    // Undefined unless stated, so sendViaSMTP infers it from the port.
+    secure: _bool(env.SMTP_SECURE, undefined),
+    requireTLS: _bool(env.SMTP_REQUIRE_TLS, undefined),
+    ignoreTLS: _bool(env.SMTP_IGNORE_TLS, undefined),
+    name: env.SMTP_NAME || undefined,             // EHLO/HELO — some servers are picky
+    authMethod: env.SMTP_AUTH_METHOD || undefined,
+    connectionTimeout: _num(env.SMTP_CONNECTION_TIMEOUT, undefined),
+    greetingTimeout: _num(env.SMTP_GREETING_TIMEOUT, undefined),
+    socketTimeout: _num(env.SMTP_SOCKET_TIMEOUT, undefined),
+    pool: _bool(env.SMTP_POOL, undefined),
+    maxConnections: _num(env.SMTP_MAX_CONNECTIONS, undefined),
+    maxMessages: _num(env.SMTP_MAX_MESSAGES, undefined),
+    debug: _bool(env.SMTP_DEBUG, undefined),
+    tls: Object.keys(tls).length ? tls : undefined,
+    // THE ESCAPE HATCH. Named options cover the common ground; this carries
+    // anything a particular server needs that this library has never heard of
+    // (dkim, proxy, tls.ciphers, a vendor's own flag). Merged last, so it can
+    // also override any of the above.
+    options: _smtpOptionsFromEnv(env.SMTP_OPTIONS)
+  });
+}
+
+// Invalid JSON THROWS rather than being skipped. A typo here would otherwise
+// drop the one option the server actually needed and fail later as a refused
+// connection or, worse, an unencrypted send that looked fine.
+function _smtpOptionsFromEnv(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return undefined;
+  var parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error('SMTP_OPTIONS is not valid JSON: ' + err.message +
+      ' — expected a JSON object, e.g. {"dkim":{"domainName":"x.com"}}');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('SMTP_OPTIONS must be a JSON OBJECT of nodemailer transport options, got ' +
+      (Array.isArray(parsed) ? 'an array' : typeof parsed) + '.');
+  }
+  return parsed;
+}
+
 // Build an email config from env (EMAIL_PROVIDER + provider vars). Pure — returns
 // the config or null if no provider is set. The single source for env→email config.
 function emailConfigFromEnv() {
@@ -329,10 +459,7 @@ function emailConfigFromEnv() {
       fromName: process.env.BREVO_FROM_NAME
     };
   } else if (provider === 'smtp') {
-    config.smtp = {
-      host: process.env.SMTP_HOST, port: process.env.SMTP_PORT,
-      user: process.env.SMTP_USER, pass: process.env.SMTP_PASS, from: process.env.SMTP_FROM
-    };
+    config.smtp = smtpFromEnv();
   }
   // aws / azure read their own vars here when those providers are used.
   return config;
@@ -346,4 +473,4 @@ function configureFromEnv() {
   return true;
 }
 
-module.exports = { sendEmail, configureEmail, emailConfigFromEnv, configureFromEnv, getDeadLetterQueue, replayDeadLetters };
+module.exports = { sendEmail, configureEmail, emailConfigFromEnv, smtpFromEnv, configureFromEnv, getDeadLetterQueue, replayDeadLetters };

package/lib/queue.js

@@ -157,6 +157,8 @@ class Queue {
   }
 }
 
+var { classifySqlError } = require('./sql-error');
+
 // ─────────────────────────────────────────────────────────────────────────
 // SqlQueue — in-memory concurrent worker pool for SQL execution.
 //
@@ -263,7 +265,8 @@ class SqlQueue {
       if (it.movementId === movementId) {
         this._byteTotal -= it.bytes;
         state.queued--;
-        state.dropped++;
+        state.dropped += rowsOf(it);
+        state.statementsDropped++;
       } else {
         kept.push(it);
       }
@@ -275,6 +278,31 @@ class SqlQueue {
     catch (e) { /* swallow — never let a hook block */ }
   }
 
+  // Drop everything queued for a movement that has already aborted.
+  //
+  // Same bookkeeping as abort()'s own sweep — these rows are lost either way,
+  // and a count that omits them is the same lie by a slower route.
+  _purgeAborted() {
+    if (!this._items.length) return;
+    var kept = [];
+    for (var i = 0; i < this._items.length; i++) {
+      var it = this._items[i];
+      var st = this._stateFor(it.movementId);
+      if (st.aborted) {
+        this._byteTotal -= it.bytes;
+        st.queued--;
+        st.dropped += rowsOf(it);
+        st.statementsDropped++;
+      } else {
+        kept.push(it);
+      }
+    }
+    if (kept.length !== this._items.length) {
+      this._items = kept;
+      this._releaseBackpressure();
+    }
+  }
+
   // Stats: per-movement if id passed, else global.
   stats(movementId) {
     if (movementId) {
@@ -302,7 +330,23 @@ class SqlQueue {
   _stateFor(movementId) {
     var s = this._movements.get(movementId);
     if (!s) {
-      s = { movementId: movementId, queued: 0, inFlight: 0, completed: 0, dropped: 0, aborted: false, abortReason: null, consecutiveDrops: 0 };
+      // `completed` and `dropped` count ROWS, not statements.
+      //
+      // They counted statements, and one statement is a multi-row INSERT — so a
+      // 12,000-row movement in three batches reported "completed: 3". That
+      // number is surfaced to people as ROWS LOADED (import_meta.completed, and
+      // the import history page reading it), which meant every import in the
+      // product has been reporting its batch count as a row count.
+      //
+      // Every queued item already carries meta.rowCount; the counters just were
+      // not using it. Statements are counted separately for anyone who wants
+      // them — see statements/statementsDropped.
+      s = {
+        movementId: movementId, queued: 0, inFlight: 0,
+        completed: 0, dropped: 0,
+        statements: 0, statementsDropped: 0,
+        aborted: false, abortReason: null, consecutiveDrops: 0
+      };
       this._movements.set(movementId, s);
     }
     return s;
@@ -321,7 +365,25 @@ class SqlQueue {
         var m = this._items[i].movementId;
         if (!this._stateFor(m).aborted) { idx = i; break; }
       }
-      if (idx < 0) { await sleep(25); continue; }
+      // NOTHING LEFT THAT IS ALLOWED TO RUN — every queued item belongs to a
+      // movement that has aborted. They can never be picked up (this loop
+      // skips aborted movements) and nothing else removes them, so without
+      // this they sit in _items forever and drain() waits on a queue that
+      // will never empty: a movement that has already finished its work and
+      // hangs, with no summary line ever written.
+      //
+      // Reachable because abort() clears what is queued AT THAT MOMENT, while
+      // items keep arriving after it — a bisect re-enqueueing children of an
+      // in-flight failure, or a still-running spool adding the next batch.
+      // Masked until deterministic errors stopped being retried: the retry
+      // backoff used to hold those children in _pendingRetries (which DOES
+      // check aborted) rather than in the queue.
+      if (idx < 0) {
+        this._purgeAborted();
+        await sleep(25);
+        this._maybeSignalIdle();
+        continue;
+      }
 
       var item = this._items.splice(idx, 1)[0];
       this._byteTotal -= item.bytes;
@@ -345,7 +407,8 @@ class SqlQueue {
     try { conn = await this._resolveConnection(item.connection); }
     catch (err) {
       // Connection resolution failure = fatal for the movement.
-      state.dropped++;
+      state.dropped += rowsOf(item);
+      state.statementsDropped++;
       this.abort(item.movementId, 'connection_resolve_failed: ' + err.message);
       return;
     }
@@ -353,7 +416,8 @@ class SqlQueue {
     item.attempt++;
     try {
       await this.executor(item, conn);
-      state.completed++;
+      state.completed += rowsOf(item);
+      state.statements++;
       state.consecutiveDrops = 0;
       return;
     } catch (err) {
@@ -380,6 +444,15 @@ class SqlQueue {
       }
 
       if (decision.decision === 'bisect' && item.meta && Array.isArray(item.meta.rows) && item.meta.rows.length > 1) {
+        // Not into an aborted movement. Splitting a batch to find out which
+        // half is bad is only worth doing if the halves can still run, and
+        // they cannot — the movement has given up. Counted as dropped,
+        // because that is what happens to them.
+        if (state.aborted) {
+          state.dropped += rowsOf(item);
+          state.statementsDropped++;
+          return;
+        }
         var mid = Math.floor(item.meta.rows.length / 2);
         var left = cloneItemWithRows(item, item.meta.rows.slice(0, mid));
         var right = cloneItemWithRows(item, item.meta.rows.slice(mid));
@@ -394,14 +467,22 @@ class SqlQueue {
       }
 
       // 'error-table' | 'drop' | anything else past max attempts → drop
-      state.dropped++;
+      state.dropped += rowsOf(item);
+      state.statementsDropped++;
       state.consecutiveDrops++;
       try {
         this.onErrorTable({
           item: item,
           error: err,
           rowNum: item.meta && item.meta.rowNum,
-          reason: decision.reason || err.message
+          reason: decision.reason || err.message,
+          // The database's OWN identifier for what went wrong ('23502', 515,
+          // 'ER_BAD_NULL_ERROR') and whether it was ever worth retrying —
+          // facts a log analyzer can group by, where the message is prose
+          // that varies by server version and locale.
+          errorCode: decision.errorCode != null ? decision.errorCode : null,
+          errorKind: decision.errorKind || null,
+          attempts: item.attempt
         });
       } catch (_) { /* swallow */ }
       if (state.consecutiveDrops >= this.maxConsecutiveDrops) {
@@ -446,11 +527,40 @@ class SqlQueue {
 function defaultErrorExecutor(ctx) {
   // Default: retry until final attempt, then route the row (or the whole
   // batch if not bisectable) to the error table.
-  if (!ctx.isFinal) return { decision: 'retry' };
-  if (ctx.item.meta && Array.isArray(ctx.item.meta.rows) && ctx.item.meta.rows.length > 1) {
-    return { decision: 'bisect' };
+  //
+  // EXCEPT when the database has already given its final answer. A NOT NULL
+  // violation, a failed cast or a missing column fails identically however
+  // many times it is sent, so retrying one buys nothing and costs the whole
+  // backoff — 65 seconds by default, per item, and a bisect resets its
+  // children to attempt 0 so that multiplies down the tree. Measured on a
+  // 1000-row movement into a NOT NULL column: 105 seconds, nearly all of it
+  // asleep, for a verdict available immediately.
+  //
+  // Straight to bisect instead, which is the fast path to the SAME outcome —
+  // it isolates which rows are bad instead of waiting to find out.
+  // classifySqlError treats anything it does not recognise as retryable, so
+  // this only ever skips waiting when the error is known to be deterministic.
+  var verdict = classifySqlError(ctx.error);
+  var bisectable = ctx.item.meta && Array.isArray(ctx.item.meta.rows) && ctx.item.meta.rows.length > 1;
+
+  if (!verdict.retryable) {
+    if (bisectable) return { decision: 'bisect', errorCode: verdict.code, errorKind: verdict.kind };
+    return {
+      decision: 'error-table',
+      reason: ctx.error && ctx.error.message,
+      errorCode: verdict.code,
+      errorKind: verdict.kind
+    };
   }
-  return { decision: 'error-table', reason: ctx.error && ctx.error.message };
+
+  if (!ctx.isFinal) return { decision: 'retry' };
+  if (bisectable) return { decision: 'bisect', errorCode: verdict.code, errorKind: verdict.kind };
+  return {
+    decision: 'error-table',
+    reason: ctx.error && ctx.error.message,
+    errorCode: verdict.code,
+    errorKind: verdict.kind
+  };
 }
 
 function cloneItemWithRows(item, rows) {
@@ -471,6 +581,14 @@ function cloneItemWithRows(item, rows) {
   return next;
 }
 
+// Rows in one queued item. The uploader puts the real count on meta; anything
+// that queues without one counts as a single row, which keeps a caller that
+// enqueues row-at-a-time honest rather than reporting zero.
+function rowsOf(item) {
+  var n = item && item.meta && item.meta.rowCount;
+  return typeof n === 'number' && n >= 0 ? n : 1;
+}
+
 function approximateBytes(item) {
   try { return JSON.stringify(item).length; } catch (_) { return 128; }
 }
@@ -480,3 +598,4 @@ function sleep(ms) { return new Promise(function(res) { setTimeout(res, ms); });
 module.exports = Queue;
 module.exports.Queue = Queue;
 module.exports.SqlQueue = SqlQueue;
+module.exports.classifySqlError = classifySqlError;

package/lib/sql-error.js

@@ -0,0 +1,208 @@
+// WHICH SQL FAILURES ARE WORTH TRYING AGAIN.
+//
+// A retry is a bet that the same statement, sent again, behaves differently.
+// That bet pays off for a dropped connection, a deadlock victim or a server
+// out of connections — and never for a NOT NULL violation, a bad cast or a
+// column that does not exist. Those fail identically every time, so retrying
+// one costs the backoff (5s + 15s + 45s by default) and then drops the rows
+// anyway.
+//
+// Measured on a real 1000-row movement into a NOT NULL column: 105 seconds,
+// almost all of it asleep, for a verdict available on the first attempt. Worse
+// than slow — a bisect restarts its children at attempt 0, so the wasted
+// backoff multiplies down the bisect tree while a person watches a movement
+// that looks hung.
+//
+// ── why one function serves postgres, mysql and mssql ────────────────────
+//
+// The three drivers throw their native error untouched (see each driver's
+// query()), and each dialect stamps its identity on a DIFFERENT property:
+//
+//   postgres   err.code    5-char SQLSTATE — '23502', '40001'
+//   mysql      err.code    ER_* name, plus err.errno — 'ER_BAD_NULL_ERROR', 1048
+//   mssql      err.number  integer — 515, 1205
+//
+// So the shapes are self-identifying and no dbType has to be threaded through
+// the queue to read them. A caller that HAS the dbType is not asked for it,
+// which keeps this usable from the queue's default error executor — the one
+// place that decides retries, and the one place with no idea what it is
+// talking to.
+//
+// ── unknown means retry ─────────────────────────────────────────────────
+//
+// An unrecognised error is treated as transient, i.e. the behavior before this
+// file existed. Wrongly retrying something deterministic costs time; wrongly
+// dropping something transient loses rows. The default belongs on the side
+// that cannot lose data.
+
+// ── postgres ────────────────────────────────────────────────────────────
+// SQLSTATE is classified by its two-character class where the whole class
+// agrees, which is most of them — listing 200 individual codes would go stale
+// against the next server release for no gain.
+//
+//   22  data exception            invalid text, numeric overflow, bad date
+//   23  integrity constraint      not null, unique, foreign key, check
+//   42  syntax error / access     no such column, no such table, no privilege
+//   3F  invalid schema name
+//   0A  feature not supported
+var PG_DETERMINISTIC_CLASSES = ['22', '23', '42', '3F', '0A'];
+//   08  connection exception      server closed the connection, failure
+//   40  transaction rollback      serialization failure, deadlock detected
+//   53  insufficient resources    too many connections, out of memory/disk
+//   57  operator intervention     shutdown, cannot connect now, admin cancel
+//   58  system error              io error
+var PG_TRANSIENT_CLASSES = ['08', '40', '53', '57', '58'];
+
+// ── mysql ───────────────────────────────────────────────────────────────
+// By errno, because err.code (the ER_ name) is absent on some client
+// versions while errno is always there. Names kept alongside for reading.
+var MYSQL_DETERMINISTIC = {
+  1048: 'ER_BAD_NULL_ERROR',          // column cannot be null
+  1062: 'ER_DUP_ENTRY',               // duplicate key
+  1064: 'ER_PARSE_ERROR',
+  1136: 'ER_WRONG_VALUE_COUNT_ON_ROW',
+  1146: 'ER_NO_SUCH_TABLE',
+  1054: 'ER_BAD_FIELD_ERROR',         // unknown column
+  1264: 'ER_WARN_DATA_OUT_OF_RANGE',
+  1265: 'WARN_DATA_TRUNCATED',
+  1292: 'ER_TRUNCATED_WRONG_VALUE',   // bad date / bad cast
+  1366: 'ER_TRUNCATED_WRONG_VALUE_FOR_FIELD',
+  1406: 'ER_DATA_TOO_LONG',
+  1451: 'ER_ROW_IS_REFERENCED_2',
+  1452: 'ER_NO_REFERENCED_ROW_2',     // foreign key
+  3819: 'ER_CHECK_CONSTRAINT_VIOLATED',
+  1364: 'ER_NO_DEFAULT_FOR_FIELD',
+  1305: 'ER_SP_DOES_NOT_EXIST'
+};
+var MYSQL_TRANSIENT = {
+  1040: 'ER_CON_COUNT_ERROR',         // too many connections
+  1203: 'ER_TOO_MANY_USER_CONNECTIONS',
+  1205: 'ER_LOCK_WAIT_TIMEOUT',
+  1213: 'ER_LOCK_DEADLOCK',
+  1290: 'ER_OPTION_PREVENTS_STATEMENT', // read-only, usually a failover
+  1053: 'ER_SERVER_SHUTDOWN',
+  2002: 'CONNECTION_REFUSED',
+  2003: 'CANT_CONNECT',
+  2006: 'SERVER_GONE_AWAY',
+  2013: 'LOST_CONNECTION'
+};
+// Client-side codes carry no errno at all — a socket that died before the
+// server ever answered.
+var MYSQL_TRANSIENT_CODES = [
+  'PROTOCOL_CONNECTION_LOST', 'PROTOCOL_SEQUENCE_TIMEOUT', 'PROTOCOL_ENQUEUE_AFTER_QUIT',
+  'POOL_CLOSED', 'POOL_CONNLIMIT'
+];
+
+// ── mssql ───────────────────────────────────────────────────────────────
+var MSSQL_DETERMINISTIC = {
+  515:  'cannot insert NULL',
+  547:  'foreign key / check constraint',
+  2601: 'duplicate key in unique index',
+  2627: 'unique constraint violation',
+  245:  'conversion failed',
+  8114: 'error converting data type',
+  8152: 'string or binary data would be truncated',
+  2628: 'string or binary data would be truncated (verbose)',
+  207:  'invalid column name',
+  208:  'invalid object name',
+  102:  'incorrect syntax',
+  220:  'arithmetic overflow',
+  232:  'arithmetic overflow for type',
+  8115: 'arithmetic overflow converting'
+};
+var MSSQL_TRANSIENT = {
+  1205:  'deadlock victim',
+  1222:  'lock request timeout',
+  3960:  'snapshot isolation update conflict',
+  4060:  'cannot open database',
+  40197: 'azure: service error, request processing',
+  40501: 'azure: service busy',
+  40613: 'azure: database unavailable',
+  49918: 'azure: cannot process request, not enough resources',
+  49919: 'azure: cannot process create or update request',
+  49920: 'azure: cannot process request, too many operations',
+  10053: 'transport-level error',
+  10054: 'connection reset by peer',
+  10060: 'connection timeout',
+  233:   'no process on the other end of the pipe',
+  64:    'transport-level error on receive'
+};
+
+// Node's own socket-level failures, dialect-independent: the driver never got
+// far enough for the server to have an opinion.
+var NODE_TRANSIENT_CODES = [
+  'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ESOCKET', 'ESOCKETTIMEOUT',
+  'EPIPE', 'EHOSTUNREACH', 'ENETUNREACH', 'ENOTFOUND', 'EAI_AGAIN',
+  'ECONNCLOSED', 'ETIMEOUT', 'ENOTOPEN'
+];
+
+/**
+ * Classify one database error.
+ *
+ * @returns {{ retryable: boolean, kind: string, code: string|null, dialect: string|null }}
+ *   kind is 'transient' | 'deterministic' | 'unknown'. `code` is whatever the
+ *   dialect stamped on it, as a string, so a log line can carry the database's
+ *   own identifier rather than a paraphrase of it.
+ */
+function classifySqlError(err) {
+  var unknown = { retryable: true, kind: 'unknown', code: null, dialect: null };
+  if (!err) return unknown;
+
+  var code = err.code != null ? String(err.code) : null;
+
+  // Socket-level, before any dialect has spoken.
+  if (code && NODE_TRANSIENT_CODES.indexOf(code) !== -1) {
+    return { retryable: true, kind: 'transient', code: code, dialect: null };
+  }
+
+  // postgres — SQLSTATE: exactly five characters, digits and capitals.
+  if (code && /^[0-9A-Z]{5}$/.test(code)) {
+    var cls = code.slice(0, 2);
+    if (PG_DETERMINISTIC_CLASSES.indexOf(cls) !== -1) {
+      return { retryable: false, kind: 'deterministic', code: code, dialect: 'postgres' };
+    }
+    if (PG_TRANSIENT_CLASSES.indexOf(cls) !== -1) {
+      return { retryable: true, kind: 'transient', code: code, dialect: 'postgres' };
+    }
+    return { retryable: true, kind: 'unknown', code: code, dialect: 'postgres' };
+  }
+
+  // mysql — errno is the reliable half; the ER_ name is not always present.
+  var errno = typeof err.errno === 'number' ? err.errno : null;
+  if (errno != null && (MYSQL_DETERMINISTIC[errno] || MYSQL_TRANSIENT[errno])) {
+    var mysqlCode = code || MYSQL_DETERMINISTIC[errno] || MYSQL_TRANSIENT[errno];
+    return MYSQL_DETERMINISTIC[errno]
+      ? { retryable: false, kind: 'deterministic', code: mysqlCode, dialect: 'mysql' }
+      : { retryable: true,  kind: 'transient',     code: mysqlCode, dialect: 'mysql' };
+  }
+  if (code && MYSQL_TRANSIENT_CODES.indexOf(code) !== -1) {
+    return { retryable: true, kind: 'transient', code: code, dialect: 'mysql' };
+  }
+  // An ER_-named error with an errno this file has never heard of is still
+  // mysql, and still unknown — reported as such rather than guessed at.
+  if (code && /^ER_/.test(code)) {
+    return { retryable: true, kind: 'unknown', code: code, dialect: 'mysql' };
+  }
+
+  // mssql — tedious puts the server's error number on `number`.
+  var number = typeof err.number === 'number' ? err.number : null;
+  if (number != null) {
+    if (MSSQL_DETERMINISTIC[number]) {
+      return { retryable: false, kind: 'deterministic', code: String(number), dialect: 'mssql' };
+    }
+    if (MSSQL_TRANSIENT[number]) {
+      return { retryable: true, kind: 'transient', code: String(number), dialect: 'mssql' };
+    }
+    return { retryable: true, kind: 'unknown', code: String(number), dialect: 'mssql' };
+  }
+
+  return code ? { retryable: true, kind: 'unknown', code: code, dialect: null } : unknown;
+}
+
+/** True only when trying the identical statement again could plausibly work. */
+function isRetryableSqlError(err) { return classifySqlError(err).retryable; }
+
+module.exports = {
+  classifySqlError: classifySqlError,
+  isRetryableSqlError: isRetryableSqlError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/utils",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Utility functions: email (SMTP, AWS SES, Azure, Brevo), cache, queue, logging client, and helpers",
   "main": "index.js",
   "files": [
@@ -69,5 +69,8 @@
     "nodemailer": {
       "optional": true
     }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
   }
 }