StreamSync

Real-time backend with WebSocket support for live feeds and instant messaging.

StreamSync bridges the gap between traditional REST APIs and modern real-time communication. It provides both WebSocket connections for instant messaging and REST endpoints for traditional HTTP-based operations.

Quick Start

# Install dependencies
pip install -r requirements.txt

# Run the server
python -m streamsync

# Or run directly
python src/app.py

Server starts at http://localhost:5000

Architecture

StreamSync provides two communication paradigms:

1. Real-Time (WebSocket)

WebSocket connections via Socket.IO for instant, bidirectional communication:

// Client-side example
const socket = io('http://localhost:5000');

// Send a message
socket.emit('message', {
    type: 'broadcast',
    data: { content: 'Hello everyone!' }
});

// Listen for messages
socket.on('message', (msg) => {
    console.log('Received:', JSON.parse(msg));
});

// Join a room
socket.emit('message', {
    type: 'room_join',
    data: { room: 'general' }
});

2. REST API

HTTP endpoints for traditional request-response operations:

Endpoint	Method	Description
/api/feed	GET	Retrieve feed items
/api/feed	POST	Create new feed item
/api/feed/<id>	GET	Get specific item
/api/feed/<id>	DELETE	Delete item
/api/rooms	GET	List active rooms
/api/connections	GET	List connected clients
/api/stats	GET	Server statistics
/api/health	GET	Health check

Key Differences: WebSocket vs REST

Aspect	WebSocket	REST API
Connection	Persistent	Request-Response
Direction	Bidirectional	Client→Server
Latency	Near-instant	HTTP overhead
Use Case	Chat, live updates	CRUD operations
State	Maintains session	Stateless
Browser Support	All modern browsers	Universal

When to Use Which

Use WebSocket when:

• Building chat applications
• Implementing live notifications
• Real-time collaboration features
• Streaming data dashboards

Use REST API when:

• Fetching historical feed data
• Administrative operations
• Integration with external services
• Batch processing

Features

• Connection Management: Track active clients, handle disconnects gracefully
• Room Support: Create topic-based rooms for group communication
• Feed Persistence: SQLite-backed message storage
• Event Broadcasting: Send messages to all connected clients
• Real-time Statistics: Monitor connections and activity

API Examples

Create Feed Item (REST)

curl -X POST http://localhost:5000/api/feed \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "content": "Hello from REST!",
    "sender_id": "user123",
    "sender_name": "John"
  }'

Get Feed (REST)

curl http://localhost:5000/api/feed?limit=10

Export Feed (REST)

curl http://localhost:5000/api/feed/export?format=csv -o feed.csv

Configuration

Environment variables:

Variable	Default	Description
SECRET_KEY	dev-secret-key	Flask secret key
DATABASE_PATH	streamsync.db	SQLite database path
DEBUG	False	Enable debug mode
LOG_LEVEL	INFO	Logging level

Project Structure

streamsync/
├── src/
│   ├── __init__.py       # Package init
│   ├── __main__.py       # Entry point
│   ├── app.py            # Flask app factory
│   ├── connections.py    # Connection manager
│   ├── feed.py           # Feed/storage manager
│   ├── routes.py         # REST API routes
│   └── websocket.py      # WebSocket server
├── templates/
│   └── index.html        # Demo UI
├── requirements.txt
├── setup.py
└── README.md

Requirements

• Python 3.8+
• Flask
• Flask-SocketIO
• python-socketio
• eventlet

License

MIT