Merge branch '0.x'

Author: itnelo

.env.dev.dist

@@ -10,6 +10,21 @@
 
 COMPOSE_PROJECT_NAME=reactphp_foundation
 
+TIMEZONE=Europe/Moscow
+SOURCE_PATH=.
+DEPLOYMENT_PATH=/var/www/foundation
+
+# php
+PHP_VERSION=7.4
+
 # app
 APP_ENV=dev
 APP_SERVER_PORT=6636
+# prebuilt image for stack
+# see Dockerfile-stack from the 'docker' directory
+APP_STACK_IMAGE_NAME=
+APP_STACK_IMAGE_VERSION=
+
+# haproxy
+HAPROXY_VERSION=2.2
+HAPROXY_PORT_EXPOSE=6637

.github/images/haproxy_stats.png

@@ -1,6 +1,8 @@
 .idea/
 
 .env
+docker-compose.yml
+docker-compose.stack.yml
 
 vendor/
 

.github/images/how_it_works_schema.png

@@ -10,6 +10,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - No changes yet.
 
+## [0.2.0] - 2020-07-20
+### Added
+
+- Shutdown service that gracefully terminates the event loop
+after corresponding signals are received (using `ext-pcntl`). 
+- Docker-compose configuration for local development.
+- Docker stack configuration for [Swarm mode](https://docs.docker.com/engine/swarm/key-concepts),
+installation guide in README.md.
+- [HAProxy](https://www.haproxy.com) configuration to balance requests
+between multiple application replicas within docker network using built-in DNS service.
+
 ## [0.1.0] - 2020-06-22
 ### Added
 
@@ -18,8 +29,8 @@ with `.env` and `parameters.yml` support.
 - Main `Application` class that starts
 the async socket server and the event loop.
 - `ServerInterface` and the `HandlerInterface`, example handler implementation.
-- Non-blocking logger (based on [wyrihaximus/react-psr-3-stdio](https://github.com/WyriHaximus/reactphp-psr-3-stdio))
+- Non-blocking logger (based on [wyrihaximus/react-psr-3-stdio](https://github.com/WyriHaximus/reactphp-psr-3-stdio)).
 
-[Unreleased]: https://github.com/itnelo/reactphp-foundation/compare/0.1.0...0.x
+[Unreleased]: https://github.com/itnelo/reactphp-foundation/compare/0.2.0...0.x
 [0.2.0]: https://github.com/itnelo/reactphp-foundation/compare/0.1.0..0.2.0
 [0.1.0]: https://github.com/itnelo/reactphp-foundation/releases/tag/0.1.0

.gitignore

@@ -18,20 +18,129 @@ This skeleton for self-sufficient, asynchronous microservice contains:
     - `symfony/config`
     - `symfony/yaml`
 
-It follows strong SOLID design and fully PSR-compatible, 
-with PHP 7.4+ features in mind
-(starting with typed properties). 
+It follows strong SOLID design and fully PSR-compatible, built
+with PHP 7.4+ features in mind (starting with typed properties). 
 
 It is also relatively lightweight and takes benefits
 from both [Symfony](https://github.com/symfony/symfony) components
 and [ReactPHP](https://github.com/reactphp/reactphp)
 without raising up a heavy artillery setup.
 
+## Installation
+
+### Docker Swarm
+
+This setup provides a basic service scalability using [Swarm mode](https://docs.docker.com/engine/swarm/key-concepts). 
+For testing purposes, let's assume we have the following servers:
+
+```
+192.169.56.1    # our pc, manager node; haproxy
+192.169.56.10   # vm, worker node; app instance
+192.169.56.20   # vm, worker node; app instance
+192.169.56.30   # vm, worker node; app instance
+```
+
+**Pre-requirements**. Ensure all necessary ports are accessible on each machine
+or it may cause implicit problems during communication between nodes.
+A common symptom is a successful `nslookup` for all replicas within overlay,
+but a failed `ping` of some of them. Here is a quick list:
+
+```
+$ sudo ufw status
+Status: active
+
+To                         Action      From
+--                         ------      ----
+22/tcp                     ALLOW       192.169.56.0/24
+2376/tcp                   ALLOW       192.169.56.0/24
+2377/tcp                   ALLOW       192.169.56.0/24
+4789/udp                   ALLOW       192.169.56.0/24
+7946/tcp                   ALLOW       192.169.56.0/24
+7946/udp                   ALLOW       192.169.56.0/24
+```
+
+**Limitations**. This setup assumes you are using a single haproxy instance,
+on the fixed node in the cluster and only that node will have its ports published:
+
+![how it works schema](https://github.com/itnelo/reactphp-foundation/blob/master/.github/images/how_it_works_schema.png)
+
+**Step 1**. Create a manager node (for haproxy with exposed ports):
+
+```
+# our pc
+$ docker swarm init --advertise-addr 192.169.56.1
+```
+
+And a few worker nodes:
+
+```
+# vm
+$ docker swarm join --token JOIN_TOKEN --advertise-addr 192.169.56.10 192.169.56.1
+```
+
+where `JOIN_TOKEN` is a parameter obtained by `docker swarm join-token worker` on the manager node.
+Repeat this action for all other worker servers in your cluster
+using their own advertise addresses.
+
+**Step 2**. Assign geography labels to be able to evenly distribute
+containers between all available servers:
+
+```
+# our pc
+$ docker node update --label-add provider_location_machine=do.fra1.d1 HOSTNAME
+```
+
+where `HOSTNAME` is a server identifier, see `docker node ls` on the manager node.
+
+**Step 3**. Clone the repository and adjust environment variables:
+
+```
+# our pc
+$ git clone git@github.com:itnelo/reactphp-foundation.git my-service && cd "$_"
+$ cp .env.dev.dist .env
+```
+
+Fill `APP_STACK_IMAGE_NAME` and `APP_STACK_IMAGE_VERSION` with your image metadata
+from the desired registry.
+
+**Step 4**. Apply stack configuration:
+
+```
+# our pc
+$ set -a; . .env; set +a && envsubst < docker-compose.stack.yml.dist > docker-compose.stack.yml
+```
+
+You should also adjust placement constraints
+(according to **Step 2**) to ensure Swarm scheduler is able to assign tasks
+to the configured nodes. Check `haproxy.stack.cfg` from the `docker` directory
+if you have changed some ports or just use a custom haproxy image as well.
+
+**Step 5**. Deploy services:
+
+```
+# our pc
+$ docker stack deploy --orchestrator swarm --compose-file docker-compose.stack.yml my-service
+```
+
+By accessing `192.169.56.1:6637/stats` (if you stick to the default configuration; 
+use your manager node IP) a rendered page with backend statistics should be available:
+
+![haproxy stats](https://github.com/itnelo/reactphp-foundation/blob/master/.github/images/haproxy_stats.png)
+
+To rebalance app replicas between nodes, after one is added or removed, use:
+
+```
+$ docker service update --force my-service_app
+```
+
 ## See also
 
 - [driftphp/driftphp](https://github.com/driftphp/driftphp) — 
 If you are looking for a deeper Symfony integration, with Kernel adaptation
 to async environment.
+- [thesecretlivesofdata.com/raft](http://thesecretlivesofdata.com/raft/) —
+A helpful visualization to understand how the distributed consensus algorithm,
+used by Docker Swarm, works.
 
 ## Changelog
 

CHANGELOG.md

@@ -45,11 +45,12 @@ $container = new ContainerBuilder($parameterBag);
 // loading service definitions.
 $definitionLoader    = new YamlFileLoader($container, new FileLocator());
 $definitionFilePaths = [
-    __DIR__ . '/../config/request_handlers.yml',
-    __DIR__ . '/../config/loggers.yml',
-    __DIR__ . '/../config/async/streams.yml',
-    __DIR__ . '/../config/async/server.yml',
-    __DIR__ . '/../config/async/event_loop.yml',
+    __DIR__ . '/../config/services/request_handlers.yml',
+    __DIR__ . '/../config/services/loggers.yml',
+    __DIR__ . '/../config/services/shutdown.yml',
+    __DIR__ . '/../config/services/async/streams.yml',
+    __DIR__ . '/../config/services/async/server.yml',
+    __DIR__ . '/../config/services/async/event_loop.yml',
     __DIR__ . '/../config/services.yml',
 ];
 
@@ -58,7 +59,7 @@ foreach ($definitionFilePaths as $definitionFilePath) {
 }
 
 // we are starting an async web server with some concurrent code
-// so we don't need any caching/preloading logic for this case.
+// so we don't need any container caching logic for this case.
 $container->compile(true);
 
 $application = new Application($container);

README.md

@@ -25,6 +25,7 @@
     "minimum-stability": "stable",
     "require": {
         "php": ">=7.4",
+        "ext-pcntl": ">=7.4",
         "psr/container": "^1.0",
         "psr/http-message": "^1.0",
         "psr/log": "^1.1",

bin/app

@@ -5,4 +5,5 @@ parameters:
     app.locale: en
 
     # Socket server configuration
+    app.server.host: 'tcp://0.0.0.0'
     app.server.port: '%env(int:APP_SERVER_PORT)%'