[#32]: v2024.3 docs update

Author: rustatian

.gitbook.yaml

@@ -1,5 +1,5 @@
 root: ./
 
-​structure:
+structure:
   readme: README.md
-  summary: SUMMARY.md​
+  summary: SUMMARY.md

SUMMARY.md

@@ -18,7 +18,8 @@
 * [Code Coverage](php/codecoverage.md)
 * [Debugging](php/debugging.md)
 * [Environment](php/environment.md)
-* [Dynamic scaling](php/scaling.md)
+* [Manual workers scaling](php/manual-scaling.md)
+* [Auto workers scaling](php/auto-scaling.md)
 * [RPC](php/rpc.md)
 
 ## 🚀 Customization
@@ -122,6 +123,7 @@
 
 ## 📚 Releases
 
+* [v2024.3.0](releases/v2024-3-0.md)
 * [v2024.2.1](releases/v2024-2-1.md)
 * [v2024.2.0](releases/v2024-2-0.md)
 * [v2024.1.5](releases/v2024-1-5.md)

app-server/aws-lambda.md

@@ -341,7 +341,7 @@ logs:
   mode: production
   level: error
   encoding: json
-  output: stderr
+  output: [ stderr ]
 
 endure:
   grace_period: 1s

http/http.md

@@ -373,7 +373,7 @@ http:
       # directory to store your certificate and key from the LE
       #
       # Default: rr_cache_dir
-      certs_dir: rr_le_certs
+      cache_dir: rr_le_certs
       # Your email
       #
       # Mandatory. Error on empty.

kv/redis.md

@@ -94,6 +94,20 @@ kv:
       # Optional section.
       # Default: false
       read_only: false
+
+      # Optional section.
+      tls:
+        # Optional section.
+        # Default: ""
+        cert: ""
+
+        # Optional section.
+        # Default: ""
+        key: ""
+
+        # Optional section.
+        # Default: ""
+        root_ca: ""
 ```
 
 {% endcode %}
@@ -176,6 +190,21 @@ suffix". A value of `0` is equivalent to a timeout of 512 milliseconds (`512ms`)
 every CPU. Please note that specifying the value corresponds to the number of connections **per core**, so if you have 8
 cores in your system, then setting the option to 2 you will get 16 connections.
 
+### TLS Configuration
+
+The `tls` section allows you to configure Transport Layer Security (TLS) for secure communication with the Redis server. 
+If no options are defined in this section, the connection will default to non-TLS. 
+
+`cert`: Path to a file containing the client certificate. This certificate is used to authenticate the client 
+when communicating with the server.
+
+`key`: Path to a file containing the client private key. This key is used in conjunction with the client 
+certificate for mutual authentication.
+
+`root_ca`: Path to a file containing the Certificate Authority (CA) certificates used to verify the server's certificate.  
+**Note**: This option can be used independently of the `cert` and `key` options. In cases where the server does not 
+require client certificate verification, you only need to provide the `root_ca` option.
+
 ### Other
 
 `min_idle_conns`: Minimum number of idle connections which is useful when establishing new connection is slow. A value 

lab/health.md

@@ -24,17 +24,29 @@ status:
 The above configuration sets the address to `127.0.0.1:2114`. This is the address that the plugin will listen to. You
 can change the address to any IP address and port number of your choice.
 
-To access the health check, you need to use the following URL: http://127.0.0.1:2114/health?plugin=http. This URL will
-return the health status of the http plugin.
+To access the health check, use the following URL: `http://127.0.0.1:2114/health`. This URL will return the health status of all plugins that are enabled and support health probes. To specify a particular plugin, you need to use the `plugin` query parameter: `http://127.0.0.1:2114/health?plugin=http`. In that case, the health status of the `http` plugin will be returned.
 
 {% hint style="info" %}
 You can specify multiple plugins by separating them with a comma. For example, to check the health status of both the
 http and grpc plugins, you can use the following URL: http://127.0.0.1:2114/health?plugin=http&plugin=grpc.
 {% endhint %}
 
-The health check endpoint will return `HTTP 200` if there is at least one worker ready to serve requests. If there are
-no workers ready to service requests, the endpoint will return `HTTP 500`. If there are any other errors, the endpoint
-will also return `HTTP 500`.
+The health check endpoint will return `HTTP 200` if there is at least one worker ready to serve requests. If there are no workers ready to service requests, the endpoint will return `HTTP 503` (or your unavailable status code, which can be set via configuration of the plugin). If there are any other errors, the endpoint will also return `HTTP 503` (or your unavailable status code). The `status` plugin also returns a payload with a list of checked plugins and errors, if any, in the following format:
+
+```json
+[
+    {
+        "plugin_name": "http",
+        "error_message": "",
+        "status_code": 200
+    },
+    {
+        "plugin_name": "grpc",
+        "error_message": "some error message",
+        "status_code": 404
+    }
+]
+```
 
 The readiness check endpoint will return `HTTP 200` if there is at least one worker ready to take the request (i.e., not
 currently busy with another request). If there is no worker ready or all workers are busy, the endpoint will return

lab/logger.md

@@ -95,7 +95,7 @@ the output key.
 
 ```yaml
 logs:
-  output: stdout
+  output: [ stdout ]
 ```
 
 {% endcode %}
@@ -131,7 +131,7 @@ logs:
   channels:
     http:
       mode: production
-      output: http.log
+      output: [ http.log ]
 ```
 
 {% endcode %}

php/auto-scaling.md

@@ -0,0 +1,55 @@
+# Auto Workers Scaling
+
+## Introduction
+
+This feature became available starting from the RoadRunner `2024.3` release.
+Users can now scale their RoadRunner workers automatically, up to 100 additional workers.
+
+### Supported plugins
+
+- All plugins that support workers pool are supported.
+
+### Limitations
+
+- This feature is not available when running RoadRunner in debug mode (`*.pool.debug=true`).
+- This feature does not scale Temporal Workerflow worker, only activity workers.
+
+### Usage
+
+Below is a configuration example demonstrating how to use this new feature:
+
+{% code title=".rr.yaml" %}
+
+```yaml
+version: '3'
+
+rpc:
+  listen: tcp://127.0.0.1:6002
+
+server:
+  command: "php worker.php"
+
+http:
+  address: 127.0.0.1:10085
+  pool:
+    num_workers: 2
+    allocate_timeout: 60s
+    destroy_timeout: 1s
+    dynamic_allocator:
+        max_workers: 25
+        spawn_rate: 10
+        idle_timeout: 10s
+
+logs:
+  mode: development
+  level: debug
+```
+
+{% endcode %}
+
+### Configuration
+
+The new `dynamic_allocator` section has been added to the `*.pool` configuration. It contains the following parameters:
+- `max_workers` - the maximum number of workers that can be additionally spawned.
+- `spawn_rate` - the number of workers that can be spawned per NoFreeWorkers error (but up to `max_workers`).
+- `idle_timeout` - the time after which dynamically allocated workers are considered not needed and would be deallocated.

php/developer.md

@@ -92,6 +92,13 @@ number of messages consumed.
 This enables you to make changes to your codebase and reload it automatically.
 {% endhint %}
 
+
+## RoadRunner-Temporal Debug Mode
+
+{% hint style="warning" %}
+Note, that in the Temporal plugin, `pool` is actually called `activities`. All other `pool` options are the same. For example, `pool.num_workers` is `activities.num_workers`.
+{% endhint %}
+
 ## Stop Command
 
 In RoadRunner, you can send a `stop` command from the worker to the parent server to force process destruction. When

php/scaling.md renamed to php/manual-scaling.md

@@ -90,14 +90,14 @@ Once you have created `$rpc` instance, you can use it to call embedded RPC servi
 {% code title="worker.php" %}
 
 ```php
-$result = $rpc->call('informer.Workers', 'http');
+$result = $rpc->call('informer.AddWorker', 'http');
 
 var_dump($result);
 ```
 
 {% endcode %}
 
-{% hint style="warning" %}  
+{% hint style="warning" %}
 In the case of running workers in debug mode `http: { pool.debug: true }` the number of http workers will be zero
 (i.e. an empty array `[]` will be returned).
 
@@ -165,19 +165,19 @@ final class MetricsIgnoreResponse implements MetricsInterface
 
     public function sub(string $name, float $value, array $labels = []): void
     {
- 
+
         $this->rpc->callIgnoreResponse('metrics.Sub', compact('name', 'value', 'labels'));
     }
 
     public function observe(string $name, float $value, array $labels = []): void
     {
-        
+
         $this->rpc->callIgnoreResponse('metrics.Observe', compact('name', 'value', 'labels'));
     }
 
     public function set(string $name, float $value, array $labels = []): void
     {
-     
+
         $this->rpc->callIgnoreResponse('metrics.Set', compact('name', 'value', 'labels'));
     }
 

php/rpc.md

@@ -60,6 +60,11 @@ tcp:
     max_jobs: 0
     allocate_timeout: 60s
     destroy_timeout: 60s
+
+  # The size of the read buffer in MB. Can be increased to reduce the number of read syscalls.
+  # Consider using a larger buffer size if you expect to receive large payloads on the TCP server.
+  # Optional; example.
+  read_buf_size: 20
 ```
 
 {% endcode %}
@@ -110,15 +115,9 @@ tcp:
     - `addr`: The server address and port, specified in the format `tcp://<IP_ADDRESS>:<PORT>`.
     - `delimiter`: (Optional) The data packet delimiter. By default, it is set to `\r\n`. Each data packet should end
       either with an `EOF` or the specified delimiter.
-    - `read_buf_size`: (Optional) The size of the read buffer in MB. To reduce the number of read syscalls, consider
-      using a larger buffer size if you expect to receive large payloads on the TCP server.
-
-- `pool`: Configuration for the PHP worker pool.
-    - `num_workers`: The number of PHP workers to allocate.
-    - `max_jobs`: The maximum number of jobs each worker can handle. Set to 0 for no limit.
-    - `allocate_timeout`: The timeout for worker allocation, specified in the format `<VALUE>s` (e.g., `60s` for 60
-      seconds).
-    - `destroy_timeout`: The timeout for worker destruction, specified in the same format as allocate_timeout.
+
+- `pool`: Configuration for the PHP worker pool for the TCP servers. See
+https://docs.roadrunner.dev/docs/php-worker/pool for available parameters.
 
 ## PHP client
 

plugins/tcp.md

@@ -13,6 +13,11 @@ implementations is not guaranteed.
 To install and configure the RabbitMQ, use the
 corresponding [documentation page](https://www.rabbitmq.com/download.html).
 
+{% hint style="info" %}
+Every messages pushed to the RabbitMQ server uses the publiser confirms. This means that the message is only considered as sent when the server confirms it. This is a reliable way to ensure that the message is delivered to the server.
+{% endhint %}
+
+
 After that, you should configure the connection to the server in the `amqp` section. This configuration section
 contains exactly one `addr` key with a [connection DSN](https://www.rabbitmq.com/uri-spec.html). The `TLS` configuration sits in the `amqp.tls` section and consists of the following options:
 
@@ -67,7 +72,7 @@ the queue settings, including those specific to AMQP.
 version: "3"
 
 amqp:
-  addr: amqp://guest:[email protected]:5672 
+  addr: amqp://guest:[email protected]:5672
 
   # AMQPS TLS configuration
   #
@@ -117,11 +122,6 @@ jobs:
         # If the job has priority set to 0, it will inherit the pipeline's priority. Default: 10.
         priority: 1
 
-        # Consume any payload type (not only Jobs structured)
-        #
-        # Default: false
-        consume_all: false
-
         # Redial timeout (in seconds). How long to try to reconnect to the AMQP server.
         #
         # Default: 60
@@ -215,17 +215,12 @@ from `pipe1` have been processed.
 
 ### Prefetch
 
-`prefetch` - rabbitMQ QoS prefetch. See also ["prefetch-size"](https://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.qos.prefetch-size). Note that if you use a large number of workers and a small `prefetch` number, some of the workers may not be loaded with messages (jobs) due to the blocking nature of the prefetch. This would result in poor RoadRunner performance and waste of resources. 
+`prefetch` - rabbitMQ QoS prefetch. See also ["prefetch-size"](https://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.qos.prefetch-size). Note that if you use a large number of workers and a small `prefetch` number, some of the workers may not be loaded with messages (jobs) due to the blocking nature of the prefetch. This would result in poor RoadRunner performance and waste of resources.
 
 ### Queue
 
 `queue` - required, AMQP internal (inside the driver) queue name.
 
-### Consume all
-
-`consume_all` - by default, RoadRunner only supports `Jobs` structures from the queue. Enable this option by setting it
-to true if you wish to consume raw payloads as well.
-
 ### Exchange
 
 `exchange` - required, rabbitMQ exchange name.
@@ -267,13 +262,13 @@ Read more about Nack in RabbitMQ official docs: https://www.rabbitmq.com/confirm
 
 ### Durable
 
-`durable` - create a durable queue. 
+`durable` - create a durable queue.
 
 Default: `false`
 
 ### Delete queue on stop
 
-`delete_queue_on_stop` - delete the queue when the pipeline is stopped. 
+`delete_queue_on_stop` - delete the queue when the pipeline is stopped.
 
 Default: `false`
 
@@ -284,20 +279,20 @@ Default: `false`
 ### Exchange durable
 
 `exchange_durable` - Durable
-exchange ([rabbitmq option](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges)). 
+exchange ([rabbitmq option](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges)).
 
 Default: `false`
 
 ### Exchange auto delete
 
-`exchange_auto_delete` - Auto-delete (exchange is deleted when last queue is unbound from it): [link](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges). 
+`exchange_auto_delete` - Auto-delete (exchange is deleted when last queue is unbound from it): [link](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges).
 
 Default: `false`
 
 ### Queue auto delete
 
 `queue_auto_delete` - Auto-delete (queue that has had at least one consumer is deleted when last consumer
-unsubscribes): [link](https://www.rabbitmq.com/queues.html#properties). 
+unsubscribes): [link](https://www.rabbitmq.com/queues.html#properties).
 
 Default: `false`
 

queues/amqp.md

@@ -46,10 +46,6 @@ jobs:
         # Default: 10
         priority: 10
 
-        # Consume any payload type (not only Jobs structured)
-        # Default: false
-        consume_all: false
-
         # Optional section.
         # Default: 1
         tube_priority: 1
@@ -82,8 +78,3 @@ value should not exceed `int32` size.
 ### Tube
 
 `tube` - The name of the inner "tube" specific to the Beanstalk driver.
-
-### Consume all
-
-`consume_all` - By default, RR supports only `Jobs` structures from the queue. Set this option to true if you want to
-also consume the raw payloads.