ALPR WebSocket

Introduction

This project establishes a real-time communication system centered around Automatic License Plate Recognition (ALPR). It leverages WebSockets for bidirectional communication between agents (presumably cameras or devices capturing license plates) and a central server. The server, built with Autobahn and Twisted, handles agent registration, configuration updates, and facilitates image and video downloads related to ALPR events. Redis acts as a crucial component for managing connections and enabling efficient request routing in a potentially scaled environment.

Class Diagram

Component Explanation

• WebsocketsServer: The core orchestrator, responsible for initializing and managing both the WebSocket and HTTP servers. It also handles the configuration setup.

• AlprlinkServerProtocol: This class handles individual WebSocket connections, managing agent registration, message processing, and connection lifecycle events.

• AlprResource: The base class for HTTP request handlers, providing common functionality for request processing and interaction with WebSockets.

• ImageResource, ConfigResource, VideoDownloadResource: These are specialized subclasses of AlprResource, each handling specific HTTP endpoints and their associated logic (image downloads, configuration changes, video downloads).

• RedisInterface: This class provides an interface to interact with a Redis database, primarily for storing and retrieving information about agent connections.

Flow Diagram

Flow Explanation

1. Clients establish WebSocket connections with the server for real-time, bidirectional communication.

2. Clients send registration and other messages over the WebSocket connection. The AlprlinkServerProtocol handles these messages, potentially interacting with Redis to store connection information or forward requests to other servers.

3. Clients also make HTTP requests to various endpoints (/img, /config, /video_download, /diagnostic).

4. The corresponding AlprResource subclass (or DiagnosticResource) handles the HTTP request. It may need to communicate with the WebSocket connection (via AlprlinkServerProtocol) to get data from the agent or forward the request to another server based on Redis information.

5. Redis acts as a central store for connection data, enabling the system to route requests to the correct server instance even if agents connect to different instances.

HTTP Endpoints

Download an image

GEThttps://your-server-address/img

Query parameters

Response

200400500

Successful image download

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://your-server-address/img?company_id=text&agent_id=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

• The client sends a GET request to /img with query parameters.

• ImageResource checks Redis to find the server hosting the agent's WebSocket connection

• If the agent is on another server, the request is forwarded; otherwise, it's handled locally

• A WebSocket message is sent to the agent requesting the image

• The agent responds with the image data

• ImageResource sends the image data back to the client in an HTTP response

Handle configuration operations

POSThttps://your-server-address/config

Body

application/json

typeenum

config_infoconfig_pushagent_status...

company_idstring

agent_idstring

Response

200400500

Successful configuration operation

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://your-server-address/config', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

• The client sends a POST request to /config with a JSON payload in the body

• ConfigResource checks Redis to find the server hosting the agent

• If needed, the request is forwarded; otherwise, it's handled locally

• A WebSocket message is sent to the agent with the configuration operation

• The agent processes the configuration and sends a response

• ConfigResource sends the configuration result back to the client

Download a video

GEThttps://your-server-address/video_download

Query parameters

Response

200400500

Successful video download

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://your-server-address/video_download?company_id=text&agent_id=text&uuid=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

• Similar to /img, but requests a video download instead

Get diagnostic information

GEThttps://your-server-address/diagnostic

Response

200500

HTML page with diagnostic details

Request

JavaScriptCurlPython

const response = await fetch('https://your-server-address/diagnostic', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

• The client requests the diagnostic page

• DiagnosticResource generates the HTML content using internal server state

• The HTML content is sent back to the client

Scaling the Project

The project employs a hybrid approach to scalability, blending stateless and stateful components. This design choice presents both opportunities and challenges when scaling the system to handle increased load.

Stateless HTTP Endpoints

The HTTP endpoints, responsible for image/video downloads, configuration interactions, and diagnostics, are inherently stateless. Each request carries all the necessary information for processing, allowing these endpoints to be scaled horizontally by simply adding more server instances behind a load balancer.

Stateful WebSocket Connections

The use of WebSockets introduces statefulness into the system. Active WebSocket connections with agents maintain essential context, including registration status, last activity timestamps, and agent identification. This statefulness creates a degree of stickiness, where subsequent requests from an agent ideally should be directed to the same server instance that holds its WebSocket connection.

Redis as a Scaling Enabler

Redis plays a pivotal role in mitigating the scaling challenges posed by stateful WebSockets. It serves as a distributed connection directory, mapping each agent's connection to the specific server instance handling it. This enables:

• Dynamic Request Routing: When an HTTP request arrives, the system consults Redis to identify the server instance responsible for the agent's WebSocket connection. If necessary, the request is forwarded to the appropriate instance, ensuring that stateful interactions are maintained even in a multi-server environment.

• Load Balancing: By distributing agent connections across multiple server instances and intelligently routing requests based on Redis information, the system achieves a degree of load balancing.

• Fault Tolerance: If a server instance fails, agents can reconnect to other instances. Redis's connection directory allows the system to seamlessly adapt to these changes, maintaining functionality even in the face of failures.