From ed47cc6fd746fef37cd9f94fb3baa4d466b0f370 Mon Sep 17 00:00:00 2001 From: Daniel LaBarge Date: Sat, 4 Mar 2017 23:32:04 -0600 Subject: [PATCH] Added instructions to readme --- README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 72 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6bd1895..e9898c4 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ to give away prizes at meetups and conferences and to teach async in PHP. This repository is the Laravel application that you install and deploy. It includes all the necessary ReactPHP components as dependencies. +From the talk, _[It's All PHP I Promise](https://drive.google.com/open?id=0B0huSIRObL68Qjdya1h0QUxzdDA)_ + ## Installation The application installs like any Laravel application. The following shows one @@ -12,8 +14,6 @@ possible way to install the application. While Composer is required, Yarn is optional and you could just as easily use NPM instead. ``` -mkdir larandomizer -cd larandomizer git clone https://github.com/larandomizer/app ./ composer install yarn install @@ -22,8 +22,29 @@ cp .env.example .env php artisan key:generate ``` +### Configure the Environment + You will still want to edit the `.env` file to customize environment settings. -No database is used as all data is stored in memory on the server. +Note that no database is used as all data is stored in memory on the server. +Restarting the server will cause all data to be lost. Below are available options +for server customization: + +- `SERVER_ADDRESS` (`127.0.0.1`): sets the address the server should bind to (`0.0.0.0` would be for allowing all external connections) +- `SERVER_PORT` (`8080`): sets the port the server will listen on for websocket connections +- `SERVER_MAX_CONNECTIONS` (`100`): the server rejects new connections after this limit (set to `0` to allow unlimited) +- `SERVER_QUEUE` (`default`): the name of the queue that realtime messages will be sent to +- `SERVER_QUEUE_DRIVER` (`beanstalkd`): the driver to use for the realtime message queue +- `SERVER_KEY` (`password`): the admin password to authenticate connections against admin protected connections + +There is a basic auth scheme in place which allows the server to `PromptForAuthentication` +against a connection and then remember that the connection is authenticated. This +simplifies further message processing and relies on any `ClientMessage` that must +be authenticated to implement the `authorize()` method. There are three basic +traits that can be used on any message to achieve a couple of common strategies: + +- `App\Server\Traits\NoProtection`: always returns true so allows any client to send the message +- `App\Server\Traits\ClientProtection`: allows admin connections and a specific related connection to be authorized +- `App\Server\Traits\AdminProtection`: allows only admins to be authorized to send the message ### Nginx Websocket Proxy Configuration @@ -64,4 +85,51 @@ and if you pass `--help` to the command you can see additional options. You can stop the running server by killing the process with `CMD + C` (or `CTRL + C`). In production you would want to have Supervisor monitor the server and restart -it if ever it crashes. +it if ever it crashes. The demo application has a "Restart Server" command which +actually just stops the server and expects Supervisor to start it again automatically. +If you are using Laravel Forge this is pretty easy to do by adding a New Deamon +on the server with a configuration of: + +- Command: `/usr/bin/php /home/forge/default/artisan server:start` +- User: `forge` + +The resulting Supervisor config might be: + +``` +[program:server] +command=/usr/bin/php /home/forge/larandomizer.com/artisan server:start +autostart=true +autorestart=true +user=forge +redirect_stderr=true +startsecs=1 +stdout_logfile=/home/forge/.forge/server.log +``` + +Forge does not add the `startsecs` by default but in practice this may be needed +to give the server ample time to start without hard exiting and forcing Supervisor +to give up on starting the process. + +### Pushing Messages to the Realtime Queue + +By default the `App\Server\Manager@start()` method adds a queue worker to the +async event loop so that "offline" messages can be sent to the "realtime" connected +websocket clients. You can use any async driver (basically don't use `sync` as +the queue driver) but if you are using Laravel Forge it is pretty easy to use +`beanstalkd` driver. Set `SERVER_QUEUE_DRIVER` and `SERVER_QUEUE` in your `.env` +to configure the driver and queue name for your realtime messages. + +To send messages from your "offline" code (e.g.: controllers, repositories, etc.) +to your "realtime" code you can `use App\Server\Traits\WebsocketQueue` trait in +your caller class and then call `$this->queue(new Command)` to push server +commands into the event loop of the websocket server. Commands should run nearly +instantly though there can be some lag depending on remaining commands within the +event loop. You can tweak the timing of the worker in `App\Server\Manager@start()` +method's configuration of the worker. + +## Licensing + +Copyright (c) 2017 [Artisans Collaborative](http://artisanscollaborative.com) + +This package is released under the MIT license. Please see the LICENSE file +distributed with every copy of the code for commercial licensing terms.