Add documentation for the jobs failure policy (#4676)

* chore: Add documentation for the jobs failure policy

Signed-off-by: Albert Callarisa <[email protected]>

* Clarify default failure policy and implications of unsetting fields in the constant policy

Signed-off-by: Albert Callarisa <[email protected]>

* Addressed some grammar suggestions

Signed-off-by: Albert Callarisa <[email protected]>

* Apply suggestions from code review

Co-authored-by: Alice Gibbons <[email protected]>
Signed-off-by: Albert Callarisa <[email protected]>

* Specified `nil` and `0` values for max_retries

Signed-off-by: Albert Callarisa <[email protected]>

---------

Signed-off-by: Albert Callarisa <[email protected]>
Signed-off-by: Albert Callarisa <[email protected]>
Co-authored-by: Mark Fussell <[email protected]>
Co-authored-by: Alice Gibbons <[email protected]>

Author: 3 people

daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md

@@ -6,7 +6,7 @@ weight: 2000
 description: "Learn more about the Dapr Jobs features and concepts"
 ---
 
-Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive 
+Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive
 into the features and concepts included with Dapr Jobs and the various SDKs. Dapr Jobs:
 - Provides a robust and scalable API for scheduling operations to be triggered in the future.
 - Exposes several capabilities which are common across all supported languages.
@@ -15,19 +15,19 @@ into the features and concepts included with Dapr Jobs and the various SDKs. Dap
 
 ## Job identity
 
-All jobs are registered with a case-sensitive job name. These names are intended to be unique across all services 
-interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as 
+All jobs are registered with a case-sensitive job name. These names are intended to be unique across all services
+interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as
 to indicate which job a triggered invocation is associated with.
 
-Only one job can be associated with a name at any given time. By default, any attempt to create a new job using the same name as an existing job results in an error. However, if the `overwrite` flag is set to `true`, the new job overwrites the existing job with the same name. 
+Only one job can be associated with a name at any given time. By default, any attempt to create a new job using the same name as an existing job results in an error. However, if the `overwrite` flag is set to `true`, the new job overwrites the existing job with the same name.
 
 ## Scheduling Jobs
 A job can be scheduled using any of the following mechanisms:
 - Intervals using Cron expressions, duration values, or period expressions
 - Specific dates and times
 
-For all time-based schedules, if a timestamp is provided with a time zone via the RFC3339 specification, that 
-time zone is used. When not provided, the time zone used by the server running Dapr is used. 
+For all time-based schedules, if a timestamp is provided with a time zone via the RFC3339 specification, that
+time zone is used. When not provided, the time zone used by the server running Dapr is used.
 In other words, do **not** assume that times run in UTC time zone, unless otherwise specified when scheduling
 the job.
 
@@ -47,7 +47,7 @@ fields spanning the values specified in the table below:
 
 ### Schedule using a duration value
 You can schedule jobs using [a Go duration string](https://pkg.go.dev/time#ParseDuration), in which
-a string consists of a (possibly) signed sequence of decimal numbers, each with an optional fraction and a unit suffix. 
+a string consists of a (possibly) signed sequence of decimal numbers, each with an optional fraction and a unit suffix.
 Valid time units are `"ns"`, `"us"`, `"ms"`, `"s"`, `"m"`, or `"h"`.
 
 #### Example 1
@@ -69,7 +69,7 @@ The following period expressions are supported. The "@every" expression also acc
 | @hourly | Run once an hour at the beginning of the hour | 0 0 * * * * |
 
 ### Schedule using a specific date/time
-A job can also be scheduled to run at a particular point in time by providing a date using the 
+A job can also be scheduled to run at a particular point in time by providing a date using the
 [RFC3339 specification](https://www.rfc-editor.org/rfc/rfc3339).
 
 #### Example 1
@@ -106,7 +106,7 @@ In this setup, you have full control over how triggered jobs are received and pr
 through this gRPC method.
 
 ### HTTP
-If a gRPC server isn't registered with Dapr when the application starts up, Dapr instead triggers jobs by making a 
+If a gRPC server isn't registered with Dapr when the application starts up, Dapr instead triggers jobs by making a
 POST request to the endpoint `/job/<job-name>`. The body includes the following information about the job:
 - `Schedule`: When the job triggers occur
 - `RepeatCount`: An optional value indicating how often the job should repeat
@@ -115,7 +115,8 @@ or the not-before time from which the schedule should take effect
 - `Ttl`: An optional value indicating when the job should expire
 - `Payload`: A collection of bytes containing data originally stored when the job was scheduled
 - `Overwrite`: A flag to allow the requested job to overwrite an existing job with the same name, if it already exists.
+- `FailurePolicy`: An optional failure policy for the job.
 
 The `DueTime` and `Ttl` fields will reflect an RC3339 timestamp value reflective of the time zone provided when the job was
 originally scheduled. If no time zone was provided, these values indicate the time zone used by the server running
-Dapr.
+Dapr.

daprdocs/content/en/reference/api/jobs_api.md

@@ -38,6 +38,7 @@ Parameter | Description
 `repeats` | An optional number of times in which the job should be triggered. If not set, the job runs indefinitely or until expiration.
 `ttl` | An optional time to live or expiration of the job. Accepts a "point in time" string in the format of RFC3339, Go duration string (calculated from job creation time), or non-repeating ISO8601.
 `overwrite` | A boolean value to specify if the job can overwrite an existing one with the same name. Default value is `false`
+`failure_policy` | An optional failure policy for the job. Details of the format are below. If not set, the job is retried up to 3 times with a delay of 1 second between retries.
 
 #### schedule
 `schedule` accepts both systemd timer-style cron expressions, as well as human readable '@' prefixed period strings, as defined below.
@@ -63,6 +64,39 @@ Entry                  | Description                                | Equivalent
 @daily (or @midnight)  | Run once a day, midnight                   | 0 0 0 * * *
 @hourly                | Run once an hour, beginning of hour        | 0 0 * * * *
 
+#### failure_policy
+
+`failure_policy` specifies how the job should handle failures.
+
+It can be set to `constant` or `drop`.
+- The `constant` policy retries the job constantly with the following configuration options.
+  - `max_retries` configures how many times the job should be retried. Defaults to retrying indefinitely. `nil` denotes unlimited retries, while `0` means the request will not be retried.
+  - `interval` configures the delay between retries. Defaults to retrying immediately. Valid values are of the form `200ms`, `15s`, `2m`, etc.
+- The `drop` policy drops the job after the first failure, without retrying.
+
+##### Example 1
+
+```json
+{
+  //...
+  "failure_policy": {
+    "constant": {
+      "max_retries": 3,
+      "interval": "10s"
+    }
+  }
+}
+```
+##### Example 2
+
+```json
+{
+  //...
+  "failure_policy": {
+    "drop": {}
+  }
+}
+```
 
 ### Request body