From 7170a8e6f7ae30ac86c8574fe56144c57b51d719 Mon Sep 17 00:00:00 2001 From: FenjuFu <92919259+FenjuFu@users.noreply.github.com> Date: Tue, 18 Aug 2026 20:28:48 -0700 Subject: [PATCH] docs: document the Cloudflare Queues input binding Covers receiving messages through an HTTP pull consumer, the API token permissions it needs, the new queueID, batchSize, visibilityTimeout, and pollingInterval metadata properties, and the per-message metadata. Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com> --- .../supported-bindings/cloudflare-queues.md | 53 ++++++++++++++++--- 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/cloudflare-queues.md b/daprdocs/content/en/reference/components-reference/supported-bindings/cloudflare-queues.md index 8a3458677b1..b595cd6458f 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/cloudflare-queues.md +++ b/daprdocs/content/en/reference/components-reference/supported-bindings/cloudflare-queues.md @@ -10,7 +10,7 @@ aliases: ## Component format -This output binding for Dapr allows interacting with [Cloudflare Queues](https://developers.cloudflare.com/queues/) to **publish** new messages. It is currently not possible to consume messages from a Queue using Dapr. +This binding for Dapr allows interacting with [Cloudflare Queues](https://developers.cloudflare.com/queues/) to **publish** new messages, and to **consume** messages from a Queue with an [HTTP pull consumer](https://developers.cloudflare.com/queues/configuration/pull-consumers/). To setup a Cloudflare Queues binding, create a component of type `bindings.cloudflare.queues`. See [this guide]({{% ref "howto-bindings.md#1-create-a-binding" %}}) on how to create and apply a binding configuration. @@ -46,6 +46,19 @@ spec: # URL of the Worker (required if the Worker has been pre-created outside of Dapr) - name: workerUrl value: "" + # ID of the Queue (optional, input binding only) + # When empty, Dapr looks the Queue up by name + - name: queueID + value: "" + # Maximum number of messages to receive with each pull (optional, input binding only) + - name: batchSize + value: "5" + # How long the received messages stay invisible to other consumers (optional, input binding only) + - name: visibilityTimeout + value: "30s" + # How long to wait before pulling again after the Queue came back empty (optional, input binding only) + - name: pollingInterval + value: "10s" ``` {{% alert title="Warning" color="warning" %}} @@ -56,22 +69,50 @@ The above example uses secrets as plain strings. It is recommended to use a secr | Field | Required | Binding support | Details | Example | |--------------------|:--------:|-------|--------|---------| -| `queueName` | Y | Output | Name of the existing Cloudflare Queue | `"mydaprqueue"` -| `key` | Y | Output | Ed25519 private key, PEM-encoded | *See example above* -| `cfAccountID` | Y/N | Output | Cloudflare account ID. Required to have Dapr manage the worker. | `"456789abcdef8b5588f3d134f74ac"def` -| `cfAPIToken` | Y/N | Output | API token for Cloudflare. Required to have Dapr manage the Worker. | `"secret-key"` -| `workerUrl` | Y/N | Output | URL of the Worker. Required if the Worker has been pre-provisioned outside of Dapr. | `"https://mydaprqueue.mydomain.workers.dev"` +| `queueName` | Y | Input/Output | Name of the existing Cloudflare Queue | `"mydaprqueue"` +| `key` | Y | Input/Output | Ed25519 private key, PEM-encoded | *See example above* +| `cfAccountID` | Y/N | Input/Output | Cloudflare account ID. Required to have Dapr manage the worker, and required for the input binding. | `"456789abcdef8b5588f3d134f74ac"def` +| `cfAPIToken` | Y/N | Input/Output | API token for Cloudflare. Required to have Dapr manage the Worker, and required for the input binding. | `"secret-key"` +| `workerUrl` | Y/N | Input/Output | URL of the Worker. Required if the Worker has been pre-provisioned outside of Dapr. | `"https://mydaprqueue.mydomain.workers.dev"` +| `queueID` | N | Input | ID of the Cloudflare Queue to receive messages from. When empty, Dapr looks the ID up by name, which requires the API token to have the `queues#read` permission. | `"8ceb4b1b5b6f4f8fa54b8b0dd7c4a6d9"` +| `batchSize` | N | Input | Maximum number of messages to receive with each pull, between `1` and `100`. Default: `5` | `10` +| `visibilityTimeout` | N | Input | How long the received messages stay invisible to other consumers, between `1s` and `12h`. It must be longer than the time your application needs to process a full batch, otherwise the messages are delivered again. Default: `30s` | `"1m"` +| `pollingInterval` | N | Input | How long Dapr waits before pulling again after the Queue came back empty. Default: `10s` | `"5s"` > When you configure Dapr to create your Worker for you, you may need to set a longer value for the `initTimeout` property of the component, to allow enough time for the Worker script to be deployed. For example: `initTimeout: "120s"` ## Binding support +This component supports both **input and output** binding interfaces. + This component supports **output binding** with the following operations: - `publish` (alias: `create`): Publish a message to the Queue. The data passed to the binding is used as-is for the body of the message published to the Queue. This operation does not accept any metadata property. +### Input binding + +The input binding receives messages with a Cloudflare [HTTP pull consumer](https://developers.cloudflare.com/queues/configuration/pull-consumers/), which is served by the Cloudflare API rather than by the Worker. As a consequence: + +- The input binding requires `cfAccountID` and `cfAPIToken` to be set; the API token must have both the `queues#read` and `queues#write` permissions. A component configured with `workerUrl` only cannot be used as an input binding. +- The Queue must have an HTTP pull consumer enabled, which you can add with the Wrangler CLI: + + ```sh + npx wrangler queues consumer http add + # For example: `npx wrangler queues consumer http add myqueue` + ``` + +Dapr pulls up to `batchSize` messages at a time and invokes your application once per message. Messages your application acknowledges (by returning a success response) are deleted from the Queue, while messages it rejects are made available again immediately for another delivery attempt. Delivery is at-least-once: if Dapr stops before a message is acknowledged, the message becomes visible again once its `visibilityTimeout` expires, and your application receives it another time. + +The body of the message is passed to your application as-is. Each message also includes these metadata properties: + +| Metadata | Description | +|----------|-------------| +| `id` | ID of the message in the Queue | +| `attempts` | Number of times the message has been delivered, starting from `1` | +| `timestamp` | Time the message was published, as a Unix timestamp in milliseconds | + ## Create a Cloudflare Queue To use this component, you must have a Cloudflare Queue created in your Cloudflare account.