Chat: Broker

1Introduction

The broker is a program running in the background, whose role is to receive new messages sent to the server (via the Message controller), and transmit them to all connected browsers (via the Event controller).

More precisely, this program is a command-line script managed by Comma. CLI scripts are written in the same way as web controllers, with just a few specific features.

2Source code

Here is the code for the cli/Broker.php file:

<?php

/** Broker script controller. */
class Broker extends \Temma\Web\Controller {
    /** Main action. */
    public function run() {
        // socket activation
        $this->zmq_broker_pub->connect();
        // infinite loop
        while (true) {
            // read a new message sent by the Message controller
            $msg = $this->zmq_broker_pull[''];
            // send the message to Event controllers
            $this->zmq_broker_pub[''] = $msg;
        }
    }
}

Line 4: Broker controller definition.
Line 6: Definition of run() action.
Line 8: Explicit opening of ZeroMQ PUB socket (publication). Normally, this isn't necessary; ZeroMQ sockets are opened when they are first used. In this case, it's necessary so that Event controllers attempting to connect to it can find a socket that accepts connections.
Line 10: Infinite loop.
Line 12: Blocking read on ZeroMQ PULL socket. Temma reads and writes data sources as if they were associative arrays. Here, the key is an empty string.
Line 14: Write the message just received to the ZeroMQ PUB socket. Here again, the data source is manipulated as if it were an associative array, with an empty string as the key.

3Execution

The script is simply launched with the command:

$ bin/comma Broker run

3.1Automatic start

To ensure that the script is automatically executed when the server is launched, you can use Linux's init system.

To do this, simply create a file /etc/init.d/broker:

#!/bin/sh

/path/to/application/bin/comma Broker run

Remember to give the script execution rights:

$ sudo chmod +x /etc/init.d/broker

Finally, configure the script to be executed at startup:

$ sudo update-rc.d broker start 01 2 .

3.2Automatic restart

It's important that the broker runs continuously, otherwise messages won't be sent to all connected users.

The automatic start-up method explained above has the advantage of being simple, but if the broker ever goes down − for whatever reason − it will not be restarted automatically.
There are several possible solutions, but one of the simplest is to use Supervisor.

To install Supervisor on Debian/Ubuntu :

$ sudo apt install supervisor

Next, create a file /etc/supervisor/conf.d/broker.conf:

[program:broker]
command=/path/to/application/bin/comma Broker run
autostart=true
autorestart=true
stdout_logfile=/var/log/supervisor/broker.log
stderr_logfile=/var/log/supervisor/broker-err.log

Line 1: Start broker program configuration.
Line 2: Enter the path to the program to be executed.
Line 3: Supervisor is asked to launch the program automatically on start-up.
Line 4: Asks Supervisor to restart the program if it is interrupted.
Line 5: Path to the log file to which the program's standard output will be redirected.
Line 6: Path to the log file to which the program's error output will be redirected.

For Supervisor to take this configuration file into account:

$ sudo supervisorctl reread
$ sudo supervisorctl update

Next, you can control program execution with the following commands (to start, stop and restart the program respectively):

$ sudo supervisorctl start broker
$ sudo supervisorctl stop broker
$ sudo supervisorctl restart broker