OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

mqtt message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: [OASIS Issue Tracker] (MQTT-234) Shared Subscriptions


     [ https://issues.oasis-open.org/browse/MQTT-234?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Peter Niblett updated MQTT-234:
-------------------------------

    Proposal: 
A. Add a new definition to 1.2 Terminology

Shared Subscription

A Shared Subscription comprises a Topic Filter and a maximum QoS and has a Subscription Name. Unlike a regular Subscription, a Shared Subscription can be associated with more than one Session, however an Application Message that matches a Shared Subscription is only sent to one of its Sessions' clients.   A Session can contain more than one Shared Subscription and can contain Shared Subscriptions alongside regular Shared Subscriptions. Each Subscription, shared or not, that is associated with a Session has a different Topic Filter 


B. Change the sentences in 3.8.3 that talk about RequestedQoS

Existing text:
"Each filter is followed by a byte called the Requested QoS. This gives the maximum QoS level at which the Server can send Application Messages to the Client. 
The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / QoS pair. A SUBSCRIBE packet with no payload is a protocol violation. See section xxx for information about handling errors.
The requested maximum QoS field is encoded in the byte following each UTF-8 encoded topic name, and these Topic Filter / QoS pairs are packed contiguously.  "

Replacement text:
"Each filter is followed by a Flags Byte. This indicates whether the filter is part of a shared or an unshared subscription and gives the maximum QoS level at which the Server can send Application Messages to the Client for this subscription. 
The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / Flags Byte pair. A SUBSCRIBE packet with no payload is a protocol violation. See section xxx for information about handling errors.
The Topic Filter / Flags Byte pairs are packed contiguously.  "

C. Change the SUBSCRIBE Packet payload format figure to change the name of byte N+1 to be Flags Byte and show its Bit 7 to be a flag called Shared.  Replace the text that follows the figure:
Existing Text 
"The upper 6 bits of the Requested QoS byte are not used in the current version of the protocol. They are reserved for future use. The Server MUST treat a SUBSCRIBE packet as malformed and close the Network Connection if any of Reserved bits in the payload are non-zero, or QoS is not 0,1 or 2. "

D. Add the following to 3.10.4 (Response section in UNSUBSCRIBE)

"If the Topic Filter supplied in the UNSUBSCRIBE packet corresponds both to a Shared Subscription and to a regular subscription the Server MUST unsubscribe the Shared Subscription, leaving the regular subscription unchanged.  
Non-normative comment
This situation could only occur if the regular subscription has a Topic Filter that starts with the Shared Subscription's name prefix, including the ":" character. This eventuality can be avoided by avoiding the use of ":" in Topic names, or at least not using it at the end of the first topic level. 

Replacement Text 
"Bit 7 of the Flags Byte indicates that this Topic Filter is part of a shared subscription.  See section 4.9 for details about shared subscriptions. 
Bits 3 through 6 of the Flags Byte are not used in the current version of the protocol. They are reserved for future use. The Server MUST treat a SUBSCRIBE packet as malformed and close the Network Connection if any of these Reserved bits in the payload are non-zero, or if QoS is not 0,1 or 2. "

E. Add new section 4.9 called Shared Subscriptions
A regular MQTT subscription is associated with exactly one MQTT Session (the Session that created it). If there are multiple clients, each with its own subscription to the same Topic,  then each client gets its own copy of the Application Messages that are published on that Topic.  This means that a regular subscription cannot be used to load balance the Application Messages across multiple consuming clients if you want each message to be delivered to exactly once client.  For scenarios like that, you can use a Shared Subscription.
A client creates a Shared Subscription by sending a SUBSCRIBE packet with the Shared flag set to true (see section 3.8.3).  The Topic Filter in a Shared Subscription has the same syntax and semantics as one used for a regular subscription except that it is prefixed with a String that forms part of the subscription name. This name prefix is separated from the remainder of the Topic Filter by a ":" character followed by a topic level separator "/" character.  
The name prefix is ignored when matching against Topic Names. 

For example:
Shared subscriptions "consumer1:/sport/tennis/+"  and "consumer2:/sport/tennis/+" are distinct shared subscriptions and both of them match the same topics as a regular subscription to sport/tennis/+ 
Shared subscription "consumer1://finance" matches the same topics as a regular subscription to /finance. 
Note that  "consumer1://finance"  and "consumer1:/sport/tennis/+"  are distinct shared subscriptions. No relationship between them is implied by them having the same name prefix.

So long as only one Session subscribes to a particular Shared Subscription, the Shared Subscription behaves like a regular subscription, except that its name prefix is not taken into account when matching against publications.  The client receives any Retained Messages that match the Topic Filter when it first subscribes. It will be sent other matching messages as they are published. The Shared Subscription lasts until the Session ends or until the client unsubscribes from it, whichever happens first. 
Once a Shared Subscription is in existence it's possible for a different Session to submit a SUBSCRIBE request with the same Topic Filter, including the same name prefix. This different session could either come from a different client or from a different connection from the same client.  If the server authorises the SUBSCRIBE request, it adds the new session into the Shared Subscription. Retained messages are not sent to this new subscriber.  Each subsequent Application Message that matches the Shared Subscription is now sent to one or other of the two Sessions that share the subscription - but not both.  
Further Sessions can also join the Shared Subscription by sending a SUBSCRIBE request with the same Topic Filter, including the same name prefix.  These new joiners don't receive any Retained Messages, however they can expect to receive Application Messages. Each subsequent Application Message that matches the Shared Subscription is  sent to one of the larger pool of Sessions that has subscribed to it. 
Sessions leave the shared subscription when they send an UNSUBSCRIBE request or when they themselves end, whichever happens first.  A Shared Subscription lasts for as long as it has at least one member Session (i.e. a Session that has issued a successful SUBSCRIBE request to its Topic Filter and that has not completed a corresponding UNSUBSCRIBE.  A Shared Subscription survives when the Session that originally created it leaves, unless it has no member Sessions left when this happens.

Further notes on Shared Subscriptions
1. If there's more than one Session associated with the Shared Subscription, the server implementation is free to choose which Session it uses to send each message and what criteria it uses to make this selection.

2. Different subscribers are permitted to specify different Requested QoS levels in their SUBSCRIBE request packets.  The server is permitted to grant different QoS levels to these subscribers. If this happens, the server MUST respect the granted QoS for the subscribing session when sending an Application Message to that session.

3. If a subscribing client is using cleanSession = false and its Connection breaks while the Server is in the process of sending it a QoS 2 message, the Server MUST handle the delivery of the message as described in section 4.3.3, completing delivery to that client when it reconnects. 

4. If the connection to a subscribing client breaks while the Server is waiting to receive an acknowledgement for a QoS 1 message, the Server MAY attempt to send the Application Message to a different Subscriber instead.

5. If a client responds with a negative acknowledgement to a message from the Server, the Server MUST discard that message and not attempt to send it to any other Subscriber.

6. A client is permitted to submit a second SUBSCRIBE request to a Shared Subscription on a Session that's already associated with that Shared Subscription - it might for example do this in order to change the Requested QoS for its subscription.  This does not increase the number of times that that Session is associated with the Shared Subscription, so the Session will leave the Shared Subscription on its first UNSUBSCRIBE.

7. Retained messages are sent to the Session that creates the Shared Subscription, by being its first subscriber. They are not sent at any other stage during the lifetime of the Shared Subscription, including on subsequent SUBSCRIBE requests from that same Session.

I have added a proposal based on my previous long comment.  A few notes:

1. I have gone with the approach of using an additional flag in SUBSCRIBE along with the syntax

name-prefix:/rest of the topic filter

There is a small possibility that expressions like this will clash with real topic filters. This only affects UNSUBSCRIBE, so I have put a note in there. 

2. I have assumed that it's ok to have different QoS levels for different subscribers. I know Ken was not keen on that, so we could revise things to prohibit that.

3. I have assumed we need to support both cleanSession = true and false. You could argue this adds extra burden on implementers, in which case we should go for just cleanSession=false - i.e. make it illegal for a Session that has cleanSession = true to attempt to create or join a Shared Subscription. 

> Shared Subscriptions
> --------------------
>
>                 Key: MQTT-234
>                 URL: https://issues.oasis-open.org/browse/MQTT-234
>             Project: OASIS Message Queuing Telemetry Transport (MQTT) TC
>          Issue Type: New Feature
>          Components: core
>    Affects Versions: 5
>            Reporter: Andrew Banks
>            Assignee: Peter Niblett
>            Priority: Critical
>
> Shared Subscriptions
> --------------------
> Shared subscriptions allow a set of clients to share the consumption of messages
> produced in response to a subscription. The set of subscribers is created by the use
> of a common share name. Shared subscriptions provide a facility similar to point to 
> point messaging in that the processing of messages is not limited to the availability 
> or capacity of a single consumer, the share name is analogous to the queue name in 
> that it names the list of messages to be processed.
> I suggest that a shared subscription be defined by the topic filter syntax:
>   $share:shareName:topicFilter
> - This specialised topic filter takes the place of the normal topic filter in the 
>   subscribe packet. 
> - The "$share:" prefix uses a reserved $ name and will therefore not cause a conflict
>   with other topic filters.
> - shareName is a string which labels the shared subscription and must not contain any 
>   ":" characters.
> - TopicFilter follows the existing topic filter rules.
> - Subscribing clients will be a member of the share only if both the shareName and
>   topicFilter are identical. So, a different shareName with the same topicFiler 
>   will create a different share. Similarly a shareName followed by a different topic
>   filter will create separate share.
> - Servers may decline to support shared subscriptions by not accepting subscribe
>   packets containing topic filters starting with the "$share:" prefix. However, if 
>   they do accept the "$share:" prefix they must follow this definition.
> - The subscribing clients may make both non durable and durable subscriptions by 
>   setting clean session true or false. The shared subscription ceases to exist if    
>   the number of clients subscribed to it reaches zero. If the shared subscription
>   ceases to exist the messages queued for processing are deleted by the server as 
>   with an non shared subscription.
> - A good server implementation will avoid allocating messages to subscribers with 
>   durable subscriptions while the client is disconnected. Instead the messages will be 
>   allocated when a suitable client connects. 
> - A Qos=1 message should be reallocated to another client sharing the same subscription
>   if the network connection to the client is lost before the PUBACK is received.
>   Qos=0 and Qos=2 messages must not be reallocated. 



--
This message was sent by Atlassian JIRA
(v6.2.2#6258)


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]