Merge branch 'silverlock/workflows/new' of github.com:cloudflare/cloudflare-docs into silverlock/workflows/new

Author: celso

src/content/changelogs/workflows.yaml

@@ -8,7 +8,7 @@ entries:
   - publish_date: "2038-01-19"
     title: Workflows is now in public beta.
     description: |-
-      Workflows, a new product for building reliable, multi-step workflows using Cloudflare Workers, is now in public beta. The public beta is avaiable to any user with a [free or paid Workers plan](/workers/platform/pricing/).
+      Workflows, a new product for building reliable, multi-step workflows using Cloudflare Workers, is now in public beta. The public beta is available to any user with a [free or paid Workers plan](/workers/platform/pricing/).
 
       A Workflow allows you to define multiple, independent steps that encapsulate errors, automatically retry, persist state, and can run for seconds, minutes, hours or even days. A Workflow can be useful for post-processing data from R2 buckets before querying it, automating a [Workers AI RAG pipeline](/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/), or managing user signup flows and lifecycle emails.
 

src/content/docs/workers/runtime-apis/bindings/workflows.mdx

@@ -1,6 +1,6 @@
 ---
 pcx_content_type: navigation
-title: Vectorize
+title: Workflows
 external_link: /workflows/
 head: []
 description: APIs available in Cloudflare Workers to interact with

src/content/docs/workers/wrangler/commands.mdx

@@ -1258,9 +1258,9 @@ wrangler workflows list
 ```
 
 - `--page` <Type text="number" /> <MetaInfo text="optional" />
-  -  Show a sepecific page from the listing, can configure page size using "per-page"
+  -  Show a specific page from the listing. You can configure page size using "per-page".
 - `--per-page` <Type text="number" /> <MetaInfo text="optional" />
-  - Configure the maximum number of workflows to show per page.
+  - Configure the maximum number of Workflows to show per page.
 
 ### `instances`
 

src/content/docs/workflows/build/dynamic-steps.mdx

@@ -8,12 +8,12 @@ sidebar:
 
 A Workflow does not have to define all of its steps statically: steps can be created programmatically and/or conditionally.
 
-This allows you to not only trigger steps based on specific input parameters, but to also name steps dynamically, set the retry configuration for a step 
+This allows you to not only trigger steps based on specific input parameters, but to also name steps dynamically and set the retry configuration for a single step. 
 
 
 ## Example
 
-Steps can be created on-the-fly, allowing you create a step for each parameter passed to your Workflow, for each file you want to read from storage, or for calls to third-party APIs.
+You can create steps on-the-fly. You can create a step for each parameter passed to your Workflow, for each file you want to read from storage, or for calls to third-party APIs.
 
 For example, you can loop over each event, label the step dynamically, and have the step operate only over that `event`:
 

src/content/docs/workflows/build/events-and-parameters.mdx

@@ -10,11 +10,11 @@ When a Workflow is triggered, it can receive an optional event. This event can i
 
 Events are a powerful part of a Workflow, as you often want a Workflow to act on data. Because a given Workflow instance executes durably, events are a useful way to provide a Workflow with data that should be immutable (not changing) and/or represents data the Workflow needs to operate on at that point in time.
 
-## Passing parameters to a Workflow
+## Pass parameters to a Workflow
 
 You can pass parameters to a Workflow in two ways:
 
-* As an optional argument to the `create` method on a [Workflow binding] when triggering a Workflow from a Worker.
+* As an optional argument to the `create` method on a [Workflow binding](/workers/wrangler/commands/#trigger) when triggering a Workflow from a Worker.
 * Via the `--params` flag when using the `wrangler` CLI to trigger a Workflow.
 
 You can pass any JSON-serializable object as a parameter.
@@ -80,7 +80,7 @@ interface YourEventType {
 }
 ```
 
