Document ttl=0 behavior #348
Conversation
Update the API documentation to explain that the default message ttl value is 0. Explain that Proton does not send any ttl header on the wire when a message's ttl is 0.
|
@ktdreyer The behavior of not sending the default values is something that Proton does in general, not just for the TTL, IIRC. Is there some particular gotcha you encountered, where this behavior is problematic? |
|
Yes, https://pagure.io/koji/issue/3120 has the background. There is some confusion around what a Python has a |
|
Having checked the AMQP spec there is no default value for TTL. I think that proton-c just reuses 0 to mean no ttl header because sending a ttl of 0 makes no sense as it would mean expire this message immediately. |
It seems that for proton-c it means send no header - this is an artifact of the C API taking an integer with no distinguished 'None' value. A newly created message will have this value anyway - in that sense it is the default value!
That is sensible but the the Python binding sits on top of the proton-c so cannot set the value to 0 because the c code uses this to mean don't send the value. I don't think it matters because send a TTL of 0 makes very little sense in any case - meaning this message has already timed out. It definitely makes sense for the Python binding to translate a None value to 0 into the C API. |
| * The default ttl value for a new message is 0. If this value is 0, Proton | ||
| * will send no ttl message header. | ||
| * |
There was a problem hiding this comment.
I think this comment is in the wrong place and should explain what getting a 0 value would mean. 'default' is an ambiguous word here. I think what you are trying to say there (in pn_message_get_ttl) would be more like: ' A newly created message returns a ttl value of 0. This means that no ttl value is set in the message header.'
Here what I think you are saying is - 'If TTL is not set on a message then no ttl value is sent in the message header. Setting a ttl value of 0 has the same effect as not setting the ttl vaule.'
In any case if you want to properly explain the handling of ttl you need to fix the explananation in get because it is noted is the primary explanation.
| @@ -225,6 +225,9 @@ def ttl(self) -> float: | |||
| """The time to live of the message measured in seconds. Expired messages | |||
| may be dropped. | |||
|
|
|||
| The default ttl value for a new message is 0. If this value is 0, | |||
| Proton will send no ttl message header. | |||
|
|
|||
| :raise: :exc:`MessageException` if there is any Proton error when using the setter. | |||
There was a problem hiding this comment.
Given your comments I'm wondering if we should check for 0 and return None in this case.
| @@ -201,6 +201,9 @@ def ttl=(time) | |||
|
|
|||
| # Returns the time-to-live, in milliseconds. | |||
| # | |||
| # The default ttl value for a new message is 0. If this value is 0, Proton | |||
| # will send no ttl message header. | |||
| # | |||
| def ttl | |||
Incidentally setting a ttl header value of 0 would be (mostly) useless because it means the message has 0ms before it expires, in other words it is already expired and can be immediately discarded - so any ActiveMQ behaviour that takes this to mean keep indefinitely is wrong. However I expect that what is actually happening is that the ttl value is not being sent at all and the broker is just not configured to auto delete messages at all. |
Update the API documentation to explain that the default message
ttlvalue is0.Explain that Proton does not send any
ttlheader on the wire when a message's ttl is0.