Working With Direct Messages
Direct messaging provides a reliable—but not guaranteed—delivery of messages from the Solace message bus to consuming clients.
Direct Messaging is the default message delivery system for the Solace Messaging Platform and does not require any configuration beyond that required to configure and start other features. Direct Messaging is always available by default to all clients connecting to the Solace router.
Direct messages have the following characteristics:
- they are delivered to subscribing clients in the order in which the publishers publish them
- they do not require subscribing clients to acknowledge receiving them
- they are not spooled on the message bus for consuming clients
- they are not retained for a client when it is not connected to a Solace router (that is, they are not spooled on the message bus for consuming clients)
- they can be discarded when congestion or system failures are encountered
- they can be reordered in the event of network topology changes when a multi‑node message routing is used
Direct Messaging is ideally suited for applications where:
- extremely high message rates and extremely low latency are required
- consuming clients can tolerate message loss in the event of network congestion
- messages do not need to be persisted for later delivery to slow or offline consumers
- messages must be efficiently published to a large number of clients with matching subscriptions
Direct messages are not delivered if:
- the client disconnects from the router while messages are being published
- the client fails to consume messages at the published rate and egress message buffer overflow results
Through the use of Solace messaging APIs, client applications can use the Deliver-To-One (DTO) feature of the Solace Messaging Platform to send a Direct delivery message to a single client even though there may be a number of clients with appropriate subscriptions that are capable of receiving the message.
The use of DTO allows for the load-balancing of received messages because only one connected client can consume a DTO message. (Note that, as a Direct message, if there are no connected clients, the router will not spool the message.)
Note: The DTO priority and behaviors are only relevant to messages published with the DTO flag set. Otherwise normal delivery rules apply (that is, all messages are delivered to all subscribers).
To control which client can receive a Deliver-To-One message, subscribing clients are assigned a local subscriber priority through a session property. The subscriber priority levels range from 1 (the highest) to 4 (the lowest).
A local priority is the priority that a client’s subscriptions have for receiving Deliver‑To-One messages published on the Solace router that the client is directly connected to.
When a Deliver-To-One message is published, a single local client with the highest subscriber priority level will receive the message. In a situation where the highest local subscriber priority level is shared by multiple clients, a single client is chosen in a round-robin fashion.
Note: When possible, a published DTO message is always delivered to a locally connected client. However, if there are no clients with assigned local subscriber priorities, the message will be delivered to a neighboring Solace router if one is available. Note that no attempt is made to evenly distribute DTO messages amongst remotely-connected routers should there be multiple options. This implies that a network of Solace routers will ensure single delivery of DTO messages amongst the appropriate clients connected to a network of Solace routers. However, load balancing can only be expected amongst clients connected to the same Solace router.
Clients can also override DTO delivery for specific topic subscriptions by applying the Deliver Always (DA) property to those subscriptions when they are added to the router. Topic subscriptions with the DA flag always receive all messages with topics that match the subscription—regardless of set priorities. Using the DA flag override can be useful if an application wants to take a copy of the message for auditing, replaying, or monitoring purposes. For example, a monitoring application should use the DA flag for every subscription it has so that it does not accidentally become a member of a DTO group and receive messages that should be delivered to other applications relying in DTO.
Note: As a special case, the subscription “>” (which matches all topics) is always treated as a DA subscription.
Subscriptions (with priority 1 to 4) and DA subscriptions that happen to share the same topic string are unique, meaning that a client may have both a DTO and DA subscription to the same topic. However, should a client be eligible to receive a given message due to both priority and DA subscriptions only a single copy of the message will be delivered.
The DTO priority of a subscription is shown by the show smrp subscriptions User EXEC command as either a value of P1 to P4 or the value DA to indicate a Deliver Always subscription.
solace> show smrp subscriptions
T - Destination Type (C=local-client, Q=local queue
P - Subscription Persistence (P=persistent, N=non-persistent)
R - Redundancy Type for Local Destinations (P=primary, B=backup
Message VPN : default (exported: Yes; 100% complete)
Destination Name Flags BlkID DTO Subscription
T P R Prio
---------------------- - - - ----- ---- ------------------------------------
#client C N S 0 P1 #MCAST/>
#client C N S 0 P1 #SEMP/lab-129-4/>
#client C N S 0 P1 #P2P/lab-129-4/#client/>
#client C N S 0 P1 #P2P/v:lab-129-4/#client/>
#client C N S 0 P1 #SEMP/v:lab-129-4/>
#client C N S 0 P1 #P2P/lab-129-4/WnAHbdbR/#client/>
dev2-180/316/#00000001 C N P 34 P1 #P2P/v:lab-129-4/27vgoQH9/dev2-180/316/#00000001/>
dev2-180/316/#00000001 C N P 33 P1 a/b
test000001 C N P 33 P3 #P2P/v:lab-129-4/YC4EzyB4/test000001/>
testInstance C N P 33 P1 #P2P/v:lab-129-4/0N7rz7R0/testInstance/>
testInstance C N P 33 DA a/b
testInstance C N P 33 P1 #P2P/CACHEINST/testInstance/>
testInstance C N P 34 P1 #P2P/CACHEINST/testCluster/>
testInstance C N P 35 P1 #P2P/CACHEINST/testCache/>
Message VPN : testVpn (exported: No; 100% complete)
Destination Name Flags BlkID DTO Subscription
T P R Prio
---------------------- - - - ----- ---- ------------------------------------
#client C N S - P1 #MCAST/>
#client C N S - P1 #SEMP/lab-129-4/>
#client C N S - P1 #P2P/lab-129-4/#client/>
#client C N S - P1 #P2P/v:lab-129-4/#client/>
#client C N S - P1 #SEMP/v:lab-129-4/>
#client C N S - P1 #P2P/lab-129-4/WnAHbdbR/#client/>
The message eliding feature enables client applications to receive only the most current Direct messages published to topics that they subscribe to, at a rate that they can manage, rather than queue up outdated messages. Message eliding can be useful in situations where there are slow consumers or where a slower message rate is required. Only Direct messages can be elided.
Note: Message eliding is not supported on Solace appliances that use a Network Acceleration Blade-0401EM (NAB-0401EM)
To use message eliding:
- Client applications must flag published message as eligible for message eliding.
- Although only a Direct message can be elided, it is possible for a publishing client to flag a persistent or non-persistent message as eliding‑eligible. However, the message will not be elided unless the delivery mode of the message is changed to Direct. This could happen if the persistent or non-persistent message is published to a topic that matches a client’s topic subscription. In that case, to accommodate the client topic subscription, the message is changed to Direct; it can then be elided.
- All messages published by MQTT client applications are treated as non‑eliding eligible.
- A receiving client application must be assigned a client profile through its client username that permits it to:
- use message eliding
- after the first message, receive subsequent messages with a time delay interval. This delay interval (configured in the client profile) controls on a topic-by-topic basis the rate of message updates sent to a client (for example, five messages per second per topic).
- receive up to the maximum number of topics the router can track for performing the eliding function on each client connection (up to 32,000 per client as configured in the client profile, with a total of 2,000,000 per router; default is 256 per client). Once the maximum number of topics number is reached, the router ages out the elided topics for the client to prevent the consumption of more eliding resources than have been allocated for the connection. Eliding behavior then continues as if this were a new client connection, and a one-time Syslog event is generated on a per client basis.
- Solace routers track the number of topics on a client connection dynamically. Whenever this number is below the set maximum, the eliding function is applied to the new incoming messages.
- For subscribers with wild card subscriptions, each topic that matches the wildcard subscription is elided, up to the maximum number of subscriptions specified by the client profile.
- It is recommended that consuming clients do not use discard indications when using message eliding. In a situation where a router’s egress priority queue for a client fills up with received messages, the oldest messages on the egress queue are discarded to make room for newly arriving messages, and the message at the head of the queue is flagged with the discard indication. However, if eliding is enabled, that message could be elided, and the client would not receive the discard indication.
The following example explains how message eliding works:
- Client P is publishing messages on topic T at a rate of one message per millisecond; each message is flagged as eliding-eligible.
- Consuming Client S is assigned a client profile that has eliding enabled and has an eliding delay of 200 ms, which imposes a cap of five updates per second per topic.
- When the first message, M1, for topic T arrives at the router for client S, it is sent to the client without any delay, assuming the TCP window is open.
- When message M2 for topic T arrives a moment later at the router for subscriber S, it is held by the router but not sent to the client since there has already been a message (that is, M1) for this same topic sent within the 200ms delay time.
- When subsequent messages (for example, M3, M4, etc.) arrive at the router for client S, each newer message replaces the previous message and is continuously held by the router.
- Then 200ms after the previous message was sent for Client S, the held message is then sent to that client, assuming the TCP window is open.
Use cases for this feature include:
- Eliding for congestion management.
- Eliding for Message Rate Control.
- Some example uses are:
- Streaming market data to human traders.
- Controlling update rates to subscribers over a Wide Area Network (WAN).
A client application wants to receive every message provided it is able to keep up with the message flow. If the client cannot keep up, then any queued messages can be elided to provide only the most recent message for each topic. For this use case a delay interval time of 0 is set.
A client application wants to receive at most five messages per second per topic. In this case, the Solace router rate controls the output of messages to it. For this use case a delay interval time of 200 ms (that is, five messages per second per topic) is set.
Even though market data updates might be published at a very high rate, humans can only deal with a few updates per second. The client always wants the latest information, but at a slower rate than the total feed rate. Message eliding can be used to limit the output stream to a few updates per topic per second.
Sometimes, WAN bandwidth versus receiver processing capacity require that only a subset of the entire feed rate be provided over the WAN. Message eliding can be used to control the message update rates to a client.
Once clients are authenticated on the Solace router they can add and remove topic subscriptions for Direct messages published to the Message VPN to which the have connected. These topic subscriptions are not durable—the clients’ subscriptions are not maintained for them after they disconnect from the router.
A client typically performs the following steps for managing their own subscriptions:
- The client connects to the Solace router and authenticates itself. At this point, the router has no subscriptions for that client.
- The client adds subscriptions to the Solace router.
- The client receives messages which matches the requested subscriptions.
- When the client disconnects from router the router immediately removes all subscriptions associated with that client.
Note: The topics that a client is permitted to subscribe to can be limited by the ACL assigned to the client username account used by the client. For more information, refer to Configuring Access Control Lists.
A client application can manage subscriptions on behalf of other clients within a Message VPN when its client username is configured to be a Subscription Manager (see Configuring Subscription Managers ), which is useful for centralizing the assignment of the Message VPN's clients and services to direct messaging subscriptions. However, it should be noted that a Subscription Manager has no control over guaranteed messaging.
When a client is configured as Subscription Manager, the subscriptions that the subscription manager client is managing are then subject to the access control permissions configured on that client’s associated Access Control List (ACL) profile—the ACLs of destination clients are not used. Thus, the client configured as Subscription Manager can not add or remove subscriptions that its own ACL rules would deny the addition of. This prevents it from inadvertently adding or removing subscriptions that it is not entitled to.
When a client is configured as Subscription Manager, other clients within the Message VPN typically perform the following steps for managing their subscriptions:
- The client connects to the Solace router.
- The client notifies the Subscription Manager that it is ready to receive messages.
- The Subscription Manager authenticates the client, determines the subscription set needed by the client, and adds subscriptions to the router on behalf of the client.
- The client receives messages which match the associated subscription set.
- Once the client is done, it disconnects and its associated subscription set is deleted from the router.
Note: Subscriptions added by the Subscription Manager on behalf of the client have the same subscription rate (subscriptions per second) as those added by the client directly for itself.
Once subscriptions have been added by a Subscription Manager on behalf of another client, they behave like any other subscriptions (for example, the subscriptions are removed if the client is disconnected). Disconnecting the Subscription Manager has no effect on the subscriptions already added by it.
For information on how clients using Solace APIs can act as Subscription Managers to add and remove subscriptions on behalf of others, see Managing Topic Subscriptions on Behalf of Other Clients.