-When we pass our `YourEventType` to `WorkflowEvent` as a type parameter, the `event.payload` property now has the type `YourEventType` throughout our workflow definition:
+When you pass your `YourEventType` to `WorkflowEvent` as a type parameter, the `event.payload` property now has the type `YourEventType` throughout your workflow definition:
 
 ```ts title="src/index.ts"
 // Import the Workflow definition

src/content/docs/workflows/build/index.mdx

@@ -3,6 +3,8 @@ title: Build with Workflows
 pcx_content_type: navigation
 sidebar:
   order: 2
+  group:
+    hideIndex: true
 
 ---
 

src/content/docs/workflows/build/rules-of-workflows.mdx

@@ -5,16 +5,16 @@ sidebar:
   order: 10
 ---
 
-A Workflow contains one or more steps. Each step is a self-contained, individually retriable component of a Workflow. Steps may emit (optional) state that allows a Workflow to persist and continue from that step, even if a Workflow fails due to a network or infrastructure issue. A Workflow is comprised of one or more steps.
+A Workflow contains one or more steps. Each step is a self-contained, individually retriable component of a Workflow. Steps may emit (optional) state that allows a Workflow to persist and continue from that step, even if a Workflow fails due to a network or infrastructure issue.
 
 This is a small guidebook on how to build more resilient and correct Workflows.
 
 ### Ensure API/Binding calls are idempotent
 
 Because a step might be retried multiple times, your steps should (ideally) be idempotent. For context, idempotency is a logical property where the operation (in this case a step),
-can be applied multiple times without changing the result beyond the intial application.
+can be applied multiple times without changing the result beyond the initial application.
 
-As an example, let's assume you have a Workflow that charges your customers and you really don't want to charge them twice by accident, before charging them, you should
+As an example, let us assume you have a Workflow that charges your customers, and you really do not want to charge them twice by accident. Before charging them, you should
 check if they were already charged:
 
 ```ts
