[Pub/sub] Overview & how-tos (#2414)

* overview; parse out howto-publish-subscribe Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * updates after talk w Mark Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * break up cloudevents into two articles Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * update to overview Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * how to and overview updates Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * grammar pass before opening for review Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * updates from Mark Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * updated diagram Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> Co-authored-by: Mark Fussell <markfussell@gmail.com>
dapr · May 26, 2022 · 92e1b10 · 92e1b10
1 parent 63b6b3f
commit 92e1b10
Show file tree

Hide file tree

Showing 10 changed files with 769 additions and 389 deletions.
diff --git a/...nt/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/...nt/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md
diff --git a/...ntent/en/developing-applications/building-blocks/pubsub/howto-route-messages.md b/...ntent/en/developing-applications/building-blocks/pubsub/howto-route-messages.md
diff --git a/...content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md b/...content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md
@@ -0,0 +1,109 @@
+---
+type: docs
+title: "Publishing & subscribing messages with Cloudevents"
+linkTitle: "Messages with Cloudevents"
+weight: 2100
+description: "Learn why Dapr uses CloudEvents, how they work in Dapr pub/sub, and how to create CloudEvents."
+---
+
+To enable message routing and 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 is automatically wrapped in a CloudEvents envelope, using the [`Content-Type` header value]({{< ref "pubsub-overview.md#content-types" >}}) for `datacontenttype` attribute.
+
+Dapr uses CloudEvents to provide additional context to the event payload, enabling features like:
+
+- Tracing
+- Deduplication by message Id
+- Content-type for proper deserialization of event data
+
+## CloudEvents example
+
+Dapr implements the following CloudEvents fields when creating a message topic.
+
+- `id`
+- `source`
+- `specversion`
+- `type`
+- `traceparent`
+- `datacontenttype` (optional)
+
+The following example demonstrates an `orders` topic message sent by Dapr that includes a W3C `traceid` unique to the message, the `data` and the fields for the CloudEvent where the data content is serialized as JSON.
+
+```json
+{
+    "topic": "orders",
+    "pubsubname": "order_pub_sub",
+    "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
+    "tracestate": "",
+    "data": {
+    "orderId": 1
+    },
+    "id": "5929aaac-a5e2-4ca1-859c-edfe73f11565",
+    "specversion": "1.0",
+    "datacontenttype": "application/json; charset=utf-8",
+    "source": "checkout",
+    "type": "com.dapr.event.sent",
+    "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01"
+}
+```
+
+As another example of a v1.0 CloudEvent, the following shows data as XML content in a CloudEvent message serialized as JSON:
+
+```json
+{
+    "specversion" : "1.0",
+    "type" : "xml.message",
+    "source" : "https://example.com/message",
+    "subject" : "Test XML Message",
+    "id" : "id-1234-5678-9101",
+    "time" : "2020-09-23T06:23:21Z",
+    "datacontenttype" : "text/xml",
+    "data" : "<note><to>User1</to><from>user2</from><message>hi</message></note>"
+}
+```
+
+## Publish your own CloudEvent
+
+If you want to use your own CloudEvent, make sure to specify the [`datacontenttype`]({{< ref "pubsub-overview.md#setting-message-content-types" >}}) as `application/cloudevents+json`.
+
+### Example
+
+{{< tabs "Dapr CLI" "HTTP API (Bash)" "HTTP API (PowerShell)">}}
+
+{{% codetab %}}
+
+Publish a CloudEvent to the `orders` topic:
+
+```bash
+dapr publish --publish-app-id orderprocessing --pubsub order-pub-sub --topic orders --data '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"orderId": "100"}}'
+```
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+Publish a CloudEvent to the `orders` topic:
+
+```bash
+curl -X POST http://localhost:3601/v1.0/publish/order-pub-sub/orders -H "Content-Type: application/cloudevents+json" -d '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"orderId": "100"}}'
+```
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+Publish a CloudEvent to the `orders` topic:
+
+```powershell
+Invoke-RestMethod -Method Post -ContentType 'application/cloudevents+json' -Body '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"orderId": "100"}}' -Uri 'http://localhost:3601/v1.0/publish/order-pub-sub/orders'
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Next steps
+
+- Learn why you might [not want to use CloudEvents]({{< ref pubsub-raw.md >}})
+- Try out the [pub/sub Quickstart]({{< ref pubsub-quickstart.md >}})
+- List of [pub/sub components]({{< ref setup-pubsub >}})
+- Read the [API reference]({{< ref pubsub_api.md >}})
+
diff --git a/...content/en/developing-applications/building-blocks/pubsub/pubsub-message-ttl.md b/...content/en/developing-applications/building-blocks/pubsub/pubsub-message-ttl.md
@@ -3,7 +3,7 @@ type: docs
 title: "Message Time-to-Live (TTL)"
 linkTitle: "Message TTL"
 weight: 6000
-description: "Use time-to-live in Pub/Sub messages."
+description: "Use time-to-live in pub/sub messages."
 ---
 
 ## Introduction
@@ -18,6 +18,11 @@ In some components, such as Kafka, time-to-live can be configured in the topic v
 
 When message time-to-live has native support in the pub/sub component, Dapr simply forwards the time-to-live configuration without adding any extra logic, keeping predictable behavior. This is helpful when the expired messages are handled differently by the component. For example, with Azure Service Bus, where expired messages are stored in the dead letter queue and are not simply deleted.
 
+{{% alert title="Note" color="primary" %}}
+ You can also set message TTL for a given message broker at creation. Look at the specific characteristic of the component that you are using to see if this is suitable.
+
+{{% /alert %}}
+
 ### Supported components
 
 #### Azure Service Bus
@@ -85,6 +90,6 @@ See [this guide]({{< ref pubsub_api.md >}}) for a reference on the pub/sub API.
 ## Next steps
 
 - Learn about [topic scoping]({{< ref pubsub-scopes.md >}})
-- Learn [how to configure Pub/Sub components with multiple namespaces]({{< ref pubsub-namespaces.md >}})
+- Learn [how to configure pub/sub components with multiple namespaces]({{< ref pubsub-namespaces.md >}})
 - List of [pub/sub components]({{< ref supported-pubsub >}})
 - Read the [API reference]({{< ref pubsub_api.md >}})