@celerispay/hazelcast-client 3.12.5 → 3.12.7

package/QUICK_START.md

@@ -1,143 +1,232 @@
-# Quick Start - Fixed Hazelcast Node.js Client 3.12.5
+# Hazelcast Node.js Client - Quick Start Guide
+
+## Version Information
+- **Package**: `@celerispay/hazelcast-client`
+- **Version**: `3.12.5-1`
+- **Publisher**: CelerisPay
+- **Base Version**: 3.12.5 (Hazelcast Inc.)
+
+## Overview
+This is a production-ready, enhanced version of the Hazelcast Node.js client with critical failover fixes that resolve connection management issues in production environments.
 
 ## Installation
 
+### Install the Fixed Version
 ```bash
-# Install the fixed version
-npm install @celerispay/hazelcast-client@3.12.5
+npm install @celerispay/hazelcast-client@3.12.5-1
+```
 
-# Or if you're using yarn
-yarn add @celerispay/hazelcast-client@3.12.5
+### Verify Installation
+```bash
+npm list @celerispay/hazelcast-client
+# Should show version 3.12.5-1
 ```
 
 ## Basic Usage
 
+### Import the Client
+```javascript
+const { ClientConfig, HazelcastClient } = require('@celerispay/hazelcast-client');
+```
+
+### Create Client Configuration
 ```javascript
-const { HazelcastClient } = require('@celerispay/hazelcast-client');
-
-async function createClient() {
-    const client = await HazelcastClient.newHazelcastClient({
-        networkConfig: {
-            addresses: ['10.0.20.30:5701', '10.0.20.31:5701'],
-            connectionAttemptLimit: 5,
-            connectionTimeout: 10000,
-            redoOperation: true,
-            smartRouting: true
-        },
-        properties: {
-            'hazelcast.client.connection.health.check.interval': 5000,
-            'hazelcast.client.connection.max.retries': 3,
-            'hazelcast.client.failover.cooldown': 5000,
-            'hazelcast.client.invocation.max.retries': 10
-        }
-    });
+const config = new ClientConfig();
+config.networkConfig.addresses = ['127.0.0.1:5701', '127.0.0.1:5702'];
+
+// Enhanced failover settings (automatically configured)
+config.properties['hazelcast.client.connection.health.check.interval'] = 5000;
+config.properties['hazelcast.client.failover.cooldown'] = 5000;
+config.properties['hazelcast.client.partition.refresh.min.interval'] = 2000;
+```
+
+### Connect and Use
+```javascript
+async function main() {
+    const client = await HazelcastClient.newHazelcastClient(config);
+    
+    const map = await client.getMap('myMap');
+    await map.put('key', 'value');
+    
+    const value = await map.get('key');
+    console.log('Value:', value);
     
-    return client;
+    await client.shutdown();
 }
+
+main().catch(console.error);
 ```
 
 ## Key Improvements
 
-✅ **Connection Health Monitoring** - Active health checks every 5 seconds  
-✅ **Automatic Failover** - Seamless switching to healthy nodes  
-✅ **Connection Cleanup** - No more connection leakage  
-✅ **Smart Retry Logic** - Intelligent retry with backoff  
-✅ **Partition Table Refresh** - Automatic partition ownership updates  
-✅ **Address Blocking** - Temporary blocking of failed addresses to prevent repeated failures  
+### 1. **Robust Failover**
+- Automatic detection of node failures
+- Intelligent failover to healthy nodes
+- Failover cooldown to prevent rapid switching
+
+### 2. **Connection Health Monitoring**
+- Continuous connection health checks
+- Automatic cleanup of failed connections
+- Prevention of connection leakage
+
+### 3. **Address Blocking System**
+- Temporary blocking of failed addresses (30 seconds)
+- Automatic unblocking after block duration
+- Prevention of repeated connection attempts
 
-## Configuration
+### 4. **Enhanced Error Handling**
+- Near cache crash prevention during failover
+- Graceful degradation during cluster changes
+- Comprehensive error logging
 
-### Essential Properties
+### 5. **Intelligent Reconnection**
+- Automatic reconnection to recovered nodes
+- Smart ownership management
+- Partition table refresh management
 
+## Configuration Properties
+
+### Connection Management
 ```javascript
-properties: {
-    // Connection health monitoring
-    'hazelcast.client.connection.health.check.interval': 5000,
-    'hazelcast.client.connection.max.retries': 3,
-    'hazelcast.client.connection.retry.delay': 1000,
-    
-    // Failover control
-    'hazelcast.client.failover.cooldown': 5000,
-    'hazelcast.client.partition.refresh.min.interval': 2000,
-    
-    // Retry behavior
-    'hazelcast.client.invocation.max.retries': 10,
-    'hazelcast.client.partition.failure.backoff': 2000
-}
+config.properties['hazelcast.client.connection.health.check.interval'] = 5000;  // 5 seconds
+config.properties['hazelcast.client.connection.max.retries'] = 3;              // Max 3 retries
+config.properties['hazelcast.client.connection.retry.delay'] = 1000;           // 1 second delay
 ```
 
-### Network Configuration
+### Failover Control
+```javascript
+config.properties['hazelcast.client.failover.cooldown'] = 5000;                // 5 seconds cooldown
+config.properties['hazelcast.client.partition.refresh.min.interval'] = 2000;   // 2 seconds minimum
+```
 
+### Retry Behavior
 ```javascript
-networkConfig: {
-    addresses: ['node1:5701', 'node2:5701'],
-    connectionAttemptLimit: 5,        // Increased from 2
-    connectionTimeout: 10000,         // Increased from 5000
-    redoOperation: true,              // Changed from false
-    smartRouting: true
-}
+config.properties['hazelcast.client.invocation.max.retries'] = 10;            // Max 10 retries
+config.properties['hazelcast.client.partition.failure.backoff'] = 2000;       // 2 seconds backoff
 ```
 
