Adds initial streaming subscriptions docs

Signed-off-by: joshvanl <me@joshvanl.dev>

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:
 

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" >}}).

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 >}}).

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.