@@ -55,13 +55,13 @@ export class MyWorkflow extends WorkflowEntrypoint {
 
 :::note
 
-Guaranteeing idempotency might be optional in your specific use-case and implementation, although we recommend it to always try to guarantee it.
+Guaranteeing idempotency might be optional in your specific use-case and implementation, but we recommend that you always try to guarantee it.
 
 :::
 
 ### Make your steps granular
 
-Steps should be as self-contained as possible, this allows your own logic to be more durable in case of failures in third-party APIs, network errors, and so on.
+Steps should be as self-contained as possible. This allows your own logic to be more durable in case of failures in third-party APIs, network errors, and so on.
 
 You can also think of it as a transaction, or a unit of work.
 
@@ -85,12 +85,12 @@ export class MyWorkflow extends WorkflowEntrypoint {
 }
 ```
 
-Otherwise your entire workflow might not be as durable as you might think, and encounter into some undefined behaviour and you can avoid them by:
+Otherwise, your entire Workflow might not be as durable as you might think, and you may encounter some undefined behaviour. You can avoid them by following the rules below:
 
 - 🔴 Do not encapsulate your entire logic in one single step.
-- 🔴 Do not call seperate services in the same step (unless you need it to prove idempotency)
-- 🔴 Do not make too many service calls in the same step (unless you need it to prove idempotency)
-- 🔴 Do not do too much CPU-intensive work inside of a single step - sometimes engine might have to restart and it will start over from that step.
+- 🔴 Do not call separate services in the same step (unless you need it to prove idempotency).
+- 🔴 Do not make too many service calls in the same step (unless you need it to prove idempotency).
+- 🔴 Do not do too much CPU-intensive work inside a single step - sometimes the engine may have to restart, and it will start over from the beginning of that step.
 
 ```ts
 export class MyWorkflow extends WorkflowEntrypoint {
@@ -106,9 +106,9 @@ export class MyWorkflow extends WorkflowEntrypoint {
 }
 ```
 
-### Don't rely on state outside of a step
+### Do not rely on state outside of a step
 
-Workflows may hibernate and lose all in-memory state. This will happen when engine detects that there's no pending work and can hibernate until it needs to wake-up (because of a sleep, retry or event).
+Workflows may hibernate and lose all in-memory state. This will happen when engine detects that there is no pending work and can hibernate until it needs to wake-up (because of a sleep, retry, or event).
 
 This means that you should not store state outside of a step:
 
@@ -193,14 +193,34 @@ export class MyWorkflow extends WorkflowEntrypoint {
 }
 ```
 
-### Set sensible retry parameters
+### Do not mutate your incoming events
 
-TODO
+The `event` passed to your Workflow's `run` method is immutable: changes you make to the event are not persisted across steps and/or Workflow restarts.
 
-### Name your steps clearly
-
-TODO
-
-### Don't mutate your incoming events
+```ts
+interface MyEvent {
+  user: string;
+  data: string;
+}
 
-TODO
+export class MyWorkflow extends WorkflowEntrypoint {
+	async run(event: WorkflowEvent<MyEvent>, step: WorkflowStep) {
+		// 🔴 Bad: Mutating the event
+		// This will not be persisted across steps and `event.data` will
+		// take on its original value.
+		await step.do("bad step that mutates the incoming event", async () => {
+		    let userData = await env.KV.get(event.user)
+				event.data = userData
+		})
+
+		// ✅ Good: persist data by returning it as state from your step
+		// Use that state in subsequent steps
+		let userData = await step.do("good step that returns state", async () => {
+		  return await env.KV.get(event.user)
+		})
+
+		let someOtherData await step.do("following step that uses that state", async () => {
+		  // Access to userData here
+			// Will always be the same if this step is retried
+		})
+```

src/content/docs/workflows/build/sleeping-and-retrying.mdx

@@ -6,20 +6,49 @@ sidebar:
 
 ---
 
-TODO
+This guide details how to sleep a Workflow and/or configure retries for a Workflow step.
 
-## Sleeping
+## Sleep a Workflow
 
-TODO
+You can set a Workflow to sleep as an explicit step, which can be useful when you want a Workflow to wait, schedule work ahead, or pause until an input or other external state is ready.
 
 :::note
 
 A Workflow instance that is resuming from sleep will take priority over newly scheduled (queued) instances. This helps ensure that older Workflow instances can run to completion and are not blocked by newer instances.
 
 :::
 
+### Sleep for a relative period
 
-## Retrying steps
+Use `step.sleep` to have a Workflow sleep for a relative period of time:
+
+```ts
+await step.sleep("sleep for a bit", "1 hour")
+```
+
+The second argument to `step.sleep` accepts both `number` (seconds) or a human-readable format, such as "1 minute" or "26 hours". The accepted units for `step.sleep` when used this way are as follows:
+
+```ts
+| "second"
+| "minute"
+| "hour"
+| "day"
+| "week"
+| "month"
+| "year"
+```
+
+### Sleep until a fixed date
+
+Use `step.sleepUntil` to have a Workflow sleep to a specific `Date`: this can be useful when you have a timestamp from another system or want to "schedule" work to occur at a specific time (e.g. Sunday, 9AM UTC).
+
+```ts
+// sleepUntil accepts a Date object as its second argument
+const workflowsLaunchDate = Date.parse("24 Oct 2024 13:00:00 UTC");
+await step.sleepUntil("sleep until X times out", workflowsLaunchDate)
+```
+
+## Retry steps
 
 Each call to `step.do` in a Workflow accepts an optional `StepConfig`, which allows you define the retry behaviour for that step.
 
@@ -41,7 +70,7 @@ When providing your own `StepConfig`, you can configure:
 * The total number of attempts to make for a step
 * The delay between attempts
 * What backoff algorithm to apply between each attempt: any of `constant`, `linear`, or `exponential`
-* When to timeout (in duration) before considering the step as failed (including during a retry attempt).
+* When to timeout (in duration) before considering the step as failed (including during a retry attempt)
 
 For example, to limit a step to 10 retries and have it apply an exponential delay (starting at 10 seconds) between each attempt, you would pass the following configuration as an optional object to `step.do`:
 
@@ -55,3 +84,27 @@ let someState = step.do("call an API", {
   timeout: "30 minutes",
 }, async () => { /* Step code goes here /* }
 ```
+
+## Force a Workflow to fail
+
+You can also force a Workflow instance to fail and _not_ retry by throwing a `NonRetryableError` from within the step.
+
+This can be useful when you detect a terminal (permanent) error from an upstream system (such as an authentication failure) or other errors where retrying would not help.
+
+```ts
+// Import the NonRetryableError definition
+import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent, NonRetryableError } from 'cloudflare:workers';
+
+// In your step code:
+export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
+	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+	  await step.do("some step", async () => {
+			  if !(event.data) {
+					throw NonRetryableError("event.data did not contain the expected payload")
+				}
+			})
+	}
+}
+```
+
+The Workflow instance itself will fail immediately, no further steps will be invoked, and the Workflow will not be retried.

src/content/docs/workflows/build/trigger-workflows.mdx

@@ -6,7 +6,11 @@ sidebar:
 
 ---
 
-TODO - intro
+You can trigger Workflows both programmatically and via the Workflows APIs, including:
+
+1. With [Workers](/workers) via HTTP requests in a `fetch` handler, or bindings from a `queue` or `scheduled` handler
+2. Using the [Workflows REST API](/api/paths/accounts-account_id--workflows/get)
+2. Via the [wrangler CLI](/workers/wrangler/commands/#workflows) in your terminal
 
 ## Workers API (Bindings)
 
@@ -17,7 +21,7 @@ You can interact with a Workflow:
 * Directly over HTTP via the [`fetch`](/workers/runtime-apis/handlers/fetch/) handler
 * From a [Queue consumer](/queues/configuration/javascript-apis/#consumer) inside a `queue` handler
 * From a [Cron Trigger](/workers/configuration/cron-triggers/) inside a `scheduled` handler
-* Within a [Durable Object](/durable-objects/).
+* Within a [Durable Object](/durable-objects/)
 
 :::note
 
@@ -52,7 +56,7 @@ The following example shows how you can manage Workflows from within a Worker, i
 
 * Retrieving the status of an existing Workflow instance by its ID
 * Creating (triggering) a new Workflow instance
-* Returning the status of a given instance ID.
+* Returning the status of a given instance ID
 
 ```ts title="src/index.ts"
 interface Env {
@@ -89,7 +93,7 @@ export default {
 
 ### Inspect a Workflow's status
 
-You can inspect the status of any running Workflow instance by calling `status` against a specific instance ID. This allows you to programmatically inspect whether an instance is queued (waiting to be scheduled), actively running, paused or errored.
+You can inspect the status of any running Workflow instance by calling `status` against a specific instance ID. This allows you to programmatically inspect whether an instance is queued (waiting to be scheduled), actively running, paused, or errored.
 
 ```ts
 let instance = await env.MY_WORKFLOW.get("abc-123")
@@ -114,7 +118,7 @@ The possible values of status are as follows:
 };
 ```
 
-### Explicitly pausing a Workflow
+### Explicitly pause a Workflow
 
 You can explicitly pause a Workflow instance (and later resume it) by calling `pause` against a specific instance ID.
 
@@ -123,7 +127,7 @@ let instance = await env.MY_WORKFLOW.get("abc-123")
 await instance.pause() // Returns Promise<void>
 ```
 
-### Resuming a Workflow
+### Resume a Workflow
 
 You can resume a paused Workflow instance by calling `resume` against a specific instance ID.
 
@@ -134,7 +138,7 @@ await instance.resume() // Returns Promise<void>
 
 Calling `resume` on an instance that is not currently paused will have no effect.
 
-### Stopping a Workflow
+### Stop a Workflow
 
 You can stop a Workflow instance by calling `abort` against a specific instance ID.
 
@@ -145,7 +149,7 @@ await instance.abort() // Returns Promise<void>
 
 Once stopped, the Workflow instance *cannot* be resumed.
 
-### Restarting a Workflow
+### Restart a Workflow
 
 You can restart a Workflow instance by calling `restart` against a specific instance ID.
 

src/content/docs/workflows/build/workers-api.mdx

@@ -12,7 +12,7 @@ TODO
 
 TODO
 
-## Interacting with Workflows
+## Interact with Workflows
 
 * Running a Workflow with the `run()` method
 * `StepConfig`