From d60eb81123fa699cb97aaf994816997fc60e43e2 Mon Sep 17 00:00:00 2001 From: joshvanl Date: Thu, 20 Jun 2024 14:35:21 +0100 Subject: [PATCH 1/9] Adds initial streaming subscriptions docs Signed-off-by: joshvanl --- .../pubsub/howto-publish-subscribe.md | 5 +- .../pubsub/pubsub-deadletter.md | 15 ++- .../building-blocks/pubsub/pubsub-overview.md | 3 +- .../pubsub/subscription-methods.md | 119 +++++++++++++++++- 4 files changed, 134 insertions(+), 8 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md index 0e53ba46906..a7ac09bfeb9 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md @@ -153,12 +153,13 @@ scopes: ## Subscribe to topics -Dapr provides two methods by which you can subscribe to topics: +Dapr provides three methods by which you can subscribe to topics: - **Declaratively**, where subscriptions are defined in an external file. +- **Streaming**, where subscriptions are defined in user code, - **Programmatically**, where subscriptions are defined in user code. -Learn more in the [declarative and programmatic subscriptions doc]({{< ref subscription-methods.md >}}). This example demonstrates a **declarative** subscription. +Learn more in the [declarative, streaming and programmatic subscriptions doc]({{< ref subscription-methods.md >}}). This example demonstrates a **declarative** subscription. Create a file named `subscription.yaml` and paste the following: 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 97c9a0db405..cd56b40864e 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 @@ -39,6 +39,17 @@ scopes: - checkout ``` +## Configuring a dead letter topic with a streaming subscription + +```go + var deadLetterTopic = "poisonMessages" + sub, err := cl.Subscribe(context.Background(), client.SubscriptionOptions{ + PubsubName: "pubsub", + Topic: "orders", + DeadLetterTopic: &deadLetterTopic, + }) +``` + ## Configuring a dead letter topic with programmatic subscription The JSON returned from the `/subscribe` endpoint shows how to configure a dead letter topic named `poisonMessages` for messages consumed from the `orders` topic. @@ -93,7 +104,7 @@ metadata: name: deadlettertopics spec: topic: poisonMessages - routes: + routes: rules: - match: path: /failedMessages @@ -112,4 +123,4 @@ Watch [this video for an overview of the dead letter topics](https://youtu.be/wL ## Next steps - For more information on resiliency policies, read [Resiliency overview]({{< ref resiliency-overview.md >}}). -- For more information on topic subscriptions, read [Declarative and programmatic subscription methods]({{< ref "pubsub-overview.md#message-subscription" >}}). +- For more information on topic subscriptions, read [Declarative, streaming and programmatic subscription methods]({{< ref "pubsub-overview.md#message-subscription" >}}). 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 a73f507a894..a5e692cd487 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 @@ -75,11 +75,12 @@ In principle, Dapr considers a message successfully delivered once the subscribe ### Receiving messages with topic subscriptions -Dapr applications can subscribe to published topics via two methods that support the same features: declarative and programmatic. +Dapr applications can subscribe to published topics via three methods that support the same features: declarative and programmatic. | Subscription method | Description | | ------------------- | ----------- | | **Declarative** | Subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | +| **Streaming** | Subscription is defined in the **user code**. Streaming subscriptions are dynamic in that they allow for adding or removing subscriptions at runtime. | | **Programmatic** | Subscription is defined in the **user code**. The programmatic approach implements the subscription in your code. | For more information, read [about the subscriptions in Subscription Methods]({{< ref subscription-methods.md >}}). diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md index 0bf43e4239e..9af884734a7 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md @@ -1,6 +1,6 @@ --- type: docs -title: "Declarative and programmatic subscription methods" +title: "Declarative, streaming and programmatic subscription methods" linkTitle: "Subscription methods" weight: 3000 description: "Learn more about the methods by which Dapr allows you to subscribe to topics." @@ -8,12 +8,13 @@ description: "Learn more about the methods by which Dapr allows you to subscribe ## Pub/sub API subscription methods -Dapr applications can subscribe to published topics via two methods that support the same features: declarative and programmatic. +Dapr applications can subscribe to published topics via three methods that support the same features: declarative and programmatic. | Subscription method | Description | | ------------------- | ----------- | | [**Declarative**]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) | Subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | -| [**Programmatic**]({{< ref "subscription-methods.md#programmatic-subscriptions" >}}) | Subscription is defined in the **application code**. The programmatic approach implements the subscription in your code. | +| [**Streaming**]({{< ref "subscription-methods.md#streaming-subscriptions" >}}) | Subscription is defined in the **application code**. Streaming subscriptions are dynamic in that they allow for adding or removing subscriptions at runtime. Doesn't require an app to be configured. | +| [**Programmatic**]({{< ref "subscription-methods.md#programmatic-subscriptions" >}}) | Subscription is defined in the **application code**. The programmatic approach implements the static subscription in your code. | The examples below demonstrate pub/sub messaging between a `checkout` app and an `orderprocessing` app via the `orders` topic. The examples demonstrate the same Dapr pub/sub component used first declaratively, then programmatically. @@ -192,6 +193,118 @@ func eventHandler(ctx context.Context, e *common.TopicEvent) (retry bool, err er The `/checkout` endpoint matches the `route` defined in the subscriptions and this is where Dapr sends all topic messages to. +### Streaming subscriptions + +Streaming subscriptions are subscriptions defined in application code which can be dynamically stopped and started at runtime. +Messages are pulled by the application from Dapr meaning no endpoint is needed to subscribe to a topic, and is possible to subscribe without any app configured on the sidecar at all. +Any number of PubSubs and topics can be subscribed to at once. +As messages are sent to the given message handler code, there is no concept of routes or bulk subscriptions. + +> **Note:** Only a single PubSub/Topic pair per application may be subscribed at a time. + +In the example below we show the different ways to stream subscribe to a topic. + +{{< tabs Go>}} + +{{% codetab %}} + +```go +package main + +import ( + "context" + "log" + + "github.com/dapr/go-sdk/client" +) + +func main() { + cl, err := client.NewClient() + if err != nil { + log.Fatal(err) + } + + sub, err := cl.Subscribe(context.Background(), client.SubscriptionOptions{ + PubsubName: "pubsub", + Topic: "orders", + }) + if err != nil { + panic(err) + } + // Close must always be called. + defer sub.Close() + + for { + msg, err := sub.Receive() + if err != nil { + panic(err) + } + + // Process the event + + // We _MUST_ always signal the result of processing the message, else the + // message will not be considered as processed and will be redelivered or + // dead lettered. + // msg.Retry() + // msg.Drop() + if err := msg.Success(); err != nil { + panic(err) + } + } +} +``` + +or + +```go +package main + +import ( + "context" + "log" + + "github.com/dapr/go-sdk/client" + "github.com/dapr/go-sdk/service/common" +) + +func main() { + cl, err := client.NewClient() + if err != nil { + log.Fatal(err) + } + + stop, err := cl.SubscribeWithHandler(context.Background(), + client.SubscriptionOptions{ + PubsubName: "pubsub", + Topic: "orders", + }, + eventHandler, + ) + if err != nil { + panic(err) + } + + // Stop must always be called. + defer stop() + + <-make(chan struct{}) +} + +func eventHandler(e *common.TopicEvent) common.SubscriptionResponseStatus { + // Process message here + // common.SubscriptionResponseStatusRetry + // common.SubscriptionResponseStatusDrop + common.SubscriptionResponseStatusDrop, status) + } + + return common.SubscriptionResponseStatusSuccess +} +``` + +{{% /codetab %}} + +{{< /tabs >}} + ### Programmatic subscriptions The dynamic programmatic approach returns the `routes` JSON structure within the code, unlike the declarative approach's `route` YAML structure. From 08b8908bbde0381ae1a45c2af0fce9c0aa769ae3 Mon Sep 17 00:00:00 2001 From: Josh van Leeuwen Date: Fri, 21 Jun 2024 11:34:57 +0100 Subject: [PATCH 2/9] Apply suggestions from code review Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Josh van Leeuwen --- .../pubsub/howto-publish-subscribe.md | 4 ++-- .../building-blocks/pubsub/pubsub-deadletter.md | 2 +- .../building-blocks/pubsub/pubsub-overview.md | 2 +- .../building-blocks/pubsub/subscription-methods.md | 14 +++++++------- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md index a7ac09bfeb9..c030505b71e 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md @@ -156,10 +156,10 @@ scopes: Dapr provides three methods by which you can subscribe to topics: - **Declaratively**, where subscriptions are defined in an external file. -- **Streaming**, where subscriptions are defined in user code, +- **Streaming**, where subscriptions are defined in user code. - **Programmatically**, where subscriptions are defined in user code. -Learn more in the [declarative, streaming and programmatic subscriptions doc]({{< ref subscription-methods.md >}}). This example demonstrates a **declarative** subscription. +Learn more in the [declarative, streaming, and programmatic subscriptions doc]({{< ref subscription-methods.md >}}). This example demonstrates a **declarative** subscription. Create a file named `subscription.yaml` and paste the following: 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 cd56b40864e..8085c1c47af 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 @@ -123,4 +123,4 @@ Watch [this video for an overview of the dead letter topics](https://youtu.be/wL ## Next steps - For more information on resiliency policies, read [Resiliency overview]({{< ref resiliency-overview.md >}}). -- For more information on topic subscriptions, read [Declarative, streaming and programmatic subscription methods]({{< ref "pubsub-overview.md#message-subscription" >}}). +- For more information on topic subscriptions, read [Declarative, streaming, and programmatic subscription methods]({{< ref "pubsub-overview.md#message-subscription" >}}). 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 a5e692cd487..e4d6bcfaf0b 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 @@ -80,7 +80,7 @@ Dapr applications can subscribe to published topics via three methods that suppo | Subscription method | Description | | ------------------- | ----------- | | **Declarative** | Subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | -| **Streaming** | Subscription is defined in the **user code**. Streaming subscriptions are dynamic in that they allow for adding or removing subscriptions at runtime. | +| **Streaming** | Subscription is defined in the **user code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. | | **Programmatic** | Subscription is defined in the **user code**. The programmatic approach implements the subscription in your code. | For more information, read [about the subscriptions in Subscription Methods]({{< ref subscription-methods.md >}}). diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md index 9af884734a7..6c497827335 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md @@ -1,6 +1,6 @@ --- type: docs -title: "Declarative, streaming and programmatic subscription methods" +title: "Declarative, streaming, and programmatic subscription methods" linkTitle: "Subscription methods" weight: 3000 description: "Learn more about the methods by which Dapr allows you to subscribe to topics." @@ -13,7 +13,7 @@ Dapr applications can subscribe to published topics via three methods that suppo | Subscription method | Description | | ------------------- | ----------- | | [**Declarative**]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) | Subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | -| [**Streaming**]({{< ref "subscription-methods.md#streaming-subscriptions" >}}) | Subscription is defined in the **application code**. Streaming subscriptions are dynamic in that they allow for adding or removing subscriptions at runtime. Doesn't require an app to be configured. | +| [**Streaming**]({{< ref "subscription-methods.md#streaming-subscriptions" >}}) | Subscription is defined in the **application code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. Doesn't require an app to be configured. | | [**Programmatic**]({{< ref "subscription-methods.md#programmatic-subscriptions" >}}) | Subscription is defined in the **application code**. The programmatic approach implements the static subscription in your code. | The examples below demonstrate pub/sub messaging between a `checkout` app and an `orderprocessing` app via the `orders` topic. The examples demonstrate the same Dapr pub/sub component used first declaratively, then programmatically. @@ -195,14 +195,14 @@ The `/checkout` endpoint matches the `route` defined in the subscriptions and th ### Streaming subscriptions -Streaming subscriptions are subscriptions defined in application code which can be dynamically stopped and started at runtime. -Messages are pulled by the application from Dapr meaning no endpoint is needed to subscribe to a topic, and is possible to subscribe without any app configured on the sidecar at all. -Any number of PubSubs and topics can be subscribed to at once. +Streaming subscriptions are subscriptions defined in application code that can be dynamically stopped and started at runtime. +Messages are pulled by the application from Dapr. This means no endpoint is needed to subscribe to a topic, and it's possible to subscribe without any app configured on the sidecar at all. +Any number of pubsubs and topics can be subscribed to at once. As messages are sent to the given message handler code, there is no concept of routes or bulk subscriptions. -> **Note:** Only a single PubSub/Topic pair per application may be subscribed at a time. +> **Note:** Only a single pubsub/topic pair per application may be subscribed at a time. -In the example below we show the different ways to stream subscribe to a topic. +The example below shows the different ways to stream subscribe to a topic. {{< tabs Go>}} From 357cca263393ce2ebbdd3ba3fb5562bb09a03814 Mon Sep 17 00:00:00 2001 From: Josh van Leeuwen Date: Sat, 22 Jun 2024 10:54:59 +0100 Subject: [PATCH 3/9] Apply suggestions from code review Co-authored-by: Mark Fussell Signed-off-by: Josh van Leeuwen --- .../building-blocks/pubsub/pubsub-overview.md | 8 ++++---- .../building-blocks/pubsub/subscription-methods.md | 6 +++--- 2 files changed, 7 insertions(+), 7 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 e4d6bcfaf0b..bbd16ccc4a8 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 @@ -75,13 +75,13 @@ In principle, Dapr considers a message successfully delivered once the subscribe ### Receiving messages with topic subscriptions -Dapr applications can subscribe to published topics via three methods that support the same features: declarative and programmatic. +Dapr applications can subscribe to published topics via three methods that support the same features: declarative, streaming and programmatic. | Subscription method | Description | | ------------------- | ----------- | -| **Declarative** | Subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | -| **Streaming** | Subscription is defined in the **user code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. | -| **Programmatic** | Subscription is defined in the **user code**. The programmatic approach implements the subscription in your code. | +| **Declarative** | The subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | +| **Streaming** | The subscription is defined in the **user code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. They do not require a subscription endpoint in your application (that is required by both programmatic and declarative subscriptions), making them easy to configure in code. Streaming subscriptions also do not require an app to be configured with the sidecar to receive messages. With streaming subscriptions, since messages are sent to message handler code, there is no concept of routes or bulk subscriptions. | +| **Programmatic** | Subscription is defined in the **user code**. The programmatic approach implements the static subscription and requires an endpoint in your code. | For more information, read [about the subscriptions in Subscription Methods]({{< ref subscription-methods.md >}}). diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md index 6c497827335..52fc2059b77 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md @@ -8,13 +8,13 @@ description: "Learn more about the methods by which Dapr allows you to subscribe ## Pub/sub API subscription methods -Dapr applications can subscribe to published topics via three methods that support the same features: declarative and programmatic. +Dapr applications can subscribe to published topics via three methods that support the same features: declarative, streaming and programmatic. | Subscription method | Description | | ------------------- | ----------- | | [**Declarative**]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) | Subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | -| [**Streaming**]({{< ref "subscription-methods.md#streaming-subscriptions" >}}) | Subscription is defined in the **application code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. Doesn't require an app to be configured. | -| [**Programmatic**]({{< ref "subscription-methods.md#programmatic-subscriptions" >}}) | Subscription is defined in the **application code**. The programmatic approach implements the static subscription in your code. | +| [**Streaming**]({{< ref "subscription-methods.md#streaming-subscriptions" >}}) | Subscription is defined in the **application code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. They do not require a subscription endpoint in your application (that is required by both programmatic and declarative subscriptions), making them easy to configure in code. Streaming subscriptions also do not require an app to be configured with the sidecar to receive messages. | +| [**Programmatic**]({{< ref "subscription-methods.md#programmatic-subscriptions" >}}) | Subscription is defined in the **application code**. The programmatic approach implements the static subscription and requires an endpoint in your code. | The examples below demonstrate pub/sub messaging between a `checkout` app and an `orderprocessing` app via the `orders` topic. The examples demonstrate the same Dapr pub/sub component used first declaratively, then programmatically. From 97ff3ef15110dd935333b533d4340e30db9cafae Mon Sep 17 00:00:00 2001 From: joshvanl Date: Sun, 23 Jun 2024 11:44:47 +0100 Subject: [PATCH 4/9] Adds notes about streaming subscription not supported by bulk or routes Signed-off-by: joshvanl --- .../building-blocks/pubsub/howto-route-messages.md | 2 +- .../building-blocks/pubsub/pubsub-bulk.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-route-messages.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-route-messages.md index d97c51b5eb7..487a7badcb4 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-route-messages.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-route-messages.md @@ -10,7 +10,7 @@ Pub/sub routing is an implementation of [content-based routing](https://www.ente While routing can be implemented with code, keeping routing rules external from the application can improve portability. -This feature is available to both the [declarative and programmatic subscription approaches]({{< ref subscription-methods.md >}}). +This feature is available to both the [declarative and programmatic subscription approaches]({{< ref subscription-methods.md >}}), however does not apply to streaming subscriptions. ## Declarative subscription diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md index 5228b5975e3..2406c9a39a9 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md @@ -272,10 +272,11 @@ Invoke-RestMethod -Method Post -ContentType 'application/json' -Uri 'http://loca ## Subscribing messages in bulk The bulk subscribe API allows you to subscribe multiple messages from a topic in a single request. -As we know from [How to: Publish & Subscribe to topics]({{< ref howto-publish-subscribe.md >}}), there are two ways to subscribe to topic(s): +As we know from [How to: Publish & Subscribe to topics]({{< ref howto-publish-subscribe.md >}}), there are three ways to subscribe to topic(s): - **Declaratively** - subscriptions are defined in an external file. - **Programmatically** - subscriptions are defined in code. +- **Streaming** - *Not supported* for bulk subscribe as messages are sent to handler code. To Bulk Subscribe to topic(s), we just need to use `bulkSubscribe` spec attribute, something like following: From dfeaa552973aa896d100f2a9baf9f768a307141f Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Mon, 24 Jun 2024 21:11:21 -0700 Subject: [PATCH 5/9] Update daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md Signed-off-by: Mark Fussell --- .../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 bbd16ccc4a8..0638d8c427f 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 @@ -80,7 +80,7 @@ Dapr applications can subscribe to published topics via three methods that suppo | Subscription method | Description | | ------------------- | ----------- | | **Declarative** | The subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | -| **Streaming** | The subscription is defined in the **user code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. They do not require a subscription endpoint in your application (that is required by both programmatic and declarative subscriptions), making them easy to configure in code. Streaming subscriptions also do not require an app to be configured with the sidecar to receive messages. With streaming subscriptions, since messages are sent to message handler code, there is no concept of routes or bulk subscriptions. | +| **Streaming** | The subscription is defined in the **user code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. They do not require a subscription endpoint in your application (that is required by both programmatic and declarative subscriptions), making them easy to configure in code. Streaming subscriptions also do not require an app to be configured with the sidecar to receive messages. With streaming subscriptions, since messages are sent to a message handler code, there is no concept of routes or bulk subscriptions. | | **Programmatic** | Subscription is defined in the **user code**. The programmatic approach implements the static subscription and requires an endpoint in your code. | For more information, read [about the subscriptions in Subscription Methods]({{< ref subscription-methods.md >}}). From 5df7af08f563febbf35025922086f3b2ea6f0c78 Mon Sep 17 00:00:00 2001 From: Josh van Leeuwen Date: Tue, 25 Jun 2024 14:14:53 +0100 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: Mark Fussell Signed-off-by: Josh van Leeuwen --- .../building-blocks/pubsub/pubsub-overview.md | 6 +++--- .../building-blocks/pubsub/subscription-methods.md | 12 ++++++------ 2 files changed, 9 insertions(+), 9 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 0638d8c427f..9916d259102 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 @@ -75,15 +75,15 @@ In principle, Dapr considers a message successfully delivered once the subscribe ### Receiving messages with topic subscriptions -Dapr applications can subscribe to published topics via three methods that support the same features: declarative, streaming and programmatic. +Dapr applications can subscribe to published topics via three subscription types that support the same features: declarative, streaming and programmatic. -| Subscription method | Description | +| Subscription type | Description | | ------------------- | ----------- | | **Declarative** | The subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | | **Streaming** | The subscription is defined in the **user code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. They do not require a subscription endpoint in your application (that is required by both programmatic and declarative subscriptions), making them easy to configure in code. Streaming subscriptions also do not require an app to be configured with the sidecar to receive messages. With streaming subscriptions, since messages are sent to a message handler code, there is no concept of routes or bulk subscriptions. | | **Programmatic** | Subscription is defined in the **user code**. The programmatic approach implements the static subscription and requires an endpoint in your code. | -For more information, read [about the subscriptions in Subscription Methods]({{< ref subscription-methods.md >}}). +For more information, read [about the subscriptions in Subscription Types]({{< ref subscription-methods.md >}}). ### Reloading topic subscriptions diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md index 52fc2059b77..16fe5f88edb 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md @@ -1,16 +1,16 @@ --- type: docs -title: "Declarative, streaming, and programmatic subscription methods" -linkTitle: "Subscription methods" +title: "Declarative, streaming, and programmatic subscription types" +linkTitle: "Subscription types" weight: 3000 -description: "Learn more about the methods by which Dapr allows you to subscribe to topics." +description: "Learn more about the subscription types that allow you to subscribe to message topics." --- -## Pub/sub API subscription methods +## Pub/sub API subscription types -Dapr applications can subscribe to published topics via three methods that support the same features: declarative, streaming and programmatic. +Dapr applications can subscribe to published topics via three subscription types that support the same features: declarative, streaming and programmatic. -| Subscription method | Description | +| Subscription type | Description | | ------------------- | ----------- | | [**Declarative**]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) | Subscription is defined in an **external file**. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code. | | [**Streaming**]({{< ref "subscription-methods.md#streaming-subscriptions" >}}) | Subscription is defined in the **application code**. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. They do not require a subscription endpoint in your application (that is required by both programmatic and declarative subscriptions), making them easy to configure in code. Streaming subscriptions also do not require an app to be configured with the sidecar to receive messages. | From 23cd72966b1d6e844fde30e8d81fb34a78d4aaf0 Mon Sep 17 00:00:00 2001 From: joshvanl Date: Tue, 25 Jun 2024 14:20:30 +0100 Subject: [PATCH 7/9] Adds Subscription type to Subscription metadata output Signed-off-by: joshvanl --- daprdocs/content/en/reference/api/metadata_api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index 77b5687500c..de705d72007 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -29,7 +29,7 @@ Binding | INPUT_BINDING, OUTPUT_BINDING Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource associated with the runtime. ### Subscriptions -The metadata API returns a list of pub/sub subscriptions that the app has registered with the Dapr runtime. This includes the pub/sub name, topic, routes, dead letter topic, and the metadata associated with the subscription. +The metadata API returns a list of pub/sub subscriptions that the app has registered with the Dapr runtime. This includes the pub/sub name, topic, routes, dead letter topic, the Subscription type, and the metadata associated with the subscription. ### Enabled features A list of features enabled via Configuration spec (including build-time overrides). @@ -114,6 +114,7 @@ topic | string | Topic name. metadata | object | Metadata associated with the subscription. rules | [Metadata API Response Subscription Rules](#metadataapiresponsesubscriptionrules)[] | List of rules associated with the subscription. deadLetterTopic | string | Dead letter topic name. +type | string | Type of the subscription, either `DECLARATIVE`, `STREAMING` or `PROGRAMMATIC`. **Metadata API Response Subscription Rules** @@ -184,6 +185,7 @@ curl http://localhost:3500/v1.0/metadata ], "subscriptions": [ { + "type": "DECLARATIVE", "pubsubname": "pubsub", "topic": "orders", "deadLetterTopic": "", @@ -305,6 +307,7 @@ Get the metadata information to confirm your custom attribute was added: ], "subscriptions": [ { + "type": "PROGRAMMATIC", "pubsubname": "pubsub", "topic": "orders", "deadLetterTopic": "", From 306fdd93f44a696d58ed209edb895f2e0b557bdc Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Wed, 26 Jun 2024 07:41:06 -0700 Subject: [PATCH 8/9] Update daprdocs/content/en/reference/api/metadata_api.md Signed-off-by: Mark Fussell --- daprdocs/content/en/reference/api/metadata_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index de705d72007..29629705a52 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -29,7 +29,7 @@ Binding | INPUT_BINDING, OUTPUT_BINDING Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource associated with the runtime. ### Subscriptions -The metadata API returns a list of pub/sub subscriptions that the app has registered with the Dapr runtime. This includes the pub/sub name, topic, routes, dead letter topic, the Subscription type, and the metadata associated with the subscription. +The metadata API returns a list of pub/sub subscriptions that the app has registered with the Dapr runtime. This includes the pub/sub name, topic, routes, dead letter topic, the subscription type, and the metadata associated with the subscription. ### Enabled features A list of features enabled via Configuration spec (including build-time overrides). From 6f17e1a68dd92c7c340b7d3f9965659fdaf68a52 Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Thu, 27 Jun 2024 09:36:11 -0400 Subject: [PATCH 9/9] Update daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- .../building-blocks/pubsub/subscription-methods.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md index 16fe5f88edb..436c1629585 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md @@ -305,6 +305,12 @@ func eventHandler(e *common.TopicEvent) common.SubscriptionResponseStatus { {{< /tabs >}} +## Demo + +Watch [this video for an overview on streaming subscriptions](https://youtu.be/57l-QDwgI-Y?t=841): + + + ### Programmatic subscriptions The dynamic programmatic approach returns the `routes` JSON structure within the code, unlike the declarative approach's `route` YAML structure.