Flask-SocketIO Documentation

Nginx (version 1.4+) can act as a front-end proxy for HTTP and WebSocket requests. To support scaling with multiple Socket.IO nodes, use the ip_hash directive in an upstream block to ensure 'sticky sessions' (routing a client to the same worker).

# Load balancing configuration
upstream socketio_nodes {
    ip_hash;
    server 127.0.0.1:5000;
    server 127.0.0.1:5001;
    server 127.0.0.1:5002;
}

server {
    listen 80;
    server_name _;

    location / {
        include proxy_params;
        proxy_pass http://127.0.0.1:5000;
    }

    location /static/ {
        alias <path-to-your-application>/static/;
        expires 30d;
    }

    location /socket.io {
        include proxy_params;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_pass http://socketio_nodes/socket.io;
    }
}

Since SocketIO does not use standard HTTP request/response cycles, traditional web forms cannot be used for authentication during the connection. You have two primary options:

1. Pre-connection Authentication: Perform traditional authentication via HTTP routes first. Store the user's identity in the session or a cookie. When the SocketIO connection is established, the handler will have access to this identity.
2. Socket.IO Protocol Authentication: Use the Socket.IO protocol's ability to pass an authentication dictionary during the connection. This dictionary is passed as an argument to the connect event handler.

Using Flask-Login with Flask-SocketIO

If you use Flask-Login, the current_user context variable is available in SocketIO handlers after login_user() has been called in an HTTP context.

Note: The @login_required decorator cannot be used on SocketIO handlers. You must implement a custom decorator to handle authentication checks.

@socketio.on('connect')
def connect_handler():
    if current_user.is_authenticated:
        emit('my response',
             {'message': '{0} has joined'.format(current_user.name)},
             broadcast=True)
    else:
        return False  # not allowed here

You can initialize Flask-SocketIO using two patterns: direct attachment to the app object or the init_app() style for factory patterns.

Important: Always use socketio.run(app) to start your server instead of app.run(). This ensures the correct web server (eventlet, gevent, or Werkzeug) is used to support WebSockets. Using flask run is not recommended as it lacks WebSocket support.

from flask import Flask
from flask_socketio import SocketIO

# Pattern 1: Direct initialization
app = Flask(__name__)
app.config['SECRET_KEY'] = 'secret!'
socketio = SocketIO(app)

if __name__ == '__main__':
    socketio.run(app)

# Pattern 2: init_app() style (Application Factory)
socketio = SocketIO()

def create_app():
    app = Flask(__name__)
    app.config['SECRET_KEY'] = 'secret!'
    socketio.init_app(app)
    return app

if __name__ == '__main__':
    app = create_app()
    socketio.run(app)

Flask-SocketIO makes SocketIO event handlers behave similarly to regular Flask HTTP routes by pushing application and request contexts.

Available Globals

• current_app and g: Available via the application context.
• request: Available via the request context. It is enhanced with the following members:
  • request.sid: A unique session ID for the connection (used as the initial room).
  • request.namespace: The currently handled namespace.
  • request.event: A dictionary containing message and args for the current event.
• session: A copy of the user session at the time of connection is made available.

Important Limitations

• Session Forking: Modifications to session within a SocketIO handler are preserved for future SocketIO handlers but are not visible to regular HTTP route handlers (because no HTTP cookie can be sent back during a WebSocket connection). If using server-side sessions (e.g., Flask-Session), changes made in HTTP routes can be seen by SocketIO handlers, provided the SocketIO handler does not modify the session itself.
• Hooks: before_request and after_request hooks are not invoked for SocketIO event handlers.
• Decorators: Most Flask decorators that rely on a Response object will not work with SocketIO handlers.