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 %}