Subscription identification

This proposal replaces the original one by Nick O'Leary. The SUBSCRIBE Packet may include zero or one subscription identifier properties. The subscription identifier is a variable byte integer, the valid range is 1 to 2**28-1. The subscription identifier applies to all of the topic filters in the subscribe packet. If a Topic Filter in the SUBSCRIBE Packet replaces an identical Topic Filter the new identifier replaces any pre existing identifier, or removes an existing one if there is no new subscription identifier. The matching PUBLISH packet includes the subscription identifier carried in the SUBSCRIBE packet. If the PUBLISH packet matches multiple topic filters and the server chooses to send a single PUBLISH packet then that PUBLISH packet must contain all of the subscription identifiers for the matching Topic Filters. If there are multiple subscription identifier properties in the PUBLISH packet their order is not significant. If the subscription is shared, then only the subscription identifiers that were in present in the SUBSCRIBE Packet from the client which is receiving the message are returned in the PUBLISH Packet. It is possible that the client made several subscriptions which match a publication and that it used the same identifier more for more than one of them. In this case the PUBLISH packet will carry multiple identical subscription identifiers. The subscription identifiers are part of the session state in the server. They are removed from the session state in the Server when the Server receives an UNSUBSCRIBE packet, when the Server receives a SUBSCRIBE packet from the client for the same topic filter but with a different subscription identifier or with no subscriptions identifier, or when the server sends session present=false in a CONNACK packet. The subscription identifiers do not form part of the session state in the client. In a useful implementation a client will associate the subscription identifiers with other client side state, this state is typically removed when the client unsubscribes, when the client subscribes for the same topic filter with a different identifier or no identifier, or when the client receives session present=false in a CONNACK packet. The server is not obliged to use the same set of subscription identifiers in a re transmitted PUBLISH packet. If the client remade a subscription after the initial transmission of a PUBLISH Packet and used a different subscription identifier then the server is allowed to use the identifiers from the first transmission in any re transmission. Alternatively the server is allowed to use the new identifiers in a re transmission. The server is not allowed to revert to the old identifier if it has sent a PUBLISH packet containing the new one. It is a protocol error for a PUBLISH packet to contain any subscription identifier other than those received in SUBSCRIBE packet which caused it to flow. A PUBLISH packet sent from a Client to a Server will never contain a subscription identifier. This proposal differs from the previous one in the following respects. 1) The identifier is assigned by the subscriber. This closes the timing windows in the previous proposal. 2) The identifier does not have to be unique within the session. This simplifies the specification and broadens the use cases, however some use cases require that the subscriber uses unique subscription identifiers. 3) The subscription identifier is at the packet level and applies to all of the topic filters in the SUBSCRIBE packet. To use different identifiers with each topic filter the subscriber must send a separate SUBSCRIBE packet for each topic filter. (non normative) Usage scenarios, for illustration only. 1) The client implementation indicates via its programming interface that a publication matched more than one subscription. The client implementation generates a new identifier each time a subscription is made. If the returned publication carries more than one subscription identifier, then the publication matched more than one subscription. 2) The client implementation allows the subscriber to direct messages to a callback associated with the subscription. The client implementation generates an identifier which uniquely maps the identifier to the callback. When a publication is received it uses the subscription identifier to determine which callback is driven. 3) The client implementation returns the topic string used to make the subscription to the application when it delivers the published message. To achieve this the client generates an identifier which uniquely identifies the topic filter. When a publication is received the client implementation uses the identifiers to look up the original topic filters and return them to the client application. 4) A gateway forwards publications received from a server to clients that have made subscriptions to the gateway. The gateway implementation maintains a map of each unique topic filter it receives to the set of clientId, subscriptionId pairs that it also received. It generates a unique identifier for each topic filter that it forwards to the server. When a publication is received the gateway uses the subscription identifiers it received from the server to look up the clientId, subscriptionId pairs associated with them. It adds these to the PUBLISH packets it sends to the clients. If the upstream Server sent multiple PUBLISH packets because the message matched multiple subscriptions, then this behaviour is mirrored to the clients. Question. Should the Subscription identifier support in the Server be optional and if so, should the server indicate its inability to handle subscription identifiers by an indication in CONNACK or a return code in SUBACK?