-## Testing the Fix
+## Testing
 
+### Run the Test Suite
 ```bash
-# Run the failover tests
-npm test -- --grep "Connection Failover Test"
-
-# Run all tests
 npm test
 ```
 
-## Migration from Previous Versions
+### Verify Configuration
+```bash
+node -e "
+const { ClientConfig } = require('@celerispay/hazelcast-client');
+const config = new ClientConfig();
+console.log('Enhanced properties:', Object.keys(config.properties).filter(p => p.includes('connection') || p.includes('failover')));
+"
+```
+
+## Migration from Original Client
 
-1. **Update package.json**:
-   ```json
-   "dependencies": {
-     "@celerispay/hazelcast-client": "3.12.5"
-   }
-   ```
+### 1. **Update Package Name**
+```bash
+# Remove original
+npm uninstall hazelcast-client
 
-2. **Update import statement**:
-   ```javascript
-   // Before
-   const { HazelcastClient } = require('hazelcast-client');
-   
-   // After
-   const { HazelcastClient } = require('@celerispay/hazelcast-client');
-   ```
+# Install fixed version
+npm install @celerispay/hazelcast-client@3.12.5-1
+```
 
-3. **No other code changes required** - All fixes are backward compatible
+### 2. **Update Import Statement**
+```javascript
+// Before
+const { ClientConfig } = require('hazelcast-client');
 
-## What's Fixed
+// After
+const { ClientConfig } = require('@celerispay/hazelcast-client');
+```
 
-- ❌ **Before**: Client hangs on partition owner failure
-- ✅ **After**: Automatic failover to healthy nodes
+### 3. **No Code Changes Required**
+- All existing code will work unchanged
+- Failover behavior will automatically improve
+- Connection management will be more robust
 
-- ❌ **Before**: Connection count keeps increasing
-- ✅ **After**: Failed connections are properly cleaned up
+## Production Recommendations
 
-- ❌ **Before**: Invocations hang indefinitely
-- ✅ **After**: Operations fail gracefully with retry limits
+### 1. **Enable Statistics**
+```javascript
+config.properties['hazelcast.client.statistics.enabled'] = true;
+```
 
-- ❌ **Before**: No health monitoring
-- ✅ **After**: Active connection health checking
+### 2. **Monitor Logs**
+Watch for these log messages:
+- `"Starting failover process..."`
+- `"Failover completed successfully"`
+- `"Connection health check interval"`
+- `"Address blocked for X seconds"`
 
-- ❌ **Before**: Repeated attempts to failed nodes
-- ✅ **After**: Temporary blocking of failed addresses (30 seconds)
+### 3. **Load Testing**
+Test failover scenarios under load:
+- Stop partition owner nodes
+- Monitor automatic failover
+- Verify reconnection to recovered nodes
 
-## Production Recommendations
+### 4. **Network Configuration**
+```javascript
+config.networkConfig.connectionAttemptLimit = 5;    // Increased from default
+config.networkConfig.connectionTimeout = 10000;     // Increased from default
+config.networkConfig.redoOperation = true;          // Enable for better failover
+```
 
-1. **Enable Statistics**: `'hazelcast.client.statistics.enabled': true`
-2. **Monitor Logs**: Watch for failover events and address blocking
-3. **Load Test**: Verify failover behavior under load
-4. **Health Checks**: Use connection health metrics
+## What's Fixed
+
+### ✅ **Connection Bombardment**
+- No more repeated connection attempts to failed nodes
+- Intelligent address blocking prevents network spam
+- Connection health monitoring detects failures early
+
+### ✅ **Failover Failures**
+- Automatic failover to healthy nodes
+- Proper partition table management during failover
+- Failover cooldown prevents rapid switching
+
+### ✅ **Near Cache Crashes**
+- Comprehensive error handling prevents crashes
+- Graceful degradation during cluster changes
+- Safe fallback values during failover
+
+### ✅ **Connection Leakage**
+- Automatic cleanup of failed connections
+- Periodic connection health checks
+- Memory leak prevention
+
+### ✅ **Hanging Operations**
+- Maximum retry limits prevent infinite loops
+- Proper error handling and logging
+- Graceful failure with user feedback
 
 ## Support
 
-- **Documentation**: See `FAILOVER_FIXES.md` for detailed information
-- **Tests**: Run test suite to verify functionality
-- **Issues**: Report problems in the repository
+### **Package Information**
+- **Name**: `@celerispay/hazelcast-client`
+- **Version**: `3.12.5-1`
+- **Publisher**: CelerisPay
+
+### **Documentation**
+- **Technical Details**: See `FAILOVER_FIXES.md`
+- **Release Notes**: See `CHANGELOG.md`
+- **Repository**: https://github.com/celerispay/hazelcast-nodejs-client
+
+### **Issues and Support**
+- **GitHub Issues**: https://github.com/celerispay/hazelcast-nodejs-client/issues
+- **Professional Support**: Available from CelerisPay
+
+## Expected Results
+
+After implementing this fixed version, you should see:
+
+1. **Stable Connections**: No more connection bombardment to failed nodes
+2. **Automatic Failover**: Seamless switching to healthy nodes when failures occur
+3. **Better Performance**: Reduced network traffic and improved response times
+4. **Cleaner Logs**: Fewer error messages and better failure information
+5. **Production Stability**: Reliable operation even during cluster topology changes
 
 ---
 
-**Note**: This version (3.12.5) includes critical connection failover fixes and is published by CelerisPay. Consider upgrading to Hazelcast 4.x or 5.x for long-term support.
+**Ready for Production**: This version has been thoroughly tested and is ready for production deployment with professional support from CelerisPay.
+