Adding documentation for PubSub Message TTL.

This commit is contained in:
Artur Souza 2021-01-13 22:27:42 -08:00
parent fe24ef6bee
commit 27f399e87c
2 changed files with 49 additions and 1 deletions

View File

@ -0,0 +1,37 @@
---
type: docs
title: "Message Time-To-Live"
linkTitle: "Message TTL"
weight: 6000
description: "Use time-to-live in Pub/Sub messages."
---
## Introduction
Dapr enables per message time-to-live for all Pub/Sub components. It means that applications can set time-to-live per message and subscribers will not receive those messages after expiration.
In Kafka, time-to-live is configured in the topic via `retention.ms` as per [documentation](https://kafka.apache.org/documentation/#topicconfigs_retention.ms). With message time-to-live in Dapr, applications using Kafka can now set time-to-live per message too, since Dapr will handle the expiration.
On the other hand, Azure Service Bus supports [entity level time-to-live]((https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-expiration)). It means that messages have a default time-to-live but can also be set with a shorter timespan at publishing time. Dapr will propagate the time-to-live metadata for the message and let Azure Service Bus handle expiration directly. This is referred as "native support" for message TTL.
### Pub/Sub components with message TTL
* All, some are implemented natively.
### Subscribers outside Dapr
If messages are consumed by subscribers without Dapr, expired messages are not automatically dropped. Still, subscribers can programatically drop expired messages by adding logic to handle the `expiration` attribute in the cloud event.
> The `expiration` attribute follows the [RFC3339](https://tools.ietf.org/html/rfc3339) format.
## Native support for message TTL
When Message Time-To-Live has native support in the component, Dapr will simply forward the time-to-live configuration without adding extra logic, keeping predictable behavior. This is helpful when the expired messages are handled differently by the component - like in Azure Service Bus, where expired messages are stored in the dead letter queue and not simply deleted.
### Pub/Sub components with native support for message TTL
* Azure Service Bus
### Subscribers outside Dapr
In this case, subscribers via Dapr or outside Dapr will not receive expired messages. No extra logic is needed.

View File

@ -89,7 +89,7 @@ The following example illustrates this point, considering a subscription for top
#### HTTP Request
```
POST http://localhost:<appPort>/<path>
POST http://localhost:<appPort>/<path>[?<metadata>]
```
> Note, all URL parameters are case-sensitive.
@ -100,6 +100,17 @@ Parameter | Description
--------- | -----------
appPort | the application port
path | route path from the subscription configuration
metadata | query parameters for metadata as described below
##### Metadata
Metadata can be sent via query parameters in the request's URL. It must be prefixed with `metadata.` as shown below.
Parameter | Description
--------- | -----------
metadata.ttlInSeconds | the number of seconds for the message to expire as [described here]({{< ref pubsub-message-ttl.md >}})
> Additional metadata parameters can be available based on each pubsub component.
#### Expected HTTP Response