WebSocket, standardized in 2011, provides a full-duplex communication channel over a single TCP connection, enabling real-time data exchange with reduced overhead. It uses ws:// or wss:// URIs and typically operates on ports 80 or 443, allowing it to bypass many firewalls.

The WebSocket handshake is initiated via an HTTP/1.1 request with Upgrade and Connection: Upgrade headers. The server responds with HTTP/1.1 101 Switching Protocols and an Upgrade: websocket header. The Sec-WebSocket-Key header, combined with a specific GUID (258EAFA5-E914-47DA-95CA-C5AB0DC85B11), is hashed and Base64-encoded to form the Sec-WebSocket-Accept response header, ensuring the handshake is intentional.

Key advantages of WebSocket include:

• Low Overhead: Minimal header data exchanged after the initial connection.
• Real-time Communication: Server can push data instantly without client request.
• Stateful Connections: Maintains connection state, reducing redundant information transmission.
• Binary Data Support: Efficient handling of binary content.
• Extensibility: Protocol supports custom extensions.
• Cross-Origin Communication: No Same-Origin Policy restrictions.

Socket.IO

Socket.IO is a JavaScript library, now a framework supporting multiple languages, for real-time web applications. It primarily uses the WebSocket protocol but can gracefully fall back to other methods like Flash Sockets or AJAX polling if WebSocket is unavailable. Beyond basic WebSocket functionality, Socket.IO offers features such as broadcasting messages to multiple clients, managing client-specific data, and asynchronous I/O operations.

While often used as a WebSocket wrapper, Socket.IO implements its own protocol and requires both client and server to use the framework. This means a standard WebSocket client cannot connect to a Socket.IO server, and vice versa.

Advantages of Socket.IO:

• Abstracts communication protocols, requiring only a conceptual understanding of sockets.
• Provides Python libraries for building real-time backends.

Disadvantage:

• Proprietary protocol requires framework compatibility on both client and server sides.

Python Server-Side Development

Installation:

pip install python-socketio

Server Creation:

Method 1: WSGI Integration (e.g., uWSGI, Gunicorn)

import socketio

# Initialize Socket.IO server
sio = socketio.Server()

# Wrap with WSGI application
app = socketio.WSGIApp(sio) # For Flask, Django, etc.

Method 2: Embedding within Flask/Django

from wsgi import app # Assuming 'app' is your Flask/Django application instance
import socketio

sio = socketio.Server()
app = socketio.WSGIApp(sio, app)

Method 3: Asynchronous with Eventlet (Recommended)

import eventlet
eventlet.monkey_patch()

import socketio
import eventlet.wsgi

sio = socketio.Server(async_mode='eventlet')
app = socketio.Middleware(sio)
eventlet.wsgi.server(eventlet.listen(('', 8000)), app)

Using an asynchronous approach like Eventlet is recommended for better performance with long-lived connections compared to multi-process or multi-thread WSGI deployments.

Event Handling:

Socket.IO services handle events rather than HTTP requests and responses. Event handlers are defined using the @sio.on() decorator.

@sio.on('connect')
def handle_connect(sid, environ):
    """
    Callback executed when a client connects.
    :param sid: Unique identifier for the client connection.
    :param environ: Dictionary containing handshake data.
    """
    print(f"Client connected: {sid}")

@sio.on('disconnect')
def handle_disconnect(sid):
    """
    Callback executed when a client disconnects.
    :param sid: Identifier of the disconnected client.
    """
    print(f"Client disconnected: {sid}")

@sio.on('custom_event')
def handle_custom_event(sid, data):
    """
    Handles a custom event named 'custom_event'.
    :param sid: Identifier of the client sending the event.
    :param data: Data payload from the client.
    """
    print(f"Received custom event from {sid}: {data}")

Note that connect and disconnect are special events with different argument signatures than custom events.

Emitting Events:

To send messages from the server to clients:

Broadcast to all clients:

sio.emit('event_name', {'message': 'Hello all!'})

Send to a specific client:

