From 2c7a576253b42e93102011845810776d55abc8de Mon Sep 17 00:00:00 2001 From: root Date: Mon, 20 Jul 2026 14:58:08 +0300 Subject: [PATCH 1/3] Issue #16: Implemented documentation for Queue v2.0.0 Signed-off-by: root --- docs/book/v2/control-commands.md | 51 +++++ .../v2/how-to/communication-with-queue.md | 206 ++++++++++++++++++ docs/book/v2/how-to/send-emails.md | 110 ++++++++++ docs/book/v2/installation.md | 85 ++++++++ docs/book/v2/messenger-configuration.md | 53 +++++ docs/book/v2/overview.md | 25 +++ docs/book/v2/server-setup.md | 168 ++++++++++++++ docs/book/v2/valkey.md | 88 ++++++++ docs/book/v2/what-is-queue.md | 40 ++++ mkdocs.yml | 14 +- 10 files changed, 839 insertions(+), 1 deletion(-) create mode 100644 docs/book/v2/control-commands.md create mode 100644 docs/book/v2/how-to/communication-with-queue.md create mode 100644 docs/book/v2/how-to/send-emails.md create mode 100644 docs/book/v2/installation.md create mode 100644 docs/book/v2/messenger-configuration.md create mode 100644 docs/book/v2/overview.md create mode 100644 docs/book/v2/server-setup.md create mode 100644 docs/book/v2/valkey.md create mode 100644 docs/book/v2/what-is-queue.md diff --git a/docs/book/v2/control-commands.md b/docs/book/v2/control-commands.md new file mode 100644 index 0000000..44e862b --- /dev/null +++ b/docs/book/v2/control-commands.md @@ -0,0 +1,51 @@ +# Available commands and usage + +The commands available are: + +1. `GetFailedMessagesCommand.php (failed)` - returns logs with messages that failed to process (levelName:error) +2. `GetProcessedMessagesCommand.php (processed)` - returns logs with messages that were successfully processed (levelName:info) +3. `GetQueuedMessagesCommand (inventory)` - returns all queued messages from Redis stream 'messages' + +The commands can be run in two different ways: + +## CLI + +To run the commands via CLI, use the following syntax: + +```shell +php bin/cli.php failed --start="yyyy-mm-dd" --end="yyyy-mm-dd" --limit=int +``` + +```shell +php bin/cli.php processed --start="yyyy-mm-dd" --end="yyyy-mm-dd" --limit=int +``` + +```shell +php bin/cli.php inventory +``` + +## TCP message + +To use commands using TCP messages, the following messages can be used: + +```shell +echo "failed --start=yyyy-mm-dd --end=yyyy-mm-dd --limit=days" | socat -t1 - TCP:host:port +``` + +```shell +echo "processed --start=yyyy-mm-dd --end=yyyy-mm-dd --limit=days" | socat -t1 - TCP:host:port +``` + +In both cases, the flags are optional. Keep in mind if both `start` and `end` are set, `limit` will not be applied, it's only used when one of `start` or `end` is missing. + +To be able to test the `processed` command, by default when processing the "control" message, it is logged as successfully processed with `"levelName":"info"` simulating that the message was processed successfully. To use it, run the following message: + +```shell +echo "control" | socat -t1 - TCP:host:port +``` + +> Using `-t1` flag is not necessary but can be useful, it is used to set a timeout of n seconds for both reading and writing; after n second of inactivity, socat will terminate the connection. If the timeout is not set and the server does not respond or keep the connection open, the socat process could freeze indefinitely. + +```shell +echo "inventory" | socat -t1 - TCP:host:port +``` diff --git a/docs/book/v2/how-to/communication-with-queue.md b/docs/book/v2/how-to/communication-with-queue.md new file mode 100644 index 0000000..6b3df7e --- /dev/null +++ b/docs/book/v2/how-to/communication-with-queue.md @@ -0,0 +1,206 @@ +# COMMUNICATE WITH QUEUE + +Communication with the [`Dotkernel Queue`](https://github.com/dotkernel/queue) can be achieved in two different ways: procedural and object-oriented. + +## Procedural approach + +The main advantage of the procedural code is its simplicity, it directly connects to the queue server, sends the prepared data, and then closes the connection. In this example, the code opens a TCP connection to `localhost:8556`, checks if the connection is successful, sends data in JSON format, and closes the socket. This makes the logic easy to follow and quick to implement. The disadvantage of this approach is the difficulty of reusing and extending the code. As the complexity of the project increases by repeatedly using this approach, the code becomes more difficult to maintain and not as flexible compared to the object-oriented approach. + +```php +// collect the PAYLOAD that will be sent to Dotkernel Queue +$data = $anyTypeOfData; + +// open TCP connection to Dotkernel Queue server +// replace localhost with the IP of the Dotkernel Queue server +// replace 8556 with the port number +$client = stream_socket_client("tcp://localhost:8556", $errno, $errstr, 30); + +if (! $client) { + // log errors + error_log("Connection error: $errstr ($errno)"); +} else { + // send the PAYLOAD to Dotkernel Queue + fwrite($client, json_encode($data) . "\n"); + // make sure your message ends with a new line + // this allows the stream to know when the message is complete + // without it, the server might keep waiting, and not process what was sent + + fclose($client); + // close connection +} +``` + +## Object-oriented approach + +Using object-oriented approach, queue is accessed through dedicated classes and objects. Instead of calling functions directly, you instantiate objects that encapsulate the behavior of the queue. This approach offers reusability, maintainability, and cleaner separation of responsibilities, which is especially beneficial in larger applications. + +To implement this approach you need to follow a few simple steps: + +## Step 1 NotificationSystem module + +Create a new directory under the Core directory with the name NotificationSystem or any other name. + +Inside it, create a new `ConfigProvider.php`, a new `NotificationService.php` and then copy the code below. + +ConfigProvider code: + +```php +, + * } + */ +class ConfigProvider +{ + /** + * @return ConfigType + */ + public function __invoke(): array + { + return [ + 'dependencies' => $this->getDependencies(), + ]; + } + + /** + * @return DependenciesType + */ + public function getDependencies(): array + { + return [ + 'factories' => [ + NotificationService::class => AttributedServiceFactory::class, + ], + ]; + } +} +``` + +Service code: + +```php +createClient( + $this->config['protocol'] . '://' . $this->config['host'] . ':' . $this->config['port'] + ); + } + + // send the PAYLOAD to Dotkernel Queue + public function send(string $message): void + { + $this->createClient()->write($message . $this->config['eof']); + } + + // encode processed data + protected function encodeEmailMessage(array $data): string + { + return Encoder::encode($data); + } + + // process and send data + // change $data type depending on what you need + public function sendNewAccountNotification(mixed $data): void + { + $data['yourKey'] = $data; + $this->send($this->encodeEmailMessage($data)); + } + + //create your own custom methods to process data +} +``` + +## Step 2 Install new dependencies + +After you have finished creating the new files, navigate to composer.json and add the new dependencies under the require key: + +```json +{ + "require": { + "ext-sockets": "*", + "clue/socket-raw": "^1.6.0" + } +} +``` + +Install new dependencies using: + +```shell +composer install +``` + +Under the `autoload` → `psr-4` key add the newly created module: + +```php +"Core\\NotificationSystem\\": "src/Core/src/NotificationSystem/src" +``` + +Run `composer dump-autoload` to regenerate Composer’s autoload files. + +## Step 3 Configuration + +Navigate to `config/config.php` and add your new Core ConfigProvider `Core\NotificationSystem\ConfigProvider::class`. + +After you have added the new config provider, navigate to `config/autoload/local.php` and add a new config key used for server connection. +> **_NOTE:_** if you only have the local.php.dist file, duplicate it, and delete .dist from the copy's name. + +```php +'notification' => [ + 'server' => [ + 'protocol' => 'tcp', + 'host' => 'IP of the Dotkernel Queue ', + 'port' => 'port number', + 'eof' => "\n", + ], + ], +``` + +## Step 4 Service usage + +Navigate to your handler, inject the new service and use your custom method where needed. + +```php + #[Inject( + NotificationService::class + )] + public function __construct( + protected NotificationService $notificationService + ) { +``` diff --git a/docs/book/v2/how-to/send-emails.md b/docs/book/v2/how-to/send-emails.md new file mode 100644 index 0000000..d672882 --- /dev/null +++ b/docs/book/v2/how-to/send-emails.md @@ -0,0 +1,110 @@ +# SEND EMAILS + +Using a queuing service solves problems such as server overload. For example, if a server receives a large number of requests, it tries to process them synchronously, resulting in long response times or even server crashes. + +A concrete example is sending emails. While a series of tasks are running on the server, a task such as sending an email is passed to a queue and run in the background so the server can move on to the next task, while the queue composes the email and sends it. Tasks are queued and processed gradually (FIFO), depending on available resources. + +To implement such a service, the [`send-email`](https://github.com/dotkernel/queue/tree/send-email) branch can be taken as a model. + +> **_NOTE:_** The default branch 1.0 holds only the base code of Queue and provides essential features such as: +> +> * Adding messages to the queue +> * Retrieving and processing messages (FIFO) + +## Step 1 Importing Core + +Importing the Core is essential for the queue to communicate with the main application logic (for this case [`dotkernel admin`](https://github.com/dotkernel/admin)). Whether you copy the Core folder directly or add it as a submodule, it’s important to keep the Core in sync between the main project and the queue so that all classes, services, and configurations are available for message processing. + +## Step 2 Core dependency + +After adding the Core, you need to make sure all external dependencies are included in composer.json. Without them, Core functionalities (cache, mail, authentication, etc.) won’t work in the queue. + +```json +{ + "dotkernel/dot-cache": "^4.3", + "dotkernel/dot-data-fixtures": "^1.4.0", + "dotkernel/dot-errorhandler": "^5.0.0", + "dotkernel/dot-mail": "^5.3.0", + "laminas/laminas-authentication": "^2.18", + "mezzio/mezzio-authentication-oauth2": "^3.0.1", + "mezzio/mezzio-twigrenderer": "^2.19.0", + "ramsey/uuid": "^4.5.0", + "ramsey/uuid-doctrine": "^2.1.0", + "roave/psr-container-doctrine": "^6.2.0" +} +``` + +Adding Core modules under `autoload` → `psr-4` enables automatic class loading, so you don’t have to manually require each class. + +```json +{ + "autoload": { + "psr-4": { + "Queue\\": "src/", + "Core\\Admin\\": "src/Core/src/Admin/src", + "Core\\App\\": "src/Core/src/App/src", + "Core\\Security\\": "src/Core/src/Security/src", + "Core\\Setting\\": "src/Core/src/Setting/src", + "Core\\User\\": "src/Core/src/User/src" + } + } +} +``` + +## Step 3 Install new dependencies + +Install all new dependencies using: + +```shell +composer install +``` + +Running `composer install` ensures that all packages required for Core and the queue are downloaded. This includes third-party libraries and all project-specific dependencies. + +## Step 4 Configuration + +Navigate to `config/config.php` and add `ConfigProvider::class` file from all packages you installed. + +```php +Mezzio\Twig\ConfigProvider::class, +Dot\Cache\ConfigProvider::class, +Dot\DataFixtures\ConfigProvider::class, +Dot\Mail\ConfigProvider::class, + +// Core +Core\Admin\ConfigProvider::class, +Core\App\ConfigProvider::class, +Core\Security\ConfigProvider::class, +Core\Setting\ConfigProvider::class, +Core\User\ConfigProvider::class, +``` + +## Step 5 Database connection + +Navigate to `config/autoload/local.php` and fill in the database connection details. +> **_NOTE:_** if you only have the local.php.dist file, duplicate it, and delete .dist from the copy's name. + +```php +$databases = [ + 'default' => [ + 'host' => '', + 'dbname' => '', + 'user' => '', + 'password' => '', + 'port' => 3306, + 'driver' => 'pdo_mysql', + 'charset' => 'utf8mb4', + 'collate' => 'utf8mb4_general_ci', + ], +]; +``` + +## Step 6 Email configuration + +Inside your `config/autoload` folder create a new file named `mail.global.php`, copy this [file](https://github.com/dotkernel/queue/blob/send-email/config/autoload/mail.global.php) content and fill in your configuration. The queue will use these settings to send emails in the background. + +## Step 7 Data management and emails sending + +Once everything is installed and configured we can move on to handle the data in the queue. In the message handler for example `MessageHandler`, each message from the queue is processed, the email is composed, and then sent. By injecting the required services and using templates, the handler can send emails without blocking the main application, respecting FIFO and asynchronous processing. + +In this [file](https://github.com/dotkernel/queue/blob/send-email/src/App/Message/MessageHandler.php) you can follow a simple example of how to create and send an email using data received from the queue inside the handler. diff --git a/docs/book/v2/installation.md b/docs/book/v2/installation.md new file mode 100644 index 0000000..93a7ed7 --- /dev/null +++ b/docs/book/v2/installation.md @@ -0,0 +1,85 @@ +# INSTALLATION + +## Location + +- Because you are logged in now with the non-root user `dotkernel`, your current server path must be `/home/dotkernel` + +> Please be sure you are using the non-root user for the below installation + +## git clone + +```shell +git clone -b default-queue https://github.com/dotkernel/queue.git +``` + +> The installation path should be now `/home/dotkernel/queue` + +## Prepare `config/autoload` files + +- duplicate `local.php.dist` as `local.php`, then fill in the database credentials and set the `$baseUrl` +- duplicate `log.local.dist` as `log.local` +- duplicate `messenger.local.php.dist` as `messenger.local.php` +- duplicate `swoole.local.php.dist` as `swoole.local.php` + +## Run Composer + +```shell +composer install --no-dev +``` + +## Create services (daemon) + +- Edit the files from `/daemon` folder and set proper paths +- copy them in /etc/systemd/system/ + +```shell +sudo cp /home/dotkernel/queue/daemon/swoole.service /etc/systemd/system/swoole.service +``` + +```shell +sudo cp /home/dotkernel/queue/daemon/messenger.service /etc/systemd/system/messenger.service +``` + +## Start the Swoole daemon + +```shell +sudo systemctl daemon-reload +``` + +```shell +sudo systemctl enable swoole.service +``` + +```shell +sudo systemctl start swoole.service +``` + +```shell +sudo systemctl status swoole.service +``` + +## Start the Messenger daemon + +```shell +sudo systemctl daemon-reload +``` + +```shell +sudo systemctl enable messenger.service +``` + +```shell +sudo systemctl start messenger.service +``` + +```shell +sudo systemctl status messenger.service +``` + +### Testing the installation + +Send a request from your local machine + +```shell +echo "Hello" | socat -T1 - TCP:SERVER-IP:8556` +``` diff --git a/docs/book/v2/messenger-configuration.md b/docs/book/v2/messenger-configuration.md new file mode 100644 index 0000000..8ffc624 --- /dev/null +++ b/docs/book/v2/messenger-configuration.md @@ -0,0 +1,53 @@ +# Messenger Configuration + +```php +return [ + 'symfony' => [ + 'messenger' => [ + 'transports' => [ + 'redis_transport' => [ + // specifies the Redis server and stream/key + // messages is the main stream where new messages are initially stored + 'dsn' => 'redis://127.0.0.1:6379/messages', + // defines which serializer to use to encode/decode messages + 'serializer' => SymfonySerializer::class, + 'retry_strategy' => [ + // maximum number of retry attempts before moving a message to the failure transport + 'max_retries' => 3, + // initial delay before retrying a failed message, in milliseconds + 'delay' => 1000, + // each retry’s delay is multiplied by this factor + 'multiplier' => 2, + // maximum delay allowed between retries, 0 means unlimited or default behavior + 'max_delay' => 0, + ], + ], + // defines a transport named failed, used to store messages that cannot be delivered after retries. + 'failed' => [ + // specifies the Redis server and stream/key + 'dsn' => 'redis://127.0.0.1:6379/failed', + // defines which serializer to use to encode/decode messages + 'serializer' => SymfonySerializer::class, + ], + ], + // tells Symfony Messenger to send messages that exceed retry limits to the failed transport + 'failure_transport' => 'failed', + ], + ], + 'dependencies' => [ + 'factories'> [ + 'redis_transport' => [TransportFactory::class, 'redis_transport'], + 'failed' => [TransportFactory::class, 'failed'], + SymfonySerializer::class => fn(ContainerInterface $container) => new PhpSerializer(), + ], + ], +]; +``` + +## Main queue stream (`messages`) + +`messages` stream is the main queue where all new messages are initially stored. The Messenger worker consume messages from this stream and attempt to process them according to the application logic. + +## Dead Letter Queue (DLQ) + +DLQ is a dedicated transport where messages are sent when they fail to be processed after a configured number of retries. Each transport can define a retry_strategy specifying the maximum number of retry attempts, delays between retries, and exponential backoff rules. When a message exceeds the allowed retries, it is automatically forwarded to the failure transport and stored in `failed` stream, ensuring that failed messages do not block the queue. diff --git a/docs/book/v2/overview.md b/docs/book/v2/overview.md new file mode 100644 index 0000000..b9b5417 --- /dev/null +++ b/docs/book/v2/overview.md @@ -0,0 +1,25 @@ +# Overview + +> [Dotkernel Queue](https://github.com/dotkernel/dot-queue) is a component based on [**Symfony Messenger**](https://github.com/symfony/messenger) that is used to queue asynchronous tasks. +[netglue/laminas-messenger](https://github.com/netglue/laminas-messenger) is an adapter that integrates Symfony Messenger with the [Laminas Service Manager](https://docs.laminas.dev/laminas-servicemanager/) container for Mezzio/Laminas applications. + +Some everyday **operations are time-consuming and resource-intensive**, so it's best if they run on separate machines, decoupled from the regular request-response cycle. +**Asynchronous execution** performed by background workers ensures that these operations won't overload the main platform. +It allows the main platform to return a response and remain responsive for new requests, while tasks with long execution times are scheduled to run later. + +![Queue process](https://docs.dotkernel.org/img/queue/schema.png) + +## Badges + +![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/queue) +![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/queue/2.0.0) + +[![GitHub issues](https://img.shields.io/github/issues/dotkernel/queue)](https://github.com/dotkernel/queue/issues) +[![GitHub forks](https://img.shields.io/github/forks/dotkernel/queue)](https://github.com/dotkernel/queue/network) +[![GitHub stars](https://img.shields.io/github/stars/dotkernel/queue)](https://github.com/dotkernel/queue/stargazers) +[![GitHub license](https://img.shields.io/github/license/dotkernel/queue)](https://github.com/dotkernel/queue/blob/2.0/LICENSE.md) + +[![Build Status](https://github.com/mezzio/mezzio-skeleton/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/mezzio/mezzio-skeleton/actions/workflows/continuous-integration.yml) +[![codecov](https://codecov.io/gh/dotkernel/queue/graph/badge.svg?token=pexSf4wIhc)](https://codecov.io/gh/dotkernel/queue) +[![Qodana](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml/badge.svg?branch=main)](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml) +[![PHPStan](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml/badge.svg?branch=main)](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml) diff --git a/docs/book/v2/server-setup.md b/docs/book/v2/server-setup.md new file mode 100644 index 0000000..8fea652 --- /dev/null +++ b/docs/book/v2/server-setup.md @@ -0,0 +1,168 @@ +# Server setup + +The below instructions were tested only on **AlmaLinux 9** or **10**. + +*For other operating systems, they need to be adapted accordingly.* + +> We recommend the use of [Hetzner Cloud via our referral link](https://hetzner.cloud/?ref=HYu6z4XGfkcP) for development thanks to the initial € 20 free [Hetzner Cloud credit](https://www.hetzner.com/legal/referrals). + +## Starting point + +A server with **AlmaLinux 9** or **10** freshly installed with `root` access. + +### Update OS + +```shell +dnf update -y +``` + +### Create a new user with sudo permissions + +```shell +useradd dotkernel +``` + +```shell +passwd dotkernel +``` + +```shell +usermod -aG wheel dotkernel +``` + +> Reboot server. + +> SSH into the server as `dotkernel`. + +### Install various utilities + +```shell +sudo dnf install -y dnf-utils +``` + +```shell +sudo dnf install zip unzip socat wget +``` + +### PHP + +```shell +sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm +``` + +```shell +sudo dnf module enable php:remi-8.5 +``` + +```shell +sudo dnf install -y php php-cli php-common php-intl +``` + +### Start PHP-FPM + +```shell +sudo systemctl start php-fpm +``` + +```shell +sudo systemctl enable php-fpm +``` + +### Install and verify swoole + +```shell +sudo dnf install php-pecl-swoole6 +``` + +```shell +php -i | grep swoole +``` + +### Valkey + +```shell +sudo dnf install valkey +``` + +```shell +sudo systemctl enable valkey +``` + +```shell +sudo systemctl start valkey +``` + +```shell +sudo valkey-cli ping +``` + +### Valkey PHP module + +```shell +sudo dnf install php-pecl-redis +``` + +Make sure that the module is installed. + +```shell +php -i | grep redis +``` + +### Git + +```shell +sudo dnf install git +``` + +### Composer + +```shell +sudo wget https://getcomposer.org/installer -O composer-installer.php +``` + +```shell +sudo chmod 777 /usr/local/bin +``` + +```shell +sudo php composer-installer.php --filename=composer --install-dir=/usr/local/bin +``` + +### Firewall setup + +To add a minimum level of security, a firewall needs to be installed and allow connections from outside only to certain ports, from certain IPs. + +> Firewall setup is not mandatory + +```shell +sudo dnf install firewalld +``` + +```shell +sudo systemctl enable firewalld +``` + +> Before starting the firewall, make sure you will not get locked outside: + +```shell +sudo firewall-offline-cmd --zone=public --add-port=22/tcp --permanent +``` + +Then enable the firewall: + +```shell +sudo systemctl start firewalld +``` + +> By default, Swoole runs on port **8556**. +> You can change that in the configuration file. + +```shell +sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="YOUR_IP_ADDRESS" port port="8556" protocol="tcp" accept' +``` + +```shell +sudo firewall-cmd --reload +``` + +> NOW THE SERVER IS READY diff --git a/docs/book/v2/valkey.md b/docs/book/v2/valkey.md new file mode 100644 index 0000000..e6a0c08 --- /dev/null +++ b/docs/book/v2/valkey.md @@ -0,0 +1,88 @@ +# Valkey usage + +Valkey is an open source (BSD) high-performance key/value datastore that supports a variety of workloads such as caching, message queues and can act as a primary database. + +The following commands can be run in the CLI to interact with Valkey. +To enter the CLI, run: + +```shell +valkey-cli +``` + +## Utility Commands + +List all keys matching a pattern. + +```shell +KEYS * +``` + +Get server information and statistics: + +```shell +INFO +``` + +Check if the server is running: + +```shell +PING +``` + +Delete all keys in all databases: + +```shell +FLUSHALL +``` + +Check data type stored at a specific key (Possible types: string, list, set, zset, hash, stream): + +```shell +TYPE keyName +``` + +## Key-Value Operations + +Set a string key to a value: + +```shell +SET keyName "keyValue" +``` + +Get the value of a key: + +```shell +GET keyName +``` + +Delete one or more keys: + +```shell +DEL keyName1 keyName2 +``` + +## Stream Commands + +Read entries from a stream, sorted from oldest to newest (switch '-' and '+' to reverse order): + +```shell +XRANGE streamName - + +``` + +Delete stream: + +```shell +DEL streamName +``` + +Remove all stream entries while also keeping the stream key: + +```shell +XTRIM streamName MAXLEN 0 +``` + +Delete a specific entry: + +```shell +XDEL streamName +``` diff --git a/docs/book/v2/what-is-queue.md b/docs/book/v2/what-is-queue.md new file mode 100644 index 0000000..3d2ddc1 --- /dev/null +++ b/docs/book/v2/what-is-queue.md @@ -0,0 +1,40 @@ +# Tasks Delegated to the Queue + +Normally, the tasks delegated to the queue: + +- Take extended periods of time to execute and may be interrupted by PHP limitations (like the PHP `max_execution_time` parameter). +- Are external which introduces delays from authentication, awaiting responses from potentially multiple interrogations, or may even fail completely because the server is offline. +- Are not part of the PHP response (sending emails, processing videos). + +Here are some example tasks meant for the queue: + +- **Data Processing** like big data analytics, scientific simulations, or mathematical computations. +- **File Handling & Media Processing** like video and image processing, or compression/decompression of large files. +- **Networking** like uploading/downloading large files. +- **Database Operations** like imports/exports or migrations. +- **System & Infrastructure Tasks** like OS updates, software compilation, CI pipelines. + +The long execution times are caused by: + +- Data size - gigabytes, terabytes etc. +- Complex algorithms. +- Hardware limitations - CPU speed, memory, storage, network bandwidth. +- External dependencies - waiting on APIs or human input. + +## How the Queue Works + +- The queue system has an active **daemon** that listens for TPC connections on a specific port and **stores incoming messages** into Redis. +This method supports a **large number of requests per second** without overloading. +- Operations are then **scheduled for execution** when resources are available. +The order of the execution uses the **FIFO** (First-In, First-Out) method where the oldest request is processed first, followed by newer requests. + +## Main Features + +- **Logging** - Ensures maintainability and allows debugging. +- **Security** - The **firewall** allows requests only from whitelisted IPs for fast response times. +- **Retry Mechanism** - Retries failing tasks a certain number of times before removing a task from the queue. +- **Reporting** - The logs enable developers to investigate various metrics via console commands like: + - Queue length - How many jobs are in the to-do list. + - Processing time per job. + - Error rates - How many messages failed. + - Throughput - Jobs/sec processed. diff --git a/mkdocs.yml b/mkdocs.yml index 81bcb21..1e8fd83 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,8 +2,9 @@ docs_dir: docs/book site_dir: docs/html extra: project: Queue - current_version: v1 + current_version: v2 versions: + - v2 - v1 nav: - Home: index.md @@ -18,6 +19,17 @@ nav: - How to: - Communication With Queue: v1/how-to/communication-with-queue.md - Send Emails: v1/how-to/send-emails.md + - v2: + - Overview: v2/overview.md + - "Understanding the Queue": v2/what-is-queue.md + - Server Setup: v2/server-setup.md + - Installation: v2/installation.md + - Messenger Configuration: v2/messenger-configuration.md + - Control Commands: v2/control-commands.md + - Valkey: v2/valkey.md + - How to: + - Communication With Queue: v2/how-to/communication-with-queue.md + - Send Emails: v2/how-to/send-emails.md site_name: queue site_description: "Dotkernel Queue" repo_url: "https://github.com/dotkernel/queue" From eff0757aef8c5398ab24813ff37d174ebe52da89 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 20 Jul 2026 16:59:02 +0300 Subject: [PATCH 2/3] fixed overview links Signed-off-by: root --- docs/book/v1/overview.md | 8 ++++---- docs/book/v2/overview.md | 8 ++++---- mkdocs.yml | 23 ++++++++++++----------- 3 files changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/book/v1/overview.md b/docs/book/v1/overview.md index 5e6852a..dbe3531 100644 --- a/docs/book/v1/overview.md +++ b/docs/book/v1/overview.md @@ -19,7 +19,7 @@ It allows the main platform to return a response and remain responsive for new r [![GitHub stars](https://img.shields.io/github/stars/dotkernel/queue)](https://github.com/dotkernel/queue/stargazers) [![GitHub license](https://img.shields.io/github/license/dotkernel/queue)](https://github.com/dotkernel/queue/blob/1.0/LICENSE.md) -[![Build Status](https://github.com/mezzio/mezzio-skeleton/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/mezzio/mezzio-skeleton/actions/workflows/continuous-integration.yml) -[![codecov](https://codecov.io/gh/dotkernel/queue/graph/badge.svg?token=pexSf4wIhc)](https://codecov.io/gh/dotkernel/queue) -[![Qodana](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml/badge.svg?branch=main)](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml) -[![PHPStan](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml/badge.svg?branch=main)](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml) +[![Build Status](https://github.com/dotkernel/queue/actions/workflows/continuous-integration.yml/badge.svg?branch=1.0)](https://github.com/dotkernel/queue/actions/workflows/continuous-integration.yml) +[![codecov](https://codecov.io/gh/dotkernel/queue/branch/1.0/graph/badge.svg?token=pexSf4wIhc)](https://codecov.io/gh/dotkernel/queue) +[![Qodana](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml/badge.svg?branch=1.0)](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml) +[![PHPStan](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml/badge.svg?branch=1.0)](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml) diff --git a/docs/book/v2/overview.md b/docs/book/v2/overview.md index b9b5417..9c7a495 100644 --- a/docs/book/v2/overview.md +++ b/docs/book/v2/overview.md @@ -19,7 +19,7 @@ It allows the main platform to return a response and remain responsive for new r [![GitHub stars](https://img.shields.io/github/stars/dotkernel/queue)](https://github.com/dotkernel/queue/stargazers) [![GitHub license](https://img.shields.io/github/license/dotkernel/queue)](https://github.com/dotkernel/queue/blob/2.0/LICENSE.md) -[![Build Status](https://github.com/mezzio/mezzio-skeleton/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/mezzio/mezzio-skeleton/actions/workflows/continuous-integration.yml) -[![codecov](https://codecov.io/gh/dotkernel/queue/graph/badge.svg?token=pexSf4wIhc)](https://codecov.io/gh/dotkernel/queue) -[![Qodana](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml/badge.svg?branch=main)](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml) -[![PHPStan](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml/badge.svg?branch=main)](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml) +[![Build Status](https://github.com/dotkernel/queue/actions/workflows/continuous-integration.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/queue/actions/workflows/continuous-integration.yml) +[![codecov](https://codecov.io/gh/dotkernel/queue/branch/2.0/graph/badge.svg?token=pexSf4wIhc)](https://codecov.io/gh/dotkernel/queue) +[![Qodana](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/queue/actions/workflows/qodana_code_quality.yml) +[![PHPStan](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/queue/actions/workflows/static-analysis.yml) diff --git a/mkdocs.yml b/mkdocs.yml index 1e8fd83..f375f63 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,17 +8,6 @@ extra: - v1 nav: - Home: index.md - - v1: - - Overview: v1/overview.md - - "Understanding the Queue": v1/what-is-queue.md - - Server Setup: v1/server-setup.md - - Installation: v1/installation.md - - Messenger Configuration: v1/messenger-configuration.md - - Control Commands: v1/control-commands.md - - Valkey: v1/valkey.md - - How to: - - Communication With Queue: v1/how-to/communication-with-queue.md - - Send Emails: v1/how-to/send-emails.md - v2: - Overview: v2/overview.md - "Understanding the Queue": v2/what-is-queue.md @@ -30,6 +19,18 @@ nav: - How to: - Communication With Queue: v2/how-to/communication-with-queue.md - Send Emails: v2/how-to/send-emails.md + - v1: + - Overview: v1/overview.md + - "Understanding the Queue": v1/what-is-queue.md + - Server Setup: v1/server-setup.md + - Installation: v1/installation.md + - Messenger Configuration: v1/messenger-configuration.md + - Control Commands: v1/control-commands.md + - Valkey: v1/valkey.md + - How to: + - Communication With Queue: v1/how-to/communication-with-queue.md + - Send Emails: v1/how-to/send-emails.md + site_name: queue site_description: "Dotkernel Queue" repo_url: "https://github.com/dotkernel/queue" From 8265caa45be1bd8f7209489a6b108d110f6b45ca Mon Sep 17 00:00:00 2001 From: root Date: Mon, 20 Jul 2026 17:00:27 +0300 Subject: [PATCH 3/3] removed empty row --- mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index f375f63..fae383f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,7 +30,6 @@ nav: - How to: - Communication With Queue: v1/how-to/communication-with-queue.md - Send Emails: v1/how-to/send-emails.md - site_name: queue site_description: "Dotkernel Queue" repo_url: "https://github.com/dotkernel/queue"