ipc-framework 1.1.2
Python IPC server for high-performance communication with Node.js applications using TCP sockets
License: MIT
Requires Python: >=3.7
Keywords: ipc, inter-process-communication, tcp, sockets, nodejs, python, server, microservices, real-time, messaging

# IPC Framework - Inter-Process Communication

[![NPM companion](https://img.shields.io/badge/Node.js%20Package-v1.1.3-green.svg)](https://www.npmjs.com/package/@ifesol/ipc-framework-nodejs)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Efficient Inter-Process Communication Framework** for **Python ↔ Node.js** backend integration. This is the **Python server package** that enables seamless **bidirectional communication** with Node.js applications using TCP sockets.

## 🐍 **Python Server Package**

This package provides the **Python IPC server** for communication with Node.js clients.

**✅ Production Ready Features:**
- ✅ TCP socket server (high-performance, low-latency)
- ✅ Hierarchical application and channel management
- ✅ Request/response and publish/subscribe patterns
- ✅ Connection pooling and auto-reconnection support
- ✅ Thread-safe operation with robust error handling

## 🚀 **Quick Start**

### **Installation**

```bash
# Install Python IPC server
pip install ipc-framework

# Install Node.js client (separate package)
npm install @ifesol/ipc-framework-nodejs
```

### **Python Server Usage**

```python
from ipc_framework import FrameworkServer, MessageType
import time

# Create server
server = FrameworkServer(host="localhost", port=8888)

# Create application and channel
app = server.create_application("my_app", "My Application")
api_channel = app.create_channel("api")

# Handle requests from Node.js clients
def handle_request(message):
    action = message.payload.get('action')
    
    if action == 'get_data':
        response = message.create_response({
            'success': True,
            'data': {'timestamp': time.time(), 'message': 'Hello from Python!'},
            'server': 'Python IPC Framework'
        })
        
        connection = server.connection_manager.get_connection(
            message.payload.get('connection_id')
        )
        server.send_to_connection(connection, response)

api_channel.set_handler(MessageType.REQUEST, handle_request)

print("🐍 Python IPC Server starting on localhost:8888")
server.start()
```

### **Node.js Client Usage**

```javascript
const { IPCClient } = require('@ifesol/ipc-framework-nodejs');

async function main() {
    const client = new IPCClient('my_app', {
        host: 'localhost',
        port: 8888
    });

    try {
        await client.connect();
        console.log('✅ Connected to Python server!');

        const response = await client.sendRequest('api', {
            action: 'get_data'
        });

        console.log('📨 Response from Python:', response.payload);
    } catch (error) {
        console.error('❌ Error:', error.message);
    } finally {
        client.disconnect();
    }
}

main();
```

## 🎯 **Architecture Features**

### **✅ Production-Ready Server:**
- **High-performance TCP sockets** for low-latency communication
- **Hierarchical structure** with applications and channels
- **Message routing** and automatic connection management
- **Thread-safe operations** with robust error handling

### **✅ Communication Patterns:**
- **Request/Response** - Direct client-server communication
- **Publish/Subscribe** - Real-time notifications and broadcasts
- **Channel-based routing** - Organized message handling
- **Connection pooling** - Efficient resource management

## 🏗️ **Integration with Node.js**

This Python server works seamlessly with Node.js applications. Here's how to connect an Express.js app:

**Node.js Express.js Integration:**
```javascript
const express = require('express');
const { IPCClient } = require('@ifesol/ipc-framework-nodejs');

const app = express();
const pythonClient = new IPCClient('web_api');

app.use(express.json());

// Initialize connection to Python IPC server
pythonClient.connect().then(() => {
    console.log('🔗 Connected to Python IPC server');
});

// API endpoint proxying to Python backend
app.post('/api/process', async (req, res) => {
    try {
        const result = await pythonClient.sendRequest('processing', {
            action: 'process_user_data',
            data: req.body,
            connection_id: pythonClient.connectionId
        });
        
        res.json(result.payload);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

app.listen(3000, () => {
    console.log('🌐 Express server running on port 3000');
    console.log('📡 Proxying requests to Python IPC server');
});
```

## 📊 **Performance Characteristics**

| Feature | Performance | Details |
|---------|-------------|---------|
| **Connection Handling** | Sub-millisecond | Fast TCP connection establishment |
| **Message Processing** | <1ms latency | Direct socket communication |
| **Concurrent Connections** | 100+ clients | Thread-safe connection management |
| **Message Throughput** | High-volume | Efficient message routing |
| **Memory Usage** | Low footprint | Optimized Python implementation |
| **Error Recovery** | Automatic | Robust connection cleanup |

## 🎯 **Use Cases**

This Python IPC server enables powerful hybrid architectures:

### **Backend Services**
- **AI/ML model serving** - Host machine learning models and serve predictions to Node.js frontends
- **Data processing pipelines** - Heavy computational tasks handled by Python, coordinated with Node.js
- **Real-time analytics** - Python analytics engines feeding real-time dashboards
- **Scientific computing** - NumPy/SciPy computations accessible from Node.js applications

### **Microservice Architecture**
- **Polyglot microservices** - Python services integrated with Node.js API gateways
- **Event-driven architecture** - Python services publishing events to Node.js consumers
- **Service mesh integration** - Python backend services in cloud-native environments
- **Legacy system integration** - Bridge existing Python systems with modern Node.js frontends

### **Hybrid Applications**
- **E-commerce platforms** - Python inventory/pricing engines with Node.js storefronts
- **Financial services** - Python quantitative analysis with Node.js trading interfaces
- **IoT platforms** - Python device controllers with Node.js monitoring dashboards
- **Chat applications** - Python NLP processing with Node.js real-time messaging

## 🆚 **Why Choose IPC over HTTP?**

| HTTP API Approach | IPC Framework |
|-------------------|---------------|
| ❌ High latency overhead | ✅ Direct TCP communication |
| ❌ Request/response only | ✅ Request/response + pub/sub |
| ❌ Manual connection management | ✅ Automatic reconnection |
| ❌ Complex error handling | ✅ Built-in fault tolerance |
| ❌ No real-time capabilities | ✅ Live notifications |
| ❌ Stateless limitations | ✅ Persistent connections |

## 🔗 **Companion Packages**

This Python server works with the Node.js client package:

- **Node.js Client**: [@ifesol/ipc-framework-nodejs](https://www.npmjs.com/package/@ifesol/ipc-framework-nodejs) - Production-ready TCP client
- **Installation**: `npm install @ifesol/ipc-framework-nodejs`
- **Documentation**: [Node.js Package Docs](https://www.npmjs.com/package/@ifesol/ipc-framework-nodejs)

## 🚀 **Getting Started**

1. **Install the Python server:**
   ```bash
   pip install ipc-framework
   ```

2. **Install the Node.js client:**
   ```bash
   npm install @ifesol/ipc-framework-nodejs
   ```

3. **Run the examples above** to see the integration in action!

## 📚 **Documentation**

- [Python API Reference](https://github.com/ifesol/ipc-framework#python-api)
- [Node.js Client Usage](https://www.npmjs.com/package/@ifesol/ipc-framework-nodejs)
- [Integration Examples](https://github.com/ifesol/ipc-framework/tree/main/examples)

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions welcome! Help us improve the Python ↔ Node.js IPC communication experience.