sio.emit('event_name', {'message': 'Hello specific user!'}, room=user_sid)

Using Rooms for Group Messaging:

Socket.IO supports grouping clients into 'rooms' for targeted communication.

Add client to a room:

sio.enter_room(sid, 'room_name')

# Example within a handler:
@sio.on('join_chat')
def join_chat(sid):
    sio.enter_room(sid, 'chat_room')

Remove client from a room:

sio.leave_room(sid, 'room_name')

# Example within a handler:
@sio.on('leave_chat')
def leave_chat(sid):
    sio.leave_room(sid, 'chat_room')

Send message to a room:

@sio.on('send_chat_message')
def send_chat_message(sid, data):
    sio.emit('new_message', data, room='chat_room')

Send message to a room, skipping a specific client:

@sio.on('send_chat_message')
def send_chat_message(sid, data):
    sio.emit('new_message', data, room='chat_room', skip_sid=sid)

Using send() for the message event:

The send() method is a shorthand for emitting the default message event.

sio.send({'data': 'Simple message'}) # Broadcasts 'message' event
sio.send({'data': 'Specific message'}, room=user_sid) # Sends 'message' event to user_sid

Example: Server Receiving Client Messages

server.py:

import socketio

sio = socketio.Server(async_mode='eventlet')
app = socketio.Middleware(sio)

main.py:

import eventlet
eventlet.monkey_patch()
import eventlet.wsgi
import sys

if len(sys.argv) < 2:
    print('Usage: python main.py [port]')
    exit(1)

port = int(sys.argv[1])

from server import app
import notify # Assuming notify.py contains event handlers

SERVER_ADDRESS = ('', port)
sock = eventlet.listen(SERVER_ADDRESS)
eventlet.wsgi.server(sock, app)

chat.py (Event Handlers):

from server import sio
import time

@sio.on('connect')
def on_connect(sid, environ):
    print(f"Client connected: {sid}")
    # Send an initial message back to the connecting client
    message_payload = {
        'text': 'Welcome!',
        'timestamp': round(time.time() * 1000)
    }
    sio.emit('message', message_payload, room=sid)

@sio.on('message')
def on_message(sid, data):
    print(f"Received message from {sid}: {data}")
    # Echo the received message back to the sender
    response_payload = {
        'text': f"Server acknowledges: {data}",
        'timestamp': round(time.time() * 1000)
    }
    sio.send(response_payload, room=sid)

Example: Server-Initiated Message Push

To push messages to clients based on external events (e.g., user follows another user), a message queue like RabbitMQ or Redis can be integrated.

Using Redis:

mgr = socketio.RedisManager('redis://')
sio = socketio.Server(client_manager=mgr)

Using RabbitMQ:

# Install prerequisite: pip install kombu
mgr = socketio.KombuManager('amqp://guest:guest@localhost:5672//') # Replace with your AMQP URL
sio = socketio.Server(client_manager=mgr)

Implementation Details:

To enable targeted pushes (e.g., to a specific user up on a 'follow' event), clients should authenticate using JWT. The server validates the JWT upon connection and adds the authenticated user_id to a room named after their ID. This allows direct message emission to that user.

main.py (updated for message queue):

import eventlet
eventlet.monkey_patch()
import eventlet.wsgi
import sys
import os

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, os.path.join(BASE_DIR, 'common'))

if len(sys.argv) < 2:
    print('Usage: python main.py [port]')
    exit(1)

port = int(sys.argv[1])

from server import app
import notify

SERVER_ADDRESS = ('', port)
sock = eventlet.listen(SERVER_ADDRESS)
eventlet.wsgi.server(sock, app)

server.py (with KombuManager):

import socketio

RABBITMQ_URL = 'amqp://guest:guest@localhost:5672/' # Example AMQP URL
JWT_SECRET_KEY = 'your_super_secret_key'

mgr = socketio.KombuManager(RABBITMQ_URL)
sio = socketio.Server(async_mode='eventlet', client_manager=mgr)
app = socketio.Middleware(sio)

