All Products
Search
Document Center

SDK guide (STOMP)

Last Updated: Jul 26, 2019

The Simple (or Streaming) Text Orientated Messaging Protocol (STOMP) is a simple message subscription and publishing protocol that is similar to the text-based protocol HTTP. This protocol is used for lightweight interaction between STOMP clients using script languages (such as Ruby, Python, and Perl) and RocketMQ brokers.

Terms

  • Topic: The topic of messages on Message Queue for RocketMQ (RocketMQ for short). This is the level-1 message category for message classification and permission management.
  • Destination: The destination of messages defined in the STOMP protocol, in the format of “/t/t1”, where the first t indicates a topic.
  • Instance ID: The ID of a RocketMQ instance.
  • Client ID: The GUID of a message sender or subscriber, which is used to query logs.

For more information about terms, see Terms of RocketMQ.

Quick start

Destination configuration

In STOMP, the level-1 string of a message destination indicates a topic on RocketMQ, which is the level-1 message category.

Permission authentication

Identity authentication

After a client establishes an STOMP connection with a RocketMQ broker, the broker verifies the identity of the client by checking its AccessKey and signature. In an STOMP header, the AccessKey and signature are encapsulated in the login and passcode fields, respectively.

The passcode is generated in the following way:

A binary array is derived from the client ID by using the HMAC-SHA1 algorithm, with AccessKeySecret as the key. Then, the binary array is encoded in Base64 format to obtain the signature string (passcode).

Permissions for topics

The destination that is specified in an STOMP header during message publishing or subscription contains a topic in the level-1 string. The client must have the relevant permission for this topic. To send messages associated with the topic, the client must have the publishing permissions for the topic. To subscribe to the topic or to cancel the subscription, the client must have the subscription permissions for the topic. For more information about how to apply for and grant permissions to topics, see Grant permissions to RAM users of RocketMQ.

Endpoint

The address and port of the remote RocketMQ broker to which the STOMP client needs to connect. The internal network access service is available only in the region of Singapore. The endpoint is as follows:

Network type Domain name Port
Classic network classic.stomp.ap-southeast-1.aliyuncs.com 8080
VPC network vpc.stomp.ap-southeast-1.aliyuncs.com 8080

Limits

  • STOMP is supported only in Singapore and will be supported in other regions later.
  • Endpoints are accessible only to clients in their regions. A client in one region cannot access an endpoint in a different region.
  • STOMP messages are not persistent. A client will not receive previous messages after reconnecting to the RocketMQ broker.
  • As required by the STOMP protocol, at most one transaction can be executed over a client connection at a time, and each transaction can have no more than three messages. After the client is disconnected, the transaction is automatically rolled back if it is not committed.
  • SSL connections are not supported.
  • The RocketMQ broker supports connections with clients that run STOMP 1.0, 1.1, and 1.2.
  • The selector function is not supported.
  • A message destination can contain digits, letters, hyphens (-), and underscores (_).

Developer guide

Many open-source STOMP client implementations are available. For more information, see the known STOMP compliant message servers. This document only provides sample code of open-source Python client stompest for message subscription and publishing.

Sample code for subscribers:

  1. import base64
  2. import hmac
  3. from hashlib import sha1
  4. from stompest.config import StompConfig
  5. from stompest.protocol import StompSpec
  6. from stompest.sync import Stomp
  7. QUEUE = '/xx/xxx'
  8. accessKey = 'xxxx'
  9. secretKey = 'xxx'
  10. clientId = 'recv_01'
  11. brokerUrl = 'tcp://xxxxxx:8080'
  12. passcode = base64.b64encode(hmac.new(secretKey.encode(), clientId.encode(), sha1).digest()).decode()
  13. CONFIG = StompConfig(brokerUrl, accessKey, passcode, StompSpec.VERSION_1_2)
  14. if __name__ == '__main__':
  15. client = Stomp(CONFIG)
  16. client.connect(
  17. {
  18. 'client-id': clientId,
  19. 'instance-id': 'xxxxx',
  20. })
  21. client.subscribe(QUEUE,
  22. {
  23. StompSpec.ACK_HEADER: StompSpec.ACK_CLIENT_INDIVIDUAL,
  24. StompSpec.ID_HEADER: '001',
  25. StompSpec.RECEIPT_HEADER: "R001"
  26. })
  27. frame = client.receiveFrame()
  28. print('recv: %s' % frame.info())
  29. while True:
  30. frame = client.receiveFrame()
  31. print('recv: %s' % frame.info())
  32. client.ack(frame)
  33. client.disconnect()

Sample code for senders:

  1. import base64
  2. import hmac
  3. import time
  4. from hashlib import sha1
  5. from stompest.config import StompConfig
  6. from stompest.protocol import StompSpec
  7. from stompest.sync import Stomp
  8. QUEUE = '/xx/xxx'
  9. accessKey = 'xxxxx'
  10. secretKey = 'xxxxx'
  11. clientId = 'send_01'
  12. brokerUrl = 'tcp://xxxx:8080'
  13. passcode = base64.b64encode(hmac.new(secretKey.encode(), clientId.encode(), sha1).digest()).decode()
  14. CONFIG = StompConfig(brokerUrl, accessKey, passcode, StompSpec.VERSION_1_2)
  15. if __name__ == '__main__':
  16. client = Stomp(CONFIG)
  17. client.connect(
  18. {
  19. 'client-id': clientId,
  20. 'instance-id': 'xxxxx'
  21. })
  22. for i in range(1, 100):
  23. msg = 'm_' + str(i)
  24. print('send :' + msg)
  25. client.send(QUEUE, msg.encode(), {StompSpec.RECEIPT_HEADER: str(i)})
  26. frame = client.receiveFrame()
  27. print('resp: %s' % frame.info())
  28. time.sleep(1)