Express Micro

A lightweight Express.js plugin for automatic service discovery and inter-service communication in microservice architectures.

Features

• Automatic Service Discovery: Services automatically discover and register with each other
• Secure Communication: Built-in authentication and optional HMAC signing for requests
• Health Monitoring: Continuous health checks and automatic service status updates
• Easy Integration: Simple proxy-based API for calling remote services
• IP Whitelisting: Optional IP-based access control for discovery endpoints
• Dual Module Support: Compatible with both CommonJS and ES6 modules

Installation

npm install express-micro

Quick Start

Basic Setup

const express = require('express');
const expressMicro = require('express-micro');

const app = express();
app.use(express.json());

// Define your routes
app.get('/api/users/:id', (req, res) => {
  res.json({ id: req.params.id, name: 'John Doe' });
});

app.post('/api/users', (req, res) => {
  res.json({ id: 1, ...req.body });
});

// Initialize Express Micro
const { services } = expressMicro(app, {
  serviceName: 'user-service',
  port: 3000,
  peers: ['http://localhost:3001'] // URLs of other services
});

app.listen(3000, () => {
  console.log('User service running on port 3000');
});

Using ES6 Modules

import express from 'express';
import expressMicro from 'express-micro';

const app = express();
// ... setup routes ...

const { services } = expressMicro(app, {
  serviceName: 'user-service',
  port: 3000
});

// ... start server ...

Configuration Options

Option	Type	Default	Description
serviceName	string	npm_package_name or 'unnamed-service'	Name of the service
port	number	app.get('port')	Port the service runs on
host	string	Auto-detected IP or '127.0.0.1'	Host address
peers	string[]	[]	Initial list of peer service URLs
pingInterval	number	5000	Health check interval in milliseconds
ipWhitelist	string[]	undefined	Allowed IPs for discovery endpoints
enableHmac	boolean	false	Enable HMAC signing for requests

API Usage

Calling Remote Services

Once services are discovered, you can call them using the services proxy:

// Assuming there's an 'order-service' with a route: app.get('/orders/:userId', ...)
const orders = await services.orderService.getOrders({ userId: 123 });

// For POST requests
const newOrder = await services.orderService.createOrder({
  userId: 123,
  items: ['item1', 'item2']
});

The proxy automatically:

• Maps function names to route handlers
• Handles URL parameter substitution
• Manages HTTP methods (GET, POST, PUT, DELETE)
• Provides error handling

Security Features

Authentication

All discovery endpoints require a shared secret token:

curl -H "Authorization: Bearer YOUR_SECRET" \
     http://localhost:3000/_discovery/services

The secret is automatically generated and stored in the system's temp directory, or can be set via the EXPRESS_DISCOVERY_KEY environment variable.

IP Whitelisting

Restrict access to discovery endpoints:

const { services } = expressMicro(app, {
  ipWhitelist: ['192.168.1.100', '10.0.0.1']
});

HMAC Signing

Enable request signing for additional security:

const { services } = expressMicro(app, {
  enableHmac: true
});

Discovery Endpoints

GET /_discovery/services

Returns information about this service and connected peers.

Response:

{
  "thisService": {
    "name": "user-service",
    "url": "http://192.168.1.100:3000",
    "routes": [...]
  },
  "connectedPeers": {
    "order-service": {
      "url": "http://192.168.1.100:3001",
      "routes": [...],
      "status": "UP"
    }
  }
}

POST /_discovery/register

Used by services to register themselves. Requires authentication.

POST /_discovery/ping

Health check endpoint. Requires authentication.

Examples

Multi-Service Setup

User Service (Port 3000):

const express = require('express');
const expressMicro = require('express-micro');

const app = express();
app.use(express.json());

app.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id, name: 'User ' + req.params.id });
});

const { services } = expressMicro(app, {
  serviceName: 'user-service',
  port: 3000,
  peers: ['http://localhost:3001']
});

app.listen(3000);

Order Service (Port 3001):

const express = require('express');
const expressMicro = require('express-micro');

const app = express();
app.use(express.json());

app.get('/orders/:userId', (req, res) => {
  res.json({ userId: req.params.userId, orders: [] });
});

const { services } = expressMicro(app, {
  serviceName: 'order-service',
  port: 3001,
  peers: ['http://localhost:3000']
});

// Call user service
app.get('/user-orders/:userId', async (req, res) => {
  try {
    const user = await services.userService.getUser({ id: req.params.userId });
    const orders = await services.orderService.getOrders({ userId: req.params.userId });
    res.json({ user, orders });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3001);

Environment Variables

# Set discovery secret
export EXPRESS_DISCOVERY_KEY=your-secret-key

# Run services
node user-service.js &
node order-service.js &

Security Notes

• Shared Secret: The discovery secret is stored in the system's temp directory with restricted permissions (0600). Never commit this file to version control.
• Network Security: Discovery endpoints should only be accessible within your internal network. Use firewalls or VPNs to restrict access.
• IP Whitelisting: Enable IP whitelisting in production to prevent unauthorized service registration.
• HMAC Signing: Enable HMAC for production deployments to ensure request integrity.
• HTTPS: Consider using HTTPS for all service communications in production.
• Secret Rotation: Regularly rotate the discovery secret and restart services.

Troubleshooting

Common Issues

1. Port not defined: Ensure app.listen(port) is called before initializing Express Micro, or provide the port in options.

2. Services not discovering each other: Check that peer URLs are correct and services are running. Verify network connectivity.

3. Authentication failures: Ensure the same secret is used across all services. Check the temp directory for the secret file.

4. Route not found errors: Verify that the remote service has the expected route and that the function name matches the route handler name.

Debug Information

Check the discovery endpoint to see registered services:

curl -H "Authorization: Bearer YOUR_SECRET" \
     http://localhost:PORT/_discovery/services

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please open an issue on GitHub.