v2024.3 docs update

.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

app-server/docker.md

@@ -24,7 +24,7 @@ FROM php:8.3-alpine
 # https://github.com/mlocati/docker-php-extension-installer
 # https://github.com/docker-library/docs/tree/0fbef0e8b8c403f581b794030f9180a68935af9d/php#how-to-install-more-php-extensions
 RUN --mount=type=bind,from=mlocati/php-extension-installer:2,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
-     install-php-extensions @composer-2 opcache zip intl sockets profobuf
+     install-php-extensions @composer-2 opcache zip intl sockets protobuf
 
 COPY --from=roadrunner /usr/bin/rr /usr/local/bin/rr
 

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/overview-kv.md

@@ -49,8 +49,8 @@ otel:
 
 {% endcode %}
 
-After that, you can see traces in your [Jaeger](https://www.jaegertracing.io/), [Uptrace](https://uptrace.dev/), [Zipkin](https://zipkin.io/) or any 
-other opentelemetry compatible tracing system.
+After that, you can see traces in your [Dash0](https://www.dash0.com/), [Jaeger](https://www.jaegertracing.io/), [Uptrace](https://uptrace.dev/), 
+[Zipkin](https://zipkin.io/) or any other opentelemetry compatible tracing system.
 
 
 ## Configuration
@@ -356,7 +356,7 @@ To make it easy to use the KV proto API in PHP, we provide
 a [GitHub repository](https://github.com/roadrunner-php/roadrunner-api-dto), that contains all the generated PHP DTO
 classes proto files, making it easy to work with these files in your PHP application.
 
-- [API](https://github.com/roadrunner-server/api/blob/master/kv/v1/kv.proto)
+- [API](https://github.com/roadrunner-server/api/blob/master/proto/kv/v1/kv.proto)
 
 ### RPC API
 

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/rpc.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/worker.md

@@ -86,10 +86,11 @@ while (true) {
         //
         // Reply by the 500 Internal Server Error response
         $psr7->respond(new Response(500, [], 'Something Went Wrong!'));
-        
+
         // Additionally, we can inform the RoadRunner that the processing 
-        // of the request failed.
-        $psr7->getWorker()->error((string)$e);
+        // of the request failed. Use error instead of response to indicate
+        // worker error, do not use both.
+        // $psr7->getWorker()->error((string)$e);
     }
 }
 ```
@@ -222,7 +223,6 @@ final class HttpDispatcher implements DispatcherInterface
                 $worker->respond(new Response(200, [], 'Hello RoadRunner!'));
             } catch (\Throwable $e) {
                 $worker->respond(new Response(500, [], 'Something Went Wrong!'));
-                $worker->getWorker()->error((string)$e);
             }
         }
     }

plugins/tcp.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