diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4f77e585519a55..6f660f11372989 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -114,7 +114,7 @@ /src/content/release-notes/kv.yaml @elithrar @thomasgauvin @rts-rob @oxyjun @cloudflare/pcx-technical-writing /src/content/partials/kv/ @elithrar @thomasgauvin @rts-rob @oxyjun @cloudflare/pcx-technical-writing /src/content/docs/pub-sub/ @elithrar @dcpena @cloudflare/pcx-technical-writing -/src/content/docs/queues/ @elithrar @maheshwarip @harshil1712 @cloudflare/pcx-technical-writing +/src/content/docs/queues/ @elithrar @jonesphillip @harshil1712 @cloudflare/pcx-technical-writing /src/content/release-notes/queues.yaml @elithrar @maheshwarip @cloudflare/pcx-technical-writing /src/content/docs/r2/ @oxyjun @elithrar @jonesphillip @aninibread @harshil1712 @cloudflare/workers-docs @cloudflare/pcx-technical-writing /src/content/release-notes/r2.yaml @oxyjun @elithrar @aninibread @cloudflare/workers-docs @cloudflare/pcx-technical-writing diff --git a/src/content/docs/queues/examples/publish-to-a-queue-over-http.mdx b/src/content/docs/queues/examples/publish-to-a-queue-over-http.mdx deleted file mode 100644 index f556b45af7600a..00000000000000 --- a/src/content/docs/queues/examples/publish-to-a-queue-over-http.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Publish to a Queue via HTTP -summary: Publish to a Queue directly via HTTP and Workers. -pcx_content_type: example -sidebar: - order: 30 -head: - - tag: title - content: Queues - Publish Directly via HTTP -description: Publish to a Queue directly via HTTP and Workers. ---- - -import { WranglerConfig } from "~/components"; - -The following example shows you how to publish messages to a queue from any HTTP client, using a shared secret to securely authenticate the client. - -This allows you to write to a Queue from any service or programming language that support HTTP, including Go, Rust, Python or even a Bash script. - -### Prerequisites - -- A [queue created](/queues/get-started/#3-create-a-queue) via the [Cloudflare dashboard](https://dash.cloudflare.com) or the [wrangler CLI](/workers/wrangler/install-and-update/). -- A [configured **producer** binding](/queues/configuration/configure-queues/#producer-worker-configuration) in the Cloudflare dashboard or Wrangler file. - -Configure your Wrangler file as follows: - - - -```toml -name = "my-worker" - -[[queues.producers]] - queue = "my-queue" - binding = "YOUR_QUEUE" - -``` - - - -### 1. Create a shared secret - -Before you deploy the Worker, you need to create a [secret](/workers/configuration/secrets/) that you can use as a shared secret. A shared secret is a secret that both the client uses to authenticate and the server (your Worker) matches against for authentication. - -:::caution - -Do not commit secrets to source control. You should use [`wrangler secret`](/workers/configuration/secrets/) to store API keys and authentication tokens securely. - -::: - -To generate a cryptographically secure secret, you can use the `openssl` command-line tool and `wrangler secret` to create a hex-encoded string that can be used as the shared secret: - -```sh -openssl rand -hex 32 -# This will output a 65 character long hex string -``` - -Copy this string and paste it into the prompt for `wrangler secret`: - -```sh -npx wrangler secret put QUEUE_AUTH_SECRET -``` - -```sh output -✨ Success! Uploaded secret QUEUE_AUTH_SECRET -``` - -This secret will also need to be used by the client application writing to the queue: ensure you store it securely. - -### 2. Create the Worker - -The following Worker script: - -1. Authenticates the client using a shared secret. -2. Validates that the payload uses JSON. -3. Publishes the payload to the queue. - -```ts -interface Env { - YOUR_QUEUE: Queue; - QUEUE_AUTH_SECRET: string; -} - -export default { - async fetch(req, env): Promise { - // Authenticate that the client has the correct auth key - if (env.QUEUE_AUTH_SECRET == "") { - return Response.json( - { err: "application not configured" }, - { status: 500 }, - ); - } - - // Return a HTTP 403 (Forbidden) if the auth key is invalid/incorrect/misconfigured - let authToken = req.headers.get("Authorization") || ""; - let encoder = new TextEncoder(); - // Securely compare our secret with the auth token provided by the client - try { - if ( - !crypto.subtle.timingSafeEqual( - encoder.encode(env.QUEUE_AUTH_SECRET), - encoder.encode(authToken), - ) - ) { - return Response.json( - { err: "invalid auth token provided" }, - { status: 403 }, - ); - } - } catch (e) { - return Response.json( - { err: "invalid auth token provided" }, - { status: 403 }, - ); - } - - // Optional: Validate the payload is JSON - // In a production application, we may more robustly validate the payload - // against a schema using a library like 'zod' - let messages; - try { - messages = await req.json(); - } catch (e) { - // Return a HTTP 400 (Bad Request) if the payload isn't JSON - return Response.json({ err: "payload not valid JSON" }, { status: 500 }); - } - - // Publish to the Queue - try { - await env.YOUR_QUEUE.send(messages); - } catch (e: any) { - console.log(`failed to send to the queue: ${e}`); - // Return a HTTP 500 (Internal Error) if our publish operation fails - return Response.json({ error: e.message }, { status: 500 }); - } - - // Return a HTTP 200 if the send succeeded! - return Response.json({ success: true }); - }, -} satisfies ExportedHandler; -``` - -To deploy this Worker: - -```sh -npx wrangler deploy -``` - -### 3. Send a test message - -To make sure you successfully authenticate and write a message to your queue, use `curl` on the command line: - -```sh -# Make sure to replace the placeholder with your shared secret -curl -H "Authorization: pasteyourkeyhere" "https://YOUR_WORKER.YOUR_ACCOUNT.workers.dev" --data '{"messages": [{"msg":"hello world"}]}' -``` - -```sh output -{"success":true} -``` - -This will issue a HTTP POST request, and if successful, return a HTTP 200 with a `success: true` response body. - -- If you receive a HTTP 403, this is because the `Authorization` header is invalid, or you did not configure a secret. -- If you receive a HTTP 500, this is either because you did not correctly create a shared secret to your Worker, or you attempted to send an invalid message to your queue. - -You can use [`wrangler tail`](/workers/observability/logs/real-time-logs/) to debug the output of `console.log`. diff --git a/src/content/docs/queues/examples/publish-to-a-queue-via-http.mdx b/src/content/docs/queues/examples/publish-to-a-queue-via-http.mdx new file mode 100644 index 00000000000000..ecd82d42ff9a11 --- /dev/null +++ b/src/content/docs/queues/examples/publish-to-a-queue-via-http.mdx @@ -0,0 +1,40 @@ +--- +title: Publish to a Queue via HTTP +summary: Publish to a Queue directly via HTTP. +pcx_content_type: example +sidebar: + order: 31 +head: + - tag: title + content: Queues - Publish Directly via HTTP +description: Publish to a Queue directly via HTTP and Workers. +--- + +The following example shows you how to publish messages to a Queue from any HTTP client, using a Cloudflare API token to authenticate. + +This allows you to write to a Queue from any service or programming language that supports HTTP, including Go, Rust, Python or even a Bash script. + +### Prerequisites + +- A [queue created](/queues/get-started/#3-create-a-queue) via the [Cloudflare dashboard](https://dash.cloudflare.com) or the [wrangler CLI](/workers/wrangler/install-and-update/). +- A Cloudflare API token with the `Queues Edit` permission. + + +### 1. Send a test message + +To make sure you successfully authenticate and write a message to your queue, use `curl` on the command line: + +```sh +# Make sure to replace the placeholder with your shared secret +curl -XPOST -H "Authorization: Bearer " "https://api.cloudflare.com/client/v4/accounts//queues//messages" --data '{ "body": { "greeting": "hello" } }' +``` + +```sh output +{"success":true} +``` + +This will issue a HTTP POST request, and if successful, return a HTTP 200 with a `success: true` response body. + +- If you receive a HTTP 403, this is because your API token is invalid or does not have the `Queues Edit` permission. + +For full documentation about the HTTP Push API, refer to the [Cloudflare API documentation](https://developers.cloudflare.com/api/resources/queues/subresources/messages/). \ No newline at end of file diff --git a/src/content/docs/queues/examples/publish-to-a-queue-via-workers.mdx b/src/content/docs/queues/examples/publish-to-a-queue-via-workers.mdx new file mode 100644 index 00000000000000..990aae0dbe671c --- /dev/null +++ b/src/content/docs/queues/examples/publish-to-a-queue-via-workers.mdx @@ -0,0 +1,101 @@ +--- +title: Publish to a Queue via Workers +summary: Publish to a Queue directly from your Worker. +pcx_content_type: example +sidebar: + order: 30 +head: + - tag: title + content: Queues - Publish Directly via a Worker +description: Publish to a Queue directly from your Worker. +--- + +import { WranglerConfig } from "~/components"; + +The following example shows you how to publish messages to a Queue from a Worker. The example uses a Worker that receives a JSON payload from the request body and writes it as-is to the Queue, but in a real application you might have more logic before you queue a message. + +### Prerequisites + +- A [queue created](/queues/get-started/#3-create-a-queue) via the [Cloudflare dashboard](https://dash.cloudflare.com) or the [wrangler CLI](/workers/wrangler/install-and-update/). +- A [configured **producer** binding](/queues/configuration/configure-queues/#producer-worker-configuration) in the Cloudflare dashboard or Wrangler file. + +Configure your Wrangler file as follows: + + + +```toml +name = "my-worker" + +[[queues.producers]] + queue = "my-queue" + binding = "YOUR_QUEUE" + +``` + + + +### 1. Create the Worker + +The following Worker script: + +1. Validates that the request body is valid JSON. +2. Publishes the payload to the queue. + +```ts +interface Env { + YOUR_QUEUE: Queue; +} + +export default { + async fetch(req, env): Promise { + // Validate the payload is JSON + // In a production application, we may more robustly validate the payload + // against a schema using a library like 'zod' + let messages; + try { + messages = await req.json(); + } catch (e) { + // Return a HTTP 400 (Bad Request) if the payload isn't JSON + return Response.json({ err: "payload not valid JSON" }, { status: 400 }); + } + + // Publish to the Queue + try { + await env.YOUR_QUEUE.send(messages); + } catch (e: any) { + console.log(`failed to send to the queue: ${e}`); + // Return a HTTP 500 (Internal Error) if our publish operation fails + return Response.json({ error: e.message }, { status: 500 }); + } + + // Return a HTTP 200 if the send succeeded! + return Response.json({ success: true }); + }, +} satisfies ExportedHandler; +``` + +To deploy this Worker: + +```sh +npx wrangler deploy +``` + +### 2. Send a test message + +To make sure you successfully write a message to your queue, use `curl` on the command line: + +```sh +# Make sure to replace the placeholder with your shared secret +curl -XPOST "https://YOUR_WORKER.YOUR_ACCOUNT.workers.dev" --data '{"messages": [{"msg":"hello world"}]}' +``` + +```sh output +{"success":true} +``` + +This will issue a HTTP POST request, and if successful, return a HTTP 200 with a `success: true` response body. + +- If you receive a HTTP 400, this is because you attempted to send malformed JSON to your queue. +- If you receive a HTTP 500, this is because the message was not written to your Queue successfully. + +You can use [`wrangler tail`](/workers/observability/logs/real-time-logs/) to debug the output of `console.log`. \ No newline at end of file diff --git a/src/content/release-notes/queues.yaml b/src/content/release-notes/queues.yaml index d066e4fbf5e33d..66afb947014900 100644 --- a/src/content/release-notes/queues.yaml +++ b/src/content/release-notes/queues.yaml @@ -5,6 +5,12 @@ productLink: "/queues/" productArea: Developer platform productAreaLink: /workers/platform/changelog/platform/ entries: + - publish_date: "2025-05-09" + title: HTTP Push for Queues + description: |- + You can now write messages to your Queues from any client that can speak HTTP, without having to use a Worker. This means all your Go, Rust, Python or Bash applications can now benefit from a globally distributed queueing system and no egress charges. + + Reading from a Queue via an HTTP client is also possible. Refer to the [documentation on pull consumers](/queues/configuration/pull-consumers/) to learn how to setup a pull consumer, acknowledge / retry messages, and setup multiple consumers. - publish_date: "2025-04-17" title: Improved limits for pull consumers description: |- diff --git a/src/util/api.ts b/src/util/api.ts index c5973f12e21efa..a54691b813658a 100644 --- a/src/util/api.ts +++ b/src/util/api.ts @@ -1,7 +1,7 @@ import SwaggerParser from "@apidevtools/swagger-parser"; import type { OpenAPI } from "openapi-types"; -const COMMIT = "8eb3957331e18523cca24d1f4ef388197defb6bc"; +const COMMIT = "4faf1588f42fb8a60eebd8fdd154b2949c614af4"; let schema: OpenAPI.Document | undefined; export const getSchema = async () => {