diff --git a/daprdocs/config.toml b/daprdocs/config.toml index ad036463628..3c5aae9f17f 100644 --- a/daprdocs/config.toml +++ b/daprdocs/config.toml @@ -109,7 +109,7 @@ id = "G-60C6Q1ETC1" lang = "en" [[module.mounts]] source = "../sdkdocs/rust/daprdocs/content/en/rust-sdk-contributing" - target = "content/contributing/sdks-contrib" + target = "content/contributing/sdk-contrib/" lang = "en" [[module.mounts]] @@ -143,7 +143,11 @@ id = "G-60C6Q1ETC1" [[module.mounts]] source = "../translations/docs-zh/translated_content/zh_CN/sdks_js" target = "content/developing-applications/sdks/js" - lang = "zh-hans" + lang = "zh-hans" + [[module.mounts]] + source = "../translations/docs-zh/translated_content/zh_CN/sdks_rust" + target = "content/developing-applications/sdks/rust" + lang = "zh-hans" [[module.mounts]] source = "../translations/docs-zh/translated_content/zh_CN/pluggable-components/dotnet" target = "content/developing-applications/develop-components/pluggable-components/pluggable-components-sdks/pluggable-components-dotnet" diff --git a/daprdocs/content/en/concepts/overview.md b/daprdocs/content/en/concepts/overview.md index 7613042ff93..fb1e3150274 100644 --- a/daprdocs/content/en/concepts/overview.md +++ b/daprdocs/content/en/concepts/overview.md @@ -76,7 +76,7 @@ Dapr exposes its HTTP and gRPC APIs as a sidecar architecture, either as a conta ## Hosting environments Dapr can be hosted in multiple environments, including: -- Self-hosted on a Windows/Linux/macOS machine for local development +- Self-hosted on a Windows/Linux/macOS machine for local development and in production - On Kubernetes or clusters of physical or virtual machines in production ### Self-hosted local development diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-features-concepts.md index e486b3243ec..da52612980b 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-features-concepts.md +++ b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-features-concepts.md @@ -57,7 +57,7 @@ This simplifies some choices, but also carries some consideration: ## Actor communication -You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint. +You can interact with Dapr to invoke the actor method by calling the HTTP endpoint. ```bash POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/// diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md index 8664045632c..233c10e9f2e 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md +++ b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md @@ -137,6 +137,10 @@ You can remove the actor reminder by calling DELETE http://localhost:3500/v1.0/actors///reminders/ ``` +If an actor reminder is triggered and the app does not return a 2** code to the runtime (for example, because of a connection issue), +actor reminders will be retried up to three times with a backoff interval of one second between each attempt. There may be +additional retries attempted in accordance with any optionally applied [actor resiliency policy]({{< ref "override-default-retries.md" >}}). + Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details. ## Error handling diff --git a/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md b/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md index 237314ac39a..595870e274b 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md @@ -10,12 +10,10 @@ description: "Overview of the conversation API building block" The conversation API is currently in [alpha]({{< ref "certification-lifecycle.md#certification-levels" >}}). {{% /alert %}} -Using the Dapr conversation API, you can reduce the complexity of interacting with Large Language Models (LLMs) and enable critical performance and security functionality with features like prompt caching and personally identifiable information (PII) data obfuscation. +Dapr's conversation API reduces the complexity of securely and reliably interacting with Large Language Models (LLM) at scale. Whether you're a developer who doesn't have the necessary native SDKs or a polyglot shop who just wants to focus on the prompt aspects of LLM interactions, the conversation API provides one consistent API entry point to talk to underlying LLM providers. Diagram showing the flow of a user's app communicating with Dapr's LLM components. -Dapr's conversation API reduces the complexity of securely and reliably interacting with Large Language Models (LLM) at scale. Whether you're a developer who doesn't have the necessary native SDKs or a polyglot shop who just wants to focus on the prompt aspects of LLM interactions, the conversation API provides one consistent API entry point to talk to underlying LLM providers. - In additon to enabling critical performance and security functionality (like [prompt caching]({{< ref "#prompt-caching" >}}) and [PII scrubbing]({{< ref "#personally-identifiable-information-pii-obfuscation" >}})), you can also pair the conversation API with Dapr functionalities, like: - Resiliency circuit breakers and retries to circumvent limit and token errors, or - Middleware to authenticate requests coming to and from the LLM @@ -57,4 +55,4 @@ Want to skip the quickstarts? Not a problem. You can try out the conversation bu ## Next steps - [How-To: Converse with an LLM using the conversation API]({{< ref howto-conversation-layer.md >}}) -- [Conversation API components]({{< ref supported-conversation >}}) \ No newline at end of file +- [Conversation API components]({{< ref supported-conversation >}}) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md index 0a5dba3b10c..38b2ab5ef6e 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md @@ -2,7 +2,7 @@ type: docs title: "How-To: Schedule and handle triggered jobs" linkTitle: "How-To: Schedule and handle triggered jobs" -weight: 2000 +weight: 5000 description: "Learn how to use the jobs API to schedule and handle triggered jobs" --- @@ -20,7 +20,103 @@ When you [run `dapr init` in either self-hosted mode or on Kubernetes]({{< ref i In your code, set up and schedule jobs within your application. -{{< tabs "Go" >}} +{{< tabs ".NET" "Go" >}} + +{{% codetab %}} + + + +The following .NET SDK code sample schedules the job named `prod-db-backup`. The job data contains information +about the database that you'll be seeking to backup regularly. Over the course of this example, you'll: +- Define types used in the rest of the example +- Register an endpoint during application startup that handles all job trigger invocations on the service +- Register the job with Dapr + +In the following example, you'll create records that you'll serialize and register alongside the job so the information +is available when the job is triggered in the future: +- The name of the backup task (`db-backup`) +- The backup task's `Metadata`, including: + - The database name (`DBName`) + - The database location (`BackupLocation`) + +Create an ASP.NET Core project and add the latest version of `Dapr.Jobs` from NuGet. + +> **Note:** While it's not strictly necessary +for your project to use the `Microsoft.NET.Sdk.Web` SDK to create jobs, as of the time this documentation is authored, +only the service that schedules a job receives trigger invocations for it. As those invocations expect an endpoint +that can handle the job trigger and requires the `Microsoft.NET.Sdk.Web` SDK, it's recommended that you +use an ASP.NET Core project for this purpose. + +Start by defining types to persist our backup job data and apply our own JSON property name attributes to the properties +so they're consistent with other language examples. + +```cs +//Define the types that we'll represent the job data with +internal sealed record BackupJobData([property: JsonPropertyName("task")] string Task, [property: JsonPropertyName("metadata")] BackupMetadata Metadata); +internal sealed record BackupMetadata([property: JsonPropertyName("DBName")]string DatabaseName, [property: JsonPropertyName("BackupLocation")] string BackupLocation); +``` + +Next, set up a handler as part of your application setup that will be called anytime a job is triggered on your +application. It's the responsibility of this handler to identify how jobs should be processed based on the job name provided. + +This works by registering a handler with ASP.NET Core at `/job/`, where `` is parameterized and +passed into this handler delegate, meeting Dapr's expectation that an endpoint is available to handle triggered named jobs. + +Populate your `Program.cs` file with the following: + +```cs +using System.Text; +using System.Text.Json; +using Dapr.Jobs; +using Dapr.Jobs.Extensions; +using Dapr.Jobs.Models; +using Dapr.Jobs.Models.Responses; + +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddDaprJobsClient(); +var app = builder.Build(); + +//Registers an endpoint to receive and process triggered jobs +var cancellationTokenSource = new CancellationTokenSource(TimeSpan.FromSeconds(5)); +app.MapDaprScheduledJobHandler((string jobName, DaprJobDetails jobDetails, ILogger logger, CancellationToken cancellationToken) => { + logger?.LogInformation("Received trigger invocation for job '{jobName}'", jobName); + switch (jobName) + { + case "prod-db-backup": + // Deserialize the job payload metadata + var jobData = JsonSerializer.Deserialize(jobDetails.Payload); + + // Process the backup operation - we assume this is implemented elsewhere in your code + await BackupDatabaseAsync(jobData, cancellationToken); + break; + } +}, cancellationTokenSource.Token); + +await app.RunAsync(); +``` + +Finally, the job itself needs to be registered with Dapr so it can be triggered at a later point in time. You can do this +by injecting a `DaprJobsClient` into a class and executing as part of an inbound operation to your application, but for +this example's purposes, it'll go at the bottom of the `Program.cs` file you started above. Because you'll be using the +`DaprJobsClient` you registered with dependency injection, start by creating a scope so you can access it. + +```cs +//Create a scope so we can access the registered DaprJobsClient +await using scope = app.Services.CreateAsyncScope(); +var daprJobsClient = scope.ServiceProvider.GetRequiredService(); + +//Create the payload we wish to present alongside our future job triggers +var jobData = new BackupJobData("db-backup", new BackupMetadata("my-prod-db", "/backup-dir")); + +//Serialize our payload to UTF-8 bytes +var serializedJobData = JsonSerializer.SerializeToUtf8Bytes(jobData); + +//Schedule our backup job to run every minute, but only repeat 10 times +await daprJobsClient.ScheduleJobAsync("prod-db-backup", DaprJobSchedule.FromDuration(TimeSpan.FromMinutes(1)), + serializedJobData, repeats: 10); +``` + +{{% /codetab %}} {{% codetab %}} @@ -92,66 +188,8 @@ In this example, at trigger time, which is `@every 1s` according to the `Schedul } ``` -At the trigger time, the `prodDBBackupHandler` function is called, executing the desired business logic for this job at trigger time. For example: - -#### HTTP - -When you create a job using Dapr's Jobs API, Dapr will automatically assume there is an endpoint available at -`/job/`. For instance, if you schedule a job named `test`, Dapr expects your application to listen for job -events at `/job/test`. Ensure your application has a handler set up for this endpoint to process the job when it is -triggered. For example: - -*Note: The following example is in Go but applies to any programming language.* - -```go - -func main() { - ... - http.HandleFunc("/job/", handleJob) - http.HandleFunc("/job/", specificJob) - ... -} - -func specificJob(w http.ResponseWriter, r *http.Request) { - // Handle specific triggered job -} - -func handleJob(w http.ResponseWriter, r *http.Request) { - // Handle the triggered jobs -} -``` - -#### gRPC - -When a job reaches its scheduled trigger time, the triggered job is sent back to the application via the following -callback function: - -*Note: The following example is in Go but applies to any programming language with gRPC support.* - -```go -import rtv1 "github.com/dapr/dapr/pkg/proto/runtime/v1" -... -func (s *JobService) OnJobEventAlpha1(ctx context.Context, in *rtv1.JobEventRequest) (*rtv1.JobEventResponse, error) { - // Handle the triggered job -} -``` - -This function processes the triggered jobs within the context of your gRPC server. When you set up the server, ensure that -you register the callback server, which will invoke this function when a job is triggered: - -```go -... -js := &JobService{} -rtv1.RegisterAppCallbackAlphaServer(server, js) -``` - -In this setup, you have full control over how triggered jobs are received and processed, as they are routed directly -through this gRPC method. - -#### SDKs - -For SDK users, handling triggered jobs is simpler. When a job is triggered, Dapr will automatically route the job to the -event handler you set up during the server initialization. For example, in Go, you'd register the event handler like this: +When a job is triggered, Dapr will automatically route the job to the event handler you set up during the server +initialization. For example, in Go, you'd register the event handler like this: ```go ... diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md new file mode 100644 index 00000000000..0d528f2c03b --- /dev/null +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md @@ -0,0 +1,121 @@ +--- +type: docs +title: "Features and concepts" +linkTitle: "Features and concepts" +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 +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. + + + +## 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 +to indicate which job a triggered invocation is associated with. + +Only one job can be associated with a name at any given time. Any attempt to create a new job using the same name +as an existing job will result in an overwrite of this existing job. + +## 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. +In other words, do **not** assume that times run in UTC time zone, unless otherwise specified when scheduling +the job. + +### Schedule using a Cron expression +When scheduling a job to execute on a specific interval using a Cron expression, the expression is written using 6 +fields spanning the values specified in the table below: + +| seconds | minutes | hours | day of month | month | day of week | +| -- | -- | -- | -- | -- | -- | +| 0-59 | 0-59 | 0-23 | 1-31 | 1-12/jan-dec | 0-6/sun-sat | + +#### Example 1 +`"0 30 * * * *"` triggers every hour on the half-hour mark. + +#### Example 2 +`"0 15 3 * * *"` triggers every day at 03:15. + +### 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. +Valid time units are `"ns"`, `"us"`, `"ms"`, `"s"`, `"m"`, or `"h"`. + +#### Example 1 +`"2h45m"` triggers every 2 hours and 45 minutes. + +#### Example 2 +`"37m25s"` triggers every 37 minutes and 25 seconds. + +### Schedule using a period expression +The following period expressions are supported. The "@every" expression also accepts a [Go duration string](https://pkg.go.dev/time#ParseDuration). + +| Entry | Description | Equivalent Cron expression | +| -- | -- | -- | +| @every | Run every (e.g. "@every 1h30m") | N/A | +| @yearly (or @annually) | Run once a year, midnight, January 1st | 0 0 0 1 1 * | +| @monthly | Run once a month, midnight, first of month | 0 0 0 1 * * | +| @weekly | Run once a week, midnight on Sunday | 0 0 0 * * 0 | +| @daily or @midnight | Run once a day at midnight | 0 0 0 * * * | +| @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 +[RFC3339 specification](https://www.rfc-editor.org/rfc/rfc3339). + +#### Example 1 +`"2025-12-09T16:09:53+00:00"` Indicates that the job should be run on December 9, 2025 at 4:09:53 PM UTC. + +## Scheduled triggers +When a scheduled Dapr job is triggered, the runtime sends a message back to the service that scheduled the job using +either the HTTP or gRPC approach, depending on which is registered with Dapr when the service starts. + +### gRPC +When a job reaches its scheduled trigger time, the triggered job is sent back to the application via the following +callback function: + +> **Note:** The following example is in Go, but applies to any programming language with gRPC support. + +```go +import rtv1 "github.com/dapr/dapr/pkg/proto/runtime/v1" +... +func (s *JobService) OnJobEventAlpha1(ctx context.Context, in *rtv1.JobEventRequest) (*rtv1.JobEventResponse, error) { + // Handle the triggered job +} +``` + +This function processes the triggered jobs within the context of your gRPC server. When you set up the server, ensure that +you register the callback server, which invokes this function when a job is triggered: + +```go +... +js := &JobService{} +rtv1.RegisterAppCallbackAlphaServer(server, js) +``` + +In this setup, you have full control over how triggered jobs are received and processed, as they are routed directly +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 +POST request to the endpoint `/job/`. 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 +- `DueTime`: An optional point in time representing either the one time when the job should execute (if not recurring) +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 + +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. \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md index 8085c1c47af..7f00d0c410a 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md @@ -70,7 +70,7 @@ app.get('/dapr/subscribe', (_req, res) => { ## Retries and dead letter topics By default, when a dead letter topic is set, any failing message immediately goes to the dead letter topic. As a result it is recommend to always have a retry policy set when using dead letter topics in a subscription. -To enable the retry of a message before sending it to the dead letter topic, apply a [retry resiliency policy]({{< ref "policies.md#retries" >}}) to the pub/sub component. +To enable the retry of a message before sending it to the dead letter topic, apply a [retry resiliency policy]({{< ref "retries-overview.md" >}}) to the pub/sub component. This example shows how to set a constant retry policy named `pubsubRetry`, with 10 maximum delivery attempts applied every 5 seconds for the `pubsub` pub/sub component. diff --git a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-services-grpc.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-services-grpc.md index 71679ff519a..adf36ab1fc6 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-services-grpc.md +++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-services-grpc.md @@ -309,6 +309,8 @@ context.AddMetadata("dapr-stream", "true"); ### Streaming gRPCs and Resiliency +> Currently, resiliency policies are not supported for service invocation via gRPC. + When proxying streaming gRPCs, due to their long-lived nature, [resiliency]({{< ref "resiliency-overview.md" >}}) policies are applied on the "initial handshake" only. As a consequence: - If the stream is interrupted after the initial handshake, it will not be automatically re-established by Dapr. Your application will be notified that the stream has ended, and will need to recreate it. diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md index 7ee3b500dae..985c1cc11de 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md +++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md @@ -195,7 +195,7 @@ string randomString = GetRandomString(); // DON'T DO THIS! Instant currentTime = Instant.now(); UUID newIdentifier = UUID.randomUUID(); -string randomString = GetRandomString(); +String randomString = getRandomString(); ``` {{% /codetab %}} @@ -242,7 +242,7 @@ string randomString = await context.CallActivityAsync("GetRandomString") ```java // Do this!! Instant currentTime = context.getCurrentInstant(); -Guid newIdentifier = context.NewGuid(); +Guid newIdentifier = context.newGuid(); String randomString = context.callActivity(GetRandomString.class.getName(), String.class).await(); ``` @@ -338,7 +338,7 @@ Do this: ```csharp // Do this!! -string configuation = workflowInput.Configuration; // imaginary workflow input argument +string configuration = workflowInput.Configuration; // imaginary workflow input argument string data = await context.CallActivityAsync("MakeHttpCall", "https://example.com/api/data"); ``` @@ -348,7 +348,7 @@ string data = await context.CallActivityAsync("MakeHttpCall", "https://e ```java // Do this!! -String configuation = ctx.getInput(InputType.class).getConfiguration(); // imaginary workflow input argument +String configuration = ctx.getInput(InputType.class).getConfiguration(); // imaginary workflow input argument String data = ctx.callActivity(MakeHttpCall.class, "https://example.com/api/data", String.class).await(); ``` @@ -358,7 +358,7 @@ String data = ctx.callActivity(MakeHttpCall.class, "https://example.com/api/data ```javascript // Do this!! -const configuation = workflowInput.getConfiguration(); // imaginary workflow input argument +const configuration = workflowInput.getConfiguration(); // imaginary workflow input argument const data = yield ctx.callActivity(makeHttpCall, "https://example.com/api/data"); ``` diff --git a/daprdocs/content/en/developing-applications/error-codes/error-codes-reference.md b/daprdocs/content/en/developing-applications/error-codes/error-codes-reference.md index 314bf67c4d7..494a123ef50 100644 --- a/daprdocs/content/en/developing-applications/error-codes/error-codes-reference.md +++ b/daprdocs/content/en/developing-applications/error-codes/error-codes-reference.md @@ -6,145 +6,199 @@ description: "List of gRPC and HTTP error codes in Dapr and their descriptions" weight: 20 --- -The following tables list the error codes returned by Dapr runtime: +The following tables list the error codes returned by Dapr runtime. +The error codes are returned in the response body of an HTTP request or in the `ErrorInfo` section of a gRPC status response, if one is present. +An effort is underway to enrich all gRPC error responses according to the [Richer Error Model]({{< ref "grpc-error-codes.md#richer-grpc-error-model" >}}). Error codes without a corresponding gRPC code indicate those errors have not yet been updated to this model. ### Actors API -| Error Code | Description | -| -------------------------------- | ------------------------------------------ | -| ERR_ACTOR_INSTANCE_MISSING | Error when an actor instance is missing. | -| ERR_ACTOR_RUNTIME_NOT_FOUND | Error the actor instance. | -| ERR_ACTOR_REMINDER_CREATE | Error creating a reminder for an actor. | -| ERR_ACTOR_REMINDER_DELETE | Error deleting a reminder for an actor. | -| ERR_ACTOR_TIMER_CREATE | Error creating a timer for an actor. | -| ERR_ACTOR_TIMER_DELETE | Error deleting a timer for an actor. | -| ERR_ACTOR_REMINDER_GET | Error getting a reminder for an actor. | -| ERR_ACTOR_INVOKE_METHOD | Error invoking a method on an actor. | -| ERR_ACTOR_STATE_DELETE | Error deleting the state for an actor. | -| ERR_ACTOR_STATE_GET | Error getting the state for an actor. | -| ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally. | -| ERR_ACTOR_REMINDER_NON_HOSTED | Error setting reminder for an actor. | +| HTTP Code | gRPC Code | Description | +| ---------------------------------- | --------- | ----------------------------------------------------------------------- | +| `ERR_ACTOR_INSTANCE_MISSING` | | Missing actor instance | +| `ERR_ACTOR_INVOKE_METHOD` | | Error invoking actor method | +| `ERR_ACTOR_RUNTIME_NOT_FOUND` | | Actor runtime not found | +| `ERR_ACTOR_STATE_GET` | | Error getting actor state | +| `ERR_ACTOR_STATE_TRANSACTION_SAVE` | | Error saving actor transaction | +| `ERR_ACTOR_REMINDER_CREATE` | | Error creating actor reminder | +| `ERR_ACTOR_REMINDER_DELETE` | | Error deleting actor reminder | +| `ERR_ACTOR_REMINDER_GET` | | Error getting actor reminder | +| `ERR_ACTOR_REMINDER_NON_HOSTED` | | Reminder operation on non-hosted actor type | +| `ERR_ACTOR_TIMER_CREATE` | | Error creating actor timer | +| `ERR_ACTOR_NO_APP_CHANNEL` | | App channel not initialized | +| `ERR_ACTOR_STACK_DEPTH` | | Maximum actor call stack depth exceeded | +| `ERR_ACTOR_NO_PLACEMENT` | | Placement service not configured | +| `ERR_ACTOR_RUNTIME_CLOSED` | | Actor runtime is closed | +| `ERR_ACTOR_NAMESPACE_REQUIRED` | | Actors must have a namespace configured when running in Kubernetes mode | +| `ERR_ACTOR_NO_ADDRESS` | | No address found for actor | + ### Workflows API -| Error Code | Description | -| -------------------------------- | ----------------------------------------------------------- | -| ERR_GET_WORKFLOW | Error getting workflow. | -| ERR_START_WORKFLOW | Error starting the workflow. | -| ERR_PAUSE_WORKFLOW | Error pausing the workflow. | -| ERR_RESUME_WORKFLOW | Error resuming the workflow. | -| ERR_TERMINATE_WORKFLOW | Error terminating the workflow. | -| ERR_PURGE_WORKFLOW | Error purging workflow. | -| ERR_RAISE_EVENT_WORKFLOW | Error raising an event within the workflow. | -| ERR_WORKFLOW_COMPONENT_MISSING | Error when a workflow component is missing a configuration. | -| ERR_WORKFLOW_COMPONENT_NOT_FOUND | Error when a workflow component is not found. | -| ERR_WORKFLOW_EVENT_NAME_MISSING | Error when the event name for a workflow is missing. | -| ERR_WORKFLOW_NAME_MISSING | Error when the workflow name is missing. | -| ERR_INSTANCE_ID_INVALID | Error invalid workflow instance ID provided. | -| ERR_INSTANCE_ID_NOT_FOUND | Error workflow instance ID not found. | -| ERR_INSTANCE_ID_PROVIDED_MISSING | Error workflow instance ID was provided but missing. | -| ERR_INSTANCE_ID_TOO_LONG | Error workflow instance ID exceeds allowable length. | - -### State Management API - -| Error Code | Description | -| ------------------------------------- | ------------------------------------------------------------------------- | -| ERR_STATE_STORE_NOT_FOUND | Error referencing a state store not found. | -| ERR_STATE_STORES_NOT_CONFIGURED | Error no state stores configured. | -| ERR_NOT_SUPPORTED_STATE_OPERATION | Error transaction requested on a state store with no transaction support. | -| ERR_STATE_GET | Error getting a state for state store. | -| ERR_STATE_DELETE | Error deleting a state from state store. | -| ERR_STATE_SAVE | Error saving a state in state store. | -| ERR_STATE_TRANSACTION | Error encountered during state transaction. | -| ERR_STATE_BULK_GET | Error performing bulk retrieval of state entries. | -| ERR_STATE_QUERY | Error querying the state store. | -| ERR_STATE_STORE_NOT_CONFIGURED | Error state store is not configured. | -| ERR_STATE_STORE_NOT_SUPPORTED | Error state store is not supported. | -| ERR_STATE_STORE_TOO_MANY_TRANSACTIONS | Error exceeded maximum allowable transactions. | +| HTTP Code | gRPC Code | Description | +| ---------------------------------- | --------- | --------------------------------------------------------------------------------------- | +| `ERR_GET_WORKFLOW` | | Error getting workflow | +| `ERR_START_WORKFLOW` | | Error starting workflow | +| `ERR_PAUSE_WORKFLOW` | | Error pausing workflow | +| `ERR_RESUME_WORKFLOW` | | Error resuming workflow | +| `ERR_TERMINATE_WORKFLOW` | | Error terminating workflow | +| `ERR_PURGE_WORKFLOW` | | Error purging workflow | +| `ERR_RAISE_EVENT_WORKFLOW` | | Error raising event in workflow | +| `ERR_WORKFLOW_COMPONENT_MISSING` | | Missing workflow component | +| `ERR_WORKFLOW_COMPONENT_NOT_FOUND` | | Workflow component not found | +| `ERR_WORKFLOW_EVENT_NAME_MISSING` | | Missing workflow event name | +| `ERR_WORKFLOW_NAME_MISSING` | | Workflow name not configured | +| `ERR_INSTANCE_ID_INVALID` | | Invalid workflow instance ID. (Only alphanumeric and underscore characters are allowed) | +| `ERR_INSTANCE_ID_NOT_FOUND` | | Workflow instance ID not found | +| `ERR_INSTANCE_ID_PROVIDED_MISSING` | | Missing workflow instance ID | +| `ERR_INSTANCE_ID_TOO_LONG` | | Workflow instance ID too long | + + +### State management API + +| HTTP Code | gRPC Code | Description | +| --------------------------------------- | --------------------------------------- | ----------------------------------------- | +| `ERR_STATE_TRANSACTION` | | Error in state transaction | +| `ERR_STATE_SAVE` | | Error saving state | +| `ERR_STATE_GET` | | Error getting state | +| `ERR_STATE_DELETE` | | Error deleting state | +| `ERR_STATE_BULK_DELETE` | | Error deleting state in bulk | +| `ERR_STATE_BULK_GET` | | Error getting state in bulk | +| `ERR_NOT_SUPPORTED_STATE_OPERATION` | | Operation not supported in transaction | +| `ERR_STATE_QUERY` | `DAPR_STATE_QUERY_FAILED` | Error querying state | +| `ERR_STATE_STORE_NOT_FOUND` | `DAPR_STATE_NOT_FOUND` | State store not found | +| `ERR_STATE_STORE_NOT_CONFIGURED` | `DAPR_STATE_NOT_CONFIGURED` | State store not configured | +| `ERR_STATE_STORE_NOT_SUPPORTED` | `DAPR_STATE_TRANSACTIONS_NOT_SUPPORTED` | State store does not support transactions | +| `ERR_STATE_STORE_NOT_SUPPORTED` | `DAPR_STATE_QUERYING_NOT_SUPPORTED` | State store does not support querying | +| `ERR_STATE_STORE_TOO_MANY_TRANSACTIONS` | `DAPR_STATE_TOO_MANY_TRANSACTIONS` | Too many operations per transaction | +| `ERR_MALFORMED_REQUEST` | `DAPR_STATE_ILLEGAL_KEY` | Invalid key | + ### Configuration API -| Error Code | Description | -| -------------------------------------- | -------------------------------------------- | -| ERR_CONFIGURATION_GET | Error retrieving configuration. | -| ERR_CONFIGURATION_STORE_NOT_CONFIGURED | Error configuration store is not configured. | -| ERR_CONFIGURATION_STORE_NOT_FOUND | Error configuration store not found. | -| ERR_CONFIGURATION_SUBSCRIBE | Error subscribing to a configuration. | -| ERR_CONFIGURATION_UNSUBSCRIBE | Error unsubscribing from a configuration. | +| HTTP Code | gRPC Code | Description | +| ---------------------------------------- | --------- | -------------------------------------- | +| `ERR_CONFIGURATION_GET` | | Error getting configuration | +| `ERR_CONFIGURATION_STORE_NOT_CONFIGURED` | | Configuration store not configured | +| `ERR_CONFIGURATION_STORE_NOT_FOUND` | | Configuration store not found | +| `ERR_CONFIGURATION_SUBSCRIBE` | | Error subscribing to configuration | +| `ERR_CONFIGURATION_UNSUBSCRIBE` | | Error unsubscribing from configuration | + ### Crypto API -| Error Code | Description | -| ----------------------------------- | ------------------------------------------ | -| ERR_CRYPTO | General crypto building block error. | -| ERR_CRYPTO_KEY | Error related to a crypto key. | -| ERR_CRYPTO_PROVIDER_NOT_FOUND | Error specified crypto provider not found. | -| ERR_CRYPTO_PROVIDERS_NOT_CONFIGURED | Error no crypto providers configured. | +| HTTP Code | gRPC Code | Description | +| ------------------------------------- | --------- | ------------------------------- | +| `ERR_CRYPTO` | | Error in crypto operation | +| `ERR_CRYPTO_KEY` | | Error retrieving crypto key | +| `ERR_CRYPTO_PROVIDER_NOT_FOUND` | | Crypto provider not found | +| `ERR_CRYPTO_PROVIDERS_NOT_CONFIGURED` | | Crypto providers not configured | + ### Secrets API -| Error Code | Description | -| -------------------------------- | ---------------------------------------------------- | -| ERR_SECRET_STORES_NOT_CONFIGURED | Error that no secret store is configured. | -| ERR_SECRET_STORE_NOT_FOUND | Error that specified secret store is not found. | -| ERR_SECRET_GET | Error retrieving the specified secret. | -| ERR_PERMISSION_DENIED | Error access denied due to insufficient permissions. | - -### Pub/Sub API - -| Error Code | Description | -| --------------------------- | -------------------------------------------------------- | -| ERR_PUBSUB_NOT_FOUND | Error referencing the Pub/Sub component in Dapr runtime. | -| ERR_PUBSUB_PUBLISH_MESSAGE | Error publishing a message. | -| ERR_PUBSUB_FORBIDDEN | Error message forbidden by access controls. | -| ERR_PUBSUB_CLOUD_EVENTS_SER | Error serializing Pub/Sub event envelope. | -| ERR_PUBSUB_EMPTY | Error empty Pub/Sub. | -| ERR_PUBSUB_NOT_CONFIGURED | Error Pub/Sub component is not configured. | -| ERR_PUBSUB_REQUEST_METADATA | Error with metadata in Pub/Sub request. | -| ERR_PUBSUB_EVENTS_SER | Error serializing Pub/Sub events. | -| ERR_PUBLISH_OUTBOX | Error publishing message to the outbox. | -| ERR_TOPIC_NAME_EMPTY | Error topic name for Pub/Sub message is empty. | +| HTTP Code | gRPC Code | Description | +| ---------------------------------- | --------- | --------------------------- | +| `ERR_SECRET_GET` | | Error getting secret | +| `ERR_SECRET_STORE_NOT_FOUND` | | Secret store not found | +| `ERR_SECRET_STORES_NOT_CONFIGURED` | | Secret store not configured | +| `ERR_PERMISSION_DENIED` | | Permission denied by policy | + + +### Pub/Sub and messaging errors + +| HTTP Code | gRPC Code | Description | +| ----------------------------- | -------------------------------------- | -------------------------------------- | +| `ERR_PUBSUB_EMPTY` | `DAPR_PUBSUB_NAME_EMPTY` | Pubsub name is empty | +| `ERR_PUBSUB_NOT_FOUND` | `DAPR_PUBSUB_NOT_FOUND` | Pubsub not found | +| `ERR_PUBSUB_NOT_FOUND` | `DAPR_PUBSUB_TEST_NOT_FOUND` | Pubsub not found | +| `ERR_PUBSUB_NOT_CONFIGURED` | `DAPR_PUBSUB_NOT_CONFIGURED` | Pubsub not configured | +| `ERR_TOPIC_NAME_EMPTY` | `DAPR_PUBSUB_TOPIC_NAME_EMPTY` | Topic name is empty | +| `ERR_PUBSUB_FORBIDDEN` | `DAPR_PUBSUB_FORBIDDEN` | Access to topic forbidden for APP ID | +| `ERR_PUBSUB_PUBLISH_MESSAGE` | `DAPR_PUBSUB_PUBLISH_MESSAGE` | Error publishing message | +| `ERR_PUBSUB_REQUEST_METADATA` | `DAPR_PUBSUB_METADATA_DESERIALIZATION` | Error deserializing metadata | +| `ERR_PUBSUB_CLOUD_EVENTS_SER` | `DAPR_PUBSUB_CLOUD_EVENT_CREATION` | Error creating CloudEvent | +| `ERR_PUBSUB_EVENTS_SER` | `DAPR_PUBSUB_MARSHAL_ENVELOPE` | Error marshalling Cloud Event envelope | +| `ERR_PUBSUB_EVENTS_SER` | `DAPR_PUBSUB_MARSHAL_EVENTS` | Error marshalling events to bytes | +| `ERR_PUBSUB_EVENTS_SER` | `DAPR_PUBSUB_UNMARSHAL_EVENTS` | Error unmarshalling events | +| `ERR_PUBLISH_OUTBOX` | | Error publishing message to outbox | + ### Conversation API -| Error Code | Description | -| ------------------------------- | ----------------------------------------------- | -| ERR_INVOKE_OUTPUT_BINDING | Error invoking an output binding. | -| ERR_DIRECT_INVOKE | Error in direct invocation. | -| ERR_CONVERSATION_INVALID_PARMS | Error invalid parameters for conversation. | -| ERR_CONVERSATION_INVOKE | Error invoking the conversation. | -| ERR_CONVERSATION_MISSING_INPUTS | Error missing required inputs for conversation. | -| ERR_CONVERSATION_NOT_FOUND | Error conversation not found. | +| HTTP Code | gRPC Code | Description | +| --------------------------------- | --------- | --------------------------------------------- | +| `ERR_CONVERSATION_INVALID_PARMS` | | Invalid parameters for conversation component | +| `ERR_CONVERSATION_INVOKE` | | Error invoking conversation | +| `ERR_CONVERSATION_MISSING_INPUTS` | | Missing inputs for conversation | +| `ERR_CONVERSATION_NOT_FOUND` | | Conversation not found | + + +### Service Invocation / Direct Messaging API + +| HTTP Code | gRPC Code | Description | +| ------------------- | --------- | ---------------------- | +| `ERR_DIRECT_INVOKE` | | Error invoking service | + + +### Bindings API + +| HTTP Code | gRPC Code | Description | +| --------------------------- | --------- | ----------------------------- | +| `ERR_INVOKE_OUTPUT_BINDING` | | Error invoking output binding | + ### Distributed Lock API -| Error Code | Description | -| ----------------------------- | ----------------------------------- | -| ERR_TRY_LOCK | Error attempting to acquire a lock. | -| ERR_UNLOCK | Error attempting to release a lock. | -| ERR_LOCK_STORE_NOT_CONFIGURED | Error lock store is not configured. | -| ERR_LOCK_STORE_NOT_FOUND | Error lock store not found. | +| HTTP Code | gRPC Code | Description | +| ------------------------------- | --------- | ------------------------- | +| `ERR_LOCK_STORE_NOT_CONFIGURED` | | Lock store not configured | +| `ERR_LOCK_STORE_NOT_FOUND` | | Lock store not found | +| `ERR_TRY_LOCK` | | Error acquiring lock | +| `ERR_UNLOCK` | | Error releasing lock | + ### Healthz -| Error Code | Description | -| ----------------------------- | --------------------------------------------------------------- | -| ERR_HEALTH_NOT_READY | Error that Dapr is not ready. | -| ERR_HEALTH_APPID_NOT_MATCH | Error the app-id does not match expected value in health check. | -| ERR_OUTBOUND_HEALTH_NOT_READY | Error outbound connection health is not ready. | +| HTTP Code | gRPC Code | Description | +| ------------------------------- | --------- | --------------------------- | +| `ERR_HEALTH_NOT_READY` | | Dapr not ready | +| `ERR_HEALTH_APPID_NOT_MATCH` | | Dapr App ID does not match | +| `ERR_OUTBOUND_HEALTH_NOT_READY` | | Dapr outbound not ready | + ### Common -| Error Code | Description | -| -------------------------- | ------------------------------------------------ | -| ERR_API_UNIMPLEMENTED | Error API is not implemented. | -| ERR_APP_CHANNEL_NIL | Error application channel is nil. | -| ERR_BAD_REQUEST | Error client request is badly formed or invalid. | -| ERR_BODY_READ | Error reading body. | -| ERR_INTERNAL | Internal server error encountered. | -| ERR_MALFORMED_REQUEST | Error with a malformed request. | -| ERR_MALFORMED_REQUEST_DATA | Error request data is malformed. | -| ERR_MALFORMED_RESPONSE | Error response data is malformed. | +| HTTP Code | gRPC Code | Description | +| ---------------------------- | --------- | -------------------------- | +| `ERR_API_UNIMPLEMENTED` | | API not implemented | +| `ERR_APP_CHANNEL_NIL` | | App channel is nil | +| `ERR_BAD_REQUEST` | | Bad request | +| `ERR_BODY_READ` | | Error reading request body | +| `ERR_INTERNAL` | | Internal error | +| `ERR_MALFORMED_REQUEST` | | Malformed request | +| `ERR_MALFORMED_REQUEST_DATA` | | Malformed request data | +| `ERR_MALFORMED_RESPONSE` | | Malformed response | + + +### Scheduler/Jobs API + +| HTTP Code | gRPC Code | Description | +| ------------------------------- | ------------------------------- | -------------------------------------- | +| `DAPR_SCHEDULER_SCHEDULE_JOB` | `DAPR_SCHEDULER_SCHEDULE_JOB` | Error scheduling job | +| `DAPR_SCHEDULER_JOB_NAME` | `DAPR_SCHEDULER_JOB_NAME` | Job name should only be set in the url | +| `DAPR_SCHEDULER_JOB_NAME_EMPTY` | `DAPR_SCHEDULER_JOB_NAME_EMPTY` | Job name is empty | +| `DAPR_SCHEDULER_GET_JOB` | `DAPR_SCHEDULER_GET_JOB` | Error getting job | +| `DAPR_SCHEDULER_LIST_JOBS` | `DAPR_SCHEDULER_LIST_JOBS` | Error listing jobs | +| `DAPR_SCHEDULER_DELETE_JOB` | `DAPR_SCHEDULER_DELETE_JOB` | Error deleting job | +| `DAPR_SCHEDULER_EMPTY` | `DAPR_SCHEDULER_EMPTY` | Required argument is empty | +| `DAPR_SCHEDULER_SCHEDULE_EMPTY` | `DAPR_SCHEDULER_SCHEDULE_EMPTY` | No schedule provided for job | + + +### Generic + +| HTTP Code | gRPC Code | Description | +| --------- | --------- | ------------- | +| `ERROR` | `ERROR` | Generic error | ## Next steps diff --git a/daprdocs/content/en/getting-started/quickstarts/actors-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/actors-quickstart.md index 3b7ad206891..fef7c9de93c 100644 --- a/daprdocs/content/en/getting-started/quickstarts/actors-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/actors-quickstart.md @@ -20,8 +20,8 @@ As a quick overview of the .NET actors quickstart: 1. Using a `SmartDevice.Service` microservice, you host: - Two `SmokeDetectorActor` smoke alarm objects - A `ControllerActor` object that commands and controls the smart devices -1. Using a `SmartDevice.Client` console app, the client app interacts with each actor, or the controller, to perform actions in aggregate. -1. The `SmartDevice.Interfaces` contains the shared interfaces and data types used by both the service and client apps. +2. Using a `SmartDevice.Client` console app, the client app interacts with each actor, or the controller, to perform actions in aggregate. +3. The `SmartDevice.Interfaces` contains the shared interfaces and data types used by both the service and client apps. @@ -30,10 +30,13 @@ As a quick overview of the .NET actors quickstart: For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 6 is the minimally supported version of .NET for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 1: Set up the environment diff --git a/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md index 68c1c61e27a..3dc076e0a6b 100644 --- a/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md @@ -443,10 +443,13 @@ In the YAML file: For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 6 is the minimally supported version of .NET for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 1: Set up the environment diff --git a/daprdocs/content/en/getting-started/quickstarts/configuration-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/configuration-quickstart.md index 1c11084b01d..bd4f44a2a8d 100644 --- a/daprdocs/content/en/getting-started/quickstarts/configuration-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/configuration-quickstart.md @@ -272,10 +272,13 @@ setTimeout(() => { For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 6 is the minimally supported version of .NET for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 1: Set up the environment diff --git a/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md index af95c1c3401..4dc5543f3e4 100644 --- a/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md @@ -358,10 +358,13 @@ console.log("Published data: " + JSON.stringify(order)); For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 6 is the minimally supported version of .NET for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 2: Set up the environment diff --git a/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md index da4c09763c1..5a799b32496 100644 --- a/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md @@ -247,10 +247,13 @@ Order-processor output: For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 6 is the minimally supported version of .NET for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 1: Set up the environment diff --git a/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md index 4bd2b237b71..9122cdab659 100644 --- a/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md @@ -315,10 +315,13 @@ console.log("Order passed: " + res.config.data); For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 7 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 6 is the minimally supported version of .NET for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 2: Set up the environment diff --git a/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md index ff92119df3e..bde517c44af 100644 --- a/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md @@ -288,10 +288,13 @@ In the YAML file: For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 6 is the minimally supported version of .NET for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 1: Set up the environment diff --git a/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md index 3cf04fac94e..6852e918d71 100644 --- a/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md @@ -507,10 +507,13 @@ The `order-processor` console app starts and manages the lifecycle of an order p For this example, you will need: - [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). -- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). - [Docker Desktop](https://www.docker.com/products/docker-desktop) +- [.NET 7](https://dotnet.microsoft.com/download/dotnet/7.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed + +**NOTE:** .NET 7 is the minimally supported version of .NET by Dapr.Workflows in Dapr v1.15. Only .NET 8 and .NET 9 +will be supported in Dapr v1.16 and later releases. ### Step 2: Set up the environment diff --git a/daprdocs/content/en/operations/resiliency/policies.md b/daprdocs/content/en/operations/resiliency/policies.md index 99a71eaef65..e69de29bb2d 100644 --- a/daprdocs/content/en/operations/resiliency/policies.md +++ b/daprdocs/content/en/operations/resiliency/policies.md @@ -1,330 +0,0 @@ ---- -type: docs -title: "Resiliency policies" -linkTitle: "Policies" -weight: 200 -description: "Configure resiliency policies for timeouts, retries, and circuit breakers" ---- - -Define timeouts, retries, and circuit breaker policies under `policies`. Each policy is given a name so you can refer to them from the `targets` section in the resiliency spec. - -> Note: Dapr offers default retries for specific APIs. [See here]({{< ref "#overriding-default-retries" >}}) to learn how you can overwrite default retry logic with user defined retry policies. - -## Timeouts - -Timeouts are optional policies that can be used to early-terminate long-running operations. If you've exceeded a timeout duration: - -- The operation in progress is terminated (if possible). -- An error is returned. - -Valid values are of the form accepted by Go's [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), for example: `15s`, `2m`, `1h30m`. Timeouts have no set maximum value. - -Example: - -```yaml -spec: - policies: - # Timeouts are simple named durations. - timeouts: - general: 5s - important: 60s - largeResponse: 10s -``` - -If you don't specify a timeout value, the policy does not enforce a time and defaults to whatever you set up per the request client. - -## Retries - -With `retries`, you can define a retry strategy for failed operations, including requests failed due to triggering a defined timeout or circuit breaker policy. - -{{% alert title="Pub/sub component retries vs inbound resiliency" color="warning" %}} -Each [pub/sub component]({{< ref supported-pubsub >}}) has its own built-in retry behaviors. Explicity applying a Dapr resiliency policy doesn't override these implicit retry policies. Rather, the resiliency policy augments the built-in retry, which can cause repetitive clustering of messages. -{{% /alert %}} - -The following retry options are configurable: - -| Retry option | Description | -| ------------ | ----------- | -| `policy` | Determines the back-off and retry interval strategy. Valid values are `constant` and `exponential`.
Defaults to `constant`. | -| `duration` | Determines the time interval between retries. Only applies to the `constant` policy.
Valid values are of the form `200ms`, `15s`, `2m`, etc.
Defaults to `5s`.| -| `maxInterval` | Determines the maximum interval between retries to which the `exponential` back-off policy can grow.
Additional retries always occur after a duration of `maxInterval`. Defaults to `60s`. Valid values are of the form `5s`, `1m`, `1m30s`, etc | -| `maxRetries` | The maximum number of retries to attempt.
`-1` denotes an unlimited number of retries, while `0` means the request will not be retried (essentially behaving as if the retry policy were not set).
Defaults to `-1`. | -| `matching.httpStatusCodes` | Optional: a comma-separated string of HTTP status codes or code ranges to retry. Status codes not listed are not retried.
Valid values: 100-599, [Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
Format: `` or range `-`
Example: "429,501-503"
Default: empty string `""` or field is not set. Retries on all HTTP errors. | -| `matching.gRPCStatusCodes` | Optional: a comma-separated string of gRPC status codes or code ranges to retry. Status codes not listed are not retried.
Valid values: 0-16, [Reference](https://grpc.io/docs/guides/status-codes/)
Format: `` or range `-`
Example: "1,501-503"
Default: empty string `""` or field is not set. Retries on all gRPC errors. | - - -{{% alert title="httpStatusCodes and gRPCStatusCodes format" color="warning" %}} -The field values should follow the format as specified in the field description or in the "Example 2" below. -An incorrectly formatted value will produce an error log ("Could not read resiliency policy") and `daprd` startup sequence will proceed. -{{% /alert %}} - - -The exponential back-off window uses the following formula: - -``` -BackOffDuration = PreviousBackOffDuration * (Random value from 0.5 to 1.5) * 1.5 -if BackOffDuration > maxInterval { - BackoffDuration = maxInterval -} -``` - -Example: - -```yaml -spec: - policies: - # Retries are named templates for retry configurations and are instantiated for life of the operation. - retries: - pubsubRetry: - policy: constant - duration: 5s - maxRetries: 10 - - retryForever: - policy: exponential - maxInterval: 15s - maxRetries: -1 # Retry indefinitely -``` - -Example 2: - -```yaml -spec: - policies: - retries: - retry5xxOnly: - policy: constant - duration: 5s - maxRetries: 3 - matching: - httpStatusCodes: "429,500-599" # retry the HTTP status codes in this range. All others are not retried. - gRPCStatusCodes: "1-4,8-11,13,14" # retry gRPC status codes in these ranges and separate single codes. -``` - -## Circuit Breakers - -Circuit Breaker (CB) policies are used when other applications/services/components are experiencing elevated failure rates. CBs monitor the requests and shut off all traffic to the impacted service when a certain criteria is met ("open" state). By doing this, CBs give the service time to recover from their outage instead of flooding it with events. The CB can also allow partial traffic through to see if the system has healed ("half-open" state). Once requests resume being successful, the CB gets into "closed" state and allows traffic to completely resume. - -| Retry option | Description | -| ------------ | ----------- | -| `maxRequests` | The maximum number of requests allowed to pass through when the CB is half-open (recovering from failure). Defaults to `1`. | -| `interval` | The cyclical period of time used by the CB to clear its internal counts. If set to 0 seconds, this never clears. Defaults to `0s`. | -| `timeout` | The period of the open state (directly after failure) until the CB switches to half-open. Defaults to `60s`. | -| `trip` | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) statement that is evaluated by the CB. When the statement evaluates to true, the CB trips and becomes open. Defaults to `consecutiveFailures > 5`. Other possible values are `requests` and `totalFailures` where `requests` represents the number of either successful or failed calls before the circuit opens and `totalFailures` represents the total (not necessarily consecutive) number of failed attempts before the circuit opens. Example: `requests > 5` and `totalFailures >3`.| - -Example: - -```yaml -spec: - policies: - circuitBreakers: - pubsubCB: - maxRequests: 1 - interval: 8s - timeout: 45s - trip: consecutiveFailures > 8 -``` - -## Overriding default retries - -Dapr provides default retries for any unsuccessful request, such as failures and transient errors. Within a resiliency spec, you have the option to override Dapr's default retry logic by defining policies with reserved, named keywords. For example, defining a policy with the name `DaprBuiltInServiceRetries`, overrides the default retries for failures between sidecars via service-to-service requests. Policy overrides are not applied to specific targets. - -> Note: Although you can override default values with more robust retries, you cannot override with lesser values than the provided default value, or completely remove default retries. This prevents unexpected downtime. - -Below is a table that describes Dapr's default retries and the policy keywords to override them: - -| Capability | Override Keyword | Default Retry Behavior | Description | -| ------------------ | ------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | -| Service Invocation | DaprBuiltInServiceRetries | Per call retries are performed with a backoff interval of 1 second, up to a threshold of 3 times. | Sidecar-to-sidecar requests (a service invocation method call) that fail and result in a gRPC code `Unavailable` or `Unauthenticated` | -| Actors | DaprBuiltInActorRetries | Per call retries are performed with a backoff interval of 1 second, up to a threshold of 3 times. | Sidecar-to-sidecar requests (an actor method call) that fail and result in a gRPC code `Unavailable` or `Unauthenticated` | -| Actor Reminders | DaprBuiltInActorReminderRetries | Per call retries are performed with an exponential backoff with an initial interval of 500ms, up to a maximum of 60s for a duration of 15mins | Requests that fail to persist an actor reminder to a state store | -| Initialization Retries | DaprBuiltInInitializationRetries | Per call retries are performed 3 times with an exponential backoff, an initial interval of 500ms and for a duration of 10s | Failures when making a request to an application to retrieve a given spec. For example, failure to retrieve a subscription, component or resiliency specification | - - -The resiliency spec example below shows overriding the default retries for _all_ service invocation requests by using the reserved, named keyword 'DaprBuiltInServiceRetries'. - -Also defined is a retry policy called 'retryForever' that is only applied to the appB target. appB uses the 'retryForever' retry policy, while all other application service invocation retry failures use the overridden 'DaprBuiltInServiceRetries' default policy. - -```yaml -spec: - policies: - retries: - DaprBuiltInServiceRetries: # Overrides default retry behavior for service-to-service calls - policy: constant - duration: 5s - maxRetries: 10 - - retryForever: # A user defined retry policy replaces default retries. Targets rely solely on the applied policy. - policy: exponential - maxInterval: 15s - maxRetries: -1 # Retry indefinitely - - targets: - apps: - appB: # app-id of the target service - retry: retryForever -``` - -## Setting default policies - -In resiliency you can set default policies, which have a broad scope. This is done through reserved keywords that let Dapr know when to apply the policy. There are 3 default policy types: - -- `DefaultRetryPolicy` -- `DefaultTimeoutPolicy` -- `DefaultCircuitBreakerPolicy` - -If these policies are defined, they are used for every operation to a service, application, or component. They can also be modified to be more specific through the appending of additional keywords. The specific policies follow the following pattern, `Default%sRetryPolicy`, `Default%sTimeoutPolicy`, and `Default%sCircuitBreakerPolicy`. Where the `%s` is replaced by a target of the policy. - -Below is a table of all possible default policy keywords and how they translate into a policy name. - -| Keyword | Target Operation | Example Policy Name | -| -------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------- | -| `App` | Service invocation. | `DefaultAppRetryPolicy` | -| `Actor` | Actor invocation. | `DefaultActorTimeoutPolicy` | -| `Component` | All component operations. | `DefaultComponentCircuitBreakerPolicy` | -| `ComponentInbound` | All inbound component operations. | `DefaultComponentInboundRetryPolicy` | -| `ComponentOutbound` | All outbound component operations. | `DefaultComponentOutboundTimeoutPolicy` | -| `StatestoreComponentOutbound` | All statestore component operations. | `DefaultStatestoreComponentOutboundCircuitBreakerPolicy` | -| `PubsubComponentOutbound` | All outbound pubusub (publish) component operations. | `DefaultPubsubComponentOutboundRetryPolicy` | -| `PubsubComponentInbound` | All inbound pubsub (subscribe) component operations. | `DefaultPubsubComponentInboundTimeoutPolicy` | -| `BindingComponentOutbound` | All outbound binding (invoke) component operations. | `DefaultBindingComponentOutboundCircuitBreakerPolicy` | -| `BindingComponentInbound` | All inbound binding (read) component operations. | `DefaultBindingComponentInboundRetryPolicy` | -| `SecretstoreComponentOutbound` | All secretstore component operations. | `DefaultSecretstoreComponentTimeoutPolicy` | -| `ConfigurationComponentOutbound` | All configuration component operations. | `DefaultConfigurationComponentOutboundCircuitBreakerPolicy` | -| `LockComponentOutbound` | All lock component operations. | `DefaultLockComponentOutboundRetryPolicy` | - -### Policy hierarchy resolution - -Default policies are applied if the operation being executed matches the policy type and if there is no more specific policy targeting it. For each target type (app, actor, and component), the policy with the highest priority is a Named Policy, one that targets that construct specifically. - -If none exists, the policies are applied from most specific to most broad. - -#### How default policies and built-in retries work together - -In the case of the [built-in retries]({{< ref "policies.md#Override Default Retries" >}}), default policies do not stop the built-in retry policies from running. Both are used together but only under specific circumstances. - -For service and actor invocation, the built-in retries deal specifically with issues connecting to the remote sidecar (when needed). As these are important to the stability of the Dapr runtime, they are not disabled **unless** a named policy is specifically referenced for an operation. In some instances, there may be additional retries from both the built-in retry and the default retry policy, but this prevents an overly weak default policy from reducing the sidecar's availability/success rate. - -Policy resolution hierarchy for applications, from most specific to most broad: - -1. Named Policies in App Targets -2. Default App Policies / Built-In Service Retries -3. Default Policies / Built-In Service Retries - -Policy resolution hierarchy for actors, from most specific to most broad: - -1. Named Policies in Actor Targets -2. Default Actor Policies / Built-In Actor Retries -3. Default Policies / Built-In Actor Retries - -Policy resolution hierarchy for components, from most specific to most broad: - -1. Named Policies in Component Targets -2. Default Component Type + Component Direction Policies / Built-In Actor Reminder Retries (if applicable) -3. Default Component Direction Policies / Built-In Actor Reminder Retries (if applicable) -4. Default Component Policies / Built-In Actor Reminder Retries (if applicable) -5. Default Policies / Built-In Actor Reminder Retries (if applicable) - -As an example, take the following solution consisting of three applications, three components and two actor types: - -Applications: - -- AppA -- AppB -- AppC - -Components: - -- Redis Pubsub: pubsub -- Redis statestore: statestore -- CosmosDB Statestore: actorstore - -Actors: - -- EventActor -- SummaryActor - -Below is policy that uses both default and named policies as applies these to the targets. - -```yaml -spec: - policies: - retries: - # Global Retry Policy - DefaultRetryPolicy: - policy: constant - duration: 1s - maxRetries: 3 - - # Global Retry Policy for Apps - DefaultAppRetryPolicy: - policy: constant - duration: 100ms - maxRetries: 5 - - # Global Retry Policy for Apps - DefaultActorRetryPolicy: - policy: exponential - maxInterval: 15s - maxRetries: 10 - - # Global Retry Policy for Inbound Component operations - DefaultComponentInboundRetryPolicy: - policy: constant - duration: 5s - maxRetries: 5 - - # Global Retry Policy for Statestores - DefaultStatestoreComponentOutboundRetryPolicy: - policy: exponential - maxInterval: 60s - maxRetries: -1 - - # Named policy - fastRetries: - policy: constant - duration: 10ms - maxRetries: 3 - - # Named policy - retryForever: - policy: exponential - maxInterval: 10s - maxRetries: -1 - - targets: - apps: - appA: - retry: fastRetries - - appB: - retry: retryForever - - actors: - EventActor: - retry: retryForever - - components: - actorstore: - retry: fastRetries -``` - -The table below is a break down of which policies are applied when attempting to call the various targets in this solution. - -| Target | Policy Used | -| ------------------ | ----------------------------------------------- | -| AppA | fastRetries | -| AppB | retryForever | -| AppC | DefaultAppRetryPolicy / DaprBuiltInActorRetries | -| pubsub - Publish | DefaultRetryPolicy | -| pubsub - Subscribe | DefaultComponentInboundRetryPolicy | -| statestore | DefaultStatestoreComponentOutboundRetryPolicy | -| actorstore | fastRetries | -| EventActor | retryForever | -| SummaryActor | DefaultActorRetryPolicy | - -## Next steps - -Try out one of the Resiliency quickstarts: -- [Resiliency: Service-to-service]({{< ref resiliency-serviceinvo-quickstart.md >}}) -- [Resiliency: State Management]({{< ref resiliency-state-quickstart.md >}}) diff --git a/daprdocs/content/en/operations/resiliency/policies/_index.md b/daprdocs/content/en/operations/resiliency/policies/_index.md new file mode 100644 index 00000000000..40cbd084b26 --- /dev/null +++ b/daprdocs/content/en/operations/resiliency/policies/_index.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "Resiliency policies" +linkTitle: "Policies" +weight: 200 +description: "Configure resiliency policies for timeouts, retries, and circuit breakers" +--- + +Define timeouts, retries, and circuit breaker policies under `policies`. Each policy is given a name so you can refer to them from the [`targets` section in the resiliency spec]({{< ref targets.md >}}). diff --git a/daprdocs/content/en/operations/resiliency/policies/circuit-breakers.md b/daprdocs/content/en/operations/resiliency/policies/circuit-breakers.md new file mode 100644 index 00000000000..afa4168126f --- /dev/null +++ b/daprdocs/content/en/operations/resiliency/policies/circuit-breakers.md @@ -0,0 +1,49 @@ +--- +type: docs +title: "Circuit breaker resiliency policies" +linkTitle: "Circuit breakers" +weight: 30 +description: "Configure resiliency policies for circuit breakers" +--- + +Circuit breaker policies are used when other applications/services/components are experiencing elevated failure rates. Circuit breakers reduce load by monitoring the requests and shutting off all traffic to the impacted service when a certain criteria is met. + +After a certain number of requests fail, circuit breakers "trip" or open to prevent cascading failures. By doing this, circuit breakers give the service time to recover from their outage instead of flooding it with events. + +The circuit breaker can also enter a “half-open” state, allowing partial traffic through to see if the system has healed. + +Once requests resume being successful, the circuit breaker gets into "closed" state and allows traffic to completely resume. + +## Circuit breaker policy format + +```yaml +spec: + policies: + circuitBreakers: + pubsubCB: + maxRequests: 1 + interval: 8s + timeout: 45s + trip: consecutiveFailures > 8 +``` + +## Spec metadata + +| Retry option | Description | +| ------------ | ----------- | +| `maxRequests` | The maximum number of requests allowed to pass through when the circuit breaker is half-open (recovering from failure). Defaults to `1`. | +| `interval` | The cyclical period of time used by the circuit breaker to clear its internal counts. If set to 0 seconds, this never clears. Defaults to `0s`. | +| `timeout` | The period of the open state (directly after failure) until the circuit breaker switches to half-open. Defaults to `60s`. | +| `trip` | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) statement that is evaluated by the circuit breaker. When the statement evaluates to true, the circuit breaker trips and becomes open. Defaults to `consecutiveFailures > 5`. Other possible values are `requests` and `totalFailures` where `requests` represents the number of either successful or failed calls before the circuit opens and `totalFailures` represents the total (not necessarily consecutive) number of failed attempts before the circuit opens. Example: `requests > 5` and `totalFailures >3`.| + +## Next steps +- [Learn more about default resiliency policies]({{< ref default-policies.md >}}) +- Learn more about: + - [Retry policies]({{< ref retries-overview.md >}}) + - [Timeout policies]({{< ref timeouts.md >}}) + +## Related links + +Try out one of the Resiliency quickstarts: +- [Resiliency: Service-to-service]({{< ref resiliency-serviceinvo-quickstart.md >}}) +- [Resiliency: State Management]({{< ref resiliency-state-quickstart.md >}}) diff --git a/daprdocs/content/en/operations/resiliency/policies/default-policies.md b/daprdocs/content/en/operations/resiliency/policies/default-policies.md new file mode 100644 index 00000000000..2d8f622f11b --- /dev/null +++ b/daprdocs/content/en/operations/resiliency/policies/default-policies.md @@ -0,0 +1,173 @@ +--- +type: docs +title: "Default resiliency policies" +linkTitle: "Default policies" +weight: 40 +description: "Learn more about the default resiliency policies for timeouts, retries, and circuit breakers" +--- + +In resiliency, you can set default policies, which have a broad scope. This is done through reserved keywords that let Dapr know when to apply the policy. There are 3 default policy types: + +- `DefaultRetryPolicy` +- `DefaultTimeoutPolicy` +- `DefaultCircuitBreakerPolicy` + +If these policies are defined, they are used for every operation to a service, application, or component. They can also be modified to be more specific through the appending of additional keywords. The specific policies follow the following pattern, `Default%sRetryPolicy`, `Default%sTimeoutPolicy`, and `Default%sCircuitBreakerPolicy`. Where the `%s` is replaced by a target of the policy. + +Below is a table of all possible default policy keywords and how they translate into a policy name. + +| Keyword | Target Operation | Example Policy Name | +| -------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------- | +| `App` | Service invocation. | `DefaultAppRetryPolicy` | +| `Actor` | Actor invocation. | `DefaultActorTimeoutPolicy` | +| `Component` | All component operations. | `DefaultComponentCircuitBreakerPolicy` | +| `ComponentInbound` | All inbound component operations. | `DefaultComponentInboundRetryPolicy` | +| `ComponentOutbound` | All outbound component operations. | `DefaultComponentOutboundTimeoutPolicy` | +| `StatestoreComponentOutbound` | All statestore component operations. | `DefaultStatestoreComponentOutboundCircuitBreakerPolicy` | +| `PubsubComponentOutbound` | All outbound pubusub (publish) component operations. | `DefaultPubsubComponentOutboundRetryPolicy` | +| `PubsubComponentInbound` | All inbound pubsub (subscribe) component operations. | `DefaultPubsubComponentInboundTimeoutPolicy` | +| `BindingComponentOutbound` | All outbound binding (invoke) component operations. | `DefaultBindingComponentOutboundCircuitBreakerPolicy` | +| `BindingComponentInbound` | All inbound binding (read) component operations. | `DefaultBindingComponentInboundRetryPolicy` | +| `SecretstoreComponentOutbound` | All secretstore component operations. | `DefaultSecretstoreComponentTimeoutPolicy` | +| `ConfigurationComponentOutbound` | All configuration component operations. | `DefaultConfigurationComponentOutboundCircuitBreakerPolicy` | +| `LockComponentOutbound` | All lock component operations. | `DefaultLockComponentOutboundRetryPolicy` | + +## Policy hierarchy resolution + +Default policies are applied if the operation being executed matches the policy type and if there is no more specific policy targeting it. For each target type (app, actor, and component), the policy with the highest priority is a Named Policy, one that targets that construct specifically. + +If none exists, the policies are applied from most specific to most broad. + +## How default policies and built-in retries work together + +In the case of the [built-in retries]({{< ref override-default-retries.md >}}), default policies do not stop the built-in retry policies from running. Both are used together but only under specific circumstances. + +For service and actor invocation, the built-in retries deal specifically with issues connecting to the remote sidecar (when needed). As these are important to the stability of the Dapr runtime, they are not disabled **unless** a named policy is specifically referenced for an operation. In some instances, there may be additional retries from both the built-in retry and the default retry policy, but this prevents an overly weak default policy from reducing the sidecar's availability/success rate. + +Policy resolution hierarchy for applications, from most specific to most broad: + +1. Named Policies in App Targets +2. Default App Policies / Built-In Service Retries +3. Default Policies / Built-In Service Retries + +Policy resolution hierarchy for actors, from most specific to most broad: + +1. Named Policies in Actor Targets +2. Default Actor Policies / Built-In Actor Retries +3. Default Policies / Built-In Actor Retries + +Policy resolution hierarchy for components, from most specific to most broad: + +1. Named Policies in Component Targets +2. Default Component Type + Component Direction Policies / Built-In Actor Reminder Retries (if applicable) +3. Default Component Direction Policies / Built-In Actor Reminder Retries (if applicable) +4. Default Component Policies / Built-In Actor Reminder Retries (if applicable) +5. Default Policies / Built-In Actor Reminder Retries (if applicable) + +As an example, take the following solution consisting of three applications, three components and two actor types: + +Applications: + +- AppA +- AppB +- AppC + +Components: + +- Redis Pubsub: pubsub +- Redis statestore: statestore +- CosmosDB Statestore: actorstore + +Actors: + +- EventActor +- SummaryActor + +Below is policy that uses both default and named policies as applies these to the targets. + +```yaml +spec: + policies: + retries: + # Global Retry Policy + DefaultRetryPolicy: + policy: constant + duration: 1s + maxRetries: 3 + + # Global Retry Policy for Apps + DefaultAppRetryPolicy: + policy: constant + duration: 100ms + maxRetries: 5 + + # Global Retry Policy for Apps + DefaultActorRetryPolicy: + policy: exponential + maxInterval: 15s + maxRetries: 10 + + # Global Retry Policy for Inbound Component operations + DefaultComponentInboundRetryPolicy: + policy: constant + duration: 5s + maxRetries: 5 + + # Global Retry Policy for Statestores + DefaultStatestoreComponentOutboundRetryPolicy: + policy: exponential + maxInterval: 60s + maxRetries: -1 + + # Named policy + fastRetries: + policy: constant + duration: 10ms + maxRetries: 3 + + # Named policy + retryForever: + policy: exponential + maxInterval: 10s + maxRetries: -1 + + targets: + apps: + appA: + retry: fastRetries + + appB: + retry: retryForever + + actors: + EventActor: + retry: retryForever + + components: + actorstore: + retry: fastRetries +``` + +The table below is a break down of which policies are applied when attempting to call the various targets in this solution. + +| Target | Policy Used | +| ------------------ | ----------------------------------------------- | +| AppA | fastRetries | +| AppB | retryForever | +| AppC | DefaultAppRetryPolicy / DaprBuiltInActorRetries | +| pubsub - Publish | DefaultRetryPolicy | +| pubsub - Subscribe | DefaultComponentInboundRetryPolicy | +| statestore | DefaultStatestoreComponentOutboundRetryPolicy | +| actorstore | fastRetries | +| EventActor | retryForever | +| SummaryActor | DefaultActorRetryPolicy | + +## Next steps + +[Learn how to override default retry policies.]({{< ref override-default-retries.md >}}) + +## Related links + +Try out one of the Resiliency quickstarts: +- [Resiliency: Service-to-service]({{< ref resiliency-serviceinvo-quickstart.md >}}) +- [Resiliency: State Management]({{< ref resiliency-state-quickstart.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/operations/resiliency/policies/retries/_index.md b/daprdocs/content/en/operations/resiliency/policies/retries/_index.md new file mode 100644 index 00000000000..8e0f5b27964 --- /dev/null +++ b/daprdocs/content/en/operations/resiliency/policies/retries/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Retry and back-off resiliency policies" +linkTitle: "Retries" +weight: 20 +description: "Configure resiliency policies for retries and back-offs" +--- \ No newline at end of file diff --git a/daprdocs/content/en/operations/resiliency/policies/retries/override-default-retries.md b/daprdocs/content/en/operations/resiliency/policies/retries/override-default-retries.md new file mode 100644 index 00000000000..949c251f01d --- /dev/null +++ b/daprdocs/content/en/operations/resiliency/policies/retries/override-default-retries.md @@ -0,0 +1,51 @@ +--- +type: docs +title: "Override default retry resiliency policies" +linkTitle: "Override default retries" +weight: 20 +description: "Learn how to override the default retry resiliency policies for specific APIs" +--- + +Dapr provides [default retries]({{< ref default-policies.md >}}) for any unsuccessful request, such as failures and transient errors. Within a resiliency spec, you have the option to override Dapr's default retry logic by defining policies with reserved, named keywords. For example, defining a policy with the name `DaprBuiltInServiceRetries`, overrides the default retries for failures between sidecars via service-to-service requests. Policy overrides are not applied to specific targets. + +> Note: Although you can override default values with more robust retries, you cannot override with lesser values than the provided default value, or completely remove default retries. This prevents unexpected downtime. + +Below is a table that describes Dapr's default retries and the policy keywords to override them: + +| Capability | Override Keyword | Default Retry Behavior | Description | +| ------------------ | ------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | +| Service Invocation | DaprBuiltInServiceRetries | Per call retries are performed with a backoff interval of 1 second, up to a threshold of 3 times. | Sidecar-to-sidecar requests (a service invocation method call) that fail and result in a gRPC code `Unavailable` or `Unauthenticated` | +| Actors | DaprBuiltInActorRetries | Per call retries are performed with a backoff interval of 1 second, up to a threshold of 3 times. | Sidecar-to-sidecar requests (an actor method call) that fail and result in a gRPC code `Unavailable` or `Unauthenticated` | +| Actor Reminders | DaprBuiltInActorReminderRetries | Per call retries are performed with an exponential backoff with an initial interval of 500ms, up to a maximum of 60s for a duration of 15mins | Requests that fail to persist an actor reminder to a state store | +| Initialization Retries | DaprBuiltInInitializationRetries | Per call retries are performed 3 times with an exponential backoff, an initial interval of 500ms and for a duration of 10s | Failures when making a request to an application to retrieve a given spec. For example, failure to retrieve a subscription, component or resiliency specification | + + +The resiliency spec example below shows overriding the default retries for _all_ service invocation requests by using the reserved, named keyword 'DaprBuiltInServiceRetries'. + +Also defined is a retry policy called 'retryForever' that is only applied to the appB target. appB uses the 'retryForever' retry policy, while all other application service invocation retry failures use the overridden 'DaprBuiltInServiceRetries' default policy. + +```yaml +spec: + policies: + retries: + DaprBuiltInServiceRetries: # Overrides default retry behavior for service-to-service calls + policy: constant + duration: 5s + maxRetries: 10 + + retryForever: # A user defined retry policy replaces default retries. Targets rely solely on the applied policy. + policy: exponential + maxInterval: 15s + maxRetries: -1 # Retry indefinitely + + targets: + apps: + appB: # app-id of the target service + retry: retryForever +``` + +## Related links + +Try out one of the Resiliency quickstarts: +- [Resiliency: Service-to-service]({{< ref resiliency-serviceinvo-quickstart.md >}}) +- [Resiliency: State Management]({{< ref resiliency-state-quickstart.md >}}) diff --git a/daprdocs/content/en/operations/resiliency/policies/retries/retries-overview.md b/daprdocs/content/en/operations/resiliency/policies/retries/retries-overview.md new file mode 100644 index 00000000000..121f5ba027c --- /dev/null +++ b/daprdocs/content/en/operations/resiliency/policies/retries/retries-overview.md @@ -0,0 +1,153 @@ +--- +type: docs +title: "Retry resiliency policies" +linkTitle: "Overview" +weight: 10 +description: "Configure resiliency policies for retries" +--- + +Requests can fail due to transient errors, like encountering network congestion, reroutes to overloaded instances, and more. Sometimes, requests can fail due to other resiliency policies set in place, like triggering a defined timeout or circuit breaker policy. + +In these cases, configuring `retries` can either: +- Send the same request to a different instance, or +- Retry sending the request after the condition has cleared. + +Retries and timeouts work together, with timeouts ensuring your system fails fast when needed, and retries recovering from temporary glitches. + +Dapr provides [default resiliency policies]({{< ref default-policies.md >}}), which you can [overwrite with user-defined retry policies.]({{< ref override-default-retries.md >}}) + +{{% alert title="Important" color="warning" %}} +Each [pub/sub component]({{< ref supported-pubsub >}}) has its own built-in retry behaviors. Explicity applying a Dapr resiliency policy doesn't override these implicit retry policies. Rather, the resiliency policy augments the built-in retry, which can cause repetitive clustering of messages. +{{% /alert %}} + +## Retry policy format + +**Example 1** + +```yaml +spec: + policies: + # Retries are named templates for retry configurations and are instantiated for life of the operation. + retries: + pubsubRetry: + policy: constant + duration: 5s + maxRetries: 10 + + retryForever: + policy: exponential + maxInterval: 15s + maxRetries: -1 # Retry indefinitely +``` + +**Example 2** + +```yaml +spec: + policies: + retries: + retry5xxOnly: + policy: constant + duration: 5s + maxRetries: 3 + matching: + httpStatusCodes: "429,500-599" # retry the HTTP status codes in this range. All others are not retried. + gRPCStatusCodes: "1-4,8-11,13,14" # retry gRPC status codes in these ranges and separate single codes. +``` + +## Spec metadata + +The following retry options are configurable: + +| Retry option | Description | +| ------------ | ----------- | +| `policy` | Determines the back-off and retry interval strategy. Valid values are `constant` and `exponential`.
Defaults to `constant`. | +| `duration` | Determines the time interval between retries. Only applies to the `constant` policy.
Valid values are of the form `200ms`, `15s`, `2m`, etc.
Defaults to `5s`.| +| `maxInterval` | Determines the maximum interval between retries to which the [`exponential` back-off policy](#exponential-back-off-policy) can grow.
Additional retries always occur after a duration of `maxInterval`. Defaults to `60s`. Valid values are of the form `5s`, `1m`, `1m30s`, etc | +| `maxRetries` | The maximum number of retries to attempt.
`-1` denotes an unlimited number of retries, while `0` means the request will not be retried (essentially behaving as if the retry policy were not set).
Defaults to `-1`. | +| `matching.httpStatusCodes` | Optional: a comma-separated string of [HTTP status codes or code ranges to retry](#retry-status-codes). Status codes not listed are not retried.
Valid values: 100-599, [Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
Format: `` or range `-`
Example: "429,501-503"
Default: empty string `""` or field is not set. Retries on all HTTP errors. | +| `matching.gRPCStatusCodes` | Optional: a comma-separated string of [gRPC status codes or code ranges to retry](#retry-status-codes). Status codes not listed are not retried.
Valid values: 0-16, [Reference](https://grpc.io/docs/guides/status-codes/)
Format: `` or range `-`
Example: "4,8,14"
Default: empty string `""` or field is not set. Retries on all gRPC errors. | + + +## Exponential back-off policy + +The exponential back-off window uses the following formula: + +``` +BackOffDuration = PreviousBackOffDuration * (Random value from 0.5 to 1.5) * 1.5 +if BackOffDuration > maxInterval { + BackoffDuration = maxInterval +} +``` + +## Retry status codes + +When applications span multiple services, especially on dynamic environments like Kubernetes, services can disappear for all kinds of reasons and network calls can start hanging. Status codes provide a glimpse into our operations and where they may have failed in production. + +### HTTP + +The following table includes some examples of HTTP status codes you may receive and whether you should or should not retry certain operations. + +| HTTP Status Code | Retry Recommended? | Description | +| ------------------------- | ---------------------- | ---------------------------- | +| 404 Not Found | ❌ No | The resource doesn't exist. | +| 400 Bad Request | ❌ No | Your request is invalid. | +| 401 Unauthorized | ❌ No | Try getting new credentials. | +| 408 Request Timeout | ✅ Yes | The server timed out waiting for the request. | +| 429 Too Many Requests | ✅ Yes | (Respect the `Retry-After` header, if present). | +| 500 Internal Server Error | ✅ Yes | The server encountered an unexpected condition. | +| 502 Bad Gateway | ✅ Yes | A gateway or proxy received an invalid response. | +| 503 Service Unavailable | ✅ Yes | Service might recover. | +| 504 Gateway Timeout | ✅ Yes | Temporary network issue. | + +### gRPC + +The following table includes some examples of gRPC status codes you may receive and whether you should or should not retry certain operations. + +| gRPC Status Code | Retry Recommended? | Description | +| ------------------------- | ----------------------- | ---------------------------- | +| Code 1 CANCELLED | ❌ No | N/A | +| Code 3 INVALID_ARGUMENT | ❌ No | N/A | +| Code 4 DEADLINE_EXCEEDED | ✅ Yes | Retry with backoff | +| Code 5 NOT_FOUND | ❌ No | N/A | +| Code 8 RESOURCE_EXHAUSTED | ✅ Yes | Retry with backoff | +| Code 14 UNAVAILABLE | ✅ Yes | Retry with backoff | + +### Retry filter based on status codes + +The retry filter enables granular control over retry policies by allowing users to specify HTTP and gRPC status codes or ranges for which retries should apply. + +```yml +spec: + policies: + retries: + retry5xxOnly: + # ... + matching: + httpStatusCodes: "429,500-599" # retry the HTTP status codes in this range. All others are not retried. + gRPCStatusCodes: "4,8-11,13,14" # retry gRPC status codes in these ranges and separate single codes. +``` + +{{% alert title="Note" color="primary" %}} +Field values for status codes must follow the format specified above. An incorrectly formatted value produces an error log ("Could not read resiliency policy") and the `daprd` startup sequence will proceed. +{{% /alert %}} + +## Demo + +Watch a demo presented during [Diagrid's Dapr v1.15 celebration](https://www.diagrid.io/videos/dapr-1-15-deep-dive) to see how to set retry status code filters using Diagrid Conductor + + + +## Next steps + +- [Learn how to override default retry policies for specific APIs.]({[< ref override-default-retries.md >]}) +- [Learn how to target your retry policies from the resiliency spec.]({{< ref targets.md >}}) +- Learn more about: + - [Timeout policies]({{< ref timeouts.md >}}) + - [Circuit breaker policies]({{< ref circuit-breakers.md >}}) + +## Related links + +Try out one of the Resiliency quickstarts: +- [Resiliency: Service-to-service]({{< ref resiliency-serviceinvo-quickstart.md >}}) +- [Resiliency: State Management]({{< ref resiliency-state-quickstart.md >}}) diff --git a/daprdocs/content/en/operations/resiliency/policies/timeouts.md b/daprdocs/content/en/operations/resiliency/policies/timeouts.md new file mode 100644 index 00000000000..619be3db553 --- /dev/null +++ b/daprdocs/content/en/operations/resiliency/policies/timeouts.md @@ -0,0 +1,50 @@ +--- +type: docs +title: "Timeout resiliency policies" +linkTitle: "Timeouts" +weight: 10 +description: "Configure resiliency policies for timeouts" +--- + +Network calls can fail for many reasons, causing your application to wait indefinitely for responses. By setting a timeout duration, you can cut off those unresponsive services, freeing up resources to handle new requests. + +Timeouts are optional policies that can be used to early-terminate long-running operations. Set a realistic timeout duration that reflects actual response times in production. If you've exceeded a timeout duration: + +- The operation in progress is terminated (if possible). +- An error is returned. + +## Timeout policy format + +```yaml +spec: + policies: + # Timeouts are simple named durations. + timeouts: + timeoutName: timeout1 + general: 5s + important: 60s + largeResponse: 10s +``` + +### Spec metadata + +| Field | Details | Example | +| timeoutName | Name of the timeout policy | `timeout1` | +| general | Time duration for timeouts marked as "general". Uses Go's [time.ParseDuration](https://pkg.go.dev/time#ParseDuration) format. No set maximum value. | `15s`, `2m`, `1h30m` | +| important | Time duration for timeouts marked as "important". Uses Go's [time.ParseDuration](https://pkg.go.dev/time#ParseDuration) format. No set maximum value. | `15s`, `2m`, `1h30m` | +| largeResponse | Time duration for timeouts awaiting a large response. Uses Go's [time.ParseDuration](https://pkg.go.dev/time#ParseDuration) format. No set maximum value. | `15s`, `2m`, `1h30m` | + +> If you don't specify a timeout value, the policy does not enforce a time and defaults to whatever you set up per the request client. + +## Next steps + +- [Learn more about default resiliency policies]({{< ref default-policies.md >}}) +- Learn more about: + - [Retry policies]({{< ref retries-overview.md >}}) + - [Circuit breaker policies]({{< ref circuit-breakers.md >}}) + +## Related links + +Try out one of the Resiliency quickstarts: +- [Resiliency: Service-to-service]({{< ref resiliency-serviceinvo-quickstart.md >}}) +- [Resiliency: State Management]({{< ref resiliency-state-quickstart.md >}}) diff --git a/daprdocs/content/en/operations/resiliency/resiliency-overview.md b/daprdocs/content/en/operations/resiliency/resiliency-overview.md index e7564757a88..c92a2c94fff 100644 --- a/daprdocs/content/en/operations/resiliency/resiliency-overview.md +++ b/daprdocs/content/en/operations/resiliency/resiliency-overview.md @@ -6,25 +6,32 @@ weight: 100 description: "Configure Dapr retries, timeouts, and circuit breakers" --- -Dapr provides a capability for defining and applying fault tolerance resiliency policies via a [resiliency spec]({{< ref "resiliency-overview.md#complete-example-policy" >}}). Resiliency specs are saved in the same location as components specs and are applied when the Dapr sidecar starts. The sidecar determines how to apply resiliency policies to your Dapr API calls. In self-hosted mode, the resiliency spec must be named `resiliency.yaml`. In Kubernetes Dapr finds the named resiliency specs used by your application. Within the resiliency spec, you can define policies for popular resiliency patterns, such as: - -- [Timeouts]({{< ref "policies.md#timeouts" >}}) -- [Retries/back-offs]({{< ref "policies.md#retries" >}}) -- [Circuit breakers]({{< ref "policies.md#circuit-breakers" >}}) - -Policies can then be applied to [targets]({{< ref "targets.md" >}}), which include: - -- [Apps]({{< ref "targets.md#apps" >}}) via service invocation -- [Components]({{< ref "targets.md#components" >}}) -- [Actors]({{< ref "targets.md#actors" >}}) - -Additionally, resiliency policies can be [scoped to specific apps]({{< ref "component-scopes.md#application-access-to-components-with-scopes" >}}). - -## Demo video +Dapr provides the capability for defining and applying fault tolerance resiliency policies via a [resiliency spec]({{< ref "resiliency-overview.md#complete-example-policy" >}}). Resiliency specs are saved in the same location as components specs and are applied when the Dapr sidecar starts. The sidecar determines how to apply resiliency policies to your Dapr API calls. +- **In self-hosted mode:** The resiliency spec must be named `resiliency.yaml`. +- **In Kubernetes:** Dapr finds the named resiliency specs used by your application. + +## Policies + +You can configure Dapr resiliency policies with the following parts: +- Metadata defining where the policy applies (like namespace and scope) +- Policies specifying the resiliency name and behaviors, like: + - [Timeouts]({{< ref timeouts.md >}}) + - [Retries]({{< ref retries-overview.md >}}) + - [Circuit breakers]({{< ref circuit-breakers.md >}}) +- Targets determining which interactions these policies act on, including: + - [Apps]({{< ref "targets.md#apps" >}}) via service invocation + - [Components]({{< ref "targets.md#components" >}}) + - [Actors]({{< ref "targets.md#actors" >}}) + +Once defined, you can apply this configuration to your local Dapr components directory, or to your Kubernetes cluster using: + +```bash +kubectl apply -f .yaml +``` -Learn more about [how to write resilient microservices with Dapr](https://youtu.be/uC-4Q5KFq98?si=JSUlCtcUNZLBM9rW). +Additionally, you can scope resiliency policies [to specific apps]({{< ref "component-scopes.md#application-access-to-components-with-scopes" >}}). - +> See [known limitations](#limitations). ## Resiliency policy structure @@ -166,7 +173,11 @@ spec: circuitBreaker: pubsubCB ``` -## Related links +## Limitations + +- **Service invocation via gRPC:** Currently, resiliency policies are not supported for service invocation via gRPC. + +## Demos Watch this video for how to use [resiliency](https://www.youtube.com/watch?t=184&v=7D6HOU3Ms6g&feature=youtu.be): @@ -174,11 +185,20 @@ Watch this video for how to use [resiliency](https://www.youtube.com/watch?t=184 +Learn more about [how to write resilient microservices with Dapr](https://youtu.be/uC-4Q5KFq98?si=JSUlCtcUNZLBM9rW). + + + ## Next steps Learn more about resiliency policies and targets: - - [Policies]({{< ref "policies.md" >}}) + - Policies + - [Timeouts]({{< ref "timeouts.md" >}}) + - [Retries]({{< ref "retries-overview.md" >}}) + - [Circuit breakers]({{< ref circuit-breakers.md >}}) - [Targets]({{< ref "targets.md" >}}) + +## Related links Try out one of the Resiliency quickstarts: - [Resiliency: Service-to-service]({{< ref resiliency-serviceinvo-quickstart.md >}}) - [Resiliency: State Management]({{< ref resiliency-state-quickstart.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/zeebe-command.md b/daprdocs/content/en/reference/components-reference/supported-bindings/zeebe-command.md index 780bfaebefe..76def5a6b42 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/zeebe-command.md +++ b/daprdocs/content/en/reference/components-reference/supported-bindings/zeebe-command.md @@ -675,7 +675,12 @@ To perform a `throw-error` operation, invoke the Zeebe command binding with a `P "data": { "jobKey": 2251799813686172, "errorCode": "product-fetch-error", - "errorMessage": "The product could not be fetched" + "errorMessage": "The product could not be fetched", + "variables": { + "productId": "some-product-id", + "productName": "some-product-name", + "productKey": "some-product-key" + } }, "operation": "throw-error" } @@ -686,6 +691,11 @@ The data parameters are: - `jobKey` - the unique job identifier, as obtained when activating the job - `errorCode` - the error code that will be matched with an error catch event - `errorMessage` - (optional) an error message that provides additional context +- `variables` - (optional) JSON document that will instantiate the variables at the local scope of the + job's associated task; it must be a JSON object, as variables will be mapped in a + key-value fashion. e.g. { "a": 1, "b": 2 } will create two variables, named "a" and + "b" respectively, with their associated values. [{ "a": 1, "b": 2 }] would not be a + valid argument, as the root of the JSON document is an array and not an object. ##### Response diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md index 2e2962d6855..fdaca4eca90 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md @@ -12,7 +12,7 @@ no_list: true The following table lists publish and subscribe brokers supported by the Dapr pub/sub building block. [Learn how to set up different brokers for Dapr publish and subscribe.]({{< ref setup-pubsub.md >}}) {{% alert title="Pub/sub component retries vs inbound resiliency" color="warning" %}} -Each pub/sub component has its own built-in retry behaviors. Before explicity applying a [Dapr resiliency policy]({{< ref "policies.md" >}}), make sure you understand the implicit retry policy of the pub/sub component you're using. Instead of overriding these built-in retries, Dapr resiliency augments them, which can cause repetitive clustering of messages. +Each pub/sub component has its own built-in retry behaviors, unique to the message broker solution and unrelated to Dapr. Before explicity applying a [Dapr resiliency policy]({{< ref "resiliency-overview.md" >}}), make sure you understand the implicit retry policy of the pub/sub component you're using. Instead of overriding these built-in retries, Dapr resiliency augments them, which can cause repetitive clustering of messages. {{% /alert %}} diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt.md index 8c4b20e2d8c..454c6ac41a2 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt.md @@ -54,13 +54,13 @@ The above example uses secrets as plain strings. It is recommended to use a secr The MQTT pub/sub component has no built-in support for retry strategies. This means that the sidecar sends a message to the service only once. If the service marks the message as not processed, the message won't be acknowledged back to the broker. Only if broker resends the message, would it would be retried. -To make Dapr use more spohisticated retry policies, you can apply a [retry resiliency policy]({{< ref "policies.md#retries" >}}) to the MQTT pub/sub component. +To make Dapr use more spohisticated retry policies, you can apply a [retry resiliency policy]({{< ref "retries-overview.md" >}}) to the MQTT pub/sub component. There is a crucial difference between the two ways of retries: 1. Re-delivery of unacknowledged messages is completely dependent on the broker. Dapr does not guarantee it. Some brokers like [emqx](https://www.emqx.io/), [vernemq](https://vernemq.com/) etc. support it but it not a part of [MQTT3 spec](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718103). -2. Using a [retry resiliency policy]({{< ref "policies.md#retries" >}}) makes the same Dapr sidecar retry redelivering the messages. So it is the same Dapr sidecar and the same app receiving the same message. +2. Using a [retry resiliency policy]({{< ref "retries-overview.md" >}}) makes the same Dapr sidecar retry redelivering the messages. So it is the same Dapr sidecar and the same app receiving the same message. ### Communication using TLS diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md index 3e94c2fc725..5dc9261a7dd 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md @@ -167,7 +167,7 @@ spec: ### Enabling message delivery retries -The Pulsar pub/sub component has no built-in support for retry strategies. This means that sidecar sends a message to the service only once and is not retried in case of failures. To make Dapr use more spohisticated retry policies, you can apply a [retry resiliency policy]({{< ref "policies.md#retries" >}}) to the Pulsar pub/sub component. Note that it will be the same Dapr sidecar retrying the redelivery the message to the same app instance and not other instances. +The Pulsar pub/sub component has no built-in support for retry strategies. This means that sidecar sends a message to the service only once and is not retried in case of failures. To make Dapr use more spohisticated retry policies, you can apply a [retry resiliency policy]({{< ref "retries-overview.md" >}}) to the Pulsar pub/sub component. Note that it will be the same Dapr sidecar retrying the redelivery the message to the same app instance and not other instances. ### Delay queue diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md index bf8ac3f271f..f6569a8f88e 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md @@ -166,7 +166,7 @@ Note that while the `caCert` and `clientCert` values may not be secrets, they ca The RabbitMQ pub/sub component has no built-in support for retry strategies. This means that the sidecar sends a message to the service only once. When the service returns a result, the message will be marked as consumed regardless of whether it was processed correctly or not. Note that this is common among all Dapr PubSub components and not just RabbitMQ. Dapr can try redelivering a message a second time, when `autoAck` is set to `false` and `requeueInFailure` is set to `true`. -To make Dapr use more sophisticated retry policies, you can apply a [retry resiliency policy]({{< ref "policies.md#retries" >}}) to the RabbitMQ pub/sub component. +To make Dapr use more sophisticated retry policies, you can apply a [retry resiliency policy]({{< ref "retries-overview.md" >}}) to the RabbitMQ pub/sub component. There is a crucial difference between the two ways to retry messages: diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v1.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v1.md index 53e4c0e75d1..3a53c1117a5 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v1.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v1.md @@ -52,7 +52,7 @@ spec: # Controls the default mode for executing queries. (optional) #- name: queryExecMode # value: "" - # Uncomment this if you wish to use PostgreSQL as a state store for actors (optional) + # Uncomment this if you wish to use PostgreSQL as a state store for actors or workflows (optional) #- name: actorStateStore # value: "true" ``` diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v2.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v2.md index d4e21f17ba8..db5d7eddfef 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v2.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql-v2.md @@ -52,7 +52,7 @@ spec: # Controls the default mode for executing queries. (optional) #- name: queryExecMode # value: "" - # Uncomment this if you wish to use PostgreSQL as a state store for actors (optional) + # Uncomment this if you wish to use PostgreSQL as a state store for actors or workflows (optional) #- name: actorStateStore # value: "true" ``` diff --git a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md index d307b70b4d4..c7bc15553ff 100644 --- a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md +++ b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md @@ -64,7 +64,7 @@ targets: # Required | Field | Required | Details | Example | |--------------------|:--------:|---------|---------| -| policies | Y | The configuration of resiliency policies, including:
  • `timeouts`
  • `retries`
  • `circuitBreakers`

[See more examples with all of the built-in policies]({{< ref policies.md >}}) | timeout: `general`
retry: `retryForever`
circuit breaker: `simpleCB` | +| policies | Y | The configuration of resiliency policies, including:
  • `timeouts`
  • `retries`
  • `circuitBreakers`

[See more examples with all of the built-in policies]({{< ref resiliency-overview.md >}}) | timeout: `general`
retry: `retryForever`
circuit breaker: `simpleCB` | | targets | Y | The configuration for the applications, actors, or components that use the resiliency policies.
[See more examples in the resiliency targets guide]({{< ref targets.md >}}) | `apps`
`components`
`actors` | diff --git a/daprdocs/package-lock.json b/daprdocs/package-lock.json index 6bcdae97208..e7dec5f674f 100644 --- a/daprdocs/package-lock.json +++ b/daprdocs/package-lock.json @@ -720,9 +720,15 @@ } }, "node_modules/nanoid": { - "version": "3.3.2", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.2.tgz", - "integrity": "sha512-CuHBogktKwpm5g2sRgv83jEy2ijFzBwMoYA60orPDR7ynsLijJDqgsi4RDGj3OJpy3Ieb+LYwiRmIOGyytgITA==", + "version": "3.3.8", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.8.tgz", + "integrity": "sha512-WNLf5Sd8oZxOm+TzppcYk8gVOgP+l58xNy58D0nbUnOxOWRWvlcCV4kUF7ltmI6PsrLl/BgKEyS4mqsGChFN0w==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], "bin": { "nanoid": "bin/nanoid.cjs" }, diff --git a/daprdocs/static/images/resiliency_inbound.png b/daprdocs/static/images/resiliency_inbound.png index f3ba94de7ed..43ddce30e8c 100644 Binary files a/daprdocs/static/images/resiliency_inbound.png and b/daprdocs/static/images/resiliency_inbound.png differ diff --git a/daprdocs/static/images/resiliency_outbound.png b/daprdocs/static/images/resiliency_outbound.png index 73c7e0bbeed..e7e810c3cf8 100644 Binary files a/daprdocs/static/images/resiliency_outbound.png and b/daprdocs/static/images/resiliency_outbound.png differ diff --git a/daprdocs/static/images/resiliency_pubsub.png b/daprdocs/static/images/resiliency_pubsub.png index d5a6c990429..50cf7982b12 100644 Binary files a/daprdocs/static/images/resiliency_pubsub.png and b/daprdocs/static/images/resiliency_pubsub.png differ diff --git a/daprdocs/static/images/resiliency_svc_invocation.png b/daprdocs/static/images/resiliency_svc_invocation.png index a46316b24c5..b0c23e16291 100644 Binary files a/daprdocs/static/images/resiliency_svc_invocation.png and b/daprdocs/static/images/resiliency_svc_invocation.png differ diff --git a/translations/docs-zh b/translations/docs-zh index 864b558a7c2..8bc9e26a7f2 160000 --- a/translations/docs-zh +++ b/translations/docs-zh @@ -1 +1 @@ -Subproject commit 864b558a7c253f037f4c8bd21a579a5dab5e1456 +Subproject commit 8bc9e26a7f2be45602974c96df024fdd2c1539e3