s3db.js 13.6.0 → 14.0.2

package/src/concerns/ip.js

@@ -10,6 +10,7 @@
  */
 
 import tryFn from './try-fn.js';
+import { ValidationError } from '../errors.js';
 
 /**
  * Validate IPv4 address format
@@ -54,7 +55,12 @@ export function isValidIPv6(ip) {
  */
 export function encodeIPv4(ip) {
   if (!isValidIPv4(ip)) {
-    throw new Error(`Invalid IPv4 address: ${ip}`);
+    throw new ValidationError('Invalid IPv4 address', {
+      field: 'ip',
+      value: ip,
+      retriable: false,
+      suggestion: 'Provide a valid IPv4 address (e.g., "192.168.0.1").'
+    });
   }
 
   const octets = ip.split('.').map(octet => parseInt(octet, 10));
@@ -70,21 +76,38 @@ export function encodeIPv4(ip) {
  */
 export function decodeIPv4(encoded) {
   if (typeof encoded !== 'string') {
-    throw new Error('Encoded IPv4 must be a string');
+    throw new ValidationError('Encoded IPv4 must be a string', {
+      field: 'encoded',
+      retriable: false,
+      suggestion: 'Pass the base64-encoded IPv4 string returned by encodeIPv4().'
+    });
   }
 
   const [ok, err, result] = tryFn(() => {
     const buffer = Buffer.from(encoded, 'base64');
 
     if (buffer.length !== 4) {
-      throw new Error(`Invalid encoded IPv4 length: ${buffer.length} (expected 4)`);
+      throw new ValidationError('Invalid encoded IPv4 length', {
+        field: 'encoded',
+        value: encoded,
+        retriable: false,
+        suggestion: 'Ensure the encoded IPv4 string was produced by encodeIPv4().'
+      });
     }
 
     return Array.from(buffer).join('.');
   });
 
   if (!ok) {
-    throw new Error(`Failed to decode IPv4: ${err.message}`);
+    if (err instanceof ValidationError) {
+      throw err;
+    }
+    throw new ValidationError('Failed to decode IPv4', {
+      field: 'encoded',
+      retriable: false,
+      suggestion: 'Confirm the value is a base64-encoded IPv4 string generated by encodeIPv4().',
+      original: err
+    });
   }
 
   return result;
@@ -97,7 +120,12 @@ export function decodeIPv4(encoded) {
  */
 export function expandIPv6(ip) {
   if (!isValidIPv6(ip)) {
-    throw new Error(`Invalid IPv6 address: ${ip}`);
+    throw new ValidationError('Invalid IPv6 address', {
+      field: 'ip',
+      value: ip,
+      retriable: false,
+      suggestion: 'Provide a valid IPv6 address (e.g., "2001:db8::1").'
+    });
   }
 
   // Handle :: expansion
@@ -196,7 +224,12 @@ export function compressIPv6(ip) {
  */
 export function encodeIPv6(ip) {
   if (!isValidIPv6(ip)) {
-    throw new Error(`Invalid IPv6 address: ${ip}`);
+    throw new ValidationError('Invalid IPv6 address', {
+      field: 'ip',
+      value: ip,
+      retriable: false,
+      suggestion: 'Provide a valid IPv6 address (e.g., "2001:db8::1").'
+    });
   }
 
   // Always encode for consistency (like IPv4)
@@ -229,7 +262,11 @@ export function encodeIPv6(ip) {
  */
 export function decodeIPv6(encoded, compress = true) {
   if (typeof encoded !== 'string') {
-    throw new Error('Encoded IPv6 must be a string');
+    throw new ValidationError('Encoded IPv6 must be a string', {
+      field: 'encoded',
+      retriable: false,
+      suggestion: 'Pass the base64-encoded IPv6 string returned by encodeIPv6().'
+    });
   }
 
   // SMART DETECTION: Check if this is unencoded IPv6
@@ -245,7 +282,12 @@ export function decodeIPv6(encoded, compress = true) {
     const buffer = Buffer.from(encoded, 'base64');
 
     if (buffer.length !== 16) {
-      throw new Error(`Invalid encoded IPv6 length: ${buffer.length} (expected 16)`);
+      throw new ValidationError('Invalid encoded IPv6 length', {
+        field: 'encoded',
+        value: encoded,
+        retriable: false,
+        suggestion: 'Ensure the encoded IPv6 string was produced by encodeIPv6().'
+      });
     }
 
     const groups = [];
@@ -260,7 +302,15 @@ export function decodeIPv6(encoded, compress = true) {
   });
 
   if (!ok) {
-    throw new Error(`Failed to decode IPv6: ${err.message}`);
+    if (err instanceof ValidationError) {
+      throw err;
+    }
+    throw new ValidationError('Failed to decode IPv6', {
+      field: 'encoded',
+      retriable: false,
+      suggestion: 'Confirm the value is a base64-encoded IPv6 string generated by encodeIPv6().',
+      original: err
+    });
   }
 
   return result;

package/src/concerns/money.js

@@ -16,6 +16,7 @@
  */
 
 import { encode, decode } from './base62.js';
+import { ValidationError } from '../errors.js';
 
 /**
  * Currency decimal places (number of decimals in smallest unit)
@@ -100,7 +101,13 @@ export function encodeMoney(value, currency = 'USD') {
 
   // Money cannot be negative (validation should happen at schema level)
   if (value < 0) {
-    throw new Error(`Money value cannot be negative: ${value}`);
+    throw new ValidationError('Money value cannot be negative', {
+      field: 'value',
+      value,
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide a non-negative monetary value or store debts in a separate field.'
+    });
   }
 
   const decimals = getCurrencyDecimals(currency);

package/src/concerns/password-hashing.js

@@ -7,6 +7,7 @@
  */
 
 import bcrypt from 'bcrypt';
+import { ValidationError } from '../errors.js';
 
 /**
  * Hash a password using bcrypt (synchronous)
@@ -16,11 +17,21 @@ import bcrypt from 'bcrypt';
  */
 export function hashPasswordSync(password, rounds = 10) {
   if (!password || typeof password !== 'string') {
-    throw new Error('Password must be a non-empty string');
+    throw new ValidationError('Password must be a non-empty string', {
+      field: 'password',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide a non-empty string before calling hashPasswordSync().'
+    });
   }
 
   if (rounds < 4 || rounds > 31) {
-    throw new Error('Bcrypt rounds must be between 4 and 31');
+    throw new ValidationError('Bcrypt rounds must be between 4 and 31', {
+      field: 'rounds',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Configure bcrypt rounds between 4 and 31 (inclusive).'
+    });
   }
 
   return bcrypt.hashSync(password, rounds);
@@ -34,11 +45,21 @@ export function hashPasswordSync(password, rounds = 10) {
  */
 export async function hashPassword(password, rounds = 10) {
   if (!password || typeof password !== 'string') {
-    throw new Error('Password must be a non-empty string');
+    throw new ValidationError('Password must be a non-empty string', {
+      field: 'password',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide a non-empty string before calling hashPassword().'
+    });
   }
 
   if (rounds < 4 || rounds > 31) {
-    throw new Error('Bcrypt rounds must be between 4 and 31');
+    throw new ValidationError('Bcrypt rounds must be between 4 and 31', {
+      field: 'rounds',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Configure bcrypt rounds between 4 and 31 (inclusive).'
+    });
   }
 
   return await bcrypt.hash(password, rounds);
@@ -82,18 +103,33 @@ export async function verifyPassword(plaintext, hash) {
  */
 export function compactHash(bcryptHash) {
   if (!bcryptHash || typeof bcryptHash !== 'string') {
-    throw new Error('Invalid bcrypt hash');
+    throw new ValidationError('Invalid bcrypt hash', {
+      field: 'bcryptHash',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide a valid bcrypt hash generated by hashPassword().'
+    });
   }
 
   // Bcrypt format: $2a$10$ or $2b$10$ or $2y$10$
   if (!bcryptHash.startsWith('$2')) {
-    throw new Error('Not a valid bcrypt hash');
+    throw new ValidationError('Not a valid bcrypt hash', {
+      field: 'bcryptHash',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Ensure the hash starts with "$2" and was produced by bcrypt.'
+    });
   }
 
   // Remove prefix (e.g., "$2b$10$")
   const parts = bcryptHash.split('$');
   if (parts.length !== 4) {
-    throw new Error('Invalid bcrypt hash format');
+    throw new ValidationError('Invalid bcrypt hash format', {
+      field: 'bcryptHash',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide a complete bcrypt hash (e.g., "$2b$10$...").'
+    });
   }
 
   // Return just the salt+hash part (last element after split)
@@ -109,7 +145,12 @@ export function compactHash(bcryptHash) {
  */
 export function expandHash(compactHash, rounds = 10) {
   if (!compactHash || typeof compactHash !== 'string') {
-    throw new Error('Invalid compacted hash');
+    throw new ValidationError('Invalid compacted hash', {
+      field: 'compactHash',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide a compacted hash returned from compactHash().'
+    });
   }
 
   // If it's already a full hash, return as-is

package/src/concerns/plugin-storage.js

@@ -31,6 +31,7 @@
 import { metadataEncode, metadataDecode } from './metadata-encoding.js';
 import { calculateEffectiveLimit, calculateUTF8Bytes } from './calculator.js';
 import { tryFn } from './try-fn.js';
+import { idGenerator } from './id.js';
 import { PluginStorageError, MetadataLimitError, BehaviorError } from '../errors.js';
 
 const S3_METADATA_LIMIT = 2047; // AWS S3 metadata limit in bytes
@@ -89,10 +90,16 @@ export class PluginStorage {
    * @param {number} options.ttl - Time-to-live in seconds (optional)
    * @param {string} options.behavior - 'body-overflow' | 'body-only' | 'enforce-limits'
    * @param {string} options.contentType - Content type (default: application/json)
-   * @returns {Promise<void>}
+   * @returns {Promise<Object>} Underlying client response (includes ETag when available)
    */
   async set(key, data, options = {}) {
-    const { ttl, behavior = 'body-overflow', contentType = 'application/json' } = options;
+    const {
+      ttl,
+      behavior = 'body-overflow',
+      contentType = 'application/json',
+      ifMatch,
+      ifNoneMatch
+    } = options;
 
     // Clone data to avoid mutating original
     const dataToSave = { ...data };
@@ -117,8 +124,15 @@ export class PluginStorage {
       putParams.body = JSON.stringify(body);
     }
 
+    if (ifMatch !== undefined) {
+      putParams.ifMatch = ifMatch;
+    }
+    if (ifNoneMatch !== undefined) {
+      putParams.ifNoneMatch = ifNoneMatch;
+    }
+
     // Save to S3
-    const [ok, err] = await tryFn(() => this.client.putObject(putParams));
+    const [ok, err, response] = await tryFn(() => this.client.putObject(putParams));
 
     if (!ok) {
       throw new PluginStorageError(`Failed to save plugin data`, {
@@ -131,6 +145,8 @@ export class PluginStorage {
         suggestion: 'Check S3 permissions and key format'
       });
     }
+
+    return response;
   }
 
   /**
@@ -165,7 +181,17 @@ export class PluginStorage {
 
     if (!ok) {
       // If not found, return null
-      if (err.name === 'NoSuchKey' || err.Code === 'NoSuchKey') {
+      // Check multiple ways the error might indicate "not found":
+      // 1. error.name is 'NoSuchKey' (standard S3)
+      // 2. error.code is 'NoSuchKey' (ResourceError with code property)
+      // 3. error.Code is 'NoSuchKey' (AWS SDK format)
+      // 4. statusCode is 404
+      if (
+        err.name === 'NoSuchKey' ||
+        err.code === 'NoSuchKey' ||
+        err.Code === 'NoSuchKey' ||
+        err.statusCode === 404
+      ) {
         return null;
       }
       throw new PluginStorageError(`Failed to retrieve plugin data`, {
@@ -625,40 +651,172 @@ export class PluginStorage {
    * @returns {Promise<Object|null>} Lock object or null if couldn't acquire
    */
   async acquireLock(lockName, options = {}) {
-    const { ttl = 30, timeout = 0, workerId = 'unknown' } = options;
+    const {
+      ttl = 30,
+      timeout = 0,
+      workerId = 'unknown',
+      retryDelay = 100,
+      maxRetryDelay = 1000
+    } = options;
     const key = this.getPluginKey(null, 'locks', lockName);
+    const token = idGenerator();
 
     const startTime = Date.now();
+    let attempt = 0;
 
     while (true) {
-      // Try to acquire
-      const existing = await this.get(key);
-      if (!existing) {
-        await this.set(key, { workerId, acquiredAt: Date.now() }, { ttl });
-        return { key, workerId };
+      const payload = {
+        workerId,
+        token,
+        acquiredAt: Date.now()
+      };
+
+      const [ok, err, putResponse] = await tryFn(() => this.set(key, payload, {
+        ttl,
+        behavior: 'body-only',
+        ifNoneMatch: '*'
+      }));
+
+      if (ok) {
+        return {
+          name: lockName,
+          key,
+          token,
+          workerId,
+          expiresAt: Date.now() + ttl * 1000,
+          etag: putResponse?.ETag || null
+        };
+      }
+
+      const originalError = err?.original || err;
+      const errorCode = originalError?.code || originalError?.Code || originalError?.name;
+      const statusCode = originalError?.statusCode || originalError?.$metadata?.httpStatusCode;
+      const isPreconditionFailure = errorCode === 'PreconditionFailed' || statusCode === 412;
+
+      if (!isPreconditionFailure) {
+        throw err;
+      }
+
+      // Check timeout (0 means don't wait, undefined means wait indefinitely)
+      if (timeout !== undefined && Date.now() - startTime >= timeout) {
+        return null;
       }
 
-      // Check timeout
-      if (Date.now() - startTime >= timeout) {
-        return null; // Could not acquire
+      // Remove expired locks (get deletes expired entries automatically)
+      const current = await this.get(key);
+      if (!current) {
+        continue; // Lock expired - retry immediately
       }
 
-      // Wait and retry (100ms intervals)
-      await new Promise(resolve => setTimeout(resolve, 100));
+      attempt += 1;
+      const delay = this._computeBackoff(attempt, retryDelay, maxRetryDelay);
+      await this._sleep(delay);
     }
   }
 
   /**
    * Release a distributed lock
    *
-   * @param {string} lockName - Lock identifier
+   * @param {Object|string} lock - Lock object returned by acquireLock or lock name
+   * @param {string} [token] - Lock token (required when passing lock name)
    * @returns {Promise<void>}
    */
-  async releaseLock(lockName) {
-    const key = this.getPluginKey(null, 'locks', lockName);
+  async releaseLock(lock, token) {
+    if (!lock) return;
+
+    let lockName;
+    let key;
+    let expectedToken = token;
+
+    if (typeof lock === 'object') {
+      lockName = lock.name || lock.lockName;
+      key = lock.key || (lockName ? this.getPluginKey(null, 'locks', lockName) : null);
+      expectedToken = lock.token ?? token;
+      if (!expectedToken && lock.token !== undefined) {
+        throw new PluginStorageError('Lock token missing on lock object', {
+          pluginSlug: this.pluginSlug,
+          operation: 'releaseLock',
+          lockName
+        });
+      }
+    } else if (typeof lock === 'string') {
+      lockName = lock;
+      key = this.getPluginKey(null, 'locks', lockName);
+      expectedToken = token;
+      if (!expectedToken) {
+        throw new PluginStorageError('releaseLock(lockName) now requires the lock token', {
+          pluginSlug: this.pluginSlug,
+          operation: 'releaseLock',
+          lockName,
+          suggestion: 'Pass the original lock object or provide the token explicitly'
+        });
+      }
+    } else {
+      throw new PluginStorageError('releaseLock expects a lock object or lock name', {
+        pluginSlug: this.pluginSlug,
+        operation: 'releaseLock'
+      });
+    }
+
+    if (!key) {
+      throw new PluginStorageError('Invalid lock key', {
+        pluginSlug: this.pluginSlug,
+        operation: 'releaseLock'
+      });
+    }
+
+    const current = await this.get(key);
+    if (!current) {
+      return;
+    }
+
+    if (current.token !== undefined) {
+      if (!expectedToken) {
+        throw new PluginStorageError('releaseLock detected a stored token but none was provided', {
+          pluginSlug: this.pluginSlug,
+          operation: 'releaseLock',
+          lockName,
+          suggestion: 'Always release using the lock object returned by acquireLock'
+        });
+      }
+      if (current.token !== expectedToken) {
+        return;
+      }
+    }
+
     await this.delete(key);
   }
 
+  /**
+   * Acquire a lock, execute a callback, and release automatically.
+   *
+   * @param {string} lockName - Lock identifier
+   * @param {Object} options - Options forwarded to acquireLock
+   * @param {Function} callback - Async function to execute while holding the lock
+   * @returns {Promise<*>} Callback result, or null when lock not acquired
+   */
+  async withLock(lockName, options, callback) {
+    if (typeof callback !== 'function') {
+      throw new PluginStorageError('withLock requires a callback function', {
+        pluginSlug: this.pluginSlug,
+        operation: 'withLock',
+        lockName,
+        suggestion: 'Pass an async function as the third argument'
+      });
+    }
+
+    const lock = await this.acquireLock(lockName, options);
+    if (!lock) {
+      return null;
+    }
+
+    try {
+      return await callback(lock);
+    } finally {
+      await tryFn(() => this.releaseLock(lock));
+    }
+  }
+
   /**
    * Check if a lock is currently held
    *
@@ -671,6 +829,16 @@ export class PluginStorage {
     return lock !== null;
   }
 
+  _computeBackoff(attempt, baseDelay, maxDelay) {
+    const exponential = Math.min(baseDelay * Math.pow(2, Math.max(attempt - 1, 0)), maxDelay);
+    const jitter = Math.floor(Math.random() * Math.max(baseDelay / 2, 1));
+    return exponential + jitter;
+  }
+
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
   /**
    * Increment a counter value
    *