From 96d7dcb0c00ab8d7e3e78a9b1bff9c22dc4c1781 Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Sun, 10 Nov 2024 20:37:38 +0100 Subject: [PATCH 01/12] chore: add docs for new healthchecks Signed-off-by: Valery Piashchynski --- lab/health.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/lab/health.md b/lab/health.md index e51b524..bcbca52 100644 --- a/lab/health.md +++ b/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 From 713c2c934138273df92e6977dc27300245419a91 Mon Sep 17 00:00:00 2001 From: Nicolai Date: Sun, 10 Nov 2024 20:51:38 +0100 Subject: [PATCH 02/12] [#29]: Adjust documentation to match errors found via schema updates and new SQS parameters --- .gitbook.yaml | 4 +- app-server/aws-lambda.md | 2 +- app-server/docker.md | 2 +- kv/overview-kv.md | 6 +- lab/logger.md | 4 +- php/worker.md | 8 +- plugins/tcp.md | 17 ++- queues/amqp.md | 10 -- queues/beanstalk.md | 9 -- queues/nats.md | 9 -- queues/sqs.md | 260 +++++++++++++++++++++++++++++---------- 11 files changed, 214 insertions(+), 117 deletions(-) diff --git a/.gitbook.yaml b/.gitbook.yaml index be8627e..6acdd6a 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -1,5 +1,5 @@ root: ./ -​structure: +structure: readme: README.md - summary: SUMMARY.md​ \ No newline at end of file + summary: SUMMARY.md diff --git a/app-server/aws-lambda.md b/app-server/aws-lambda.md index fb09b82..c5aab2f 100644 --- a/app-server/aws-lambda.md +++ b/app-server/aws-lambda.md @@ -341,7 +341,7 @@ logs: mode: production level: error encoding: json - output: stderr + output: [ stderr ] endure: grace_period: 1s diff --git a/app-server/docker.md b/app-server/docker.md index 869dafa..ed64d7d 100644 --- a/app-server/docker.md +++ b/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 diff --git a/kv/overview-kv.md b/kv/overview-kv.md index 479f02f..db65698 100644 --- a/kv/overview-kv.md +++ b/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 diff --git a/lab/logger.md b/lab/logger.md index 4486958..2d8279d 100644 --- a/lab/logger.md +++ b/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 %} diff --git a/php/worker.md b/php/worker.md index 436a439..9f80770 100644 --- a/php/worker.md +++ b/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); } } } diff --git a/plugins/tcp.md b/plugins/tcp.md index 7b12cc5..73d2b60 100644 --- a/plugins/tcp.md +++ b/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://:`. - `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 `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 diff --git a/queues/amqp.md b/queues/amqp.md index 5f13504..de1a620 100644 --- a/queues/amqp.md +++ b/queues/amqp.md @@ -117,11 +117,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 @@ -221,11 +216,6 @@ from `pipe1` have been processed. `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. diff --git a/queues/beanstalk.md b/queues/beanstalk.md index 0682384..a83daf9 100644 --- a/queues/beanstalk.md +++ b/queues/beanstalk.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. diff --git a/queues/nats.md b/queues/nats.md index 3c34a48..95911e2 100644 --- a/queues/nats.md +++ b/queues/nats.md @@ -33,10 +33,6 @@ jobs: # Messages to read into the channel prefetch: 100 - # Consume any payload type (not only Jobs structured) - # Default: false - consume_all: false - # NATS subject # Default: default subject: default @@ -91,8 +87,3 @@ jobs: ### Delete after ack `delete_after_ack` - delete message after it successfully acknowledged. - -### 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. diff --git a/queues/sqs.md b/queues/sqs.md index 0674137..fdb36c7 100644 --- a/queues/sqs.md +++ b/queues/sqs.md @@ -1,64 +1,114 @@ # SQS Driver -[Amazon SQS Simple Queue Service](https://aws.amazon.com/sqs/) is an alternative -queue server also developed by Amazon and is also part of the AWS -service infrastructure. If you prefer to use the "cloud" option, you can use the -[prebuilt documentation](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configuring.html) -for its installation. - -In addition to the ability to use this queue server within AWS, you can also use the -can also use the local installation of this system on your own servers. If you prefer -this option, you can use the [softwaremill's implementation](https://github.com/softwaremill/elasticmq) -of the Amazon SQS server. - -After you have created the SQS server, you need to specify the following -connection settings in the `sqs` configuration settings. Unlike AMQP and Beanstalk, -SQS requires more values to set up a connection and will be different from what we are used to. -we're used to. +[Amazon Simple Queue Service (SQS)](https://aws.amazon.com/sqs/) is an alternative +queue server developed by Amazon, provided as part of the AWS Cloud infrastructure. You can find the documentation +[here](https://docs.aws.amazon.com/sqs/). + +While this service is usually deployed on AWS, you can also self-host any compatible version, such as the +community-developed [ElasticMQ](https://github.com/softwaremill/elasticmq). ## Configuration +Specify the following connection settings in the `sqs` configuration settings. + {% code title=".rr.yaml" %} ```yaml sqs: - # Required AccessKey ID. + # AWS AccessKey ID. # Default: empty key: access-key - # Required secret access key. + # AWS Access Key Secret. # Default: empty secret: api-secret - # Required AWS region. + # AWS region. # Default: empty region: us-west-1 - # Required AWS session token. + # AWS SQS endpoint. + # This parameter *is only required* if your SQS endpoint is *not* hosted on the AWS infrastructure. + # Always leave this empty if your queue is on AWS SQS. + # For ElasticMQ, the default is http://127.0.0.1:9324 # Default: empty - session_token: test + endpoint: "" +``` - # Required AWS SQS endpoint to connect. - # Default: http://127.0.0.1:9324 - endpoint: http://127.0.0.1:9324 +{% endcode %} + +### Examples + +Because the options can be mixed in ways that don't make sense, here are a few examples of how to use the driver +in various scenarios. In all examples, the **queue name** is provided in the `jobs.pipelines.pipeline_name.config.queue` +property below. + +#### AWS SQS with dynamic IAM in same region + +If you access your AWS SQS queue from inside AWS via a service that supports dynamic IAM roles (such as EC2), and the +queue is in the same region. + +{% code title=".rr.yaml" %} + +```yaml +sqs: +# No parameters are required. Normally, if your IAM role has the required permissions and your service endpoint +# is in the same region, the environment variables associated with your instance/task will resolve all the +# configuration for you. You must provide the parent sqs key to enable SQS, even if you want to use the defaults. ``` {% endcode %} -{% hint style="info" %} -Please note that although each of the sections contains default values, it is marked as "required". This means that in -almost all cases they are required to be specified in order to correctly configure the driver. -{% endhint %} +#### AWS SQS in different region with dynamic IAM -After you have configured the connection - you should configure the queue that will use this connection: +If you access your AWS SQS queue from inside AWS via a service that supports dynamic IAM roles (such as EC2), and the +queue is in a different region. -{% hint style="info" %} -You may also skip the whole `sqs` configuration section (global, not the pipeline) to use the AWS IAM credentials if -the RR is inside the EC2 machine. RR will try to detect env automatically by making a http request to -the `http://169.254.169.254/latest/dynamic/instance-identity/` as -pointer [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/identify_ec2_instances.html). -However, if you want to use credentials from the `sqs` section, you might specify them and IAM credentials will be overridden. -{% endhint %} +{% code title=".rr.yaml" %} + +```yaml +sqs: + # Only region is required + region: eu-central-1 +``` + +{% endcode %} + +#### AWS SQS without dynamic IAM + +If you access your AWS SQS queue from outside AWS, or from a service that does not support IAM, you must provide +an access key and secret. If you access the service from outside AWS, you must also provide `region`. +You may also use this option if your service *does* support dynamic IAM, but you want to use explicit access keys. + +{% code title=".rr.yaml" %} + +```yaml +sqs: + key: ASIAIOSFODNN7EXAMPLE + secret: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + # If in a different region *or* if outside AWS, provide the correct region. + region: eu-west-1 +``` + +{% endcode %} + +#### Self-hosted (ElasticMQ) + +If you self-host your SQS-compatible queue, only the endpoint is required. You may be required to provide a set key of +and secret in order to satisfy parameters of the AWS SQS SDK, which RoadRunner uses under the hood. + +{% code title=".rr.yaml" %} + +```yaml +sqs: + key: foo + secret: bar + endpoint: http://127.0.0.1:9324 +``` + +{% endcode %} + +After you have configured the driver, you should configure the queue that will use this connection. {% code title=".rr.yaml" %} @@ -66,7 +116,7 @@ However, if you want to use credentials from the `sqs` section, you might specif version: "3" sqs: -# SQS connection configuration... +# SQS connection configuration. See above example. jobs: pipelines: @@ -80,14 +130,14 @@ jobs: # Default: 10 prefetch: 10 - # Consume any payload type (not only Jobs structured) - # Default: false - consume_all: false - # Get queue URL only # Default: false skip_queue_declaration: false + # Maximum number of messages that can be in-flight at any given time. This is useful to limit the number of messages that are being processed concurrently. + # Default: the same value as prefetch + max_messages_in_flight_limit: 10 + # Optional section. # Default: 0 visibility_timeout: 0 @@ -118,53 +168,124 @@ jobs: {% endcode %} -## Configuration options +## FIFO Queues + +AWS supports [FIFO](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fifo-queues.html) +queues, which guarantee order of delivery. In order for RoadRunner to correctly handle this scenario, some +configuration is required. -**Here is a detailed description of each of the SQS-specific options:** +1. You should set `retain_failed_jobs` to `true` on the pipeline, so a failed job does not get re-queued at the back of +the queue. This would break the FIFO order. +2. You should have `prefetch` set to `1` for the pipeline. If you fetch multiple messages at a time, RoadRunner may not +process the jobs in correct order. +3. You should make sure to either use an explicit non-zero `visibility_timeout` **or** make sure that the default +visibility configuration attribute on your queue (`VisibilityTimeout`) is non-zero. + +## Configuration Options ### Prefetch -`prefetch` - Number of jobs to prefetch from the SQS until ACK/NACK. -Default: `10`. +`prefetch` - The number of jobs to request from SQS at a time. This sets the `MaxNumberOfMessages` parameter on the +[`ReceiveMessage`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) call +to the queue. Additionally, it limits the number of queues that may be retained on the priority queue in RoadRunner for +the pipeline. If you set this to zero or omit it, the default value of 1 will be used. -### Visibility timeout +Default: `1` +Maximum: `10` -`visibility_timeout` - The duration (in seconds) that the received messages are hidden from subsequent retrieve requests -after being retrieved by a `ReceiveMessage` request. Max value is `43200` seconds (12 hours). Default: `0`. +### Visibility Timeout -### Wait time seconds +`visibility_timeout` - The duration (in seconds) that received messages are hidden from subsequent retrieve requests +after being retrieved by a consumer. This value should be **longer** than the time you expect each job to take, or the +job may run multiple times. If you do not provide a value for this parameter or set it to 0, the `VisibilityTimeout` +attribute of the queue is used, which defaults to 30 seconds. For more information, see the documentation on +[visibility timeouts](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html). -`wait_time_seconds` - The duration (in seconds) for which the call waits for a message to arrive in the queue before -returning. If a message is available, the call returns sooner than WaitTimeSeconds. If no messages are available and the -wait time expires, the call returns successfully with an empty list of messages. +Default: `0` +Maximum: `43200` (12 hours) -Default: `5`. +### Error Visibility Timeout + +`error_visibility_timeout` - If `retain_failed_jobs` is enabled, this is the duration (in seconds) that `NACK`'ed (or +failed) jobs will have their visibility timeout changed to. Note that you cannot have a message remain invisible for +more than the maximum value in cases where it fails multiple times, so setting this value to the maximum is error-prone. +This parameter is ignored if `retain_failed_jobs` is `false`, and it must be larger than zero to apply. + +Default: `0` +Maximum: `43200` (12 hours) + +### Retain Failed Jobs + +`retain_failed_jobs` - If enabled, jobs will **not** be deleted and re-queued if they fail. Instead, RoadRunner will +simply let them be processed again after `visibility_timeout` has passed. If you set `error_visibility_timeout` and +enable this feature, RoadRunner will change the timeout of the job to the value of `error_visibility_timeout`. This lets +you customize the timeout for errors specifically. If you enable this feature, you can configure SQS to automatically +move jobs that fail multiple times to a +[dead-letter queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html). +Always enable this feature if you consume from a FIFO queue. + +Default: `false` + +### Wait Time + +`wait_time_seconds` - The duration (in seconds) for which the call waits for a message to arrive in the queue before +returning. If a message is available, the call returns sooner than `wait_time_seconds`. If no messages are available and +the wait time expires, the call returns successfully with an empty list of messages. Please note that this parameter +cannot be explicitly configured to use zero, as zero will apply the queue defaults. In most cases, you should set this +to a non-zero value. + +Default: `0` +Maximum: `20` + +{% hint style="warning" %} +### Short vs. Long Polling + +By default, SQS and RoadRunner is configured to use **short polling**. Please review the documentation on the +differences between +[short and long polling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html) +and make sure that your queue and RoadRunner is configured correctly. Long polling will *usually* be a cost-saving +feature with no practical impact on performance or functionality. Remember that not providing a value (or zero) for +`wait_time_seconds` will cause your queue wait time to be based on the `ReceiveMessageWaitTimeSeconds` attribute +configured on the queue, which also defaults to zero. +{% endhint %} ### Queue -`queue` - SQS internal queue name. Can contain alphanumeric characters, hyphens (`-`), and underscores (`_`). +`queue` - The name of the queue. May only contain alphanumeric characters, hyphens (`-`), and underscores (`_`). On AWS, +this will form the last part of the queue URL, i.e. `https://sqs..amazonaws.com//`. -Default value is `default` string. +Default: `default` + +{% hint style="info" %} +Please note that [FIFO](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fifo-queues.html) +queue names **must** end with `.fifo`. +{% endhint %} ### Message Group ID -`message_group_id` - Message group ID is required for FIFO queues. Messages that belong to the same message group are processed in a FIFO manner. -More info: [link](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html#SQS-SendMessage-request-MessageGroupId) +`message_group_id` - Message group ID is required for FIFO queues. Messages that belong to the same message group are +processed in a FIFO manner. +More info: +[link](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html#SQS-SendMessage-request-MessageGroupId) -### Skip queue declaration +### Skip Queue Declaration -`skip_queue_declaration` - By default, RR tries to declare the queue by default and then gets the queue URL. Set this -option to `true` if the user already declared the queue to only get its URL. +`skip_queue_declaration` - By default, RR tries to create the queue (using the `queue` name) if it does not exist. Set +this option to `true` if the queue already exists. -### Consume all +Default: `false` -`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. +{% hint style="info" %} +For queue creation to work, the credentials or the IAM role used must have the +[required permissions](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-api-permissions-reference.html), +such as `sqs:CreateQueue` and `sqs:SetQueueAttributes`. +{% endhint %} ### Attributes -`attributes` - List of -the [AWS SQS attributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html). +`attributes` - A list of +[AWS SQS attributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html) +to configure for the queue. {% code title=".rr.yaml" %} @@ -179,11 +300,16 @@ attributes: {% endcode %} +{% hint style="info" %} +Attributes are only set if RoadRunner creates the queue. Attributes of existing queues are **not modified**. +{% endhint %} + ### Tags -`tags` - Tags don't have any semantic meaning. Amazon SQS interprets tags as character. +`tags` - Tags don't have any semantic meaning. Amazon SQS interprets tags as character strings. Tags are only set if +RoadRunner creates the queue. Existing queues are **not** modified. {% hint style="info" %} -This functionality is rarely used and slows down the work of -queues: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-queue-tags.html +This functionality is rarely used and slows down queues. Please see +[this link](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-queue-tags.html). {% endhint %} From 951c603e242d6a3d9cae5698739908cdfa4613e3 Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Sun, 10 Nov 2024 20:55:22 +0100 Subject: [PATCH 03/12] chore: add pub confirms info to the AMQP driver Signed-off-by: Valery Piashchynski --- queues/amqp.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/queues/amqp.md b/queues/amqp.md index de1a620..e4ce5b3 100644 --- a/queues/amqp.md +++ b/queues/amqp.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:guest@127.0.0.1:5672 + addr: amqp://guest:guest@127.0.0.1:5672 # AMQPS TLS configuration # @@ -210,7 +215,7 @@ 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 @@ -257,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` @@ -274,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` From 10c57a06d0eac73866da556d03311b028ca4e75b Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Mon, 11 Nov 2024 13:39:32 +0100 Subject: [PATCH 04/12] chore: update sqs option Signed-off-by: Valery Piashchynski --- SUMMARY.md | 1 + php/rpc.md | 10 +++++----- queues/sqs.md | 2 +- releases/v2024-3-0.md | 15 +++++++++++++++ 4 files changed, 22 insertions(+), 6 deletions(-) create mode 100644 releases/v2024-3-0.md diff --git a/SUMMARY.md b/SUMMARY.md index e57a7d3..f8cb283 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -122,6 +122,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) diff --git a/php/rpc.md b/php/rpc.md index dfdca6d..946ce0f 100644 --- a/php/rpc.md +++ b/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')); } diff --git a/queues/sqs.md b/queues/sqs.md index fdb36c7..3f6e4aa 100644 --- a/queues/sqs.md +++ b/queues/sqs.md @@ -136,7 +136,7 @@ jobs: # Maximum number of messages that can be in-flight at any given time. This is useful to limit the number of messages that are being processed concurrently. # Default: the same value as prefetch - max_messages_in_flight_limit: 10 + max_messages_in_flight: 10 # Optional section. # Default: 0 diff --git a/releases/v2024-3-0.md b/releases/v2024-3-0.md new file mode 100644 index 0000000..0bb6bbf --- /dev/null +++ b/releases/v2024-3-0.md @@ -0,0 +1,15 @@ +# πŸš€ v2024.2.1 πŸš€ + +### `OTEL` plugin: + +- πŸ”₯: Several improvements by @devnev: Do not set `Endpoint` and `Headers` for gRPC if they're empty: [PR](https://github.com/roadrunner-server/otel/pull/62), Support standard `OTEL` exporter protocol environment variables: [PR](https://github.com/roadrunner-server/otel/pull/63). (thanks @devnev) + +### `RoadRunner-Temporal` plugin: +- πŸ›: gRPC client closed too early after shutdown: [BUG](https://github.com/roadrunner-server/roadrunner/issues/1986). (thanks @kkosowski-p) + +### `AMQP` driver: +- πŸ›: `redial_timeout` was not respected when dynamically creating pipeline. [BUG](https://github.com/roadrunner-server/roadrunner/issues/2000), (thanks @algirdasci) + +###
🧹 Chore:
+ +- πŸ§‘β€πŸ­: All plugins were updated to Go 1.23 (including `Velox` Dockerfile). From ccfb465fb175d97336fd289ad5eeec4c46e6faae Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Thu, 14 Nov 2024 17:12:03 +0100 Subject: [PATCH 05/12] chore: update dev mode docs Signed-off-by: Valery Piashchynski --- php/developer.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/php/developer.md b/php/developer.md index 9c2a173..3c942a5 100644 --- a/php/developer.md +++ b/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 From cfd26f23e442fb3fe98533a05c99a9d0bb89e553 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Ren=C3=A9=20S=C3=B8rensen?= Date: Thu, 21 Nov 2024 01:14:34 +0100 Subject: [PATCH 06/12] [#33]: documentation for redis tls support --- kv/redis.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/kv/redis.md b/kv/redis.md index 7a1441c..8e0fa61 100644 --- a/kv/redis.md +++ b/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 From 845a7e066dc3bee6e0176fb69b2be2da742f571b Mon Sep 17 00:00:00 2001 From: shellphy Date: Thu, 21 Nov 2024 16:52:03 +0800 Subject: [PATCH 07/12] [#34]: typo: http acme dir --- http/http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http/http.md b/http/http.md index b01b835..3950966 100644 --- a/http/http.md +++ b/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. From 33fb9f0f2bf8650d50f4eb83efb97b6dd2c51bec Mon Sep 17 00:00:00 2001 From: shellphy Date: Thu, 21 Nov 2024 21:40:49 +0800 Subject: [PATCH 08/12] chore: `Nats` duplicated messages notice --- queues/nats.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/queues/nats.md b/queues/nats.md index 95911e2..5844f18 100644 --- a/queues/nats.md +++ b/queues/nats.md @@ -72,6 +72,10 @@ jobs: `stream` - stream name. +{% hint style="info" %} +To prevent duplicate message consumption, ensure that each pipeline is configured with a unique NATS stream. Using the same stream for multiple pipelines will result in the same message being processed multiple times. +{% endhint %} + ### Deliver new `deliver_new` - the consumer will only start receiving messages that were created after the consumer was created. From 522f0225fb35d0f8e1f869122cd99e717692c1aa Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Wed, 4 Dec 2024 20:29:16 +0100 Subject: [PATCH 09/12] feature: auto-scaling docs Signed-off-by: Valery Piashchynski --- SUMMARY.md | 3 +- php/auto-scaling.md | 55 +++++++++++++++++++++++++++ php/{scaling.md => manual-scaling.md} | 0 3 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 php/auto-scaling.md rename php/{scaling.md => manual-scaling.md} (100%) diff --git a/SUMMARY.md b/SUMMARY.md index f8cb283..19bbefc 100644 --- a/SUMMARY.md +++ b/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 diff --git a/php/auto-scaling.md b/php/auto-scaling.md new file mode 100644 index 0000000..8797883 --- /dev/null +++ b/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. diff --git a/php/scaling.md b/php/manual-scaling.md similarity index 100% rename from php/scaling.md rename to php/manual-scaling.md From bc1b4fe79d281fbdf3bf6fc776cef03f28449ba6 Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Thu, 5 Dec 2024 16:03:48 +0100 Subject: [PATCH 10/12] chore: update release notes Signed-off-by: Valery Piashchynski --- releases/unreleased.md | 4 +++ releases/v2024-3-0.md | 57 ++++++++++++++++++++++++++++++++++++------ 2 files changed, 54 insertions(+), 7 deletions(-) create mode 100644 releases/unreleased.md diff --git a/releases/unreleased.md b/releases/unreleased.md new file mode 100644 index 0000000..8b78d2d --- /dev/null +++ b/releases/unreleased.md @@ -0,0 +1,4 @@ +# πŸš€ vNext πŸš€ + +## πŸŽ‰ New Features + diff --git a/releases/v2024-3-0.md b/releases/v2024-3-0.md index 0bb6bbf..c3db2eb 100644 --- a/releases/v2024-3-0.md +++ b/releases/v2024-3-0.md @@ -1,15 +1,58 @@ -# πŸš€ v2024.2.1 πŸš€ +# πŸš€ v2024.3.0 πŸš€ + +Meet the new RoadRunner release! This time we have a lot of new features, improvements, and bug fixes. Let's dive in! In this realse we have added a new feature called [Auto Workers Scaling](https://docs.roadrunner.dev/docs/php-worker/auto-scaling). This feature allows users to scale their RoadRunner workers automatically, up to 100 additional workers. `SQS` plugin was significantly reworked without major breaking changes, please, read the updated documentation carefully. `RoadRunner-Temporal`plugin now supports API-Keys (which would be added via our SDK-PHP and documentated in it as well). + +### πŸ“¦ Core RoadRunner SDK: +- πŸ”₯: Dynamic Workers Scaling: [FR](https://github.com/roadrunner-server/roadrunner/issues/97), [docs](https://docs.roadrunner.dev/docs/php-worker/auto-scaling) ### `OTEL` plugin: +- πŸ”₯: Detect resources from environment variables when not set in config [PR](https://github.com/roadrunner-server/otel/pull/64/), (thanks @devnev) + +### πŸ“¦ `In-Memory` KV driver: +- πŸ›: Fixed very tricky memory leak, when trying to update the same key with TTL multiple times in a row: [BUG](https://github.com/roadrunner-server/roadrunner/issues/2051), (thanks @segrax) + +### πŸ“¦ `Symfony` integration: +- πŸ”₯: Symfony Runtime (PHP) now supports RoadRunner v2023/2024: [PR](https://github.com/php-runtime/runtime/pull/172), (thanks @msmakouz) + +### πŸ“¦ `Redis` driver: +- πŸ”₯: Add TLS support [PR](https://github.com/roadrunner-server/redis/pull/104), (thanks, @sicet7) + +### πŸ“¦ Temporal: +- πŸ”₯: Support API keys: [PR](https://github.com/temporalio/roadrunner-temporal/pull/575), [docs](https://docs.temporal.io/cloud/api-keys). This feature would be added to our SDK-PHP and documentated (how to use) in it as well. +- πŸ”₯: Support h2c TLS without certs: [PR](https://github.com/temporalio/roadrunner-temporal/pull/579), (thanks @cv65kr) + +### πŸ“¦ `SQS` driver: +- πŸ”₯: Complete rework without major breaks by @nickdnk. Please, read the updated docs carefully: [docs](https://docs.roadrunner.dev/docs/queues-and-jobs/sqs) + +### πŸ“¦ `Nats` driver: +- πŸ›: Properly pass user-defined headers [FR](https://github.com/roadrunner-server/nats/pull/182) + +### πŸ“¦ `Config` plugin: +- πŸ”₯: Config for RPC plugin does not work when included from another file [BUG](https://github.com/roadrunner-server/roadrunner/issues/2017), (thanks @Kaspiman) + +### πŸ“¦ `Server` plugin: +- πŸ”₯: Add new option `server.on_init.exit_on_error` to stop RoadRunner when `on_init` error occured: [FR](https://github.com/roadrunner-server/roadrunner/issues/2075), (thanks @wizardist) + +### πŸ“¦ `RabbitMQ (AMQP)` driver: +- πŸ”₯: Support publish confirmations [FR](https://github.com/roadrunner-server/roadrunner/issues/2014), (thanks @algirdasci) +- πŸ›: [PHP] Fixed option name from redelivery to requeue: [BUG](https://github.com/roadrunner-php/jobs/pull/71), (thanks @msmakouz) + +### πŸ“¦ `Locks` plugin: +- πŸ›: Fixed `forceRelease` method, removed requirement for input ID [BUG](https://github.com/roadrunner-server/roadrunner/issues/2050), (thanks @fugikzl) -- πŸ”₯: Several improvements by @devnev: Do not set `Endpoint` and `Headers` for gRPC if they're empty: [PR](https://github.com/roadrunner-server/otel/pull/62), Support standard `OTEL` exporter protocol environment variables: [PR](https://github.com/roadrunner-server/otel/pull/63). (thanks @devnev) +### πŸ“¦ `Metrics` plugin: +- πŸ”₯: Declare metrics in upsert mode: [CHORE](https://github.com/roadrunner-server/metrics/pull/113), (thanks @cv65kr) -### `RoadRunner-Temporal` plugin: -- πŸ›: gRPC client closed too early after shutdown: [BUG](https://github.com/roadrunner-server/roadrunner/issues/1986). (thanks @kkosowski-p) +### πŸ“¦ `Velox`: +- πŸ›: Fixed base64 logs output: [BUG](https://github.com/roadrunner-server/roadrunner/issues/2028), (thanks @rauanmayemir) -### `AMQP` driver: -- πŸ›: `redial_timeout` was not respected when dynamically creating pipeline. [BUG](https://github.com/roadrunner-server/roadrunner/issues/2000), (thanks @algirdasci) +### Thanks to out contributors: +- @nickdnk - for the help with the `SQS` driver and reworking the whole JSON schema across all plugins (which is actually HUGE). +- @msmakouz - for working on the PHP RoadRunner SDK. +- @cv65kr - for the help with the `Metrics` and `RoadRunner-Temporal` plugins. +- @sicet7 - TLS support in the `Redis` plugin. +- @Kaspiman, @wizardist, @rauanmayemir, @algirdasci and @fugikzl - for being proactive, reporting issues and being collaborative. ###
🧹 Chore:
-- πŸ§‘β€πŸ­: All plugins were updated to Go 1.23 (including `Velox` Dockerfile). +- πŸ§‘β€πŸ­: All plugins dependences were updated to the latest versions. From fdcee28a076b99202040a3ab489d76a96538d635 Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Thu, 5 Dec 2024 16:08:15 +0100 Subject: [PATCH 11/12] chore: status plugin Signed-off-by: Valery Piashchynski --- releases/v2024-3-0.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/releases/v2024-3-0.md b/releases/v2024-3-0.md index c3db2eb..fb030d3 100644 --- a/releases/v2024-3-0.md +++ b/releases/v2024-3-0.md @@ -11,6 +11,9 @@ Meet the new RoadRunner release! This time we have a lot of new features, improv ### πŸ“¦ `In-Memory` KV driver: - πŸ›: Fixed very tricky memory leak, when trying to update the same key with TTL multiple times in a row: [BUG](https://github.com/roadrunner-server/roadrunner/issues/2051), (thanks @segrax) +### πŸ“¦ `Status` plugin: +- πŸ”₯: JSON status reporting, remove strict requirement for providing list of plugins: [FR](https://github.com/roadrunner-server/roadrunner/issues/1998), (thanks @Kaspiman) + ### πŸ“¦ `Symfony` integration: - πŸ”₯: Symfony Runtime (PHP) now supports RoadRunner v2023/2024: [PR](https://github.com/php-runtime/runtime/pull/172), (thanks @msmakouz) From 37cf7f8966299c3585a03162f434ae42e18b28b2 Mon Sep 17 00:00:00 2001 From: Valery Piashchynski Date: Thu, 5 Dec 2024 17:18:06 +0100 Subject: [PATCH 12/12] chore: remove not needed docs section Signed-off-by: Valery Piashchynski --- releases/v2024-3-0.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/releases/v2024-3-0.md b/releases/v2024-3-0.md index fb030d3..fab1dad 100644 --- a/releases/v2024-3-0.md +++ b/releases/v2024-3-0.md @@ -56,6 +56,3 @@ Meet the new RoadRunner release! This time we have a lot of new features, improv - @sicet7 - TLS support in the `Redis` plugin. - @Kaspiman, @wizardist, @rauanmayemir, @algirdasci and @fugikzl - for being proactive, reporting issues and being collaborative. -###
🧹 Chore:
- -- πŸ§‘β€πŸ­: All plugins dependences were updated to the latest versions.