navis.js 1.0.0 → 2.0.0

package/README.md

@@ -2,6 +2,8 @@
 
 A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js.
 
+**Author:** Syed Iman Ali
+
 ## Philosophy
 
 Navis.js is "Express for serverless microservices — but simpler."
@@ -71,11 +73,14 @@ exports.handler = async (event) => {
 ```bash
 # Start example server
 navis start
+
+# Generate a new microservice (v2)
+navis generate service my-service
 ```
 
 ## Features
 
-### v1 (Current)
+### v1
 
 - ✅ HTTP routing (GET, POST, PUT, DELETE)
 - ✅ Middleware support (`app.use()`)
@@ -84,14 +89,20 @@ navis start
 - ✅ ServiceClient for service-to-service calls
 - ✅ Timeout support
 
-### v2 (Planned)
+### v2 (Current)
+
+- ✅ **Retry logic** - Automatic retry with exponential backoff
+- ✅ **Circuit breaker** - Prevents cascading failures
+- ✅ **Config-based services** - Centralized service configuration
+- ✅ **Service discovery** - Health checks and load balancing
+- ✅ **Additional HTTP methods** - PUT, DELETE, PATCH support
+- ✅ **CLI generators** - `navis generate service` command
+
+### v3 (Planned)
 
-- 🔄 Retry logic
-- 🔄 Circuit breaker
-- 🔄 Config-based services
-- 🔄 Service discovery
 - 🔄 Async messaging (SQS / Kafka / NATS)
-- 🔄 CLI generators (`navis generate service`)
+- 🔄 Advanced observability
+- 🔄 Enhanced CLI features
 
 ## API Reference
 
@@ -107,19 +118,66 @@ navis start
 - `app.listen(port, callback)` - Start HTTP server (Node.js)
 - `app.handleLambda(event)` - Handle AWS Lambda event
 
-### ServiceClient
+### ServiceClient (v2 Enhanced)
 
+```javascript
 const { ServiceClient } = require('navis.js');
 
+// Basic usage
 const client = new ServiceClient('http://api.example.com', {
-  timeout: 5000, // milliseconds
+  timeout: 5000,
+});
+
+// With retry and circuit breaker (v2)
+const resilientClient = new ServiceClient('http://api.example.com', {
+  timeout: 5000,
+  maxRetries: 3,
+  retryBaseDelay: 1000,
+  circuitBreaker: {
+    failureThreshold: 5,
+    resetTimeout: 60000,
+  },
 });
 
-// GET request
-const response = await client.get('/users');
+// All HTTP methods (v2)
+await client.get('/users');
+await client.post('/users', { name: 'John' });
+await client.put('/users/1', { name: 'Jane' });      // v2
+await client.patch('/users/1', { name: 'Bob' });      // v2
+await client.delete('/users/1');                      // v2
+```
+
+### Service Configuration (v2)
+
+```javascript
+const { ServiceConfig, ServiceClient } = require('navis.js');
+
+const config = new ServiceConfig({
+  defaultOptions: {
+    timeout: 5000,
+    retry: { maxRetries: 3 },
+    circuitBreaker: { failureThreshold: 5 },
+  },
+});
 
-// POST request
-const result = await client.post('/users', { name: 'John' });
+config.register('userService', 'http://localhost:3001');
+const userConfig = config.get('userService');
+const client = new ServiceClient(userConfig.baseUrl, userConfig);
+```
+
+### Service Discovery (v2)
+
+```javascript
+const { ServiceDiscovery, ServiceClient } = require('navis.js');
+
+const discovery = new ServiceDiscovery();
+discovery.register('api', [
+  'http://api1.example.com',
+  'http://api2.example.com',
+]);
+
+const url = discovery.getNext('api'); // Round-robin
+const client = new ServiceClient(url);
 ```
 
 ### Response Helpers
@@ -141,18 +199,30 @@ See the `examples/` directory:
 - `server.js` - Node.js HTTP server example
 - `lambda.js` - AWS Lambda handler example
 - `service-client-demo.js` - ServiceClient usage example
+- `v2-features-demo.js` - v2 features demonstration (retry, circuit breaker, etc.)
 
 ## Roadmap
 
-### v1 (Current)
+### v1 ✅
 Core functionality: routing, middleware, Lambda support, ServiceClient
 
-### v2 (Next)
-Resilience patterns: retry, circuit breaker, service discovery
+### v2 ✅ (Current)
+Resilience patterns: retry, circuit breaker, service discovery, CLI generators
 
 ### v3 (Future)
-Advanced features: async messaging, observability, advanced CLI
+Advanced features: async messaging (SQS/Kafka/NATS), observability, enhanced CLI
+
+## Documentation
+
+- [V2 Features Guide](./V2_FEATURES.md) - Complete v2 features documentation
+- [Verification Guide](./VERIFY_V2.md) - How to verify all features
 
 ## License
 
-MIT
+MIT
+
+## Author
+
+**Syed Iman Ali**
+
+Created with ❤️ for the serverless microservices community.

package/bin/generators/service.js

@@ -0,0 +1,167 @@
+/**
+ * Service Generator
+ * v2: Generate service boilerplate
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Generate service boilerplate
+ * @param {string} serviceName - Name of the service
+ * @param {string} targetDir - Target directory (default: current directory)
+ */
+function generateService(serviceName, targetDir = process.cwd()) {
+  const serviceDir = path.join(targetDir, serviceName);
+  
+  // Create service directory
+  if (!fs.existsSync(serviceDir)) {
+    fs.mkdirSync(serviceDir, { recursive: true });
+  }
+
+  // Generate service.js
+  const serviceTemplate = `const { NavisApp, response } = require('navis.js');
+
+const app = new NavisApp();
+
+// Middleware
+app.use((req, res, next) => {
+  console.log(\`\${req.method} \${req.url}\`);
+  next();
+});
+
+// Routes
+app.get('/', (req, res) => {
+  response.success(res, { 
+    service: '${serviceName}',
+    message: 'Welcome to ${serviceName} service',
+    version: '1.0.0'
+  });
+});
+
+app.get('/health', (req, res) => {
+  response.success(res, { status: 'ok', service: '${serviceName}' });
+});
+
+// Add your routes here
+// app.get('/api/users', (req, res) => { ... });
+// app.post('/api/users', (req, res) => { ... });
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(\`${serviceName} service running on http://localhost:\${PORT}\`);
+});
+
+module.exports = app;
+`;
+
+  fs.writeFileSync(path.join(serviceDir, 'service.js'), serviceTemplate);
+
+  // Generate lambda.js
+  const lambdaTemplate = `const { NavisApp } = require('navis.js');
+
+const app = new NavisApp();
+
+// Middleware
+app.use((req, res, next) => {
+  console.log(\`Lambda: \${req.method} \${req.path}\`);
+  next();
+});
+
+// Routes
+app.get('/', (req, res) => {
+  res.statusCode = 200;
+  res.body = { 
+    service: '${serviceName}',
+    message: 'Welcome to ${serviceName} service (Lambda)',
+    version: '1.0.0'
+  };
+});
+
+app.get('/health', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'ok', service: '${serviceName}' };
+});
+
+// Lambda handler
+exports.handler = async (event) => {
+  return await app.handleLambda(event);
+};
+`;
+
+  fs.writeFileSync(path.join(serviceDir, 'lambda.js'), lambdaTemplate);
+
+  // Generate package.json
+  const packageJson = {
+    name: serviceName,
+    version: '1.0.0',
+    description: `${serviceName} microservice`,
+    main: 'service.js',
+    scripts: {
+      start: 'node service.js',
+      'start:lambda': 'node lambda.js',
+    },
+    dependencies: {
+      'navis.js': '^1.0.0',
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(serviceDir, 'package.json'),
+    JSON.stringify(packageJson, null, 2)
+  );
+
+  // Generate README.md
+  const readmeTemplate = `# ${serviceName}
+
+Microservice generated with Navis.js
+
+## Installation
+
+\`\`\`bash
+npm install
+\`\`\`
+
+## Running
+
+### Local Development
+
+\`\`\`bash
+npm start
+# or
+node service.js
+\`\`\`
+
+### AWS Lambda
+
+Deploy \`lambda.js\` to AWS Lambda and configure API Gateway.
+
+## API Endpoints
+
+- \`GET /\` - Service information
+- \`GET /health\` - Health check
+
+## Development
+
+Add your routes in \`service.js\`:
+
+\`\`\`javascript
+app.get('/api/users', (req, res) => {
+  // Your route handler
+});
+\`\`\`
+`;
+
+  fs.writeFileSync(path.join(serviceDir, 'README.md'), readmeTemplate);
+
+  console.log(`✅ Service "${serviceName}" generated successfully!`);
+  console.log(`📁 Location: ${serviceDir}`);
+  console.log(`\nNext steps:`);
+  console.log(`  cd ${serviceName}`);
+  console.log(`  npm install`);
+  console.log(`  npm start`);
+}
+
+module.exports = { generateService };
+

package/bin/navis.js

@@ -33,8 +33,26 @@ if (command === 'start') {
     process.exit(code);
   });
 } else if (command === 'generate') {
-  // TODO v2: Implement navis generate service
-  console.log('Generator commands coming in v2');
+  const subcommand = process.argv[3];
+  
+  if (subcommand === 'service') {
+    const serviceName = process.argv[4];
+    
+    if (!serviceName) {
+      console.error('Error: Service name is required');
+      console.log('Usage: navis generate service <service-name>');
+      process.exit(1);
+    }
+    
+    const { generateService } = require('./generators/service');
+    generateService(serviceName);
+  } else {
+    console.log('Generator commands:');
+    console.log('  navis generate service <name>    Generate a new microservice');
+    console.log('');
+    console.log('Example:');
+    console.log('  navis generate service user-service');
+  }
 } else {
   console.log('Navis.js CLI');
   console.log('');

package/examples/v2-features-demo.js

@@ -0,0 +1,190 @@
+/**
+ * Navis.js v2 Features Demo
+ * Demonstrates retry logic, circuit breaker, service config, and service discovery
+ */
+
+const {
+  ServiceClient,
+  ServiceConfig,
+  ServiceDiscovery,
+  retry,
+} = require('../src/index');
+
+// Example 1: ServiceClient with retry and circuit breaker
+async function demoServiceClient() {
+  console.log('\n=== ServiceClient with Retry & Circuit Breaker ===\n');
+
+  const client = new ServiceClient('http://localhost:3000', {
+    timeout: 3000,
+    maxRetries: 3,
+    retryBaseDelay: 1000,
+    circuitBreaker: {
+      failureThreshold: 3,
+      resetTimeout: 10000,
+    },
+  });
+
+  try {
+    const response = await client.get('/health');
+    console.log('✅ Request successful:', response.data);
+  } catch (error) {
+    if (error.circuitBreakerOpen) {
+      console.log('❌ Circuit breaker is OPEN:', error.message);
+      console.log('Circuit state:', error.circuitState);
+    } else {
+      console.log('❌ Request failed:', error.message);
+    }
+  }
+
+  // Check circuit breaker state
+  const state = client.getCircuitBreakerState();
+  if (state) {
+    console.log('Circuit breaker state:', state);
+  }
+}
+
+// Example 2: Service Configuration
+async function demoServiceConfig() {
+  console.log('\n=== Service Configuration ===\n');
+
+  const config = new ServiceConfig({
+    defaultOptions: {
+      timeout: 5000,
+      retry: {
+        maxRetries: 3,
+        baseDelay: 1000,
+      },
+      circuitBreaker: {
+        failureThreshold: 5,
+        resetTimeout: 60000,
+      },
+    },
+  });
+
+  // Register services
+  config.register('userService', 'http://localhost:3001', {
+    timeout: 3000,
+  });
+
+  config.register('orderService', 'http://localhost:3002', {
+    retry: {
+      maxRetries: 5,
+    },
+  });
+
+  console.log('Registered services:', Object.keys(config.getAll()));
+
+  // Get service config
+  const userServiceConfig = config.get('userService');
+  console.log('User service config:', userServiceConfig);
+}
+
+// Example 3: Service Discovery
+async function demoServiceDiscovery() {
+  console.log('\n=== Service Discovery ===\n');
+
+  const discovery = new ServiceDiscovery({
+    healthCheckInterval: 10000,
+    healthCheckPath: '/health',
+  });
+
+  // Register service with multiple endpoints
+  discovery.register('api', [
+    'http://localhost:3000',
+    'http://localhost:3001',
+    'http://localhost:3002',
+  ]);
+
+  // Get next available service (round-robin)
+  const url1 = discovery.getNext('api');
+  console.log('Next service URL:', url1);
+
+  const url2 = discovery.getNext('api');
+  console.log('Next service URL:', url2);
+
+  // Get all healthy services
+  const healthy = discovery.getHealthy('api');
+  console.log('Healthy services:', healthy);
+}
+
+// Example 4: Using retry utility directly
+async function demoRetryUtility() {
+  console.log('\n=== Retry Utility ===\n');
+
+  let attemptCount = 0;
+
+  const flakyFunction = async () => {
+    attemptCount++;
+    console.log(`Attempt ${attemptCount}...`);
+    
+    if (attemptCount < 3) {
+      throw new Error('Temporary failure');
+    }
+    
+    return { success: true, attempt: attemptCount };
+  };
+
+  try {
+    const result = await retry(flakyFunction, {
+      maxRetries: 3,
+      baseDelay: 500,
+    });
+    console.log('✅ Success after retries:', result);
+  } catch (error) {
+    console.log('❌ Failed after all retries:', error.message);
+  }
+}
+
+// Example 5: ServiceClient with additional HTTP methods
+async function demoHttpMethods() {
+  console.log('\n=== Additional HTTP Methods ===\n');
+
+  const client = new ServiceClient('http://localhost:3000', {
+    retry: false, // Disable retry for demo
+  });
+
+  try {
+    // PUT request
+    const putResponse = await client.put('/api/users/1', { name: 'John' });
+    console.log('PUT response:', putResponse.data);
+
+    // DELETE request
+    const deleteResponse = await client.delete('/api/users/1');
+    console.log('DELETE response:', deleteResponse.data);
+
+    // PATCH request
+    const patchResponse = await client.patch('/api/users/1', { name: 'Jane' });
+    console.log('PATCH response:', patchResponse.data);
+  } catch (error) {
+    console.log('Request failed (expected if server not running):', error.message);
+  }
+}
+
+// Run all demos
+async function runDemos() {
+  console.log('🚀 Navis.js v2 Features Demo\n');
+  console.log('='.repeat(50));
+
+  await demoServiceConfig();
+  await demoServiceDiscovery();
+  await demoRetryUtility();
+  await demoHttpMethods();
+  
+  // ServiceClient demo requires a running server
+  console.log('\n💡 Note: ServiceClient demo requires a running server on port 3000');
+  console.log('   Run: node examples/server.js');
+}
+
+// Run if called directly
+if (require.main === module) {
+  runDemos().catch(console.error);
+}
+
+module.exports = {
+  demoServiceClient,
+  demoServiceConfig,
+  demoServiceDiscovery,
+  demoRetryUtility,
+  demoHttpMethods,
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navis.js",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -1,12 +1,30 @@
-const NavisApp = require('./core/app');
-const ServiceClient = require('./utils/service-client');
-const { success, error } = require('./utils/response');
-
-module.exports = {
-  NavisApp,
-  ServiceClient,
-  response: {
-    success,
-    error,
-  },
-};
+const NavisApp = require('./core/app');
+const ServiceClient = require('./utils/service-client');
+const ServiceConfig = require('./utils/service-config');
+const ServiceDiscovery = require('./utils/service-discovery');
+const CircuitBreaker = require('./utils/circuit-breaker');
+const { success, error } = require('./utils/response');
+const { retry, shouldRetryHttpStatus } = require('./utils/retry');
+
+module.exports = {
+  // Core
+  NavisApp,
+  
+  // Service Client (v2 enhanced)
+  ServiceClient,
+  
+  // v2 Features
+  ServiceConfig,
+  ServiceDiscovery,
+  CircuitBreaker,
+  
+  // Utilities
+  response: {
+    success,
+    error,
+  },
+  retry: {
+    retry,
+    shouldRetryHttpStatus,
+  },
+};

package/src/utils/circuit-breaker.js

@@ -0,0 +1,107 @@
+/**
+ * Circuit Breaker - Prevents cascading failures in microservices
+ * v2: Circuit breaker pattern implementation
+ */
+
+class CircuitBreaker {
+  constructor(options = {}) {
+    this.failureThreshold = options.failureThreshold || 5; // Open circuit after 5 failures
+    this.resetTimeout = options.resetTimeout || 60000; // 60 seconds
+    this.monitoringWindow = options.monitoringWindow || 10000; // 10 seconds
+    
+    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.lastFailureTime = null;
+    this.nextAttemptTime = null;
+  }
+
+  /**
+   * Record a successful request
+   */
+  recordSuccess() {
+    if (this.state === 'HALF_OPEN') {
+      this.successCount++;
+      if (this.successCount >= 2) {
+        // Reset to CLOSED after 2 successes in HALF_OPEN
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.successCount = 0;
+      }
+    } else if (this.state === 'CLOSED') {
+      this.failureCount = 0; // Reset failure count on success
+    }
+  }
+
+  /**
+   * Record a failed request
+   */
+  recordFailure() {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+
+    if (this.state === 'CLOSED' && this.failureCount >= this.failureThreshold) {
+      // Open the circuit
+      this.state = 'OPEN';
+      this.nextAttemptTime = Date.now() + this.resetTimeout;
+    } else if (this.state === 'HALF_OPEN') {
+      // Failed in half-open, go back to open
+      this.state = 'OPEN';
+      this.nextAttemptTime = Date.now() + this.resetTimeout;
+      this.successCount = 0;
+    }
+  }
+
+  /**
+   * Check if request should be allowed
+   * @returns {boolean} - true if request should proceed
+   */
+  canAttempt() {
+    if (this.state === 'CLOSED') {
+      return true;
+    }
+
+    if (this.state === 'OPEN') {
+      if (Date.now() >= this.nextAttemptTime) {
+        // Transition to HALF_OPEN
+        this.state = 'HALF_OPEN';
+        this.successCount = 0;
+        return true;
+      }
+      return false; // Circuit is open, reject request
+    }
+
+    if (this.state === 'HALF_OPEN') {
+      return true; // Allow limited requests in half-open state
+    }
+
+    return false;
+  }
+
+  /**
+   * Get current circuit state
+   */
+  getState() {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      successCount: this.successCount,
+      lastFailureTime: this.lastFailureTime,
+      nextAttemptTime: this.nextAttemptTime,
+    };
+  }
+
+  /**
+   * Reset circuit breaker
+   */
+  reset() {
+    this.state = 'CLOSED';
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.lastFailureTime = null;
+    this.nextAttemptTime = null;
+  }
+}
+
+module.exports = CircuitBreaker;
+