navis.js 1.0.0 → 3.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,20 @@ exports.handler = async (event) => {
 ```bash
 # Start example server
 navis start
+
+# Generate a new microservice (v2)
+navis generate service my-service
+
+# Run verification tests (v3)
+navis test
+
+# Show metrics endpoint info (v3)
+navis metrics
 ```
 
 ## Features
 
-### v1 (Current)
+### v1
 
 - ✅ HTTP routing (GET, POST, PUT, DELETE)
 - ✅ Middleware support (`app.use()`)
@@ -84,14 +95,22 @@ navis start
 - ✅ ServiceClient for service-to-service calls
 - ✅ Timeout support
 
-### v2 (Planned)
+### v2
+
+- ✅ **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
 
-- 🔄 Retry logic
-- 🔄 Circuit breaker
-- 🔄 Config-based services
-- 🔄 Service discovery
-- 🔄 Async messaging (SQS / Kafka / NATS)
-- 🔄 CLI generators (`navis generate service`)
+### v3 (Current)
+
+- ✅ **Async messaging** - SQS, Kafka, and NATS adapters
+- ✅ **Structured logging** - Multi-level logging with context
+- ✅ **Metrics collection** - Counters, gauges, histograms with Prometheus export
+- ✅ **Distributed tracing** - Trace and span management
+- ✅ **Enhanced CLI** - Test and metrics commands
 
 ## API Reference
 
@@ -107,19 +126,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,
 });
 
-// GET request
-const response = await client.get('/users');
+// 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,
+  },
+});
+
+// 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 },
+  },
+});
+
+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',
+]);
 
-// POST request
-const result = await client.post('/users', { name: 'John' });
+const url = discovery.getNext('api'); // Round-robin
+const client = new ServiceClient(url);
 ```
 
 ### Response Helpers
@@ -134,6 +200,54 @@ response.success(res, { data: 'value' }, 200);
 response.error(res, 'Error message', 500);
 ```
 
+### Observability (v3)
+
+```javascript
+const { Logger, Metrics, Tracer } = require('navis.js');
+
+// Structured logging
+const logger = new Logger({ level: 'INFO', context: { service: 'api' } });
+logger.info('User logged in', { userId: 123 });
+
+// Metrics collection
+const metrics = new Metrics();
+metrics.increment('api_calls', 1, { endpoint: '/users' });
+metrics.recordRequest('GET', '/users', 150, 200);
+
+// Expose Prometheus metrics
+app.get('/metrics', (req, res) => {
+  res.setHeader('Content-Type', 'text/plain');
+  res.end(metrics.toPrometheus());
+});
+
+// Distributed tracing
+const tracer = new Tracer({ serviceName: 'api' });
+const traceId = tracer.startTrace('user-operation');
+const spanId = tracer.startSpan('db-query', { traceId });
+tracer.finishSpan(spanId, { status: 'ok' });
+```
+
+### Async Messaging (v3)
+
+```javascript
+const { SQSMessaging, KafkaMessaging, NATSMessaging } = require('navis.js');
+
+// AWS SQS (requires @aws-sdk/client-sqs)
+const sqs = new SQSMessaging({ region: 'us-east-1' });
+await sqs.connect();
+await sqs.publish(queueUrl, { userId: 123, action: 'user.created' });
+
+// Kafka (requires kafkajs)
+const kafka = new KafkaMessaging({ brokers: ['localhost:9092'] });
+await kafka.connect();
+await kafka.publish('user-events', { userId: 123, event: 'created' });
+
+// NATS (requires nats)
+const nats = new NATSMessaging({ servers: ['nats://localhost:4222'] });
+await nats.connect();
+await nats.publish('user.created', { userId: 123 });
+```
+
 ## Examples
 
 See the `examples/` directory:
@@ -141,18 +255,33 @@ 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.)
+- `v3-features-demo.js` - v3 features demonstration (messaging, observability, etc.)
 
 ## Roadmap
 
-### v1 (Current)
+### v1 ✅
 Core functionality: routing, middleware, Lambda support, ServiceClient
 
-### v2 (Next)
-Resilience patterns: retry, circuit breaker, service discovery
+### v2 ✅
+Resilience patterns: retry, circuit breaker, service discovery, CLI generators
+
+### v3 ✅ (Current)
+Advanced features: async messaging (SQS/Kafka/NATS), observability, enhanced CLI
 
-### v3 (Future)
-Advanced features: async messaging, observability, advanced CLI
+## Documentation
+
+- [V2 Features Guide](./V2_FEATURES.md) - Complete v2 features documentation
+- [V3 Features Guide](./V3_FEATURES.md) - Complete v3 features documentation
+- [Verification Guide v2](./VERIFY_V2.md) - How to verify v2 features
+- [Verification Guide v3](./VERIFY_V3.md) - How to verify v3 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,57 @@ 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 if (command === 'deploy') {
+  // v3: Deploy command (placeholder for future deployment features)
+  console.log('Deploy command - Coming soon');
+  console.log('This will support deployment to AWS Lambda, Docker, etc.');
+} else if (command === 'test') {
+  // v3: Test command
+  const { spawn } = require('child_process');
+  const testPath = path.join(__dirname, '..', 'verify-v2.js');
+  
+  if (fs.existsSync(testPath)) {
+    const test = spawn('node', [testPath], {
+      stdio: 'inherit',
+      cwd: path.join(__dirname, '..'),
+    });
+    
+    test.on('exit', (code) => {
+      process.exit(code);
+    });
+  } else {
+    console.log('No test file found');
+  }
+} else if (command === 'metrics') {
+  // v3: Show metrics endpoint
+  console.log('Metrics endpoint:');
+  console.log('  Add /metrics route to your app to expose Prometheus metrics');
+  console.log('');
+  console.log('Example:');
+  console.log('  app.get("/metrics", (req, res) => {');
+  console.log('    res.setHeader("Content-Type", "text/plain");');
+  console.log('    res.end(metrics.toPrometheus());');
+  console.log('  });');
 } else {
   console.log('Navis.js CLI');
   console.log('');
@@ -43,4 +92,9 @@ if (command === 'start') {
   console.log('');
   console.log('v2 commands:');
   console.log('  navis generate     Generate service boilerplate');
+  console.log('');
+  console.log('v3 commands:');
+  console.log('  navis test         Run verification tests');
+  console.log('  navis metrics      Show metrics endpoint info');
+  console.log('  navis deploy       Deploy service (coming soon)');
 }

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,
+};
+