From ac44c299097a70f4b63bda0b2cda16b582c9f0b3 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 16 Dec 2020 17:21:28 -0800 Subject: [PATCH 1/9] Update pull_request_template.md --- .github/pull_request_template.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1c4b36b52..5abcc9a8b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,8 +1,13 @@ Thank you for helping make the Dapr documentation better! -If you are a new contributor, please see the [this contribution guidance](https://github.com/dapr/docs/blob/master/contributing/README.md) which helps keep the Dapr documentation readable, consistent and useful for Dapr users. +**Please follow this checklist before submitting:** -If you are contributing a new authored "How To" article, [this template](https://github.com/dapr/docs/blob/master/contributing/howto-template.md) was created to assist you. +- [ ] [Read the contribution guide](https://docs.dapr.io/contributing/contributing-docs/) +- [ ] Commands include options for Linux, MacOS, and Windows within codetabs +- [ ] New file and folder names are globally unique +- [ ] Page references use shortcodes instead of markdown or URL links +- [ ] Images use HTML style and have alternative text +- [ ] Places where multiple code/command options are given have codetabs In addition, please fill out the following to help reviewers understand this pull request: From c35ea4edef1dc4f109a9b300e5ab06cc9c076293 Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 17 Dec 2020 13:24:32 -0800 Subject: [PATCH 2/9] Fix link in get How To: Retrieve a secret Link was referencing old github file structure instead of using the hugo link method. https://github.com/dapr/docs/issues/957 --- .../building-blocks/secrets/howto-secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md b/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md index 512704261..21e679fec 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md +++ b/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md @@ -36,7 +36,7 @@ Watch this [video](https://www.youtube.com/watch?v=OtbYCBt9C34&feature=youtu.be& Now that the secret store is set up, you can call Dapr to get the secrets for a given key for a specific secret store. -For a full API reference, go [here](https://github.com/dapr/docs/blob/master/reference/api/secrets_api.md). +For a full API reference, go [here]({{< ref "/operations/components/setup-bindings/supported-bindings/blobstorage.md" >}}). Here are a few examples in different programming languages: From 016d9854f9526c0a78f7fe9abd55966b4d5566a4 Mon Sep 17 00:00:00 2001 From: Mark Chmarny Date: Thu, 17 Dec 2020 13:33:35 -0800 Subject: [PATCH 3/9] Clarifies pub/sub concepts, more doc links --- .../building-blocks/pubsub/pubsub-overview.md | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md index 09112ba7f..0d116e9f7 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md @@ -8,44 +8,30 @@ description: "Overview of the Dapr Pub/Sub building block" ## Introduction -The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows your microservices to communicate with each other purely by sending messages. In this system, the **producer** of a message sends it to a **topic**, with no knowledge of what service will receive the message. A messages can even be sent if there's no consumer for it. +The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows microservices to communicate with each other using messages. The **producer** sends messages to a **topic** without knowledge of what application will receive them. Similarly, a **consumer** will subscribe to the topic and receive its messages without any knowledge of what application producerd these messages. This pattern is especially useful when you need to decouple microservices from one another. -Similarly, a **consumer** will receive messages from a topic without knowledge of what producer sent it. This pattern is especially useful when you need to decouple microservices from one another. - -Dapr provides a publish/subscribe API that provides at-least-once guarantees and integrates with various message brokers implementations. These implementations are pluggable, and developed outside of the Dapr runtime in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub). +The publish/subscribe API in Dapr provides at-least-once guarantee and integrates with various message brokers and queing systems. The specific implementation to your application is pluggable and configured externally at runtime. This approach removes dependancy from your application and, as a result, makes your application more portable. The complete list of available publish/subscribe implementations is available in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub) repository. ## Features ### Publish/Subscribe API -The API for Publish/Subscribe can be found in the [spec repo]({{< ref pubsub_api.md >}}). +The publish/subscribe API is located in the [spec repo]({{< ref pubsub_api.md >}}). -### At-Least-Once guarantee +### Message Format -Dapr guarantees At-Least-Once semantics for message delivery. -That means that when an application publishes a message to a topic using the Publish/Subscribe API, it can assume the message is delivered at least once to any subscriber when the response status code from that endpoint is `200`, or returns no error if using the gRPC client. +To enable message routing and to provide additonal context with each message Dapr uses the [CloudEvents 1.0 specification](https://github.com/cloudevents/spec/tree/v1.0) as its message format. Any message sent by an paylication to a topic using Dapr will autoamtically be "wrapped" in Cloud Events envelope, using `Content-Type` header value for `datacontenttype` attribute. -### Consumer groups and multiple instances +Dapr implements the following Cloud Events fields: -The burden of dealing with concepts like consumer groups and multiple instances inside consumer groups is all handled autoamtically by Dapr: - -* When multiple instances of the same application (same IDs) subscribe to a topic, Dapr will deliver each message to only one instance of that application. -* If two different applications (different IDs) subscribe to the same topic, Dapr will deliver each message to only one instance of each application. - -### Cloud events - -Dapr follows the [CloudEvents 1.0 Spec](https://github.com/cloudevents/spec/tree/v1.0) and wraps any payload sent to a topic inside a Cloud Events envelope, using `Content-Type` header value for `datacontenttype` attribute. - -The following fields from the Cloud Events spec are implemented with Dapr: -- `id` -- `source` -- `specversion` -- `type` -- `datacontenttype` (Optional) - -> Starting with Dapr v0.9, Dapr no longer wraps published content into CloudEvent if the published payload itself is already in CloudEvent format. +* `id` +* `source` +* `specversion` +* `type` +* `datacontenttype` (Optional) The following example shows an XML content in CloudEvent v1.0 serialized as JSON: + ```json { "specversion" : "1.0", @@ -59,9 +45,23 @@ The following example shows an XML content in CloudEvent v1.0 serialized as JSON } ``` +> Starting with v0.9 release, Dapr no longer wraps published content into CloudEvent if the published payload is already in the CloudEvent format. + +### Message Delivery + +In principle, Dapr considers message sucessfully delivered when the subscriber does not respond with an error after processing the message. For more granular control, Dapr's publish/subscribe API also provides explicit statuses, defined in the respons paylaod, which the subscriber can use to indicate the specific handling instructions to Dapr (e.g. `RETRY` or `DROP`). For more information message routing see [Dapr publish/subscribe API documentation] (https://docs.dapr.io/reference/api/pubsub_api/#provide-routes-for-dapr-to-deliver-topic-events) + +### At-Least-Once guarantee + +Dapr guarantees at-least-once semantics for message delivery. That means that when an application publishes a message to a topic using the publish/subscribe API, Dapr ensures that this message will be delivered at least once to every subscriber. + +### Consumer groups and multiple instances + +The burden of dealing with concepts like consumer groups and multiple application instances using single consumer group is all handled autoamtically by Dapr. When multiple instances of the same application (same IDs) subscribe to a topic, Dapr delivers each message to only one instance of that application. Similarly, if two different applications (different IDs) subscribe to the same topic, Dapr will deliver each message to only one instance of each application. + ### Topic scoping -Limit which topics applications are able to publish/subscibe to in order to limit access to potentially sensitive data streams. Read [Pub/Sub scoping]({{< ref pubsub-scopes.md >}}) for more information. +By default, all topics backing the Dapr publish/subscribe component (e.g. Kafka, Redis, RabbitMQ) are available to every applicatoin configured with that component. To limit which application can publish or subscibe to which topic, Dapr provides topic scopping. See [publish/subscribe topic scoping]({{< ref pubsub-scopes.md >}}) for more information. ## Next steps From 21d14f956b868e7744082f6f94dc87b1e0660457 Mon Sep 17 00:00:00 2001 From: Mark Chmarny Date: Thu, 17 Dec 2020 13:43:49 -0800 Subject: [PATCH 4/9] Adds declarative subscription --- .../building-blocks/pubsub/pubsub-overview.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md index 0d116e9f7..8ea4b9902 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md @@ -47,7 +47,11 @@ The following example shows an XML content in CloudEvent v1.0 serialized as JSON > Starting with v0.9 release, Dapr no longer wraps published content into CloudEvent if the published payload is already in the CloudEvent format. -### Message Delivery +### Message Subscription + +Dapr allows two methods by which you can subscribe to topics: declarative, where subscription is defined in an external file, and programmatic, where subscription is defined in the user code. For more information see Dapr's documentation on [creating subscription](https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-publish-subscribe/#step-2-subscribe-to-topics). + +### Message Delivery In principle, Dapr considers message sucessfully delivered when the subscriber does not respond with an error after processing the message. For more granular control, Dapr's publish/subscribe API also provides explicit statuses, defined in the respons paylaod, which the subscriber can use to indicate the specific handling instructions to Dapr (e.g. `RETRY` or `DROP`). For more information message routing see [Dapr publish/subscribe API documentation] (https://docs.dapr.io/reference/api/pubsub_api/#provide-routes-for-dapr-to-deliver-topic-events) From f8eda4cd32ff97d05061be41d5277f0e66c1df9b Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Thu, 17 Dec 2020 14:51:31 -0800 Subject: [PATCH 5/9] Adding embedded Dapr video to overview --- daprdocs/content/en/concepts/overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/concepts/overview.md b/daprdocs/content/en/concepts/overview.md index 7031fd901..fb1a029b9 100644 --- a/daprdocs/content/en/concepts/overview.md +++ b/daprdocs/content/en/concepts/overview.md @@ -7,7 +7,9 @@ description: > Introduction to the Distributed Application Runtime --- -Dapr is a portable, event-driven runtime that makes it easy for enterprise developers to build resilient, stateless and stateful microservice applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks. +Dapr is a portable, event-driven runtime that makes it easy for any developer to build resilient, stateless and stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks. + +{{< youtube 9o9iDAgYBA8 >}} ## Any language, any framework, anywhere From 6ab4d3bf8ad9ccc59b46891c850c93d421b15e42 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Thu, 17 Dec 2020 14:57:16 -0800 Subject: [PATCH 6/9] Update link --- .../building-blocks/secrets/howto-secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md b/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md index 21e679fec..a73f15fe9 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md +++ b/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md @@ -36,7 +36,7 @@ Watch this [video](https://www.youtube.com/watch?v=OtbYCBt9C34&feature=youtu.be& Now that the secret store is set up, you can call Dapr to get the secrets for a given key for a specific secret store. -For a full API reference, go [here]({{< ref "/operations/components/setup-bindings/supported-bindings/blobstorage.md" >}}). +For a full API reference, go [here]({{< ref secrets_api.md >}}). Here are a few examples in different programming languages: From 7d92fe92ab9bac4f16b9819f44e6ec5cee6c9855 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Thu, 17 Dec 2020 15:15:14 -0800 Subject: [PATCH 7/9] Grammer --- .../building-blocks/pubsub/pubsub-overview.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md index 8ea4b9902..340bb84dc 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md @@ -8,19 +8,19 @@ description: "Overview of the Dapr Pub/Sub building block" ## Introduction -The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows microservices to communicate with each other using messages. The **producer** sends messages to a **topic** without knowledge of what application will receive them. Similarly, a **consumer** will subscribe to the topic and receive its messages without any knowledge of what application producerd these messages. This pattern is especially useful when you need to decouple microservices from one another. +The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows microservices to communicate with each other using messages. The **producer** sends messages to a **topic** without knowledge of what application will receive them. Similarly, a **consumer** will subscribe to the topic and receive its messages without any knowledge of what application produced these messages. This pattern is especially useful when you need to decouple microservices from one another. -The publish/subscribe API in Dapr provides at-least-once guarantee and integrates with various message brokers and queing systems. The specific implementation to your application is pluggable and configured externally at runtime. This approach removes dependancy from your application and, as a result, makes your application more portable. The complete list of available publish/subscribe implementations is available in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub) repository. +The publish/subscribe API in Dapr provides an at-least-once guarantee and integrates with various message brokers and queuing systems. The specific implementation to your application is pluggable and configured externally at runtime. This approach removes the dependency from your application and, as a result, makes your application more portable. The complete list of available publish/subscribe implementations is available [here]({{< ref supported-pubsub >}}). ## Features ### Publish/Subscribe API -The publish/subscribe API is located in the [spec repo]({{< ref pubsub_api.md >}}). +The publish/subscribe API is located in the [API reference]({{< ref pubsub_api.md >}}). ### Message Format -To enable message routing and to provide additonal context with each message Dapr uses the [CloudEvents 1.0 specification](https://github.com/cloudevents/spec/tree/v1.0) as its message format. Any message sent by an paylication to a topic using Dapr will autoamtically be "wrapped" in Cloud Events envelope, using `Content-Type` header value for `datacontenttype` attribute. +To enable message routing and to provide additonal context with each message Dapr uses the [CloudEvents 1.0 specification](https://github.com/cloudevents/spec/tree/v1.0) as its message format. Any message sent by an application to a topic using Dapr will automatically be "wrapped" in Cloud Events envelope, using `Content-Type` header value for `datacontenttype` attribute. Dapr implements the following Cloud Events fields: @@ -49,11 +49,11 @@ The following example shows an XML content in CloudEvent v1.0 serialized as JSON ### Message Subscription -Dapr allows two methods by which you can subscribe to topics: declarative, where subscription is defined in an external file, and programmatic, where subscription is defined in the user code. For more information see Dapr's documentation on [creating subscription](https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-publish-subscribe/#step-2-subscribe-to-topics). +Dapr allows two methods by which you can subscribe to topics: **declarative**, where a subscription is defined in an external file, and **programmatic**, where a subscription is defined in the user code. For more information see Dapr's documentation on [subscribing to a topic](https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-publish-subscribe/#step-2-subscribe-to-topics). ### Message Delivery -In principle, Dapr considers message sucessfully delivered when the subscriber does not respond with an error after processing the message. For more granular control, Dapr's publish/subscribe API also provides explicit statuses, defined in the respons paylaod, which the subscriber can use to indicate the specific handling instructions to Dapr (e.g. `RETRY` or `DROP`). For more information message routing see [Dapr publish/subscribe API documentation] (https://docs.dapr.io/reference/api/pubsub_api/#provide-routes-for-dapr-to-deliver-topic-events) +In principle, Dapr considers message successfully delivered when the subscriber responds with a non-error response after processing the message. For more granular control, Dapr's publish/subscribe API also provides explicit statuses, defined in the response payload, which the subscriber can use to indicate the specific handling instructions to Dapr (e.g. `RETRY` or `DROP`). For more information message routing see [Dapr publish/subscribe API documentation] ({{< ref "pubsub_api.md#provide-routes-for-dapr-to-deliver-topic-events" >}}) ### At-Least-Once guarantee @@ -61,13 +61,14 @@ Dapr guarantees at-least-once semantics for message delivery. That means that wh ### Consumer groups and multiple instances -The burden of dealing with concepts like consumer groups and multiple application instances using single consumer group is all handled autoamtically by Dapr. When multiple instances of the same application (same IDs) subscribe to a topic, Dapr delivers each message to only one instance of that application. Similarly, if two different applications (different IDs) subscribe to the same topic, Dapr will deliver each message to only one instance of each application. +The burden of dealing with concepts like consumer groups and multiple application instances using a single consumer group is all handled automatically by Dapr. When multiple instances of the same application (same IDs) subscribe to a topic, Dapr delivers each message to only one instance of that application. Similarly, if two different applications (different IDs) subscribe to the same topic, Dapr will deliver each message to only one instance of each application. ### Topic scoping -By default, all topics backing the Dapr publish/subscribe component (e.g. Kafka, Redis, RabbitMQ) are available to every applicatoin configured with that component. To limit which application can publish or subscibe to which topic, Dapr provides topic scopping. See [publish/subscribe topic scoping]({{< ref pubsub-scopes.md >}}) for more information. +By default, all topics backing the Dapr publish/subscribe component (e.g. Kafka, Redis, RabbitMQ) are available to every application configured with that component. To limit which application can publish or subscribe to topics, Dapr provides topic scoping. See [publish/subscribe topic scoping]({{< ref pubsub-scopes.md >}}) for more information. ## Next steps - Read the How-To guide on [publishing and subscribing]({{< ref howto-publish-subscribe.md >}}) - Learn about [Pub/Sub scopes]({{< ref pubsub-scopes.md >}}) +- Read the [API reference]({{< ref pubsub_api.md >}}) From 2194251f136f11dbd49ec36d6d56baf0b87f1d31 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Thu, 17 Dec 2020 15:16:45 -0800 Subject: [PATCH 8/9] typo --- .../building-blocks/pubsub/pubsub-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md index 340bb84dc..6e563b842 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md @@ -20,7 +20,7 @@ The publish/subscribe API is located in the [API reference]({{< ref pubsub_api.m ### Message Format -To enable message routing and to provide additonal context with each message Dapr uses the [CloudEvents 1.0 specification](https://github.com/cloudevents/spec/tree/v1.0) as its message format. Any message sent by an application to a topic using Dapr will automatically be "wrapped" in Cloud Events envelope, using `Content-Type` header value for `datacontenttype` attribute. +To enable message routing and to provide additional context with each message Dapr uses the [CloudEvents 1.0 specification](https://github.com/cloudevents/spec/tree/v1.0) as its message format. Any message sent by an application to a topic using Dapr will automatically be "wrapped" in Cloud Events envelope, using `Content-Type` header value for `datacontenttype` attribute. Dapr implements the following Cloud Events fields: From 4853b32da0c04360848ed95c42bd64939e7f86a2 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Thu, 17 Dec 2020 15:27:00 -0800 Subject: [PATCH 9/9] Update pull_request_template.md --- .github/pull_request_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5abcc9a8b..aa50e1dc1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,8 +13,8 @@ In addition, please fill out the following to help reviewers understand this pul ## Description -_Please explain the changes you've made_ + ## Issue reference -_Please reference the issue this PR will close: #[issue number]_ +