notify.py (JWT Validation and Room Entry):

from server import sio, JWT_SECRET_KEY
from werkzeug.wrappers import Request
# Assume 'utils.jwt_util' provides a 'verify_jwt' function
# from utils.jwt_util import verify_jwt 

def verify_jwt(token, secret):
    # Placeholder for actual JWT verification logic
    # Returns payload dict or None
    import jwt
    try:
        return jwt.decode(token, secret, algorithms=['HS256'])
    except jwt.ExpiredSignatureError:
        print("Token expired")
        return None
    except jwt.InvalidTokenError:
        print("Invalid token")
        return None

@sio.on('connect')
def on_connect(sid, environ):
    request = Request(environ)
    auth_token = request.args.get('token')
    user_id = None
    if auth_token:
        payload = verify_jwt(auth_token, JWT_SECRET_KEY)
        if payload:
            user_id = payload.get('user_id')
            print(f"Client {sid} authenticated as user: {user_id}")
            sio.enter_room(sid, str(user_id))
    if not user_id:
        print(f"Client {sid} failed to authenticate or no token provided.")

@sio.on('disconnect')
def on_disconnect(sid):
    print(f"Client disconnected: {sid}")
    # Optionally remove from rooms if necessary, though usually managed by client context
    try:
        # Attempt to find user_id associated with sid if needed, or just clear known rooms
        # For simplicity, let's assume we know the user_id if they were authenticated
        # In a real scenario, you might maintain a mapping of sid to user_id
        pass # Simplified: no explicit leave_room needed if re-auth handles it
    except Exception as e:
        print(f"Error during disconnect cleanup for {sid}: {e}")

In your application's main factory (e.g., toutiao-backend/toutiao/__init__.py):

import socketio

def create_app(config, enable_config_file=False):
    # ... other app setup ...

    # Initialize Socket.IO with the message manager
    rabbitmq_url = config.get('RABBITMQ_URL', 'amqp://guest:guest@localhost:5672/')
    app.sio_manager = socketio.KombuManager(rabbitmq_url, write_only=True)
    
    # You might need to pass this manager to the Server instance if not using Middleware directly
    # For Middleware approach, server initialization in server.py uses the manager
    # If using Server directly, you'd do: sio = socketio.Server(client_manager=app.sio_manager)
    
    # ... other app setup ...
    return app

Example: Triggering a notification from a resource:

When a user follows another, emit an event:

# In a Flask-RESTful resource or similar view handler
# from flask import current_app
# Assuming current_app.sio_manager is the KombuManager instance

# Example data structure
follower_info = {
    'follower_id': 'user123',
    'follower_name': 'Alice',
    'follower_avatar': 'url_to_alice_avatar',
    'timestamp': int(time.time())
}

# Target user ID to receive the notification
target_user_id = 'user456'

# Emit the 'new_follower' event to the target user's room
# You'll need access to the SocketIO Server instance (sio) from server.py
# Assuming 'sio' is accessible or passed correctly

# If sio is global or accessible:
# sio.emit('new_follower', follower_info, room=str(target_user_id))

# If using Flask's current_app.sio_manager and need to emit from a different place:
# This typically requires access to the underlying SocketIO Server instance.
# Often, the Server instance itself is made available globally or passed around.
# A common pattern is: from your_app.server import sio
# followed by: sio.emit(...)

# For demonstration, let's assume 'sio' is accessible:
# from server import sio # Example import
# sio.emit('new_follower', follower_info, room=str(target_user_id))

# If using the app factory pattern and passing the manager:
# app = create_app(...)
# app.sio_manager is the KombuManager
# You'd likely need to instantiate Server *with* this manager where needed.
# A simpler pattern is often to make the Server instance available globally.

# Assuming 'sio' from server.py is available:
# Example snippet within a Flask view context:
# from flask import g, current_app
# from server import sio # Direct access to the global sio instance

# ... database operations to record follow ...

# user_data = { ... }
# target_user_id = ...
# sio.emit('following_notification', user_data, room=str(target_user_id))