J. Tegen Internet Draft OmicronSoft Document: draft-tegen-smqp-02.txt September 2001 Expires: March 1, 2002 SMQP: Simple Message Queue Protocol Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 10 of RFC2026 except that the right to produce derivative works is not granted. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. All comments should be directed to the author at john@omicronsoft.com Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved Abstract The Simple Message Queue Protocol (SMQP) provides a standard form of sharing data between those that publish data and those that desire to subscribe to data. Publish/subscribe systems decouple the two end points from knowing about one another. SMQP will provide a common protocol to be used for a variety of implementation from simple chat applications to mission critical message flows. Tegen Internet Draft 1 Simple Message Queue Protocol (SMQP) October 2001 Revisions The following are the changes to the draft specifications. The Table of contents will be out of sync until the final draft is complete and this Revisions section is removed. 01: o Illegal characters in the document. o Cleaned up grammar in various locations. 02: o Various grammar, BNF, samples, and formatting corrections. o Removed spec that all messages are placed in Trash queue after deliver. o Removed command REPUBLISH since the publisher would be responsible in sending a message again. o Domain context removed since multiple servers can be configured on one computer using VHOST. o Added command LIST SUBSCRIPTIONS so the client can receive the current list of topics they are subscribed to. o SET NOTIFY PORT now includes an optional ip-address parameter so the client can re-direct the server to send notification messages to another machine, as well as the previously parameter ip-port. o SET NOTIFY SUSPEND and RESUME now has an optional topic parameter to allow a client to suspend and resume based on the topic's path. o SMUID definition expanded to not be re-circulated over time. o Guarantee attribute added to PUBLISH MESSAGE command. Table of Contents 1. Introduction ............................................... 4 1.1 Overview of SMQP Functionality ........................ 4 1.2 Terminology ........................................... 4 2. Architecture of SMQP ....................................... 6 2.1 Goal of the Architecture .............................. 6 2.2 Topics and Queues ..................................... 7 2.2.1 Trash Topics ..................................... 8 2.2.2 Login Topics ..................................... 8 2.3 Server Domains ........................................ 9 2.4 Messages .............................................. 10 3. Publisher and Subscriber Identification .................... 11 4. The SMQP Specifications .................................... 11 4.1 SMQP Commands ......................................... 12 4.1.1 LOGIN ............................................ 12 Authentication / PASSWORD ........................ 14 4.1.2 COUNT ............................................ 15 4.1.2.1 TOPIC ....................................... 15 4.1.2.2 MESSAGE ..................................... 15 4.1.2.3 SUBSCRIBERS ................................. 16 4.1.3 LIST ............................................. 16 4.1.3.1 TOPIC ....................................... 16 4.1.3.2 MESSAGE ..................................... 17 4.1.4 CREATE ........................................... 17 4.1.4.1 TOPIC ....................................... 17 4.1.5 REMOVE ........................................... 18 Tegen Internet Draft 2 Simple Message Queue Protocol (SMQP) October 2001 4.1.5.1 TOPIC ....................................... 18 4.1.6 SET .............................................. 19 4.1.6.1 TOPIC ....................................... 19 4.1.6.1.1 NAME ................................... 19 4.1.6.1.2 KEYWORD ................................ 20 4.1.6.2 LOGIN ....................................... 20 4.1.6.2.1 PASSWORD ............................... 20 4.1.6.2.2 NAME ................................... 20 4.1.6.2.3 EMAIL .................................. 21 4.1.6.2.4 ADDRESS ................................ 21 4.1.6.2.5 PHONE................................... 21 4.1.6.3 NOTIFY ...................................... 21 4.1.6.3.1 PORT ................................... 21 4.1.6.3.2 SUSPEND ................................ 22 4.1.6.3.3 RESUME ................................. 22 4.1.7 FIND ............................................. 22 4.1.7.1 TOPIC ....................................... 22 4.1.8 PUBLISH .......................................... 24 4.1.8.1 MESSAGE ..................................... 24 4.1.8.2 REPLY ....................................... 28 4.1.9 SUBSCRIBE ........................................ 30 4.1.9.1 MESSAGE ..................................... 30 4.1.9.2 TOPIC ....................................... 31 4.1.9.3 SUBSCRIBER .................................. 31 4.1.9.4 SERVER ...................................... 32 4.1.9.4.1 TIMEOUT ................................ 32 4.1.10 UNSUBSCRIBE ...................................... 32 4.1.10.1 MESSAGE ..................................... 32 4.1.10.2 TOPIC ....................................... 33 4.1.10.3 SUBSCRIBER .................................. 34 4.1.11 NOTIFY ........................................... 34 4.1.11.1 MESSAGE ..................................... 35 4.1.11.2 TOPIC ....................................... 37 4.1.11.3 SUBSCRIBER .................................. 37 4.1.11.4 SERVER ...................................... 38 4.1.11.4.1 TIMEOUT ................................ 38 4.1.11.4.2 BYE .................................... 38 4.1.12 GET .............................................. 38 4.1.12.1 MESSAGE ..................................... 38 4.1.12.2 TOPIC ....................................... 39 4.1.13 NOOP ............................................. 40 4.1.14 QUIT ............................................. 40 5. Implementation Considerations .............................. 41 6. Security Consideration ..................................... 41 7. Variable Definitions ....................................... 43 8. Authors' Address ........................................... 45 APPENDIX A: Reply Codes ......................................... 46 APPENDIX B: Message Flow ........................................ 49 References ...................................................... 50 Glossary ........................................................ 50 Full Copyright Statement ........................................ 52 Tegen Internet Draft 3 Simple Message Queue Protocol (SMQP) October 2001 Tegen Internet Draft 4 Simple Message Queue Protocol (SMQP) October 2001 1.0 Introduction 1.1 Overview of SMQP Functionality This document specifies the Simple Message Queue Protocol (SMQP) for use of exchanging messages from publishers of data to subscribers of data. Many Internet applications use publish and subscribe architecture but they either use separate Internet Protocols or proprietary protocols. Proprietary protocols include those with proprietary implementations. The market leaders for publish and subscribe applications include MQSeries (R) from IBM and MSMQ (R) from Microsoft. SMQP will allow the asynchronous sending of messages from publishers of data, to subscribers of data independent from implementation, OS platform, vendor, and computer language. Message queuing allows for a message to be pushed out to a network and reside there until at least one subscriber of that message receives it. SMQP will allow for mission critical message flow to be achieved in near real-time. Examples of publish and subscribe mechanisms include financial transactions (stock quotes and trades), mail, chat rooms, file sharing/transferring, paging, instant messaging, news forums, system alerts, database transactions, and list forums. Wherever data needs to be shared between any number of sources that provide the data and any number of recipients that want to receive that data, SMQP may be used. A single transaction protocol can be used where currently many different protocols are current being used (both open and proprietary). 1.2 Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. This document used Backus-Naur Form (BNF) nomenclature [RFC822]. The augmented BNF has the following constructs: name = definition The name of a rule is simply the name itself (without any enclosing "<" and ">") and is separated from its definition by the equal "=" character. White space is only significant in that indentation of continuous lines is used to indicate a rule definition that spans more than one line. Certain basic rules are uppercase as SP, LWS, HT, CRLF, DIGIT, and ALPHA, etc. Angle brackets are used within definition whenever their presence will facilitate discerning the use of rule names. "literal" Quotation marks surround literal text. Unless otherwise, the text is case-insensitive. rule1 | rule2 Tegen Internet Draft 5 Simple Message Queue Protocol (SMQP) October 2001 Elements separated by a bar ("|") are alternatives, e.g. "yes | no" will accept yes or no. (rule1 | rule2) Elements enclosed in parentheses are treated as a single element. Thus, "(elem ( foo | bar ) elem )" allows for tokens sequences "elem foo elem" and "elem bar elem". *rule The character "*" preceding an element indicates repetition. The full form is "*element" indicating at least and at most occurrences of element. Default values are 0 and infinity so that "*(element)" allows any number, including zero; "1*element" requires at least one; and "1*2element" allows for one or two. [rule] Square brackets enclose optional elements; "[foo bar]" is equivalent to "*1(foo bar)". N rule Specific repetition: "(element)" is equivalent to "*(element)"; that is exactly occurrences of (element). Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three alphabetic characters. #rule A construct of "#" is defined, similar to "*", for defining lists of elements. The full form is "#element" indicating at least and at most elements, each separated by one or more commas (",") and OPTIONAL linear white space (LWS). This makes usual form of list very easy; a rule such as ( *LWS element *(*LWS "," *LWS element )) can shown as 1#element. Whenever this construct is used, null elements are allowed, but do not contribute to the count of elements present. That is, "(element), , (element)" is permitted, but counts as only two elements. Therefore, where at least one element is required, at least one non-null element MUST be present. Default values are 0 and infinity so that "#element" allows any number, including zero; "1#element" requires at lease one; and "1#2element" allows one or two. ; comment A semi-colon, set off some distance to the right of rule text, starts a comment that continues to the end of the line. implied *LWS The grammar described by this specification is word-based. Except where noted otherwise, linear white space (LWS) can be included between any two adjacent words (token or quoted-string), and between words and separators, without changing the interpretation of a field. At least one delimiter (LWS and/or separator) MUST exist between any two tokens, since they would otherwise be interpreted as a single token. Tegen Internet Draft 6 Simple Message Queue Protocol (SMQP) October 2001 2. Architecture of SMQP SMQP focuses on the distribution of messages between publishers and subscribers. SMQP is based upon client-server architecture. A client is either a publisher of messages, a subscriber of messages, or both. The server receives published messages and then brokers the messages to subscribers based upon a topic context. The server MAY also be a client to another SMQP server by publishing a message from its cluster of clients to the cluster of clients of another SMQP server. A client must authenticate itself with each server it wishes to publish or subscribe messages with. Here is an example of a publish/subscribe system. [ Publisher : Stocks ] [ Publisher : Chat ] [ Publisher : News ] | | | +-----------------------+---------------------+ | [ Broker ] | +-----------------------+---------------------+ | | [ Subscriber : Chat ] [ Subscriber : News ] Messages are categorized by a topic. A single message queue on the server is assigned to a single topic. Topics and queues can be considered one in the same. The SMQP server controls access permissions of a client to publish or subscribe to a topic. A request to publish or subscribed by a client SHALL be rejected by the server. The server, by default will listen for TCP notifications on port 721. The client, by default, will connect to the SMQP server using TCP port 720. 2.1 Goal of the Architecture The goal of the SMTP architecture is to provide a simple to use, publish and subscribe messaging protocol. This is achieved by: 1) Messages are transaction based by default. 2) Messages are persisted before being forwarded to the subscriber by default. 3) Asynchronous delivery of messages. 4) Any number of publishers can publish messages. 5) Any number of subscribers can receive messages. 6) Messages MAY contain multiple type(s) of data based on MIME specifications. 7) Once only delivery of messages. 8) Fault tolerate behavior. 2.2. Topics and Queues Topics are a hierarchal description of a message between a publisher and a subscriber. The topic is independent of the format of the message data. This allows for a topic to contain any number of message types. Topics are: Tegen Internet Draft 7 Simple Message Queue Protocol (SMQP) October 2001 1) Hierarchical 2) Case insensitive 3) UTF-8 character set 4) Contain no spaces 5) Cannot start with a number 6) Cannot contain non-alphanumeric characters 7) Always separated by a forward slash ("/") 8) Root hierarchy begins with a forward slash The hierarchical topics allow topics to relate to one another. Defining the topics this way makes it easier to traverse and find other topics that might be of interest to a client. The hierarchical topics are very similar to a file system directory structure. The root topic starts with the forward slash ("/"). Topics are case insensitive. A sample topic hierarchical MAY look something like: +- chat ---+- internet | | | +- intranet | / -+- news ---+- us | | | +- europe | | | +- asia | +- stocks -+- quotes | +- charts Each of the end topics is considered to be a "leaf" topic. All leaf topics have parent topics, unless the topic is at the first level of the hierarchy. Topics, like chat shown above, have two child topics (internet and intranet). There is no restriction in the architecture that limits the depth and width of the topics. The only restrictions that MAY be put into place would be the particular SMQP server implementation. Topic names SHALL NOT exceed 32 characters each. Topics SHALL be placed in queues. The server MAY implement queues as necessary, but it is easy to think of queues as the same thing as topics and could have the same structure and context as the topic. If a particular topic does not contain permission for a particular user, then the topic will use the permissions defined by the parent topic. This would progress until the root is reached. Newly created topics inherit the permissions of the parent topic. Other characteristics of a topic/queue are: 1) Messages are processed First In-First Out (FIFO). Higher priority messages MAY be moved forward in the queue based upon the server's implementation. For example, a server MAY ignore message priority or perform some heuristics on Tegen Internet Draft 8 Simple Message Queue Protocol (SMQP) October 2001 messages with priorities based on the publisher. This would allow a fair weighting of message priority in the queue. 2) Topics can have keywords associated with it. These key words MAY be used to query the server for a topic based on some combination of these keywords. 3) Topics can be virtually represented on the SMQP server. A virtual topic links to an actual topic. Virtual topics behave just like actual topics. Virtual topics MAY be used for variations of topic structure or allow an older topic to be transitioned to a newer topic without publishers and subscribers failing because of a re-organization of topics. Virtual topics SHALL only map to actual topics and cannot link to them. Any number of virtual topics can be linked to the same actual topic. A topic of /weather/us/ca/san/forecast MAY contain many types of published messages including text that describes the temperature, humidity, rainfall, and wind; as well as a JPEG image of the satellite image of the region. Some level of standardization would need to be done so that subscribers can find the topic path it needs to subscribe to. A client can request the currently available topics that are available on the server. 2.2.1. Trash Topics Each topic contains a child topic with the name "Trash". "Trash" is a reserved topic name (case insensitive) that MUST NOT be used in the hierarchy of topics. The Trash topic/queue is a repository of messages for the parent topic that contains dead messages. Dead messages are any message that is not still pending in the parent queue. This includes messages that were unable to be delivered to subscribers after a certain number of attempts. Messages in the Trash queue will remain there until the server periodically empties the messages in a particular topic's trash or all the topics trash. 2.2.2. Login Topics Each time a login account is created, a topic/queue is created for that account. These topics are used for reply messages that MAY be generated by a subscriber. Tegen Internet Draft 9 Simple Message Queue Protocol (SMQP) October 2001 2.3. Server Domains Each SMQP server SHALL reside in a domain. Each server has its own unique context that is usually the domain name of the server, or its static IP address. For example: www.domain.com The domain name SHOULD be used for the server context due to physical changes of hardware and to keep the server's location transparent to the clients and other SMQP servers. A SMQP server can be configured to link with another SMQP server. Clients based on the same domain host name, but unique port numbers connect to multiple SMQP servers on the same host. Published messages from one SMQP domain will be forwarded to any other registered domains that have at least one subscriber for that message. Messages that are sent to the immediate SMQP server are considered "local" messages. Messages that are passed to other SMQP servers, by the local server, will then be considered "remote" messages. A message being published MAY define the depth message is allowed to be forwarded. By default, the depth is only to the local server. Messages that are passed to other domains will have their topic pre- pended with the server's domain. Messages that are routed between servers are verified before delivery to ensure the message has not already passed to that server via another route path. Servers connecting with another server are authenticated like any other client application connecting to a server. The server accepting the connection determines the authenticity and permissions of the adjoining server. Since the server does not contain user authentication for each of the accounts of the requesting server, it MUST assume it to be an un-trusted environment. The administrator of the server MUST determine which topics the requesting server has access to. It has to assume that any user access granted from the requesting server has permission to access the topics that it allows for the requesting server. User Access List (UAL) is also defined by a server of which remote servers an account as permission to access. Tegen Internet Draft 10 Simple Message Queue Protocol (SMQP) October 2001 2.4. Messages A message is a container of data, with a header that is passed from a publisher (that created the data), through the SMQP server that brokers (routes) the message to subscribed clients. [ Publisher ] ----[X]--->[ Broker ]------->[ Subscriber ] ^ | message +------------>[ Subscriber ] Other than the header, the message does not concern itself with the contents of the data except that it knows the messages' length and associated MIME type that is used by the subscriber to understand it's contents. Messages MAY have multiple parts to the data section of the message. Each part MUST have an associated MIME type and length. Messages persist with the SMQP server until some period has expired. Subscribers that are no longer logged into the SMQP server and did not unsubscribe to the topic will receive pending messages that were published since the last time the subscriber logged in, as long as the messages did not expire. Most publish/subscribe messages are event based. When something changes in the publisher, it would publish an event-based message. For example, stock quote change, stock purchase, news item, et cetera. The other type of message is state based. State based messages persist longer than an event-based message. The only difference that separates these two types of message is the length of the messages timeout. The message timeout informs the server how long a message will wait around for a subscriber to receive it. The timeout is the life span of the message. For example, a message with a timeout of 1 minute will persist on the server for 1 minute after all the current subscribers have been informed. If a new client subscribes to that topic within that 1 minute, it will also receive that message. Clients that subscribe after the 1 minute will not receive the message nor would they know that the message ever existed. If a publisher publishes message for a chat topic, they MAY set the timeout for 48 hours, long enough time for client subscribers to get recent chat discussions. A publisher for a list or news forum MAY set the timeout to be infinite, so any new client subscriber will always receive all the messages in that topic. While a client is subscribing to a topic, they can OPTIONALLY specify a timeout period that would limit which messages are then transmitted to them, based on server's received date/time of the message. Publishers of state based messages SHALL be responsible for deleting those messages before publishing a new state message. Messages are delivered to subscribers in the order that the publishing clients sent them (FIFO). However, it is possible that messages MAY be sent out of order due to network latency, server outages, resources on a topic's queue has exceeding so messages are held out until resources are balanced again, or administration of server causes later messages to slip by earlier messages. Publishers whose message order is vital (e.g. stock quotes), their Tegen Internet Draft 11 Simple Message Queue Protocol (SMQP) October 2001 messages can be sequenced. The message can have an OPTIONAL sequence number that is incremented sequentially by the publisher for each message. The server does nothing with the sequence number. It SHALL be the subscriber's responsibility to check and manage messages that MAY have been received in a different order than the sequence number indicates. There is no correlation between a topic and the message's data that MAY be published to that topic. That enforcement, if any, is the responsibility of the publisher and subscriber and/or another RFC. 3. Publisher and Subscriber Identification Publishers and subscribers are identified by the login account in addition to some global unique identifier (GUID). The account name, plus GUID will then allow the same account to be logged into multiple times to the same server. The server SHALL enforce unique login accounts. If a user is logged into the server more than once, each site will receive the same published messages. 4. The SMQP Specifications Once a client connects to the SMQP server via TCP/IP connection, the server SHALL respond to the client with the SMQP identifier, version, and implementation identification; ending with . For example, SMQP/1.0 Ready. OmicronSoft SMQP Server/1.0 (c) 2001 The server is REQUIRED to return this identification when a new client connects to it. "SMQP" "/" version [ 1*SP status "." [ 1*SP server-ident ] ] version = 1*DIGIT "." 1*DIGIT ; . status = ( "Ready" | "Not Available" ) server-ident = The client MAY ignore anything after the "SMQP/1.0". The client MAY use this to identify the protocol and version of the protocol being used by the server. After the server identification, the client may interact with the server by issuing commands, along with server data, and then wait for a reply from the server. Tegen Internet Draft 12 Simple Message Queue Protocol (SMQP) October 2001 4.1. SMQP Command The SMQP commands define the message transaction of the user or client application. SMQP commands MUST be character strings that terminate by . The commands themselves are alphabetic characters separated by if any parameters follow and otherwise. Various examples are provided in this section. Each command or response is prefixed to designate who is sending or receiving the information. "C:" designates that the client is issuing the command or response. "S:" designates that the server is issuing the command or response. Many of the commands can be abbreviated to shorten the number of bytes that are transmitted and received. Abbreviated commands are OPTIONAL. Clients and server implementations SHALL NOT introduce alternative abbreviations and MUST support the receiving of the abbreviated commands. 4.1.1. LOGIN "LOGIN" 1*SP username 1*SP authentication-method "/" version authentication-method is the method the client wishes to encrypt the password with the server. This may be a series of interactions with the server that may include determining which authentication method is supported by the server and/or a series of steps need as part of the selected authentication method. Example authentication methods include "CLEAR", "KERBEROS", and "MD5". Minimally, all servers SHALL implement "CLEAR" authentication, which sends the client's password in the clear (not encrypted). It is up to the client to determine the method of authentication. CLEAR authentication example: C: LOGIN jtegen CLEAR/1.0 S: 200 OK C: PASS jtegen mypasswd S: 200 OK The version for CLEAR method is meaningless but SHOULD be provided to the server for consistency. KERBEROS authentication example (not supported by server): C: LOGIN jtegen KERBEROS/5.0 S: 405 Not allowed KERBEROS authentication example (supported by server): C: LOGIN jtegen KERBEROS/5.0 S: 200-OK S: 200-+ AmFYig== C: BAcAQU5EUkVXLkDFeFDERFCEFEFee/RETYEFE... S: + or//EoAADZI Tegen Internet Draft 13 Simple Message Queue Protocol (SMQP) October 2001 C: DiAF5A4gA+oIALuBKAAmw== S: 200 OK Client application SHALL log into the server. Upon successful authentication, the client application SHALL then be allowed to publish and subscribe messages. The server will OPTIONALLY respond with default values that it has currently set that the client MAY use in sending and receiving messages. The default state MAY change during the runtime period of a client. The client has the option to subscribe to state changes of the server. Reply Codes: 200 OK 311 Redirect request REDIRECT = ip-address ":" ip-port 400 Bad Request 401 Unauthorized (password not correct) 404 Not found (account not found) 405 Not allowed (authentication method) Redirect Request A reply code of 311 from the server upon LOGIN informs the client that the server is not accepting additional requests, and the client should try another IP address and/or port number. The 311 reply code is followed by the redirection address. For example, C: LOGIN jtegen CLEAR/1.0 S: 311-Redirect request S: 311 192.168.0.100:721 The client, upon receiving this reply, should disconnect from the server and re-connect to the suggested IP address and port. Depending on the configuration of the server, a client may be re- directed several times. All redirected LOGIN requests contains the same topic structure as the original server, and other than the redirect LOGIN request, the client would not experience any additional differences with the server farm. Tegen Internet Draft 14 Simple Message Queue Protocol (SMQP) October 2001 Authentication Each authentication method applies different rules to validate the client login process. Minimally, both client and server implementations SHALL include the "CLEAR" method. However, it is still up to the server's implementation and rules that it MAY apply to its installation and login accounts. When the CLEAR method is used between the client and server, the client SHALL respond to the server with the PASSWORD command. The PASSWORD command only applies to the CLEAR authentication-method. PASSWORD = ( "PASSWORD" | "PASS" ) 1*SP account 1*SP password Each login method needs to inform the server which account the password verification is meant for. The server MAY be processing other LOGIN requests during the period of time a client is responding to their LOGIN request. The server SHALL return the REQUIRED name value attributes, and OPTIONALLY the OPTIONAL attributes. Attributes are a name, followed by a value, separated by a colon (:). TOPIC = "Topic" ":" topic REQUIRED topic of the user's account. The client application SHOULD subscribe to this topic so it MAY receive system and reply messages. TIMEOUT = "Timeout" ":" timeout OPTIONAL server default message timeout. Messages that do not specify a timeout will default to the server's timeout period. If the server does not return a TIMEOUT attribute on login, it is RECOMMENDED that the client sets a timeout period for all messages. TIME = "Time" ":" date-time The REQUIRED TIME is the current date/time of the server. This can be used to correlate messages published and received to and from the server. The client SHOULD assume some measure of latency in the actual time of the server, and the time it took to deliver the reply. Time is delivered at GMT. GUID = "Guid" ":" guid The server that describes that instance of the account login returns a global unique identifier. This allows the same login identification be logged into the server multiple times. The generation of the GUID is server implementation dependent as long it is unique for each logged in instance of the account. Tegen Internet Draft 15 Simple Message Queue Protocol (SMQP) October 2001 Example LOGIN sequence: C: LOGIN jtegen CLEAR/1.0 S: 200 OK C: PASS jtegen rowe7kuy S: 200-OK S: 200-Topic: /accounts/jtegen S: 200-Timeout: 00:24:00:00 S: 200-Time: D20010823T14451246Z S: 200 Guid: jtegen0456 S: 4.1.2. COUNT "COUNT" 1*SP resource 1*SP topic COUNT returns the quantity of a given resource. Both the and are REQUIRED fields. For all COUNT commands, a wildcard can be used for the leaf topic. The wildcard SHALL traverse all child topics of the parent topic, regardless of depth. Reply codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (item not found) 4.1.2.1 TOPIC "COUNT" 1*SP "TOPIC" 1*SP topic COUNT TOPIC returns the quantity of child topics of a given parent topic. The quantity does not include any system child topics like the "Trash" topic. Example COUNT TOPIC: C: COUNT TOPIC /news C: S: 200-OK S: 200 2 S: 4.1.2.2 MESSAGE "COUNT" 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic The COUNT command can be used to determine the number of messages currently retained by the SMQP server at the instance the request was made. This is not totally accurate, since the volume of message passing through a queue could be Tegen Internet Draft 16 Simple Message Queue Protocol (SMQP) October 2001 very large and the rate in which they are being processed MAY lag the value being returned. Example COUNT MESSAGE sequence: C: COUNT MESSAGE /stock/quote/ibm C: S: 200-OK S: 200 45 S: 4.1.2.3 SUBSCRIBERS "COUNT" 1*SP ( "SUBSCRIBERS" | "SUB" ) 1*SP topic COUNT SUBSCRIBERS command returns the number of currently subscribed clients to a particular topic. Example COUNT SUBSCRIBERS sequence: C: COUNT SUB /stock/quote/ibm C: S: 200-OK S: 200 12 S: 4.1.3. LIST "LIST" 1*SP resource [ 1*SP item ] LIST command allows a client to list various items on the server. The server controls access for what a particular login has access to. Though a particular item MAY exist on the server, the LIST command will not return its existence if the login does not have permission to access it. Reply Codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (item not found) 4.1.3.1. LIST TOPIC "LIST" 1*SP "TOPIC" 1*SP topic LIST TOPIC returns a list of topics underneath the provided topic. The server, except for any system topics like the "Trash" topic, will return all child topics of the given topic. Each child topic will be in its own line of the return stream, followed by a . The parent-topic parameter is REQUIRED. Tegen Internet Draft 17 Simple Message Queue Protocol (SMQP) October 2001 Example LIST TOPIC sequence: C: LIST TOPIC / C: S: 200-OK S: 200-/stocks S: 200-/info S: 200-/news > /info/news/cnn S: 200 /weather S: The last returned topic displays a virtual topic that is actually linked to another topic. 4.1.3.2. LIST MESSAGE "LIST" 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic LIST MESSAGE returns a list of message identifiers currently in the given topic. This is only a snap shot of the current messages, since those messages MAY change in the next fraction of a second. The topic parameter is REQUIRED. Example LIST MESSAGE sequence: C: LIST MESSAGES /stocks/quotes/ibm C: S: 200-OK S: 200 1809-1812,1845,1850-1890 S: 4.1.3.2. LIST SUBSCRIPTIONS "LIST" 1*SP ( "SUBSCRIOTIONS" | "SUB" ) LIST SUBSCRIPTIONS returns a list of topics the client is currently subscribed to. Clients that previously subscribed to topics without unsubscribing to them upon QUITing will still be subscribed to those topics. A client MAY wish to issue this command before subscribing to those same topics. Example LIST SUBSCRIPTIONS sequence: C: LIST SUBSCRIPTIONS C: S: 200-OK S: 200-/stocks/quotes/ibm S: 200 /stocks/quotes/msft S: Tegen Internet Draft 18 Simple Message Queue Protocol (SMQP) October 2001 4.1.4. CREATE "CREATE" 1*SP "TOPIC" 1*SP topic [ 1*SP "(" keyword "," ... ")" ] [ 1*SP ">" 1*SP topic ] CREATE TOPIC creates a new topic by the given topic path. If the topic already exists, the server will return a reply code that signifies this. Topics are case insensitive. Server SHALL disallow the creation of a topic by the same path of a user's account reply topics. Topic leaf names SHALL not exceed 32 characters. Reply codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (destination-topic not found) 405 Not allowed (topic link bad) 409 Conflict (topic and destination-topic the same) 414 Resource too large (too many topics for parent topic) Example CREATE TOPIC sequence: C: CREATE TOPIC /stocks/quotes/ibm C: S: 200 OK S: CREATE TOPIC command can also create a virtual topic by defining what the new topic SHOULD map to. The topic being mapped to MUST already exist. Example CREATE TOPIC sequence for virtual topics: C: CREATE TOPIC /stocks/quotes/ibm > /stocks/ibm/quote C: S: 200 OK S: The creation of the topic can also add OPTIONAL keywords to the topic, allowing another client to query a topic based on these key words. The topic keywords are unstructured. Keywords are OPTIONALLY added as the last parameter in the list. A comma separates each keyword. Keywords are case insensitive. Example CREATE TOPIC sequence with keywords: C: CREATE TOPIC /stocks/ibm (IBM,STOCKS,QUOTE,BIG BLUE) C: S: 200 OK S: Tegen Internet Draft 19 Simple Message Queue Protocol (SMQP) October 2001 Example CREATE TOPIC sequence for a virtual topic, with keywords: C: CREATE TOPIC /stocks/ibm (BIG BLUE) > /stocks/quotes/ibm C: S: 200 OK S: 4.1.5. REMOVE ( "REMOVE" | "REM" ) 1*SP "TOPIC" 1*SP topic Topics can be removed from the server, but will only be removed when the last message has been delivered to clients that MAY have subscribed to that topic. Any new, published messages to that topic will return an error as if the topic no longer exists. Only authorized clients have permission to delete a topic. The topic parameter is REQUIRED. Reply Codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (topic) Example REMOVE TOPIC sequence: C: REMOVE TOPIC /stocks/quotes/ibm S: 200-OK S: 200 12 messages pending S: 4.1.6. SET SET commands allows the client to set values of various resources. SET command allows the client to possibly modify the current value of one of these resources. 4.1.6.1. SET TOPIC SET TOPIC family of commands allows the client to set various properties of a topic/queue. 4.1.6.1.1. SET TOPIC NAME "SET" 1*SP "TOPIC" 1*SP "NAME" 1*SP topic 1*SP new-topic A client can set a topic's name. Renaming a topic does not affect any pending messages in the queue. However, any new messages published to the topic will return an error to the publisher as if the topic no longer exists. The new topic would be available for publishers to send messages to. A topic cannot be renamed to itself or to a topic that already exists. Both the topic and new-topic parameters are REQUIRED. Tegen Internet Draft 20 Simple Message Queue Protocol (SMQP) October 2001 Account topics SHALL NOT be allowed to be removed by this command. This command should be used very carefully. The server MAY wish to restrict authorization of this command for only the original creator of the topic and possibly the administrator of the server. Reply Codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (topic) 409 Conflict (new-topic and topic are the same) Example SET TOPIC NAME sequence: C: SET TOPIC NAME /stocks/quotes/ibm /stocks/ibm/quote C: S: 200 OK S: 4.1.6.1.2. SET TOPIC KEYWORD "SET" 1*SP "TOPIC" 1*SP "KEYWORD" 1*SP topic 1*SP keywords A client can set topics keywords. Any existing keywords for the designated topic will be replace to the new values. Example SET TOPIC KEYWORD sequence: C: SET TOPIC KEYWORD /stocks/ibm (BLUE,IBM,STOCKS) C: S: 200 OK S: 4.1.6.2. SET LOGIN SET LOGIN command allows the client to set various properties of their user login account. "SET" 1*SP "LOGIN" 1*SP ( "PASSWORD" | "NAME" | "EMAIL" | "ADDRESS" | "PHONE" ) ... 4.1.6.2.1. SET LOGIN PASSWORD "SET" 1*SP "LOGIN" 1*SP ( "PASSWORD" | "PASS" ) 1*SP authentication-method 1*SP "/" 1*SP version Tegen Internet Draft 21 Simple Message Queue Protocol (SMQP) October 2001 A client can set their login password to a new value. The client application enforces password expiration and rules governing password rules (e.g. length, duplication, etc.). As with the LOGIN command, the SET LOGIN PASSWORD needs to negotiate with the server on the method of authentication. The server SHALL accept or deny the authentication method suggested by the client. In general, the client SHOULD use the same authentication method used during the LOGIN. Once the server accepts the authentication method, the client would pass the old password and then the new password. For example: C: SET LOGIN PASSWORD CLEAR/1.0 S: 405 Not allowed C: SET LOGIN PASSWORD KABEROS/4.0 S: 200-OK S: 200 + AmFYig== C: BAcAQU5EUkVXLkDFeFDERFCEFEFee/RETYEFE... S: + or//EoAADZI C: DiAF5A4gA+oIALuBKAAmw== S: AmFYig== C: BAcAQU5eUkVXLkDF6FDuRFCyFEFee/RETYiFE... S: + or//EojArZI C: pOAF5A4UA+oI6LuBKAimw== S: 200 OK 4.1.6.2.2. SET LOGIN NAME "SET" 1*SP "LOGIN" 1*SP "NAME" 1*SP name SET LOGIN NAME allows the client to change the owner's name of the current logged in account. This is the proper name of the account, for example, "Jayne Smith". 4.1.6.2.3. SET LOGIN EMAIL "SET" 1*SP "LOGIN" 1*SP "EMAIL" 1*SP email-address SET LOGIN EMAIL allows the client to change the owner's e- mail account of the current logged in account. 4.1.6.2.4. SET LOGIN ADDRESS "SET" 1*SP "LOGIN" 1*SP "ADDRESS" 1*SP address SET LOGIN ADDRESS allows the client to change the owner's ground mail address of the current logged in account. 4.1.6.2.5. SET LOGIN PHONE Tegen Internet Draft 22 Simple Message Queue Protocol (SMQP) October 2001 "SET" 1*SP "LOGIN" 1*SP "PHONE" 1*SP phone-number SET LOGIN PHONE allows the client to change the owner's telephone number of the current logged in account. 4.1.6.3. SET NOTIFY "SET" 1*SP "NOTIFY" 1*SP ( "PORT" | "SUSPEND" | "RESUME" ) SET NOTIFY commands allows the client to inform the server how it wants to be notified of published messages. The SET NOTIFY command affects all subscribed messages to the client. 4.1.6.3.1. SET NOTIFY PORT [ ip-address ] "SET" 1*SP "NOTIFY" 1*SP "PORT" 1*SP ip-port [ 1*SP ip-address ] SET NOTIFY PORT informs the server that the client is now listening for publications on a different port number. The server SHALL discontinue any connections to the existing client port and re-connect to the new port number and/or optional address. The client SHALL begin listening to messages to the ip-port/ip-address prior to sending this request to the server, since the server SHALL attempt to connect to this port/address before replying. By default, a client begins listening on default-client-port. Reply Codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (port) 408 Request timeout 4.1.6.3.2. SET NOTIFY SUSPEND [ topic ] "SET" 1*SP "NOTIFY" 1*SP ( "SUSPEND" | "SUS" ) [ 1*SP topic ] SET NOTIFY SUSPEND informs the server to suspend sending any publications that the client may have subscribed to. Messages will not be published to the client until a RESUME message is sent to the server. By default, all topics are suspended, however, the client MAY suspend a specific topic. The normal command, without topic, is equivalent to SET NOTIFY SUSPEND *. Tegen Internet Draft 23 Simple Message Queue Protocol (SMQP) October 2001 4.1.6.3.3. SET NOTIFY RESUME [ topic ] "SET" 1*SP "NOTIFY" 1*SP ( "RESUME" | "RES" ) [ 1*SP topic ] SET NOTIFY RESUME informs the server to resume sending any publications that the client may have subscribed to. This is normally issued after a SUSPEND request. The server SHALL ignore the RESUME request if no previous SUSPEND request was issued by the client. By default, all topics are resumed, however, the client MAY resume a specific topic. The normal command, without topic, is equivalent to SET NOTIFY RESUME *. 4.1.7. FIND "FIND" 1*SP "TOPIC" 1*SP topic [ 1*SP keyword [ "," keyword ]... ] FIND TOPIC will return the topic(s) specified in the REQUIRED topic parameter. The return will provide any keywords associated with the topic, encased in "(" and ")". The server SHALL return a list of topics that match the search. Reply Codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (topic) 405 Not allowed Example FIND TOPIC sequence: C: FIND TOPIC /stocks C: S: 200-OK S: 200 /stocks (STOCKS,TICKERS) S: This example can be used to verify an existence of a topic and return any keywords that MAY have been assigned to it. FIND TOPIC can be used to find those topics that match the OPTIONAL keyword search, from a given parent topic. The keyword parameter case insensitive. Example FIND TOPIC by keyword sequence: C: FIND TOPIC /stocks BLUE C: S: 200-OK S: 200 /stocks/ibm (IBM,STOCKS,BIG BLUE) S: Tegen Internet Draft 24 Simple Message Queue Protocol (SMQP) October 2001 Wildcards can be used on the FIND command, in combination of the keyword search. The following example will search for all child topics underneath /stocks, that contains any portion of the keyword "BLUE". C: FIND TOPICS /stocks/* BLUE C: S: 200-OK S: 200-/stocks/ibm (IBM,STOCKS,BIG BLUE) S: 200 /stocks/floral (FLOWERS,BLUE CARNATIONS) S: 4.1.8. PUBLISH 4.1.8.1. PUBLISH MESSAGE ( "PUBLISH" | "PUB" ) 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic 1*SP cmuid The PUBLISH command publishes a message to a REQUIRED topic, by a REQUIRED client message unique identifier (cmuid). The message comprised of two sections; the header and an OPTIONAL data. Any subscriber, subscribed to that topic, will be forwarded the publisher's message. Publishing a message to the SMQP server is a single-phase transaction. If the server does not respond with an affirmative reply, the publisher has to assume the message did not get published. +------------------------------+ | Header | +------------------------------+ | Data Section | |+----------------------------+| || Data Header (0) || |+----------------------------+| || Data || || || || || |+----------------------------+| |+----------------------------+| || Data Header (n) || |+----------------------------+| || Data || || || || || |+----------------------------+| +------------------------------+ Tegen Internet Draft 25 Simple Message Queue Protocol (SMQP) October 2001 The published message has a list of attributes that are define in the header of the message. NAME = "Name" ":" text-UTF8 A message may have a context. This can be viewed as the subject of the message. The name does not have to be unique in a given topic. The name is free formed but shall be limited to one line of no more than 128 characters. The NAME attribute is OPTIONAL. An example of this attribute is: Name: New Protocol Release; charset="iso-8859-4" PRIORITY = ( "Priority" | "Pri" ) ":" positive-number PRIORITY is a numeric value greater than zero that can OPTIONALLY define the priority of the message in the topic's queue. Messages are normally processed FIFO in a topic's queue. Messages that define a priority are organized so that lower priority numbers are sent before higher priority numbers (priority of 2 is sent before a priority of 10). CREATED = "Created" ":" date-time CREATED is the REQUIRED date/time the message was created, just prior to being streamed to the server. The date/time is REQUIRED to be based on GMT (Zulu) zone and seconds are expressed in fractions of a second. The CREATED date/time MAY be used by the subscriber to verify the ordering of messages received. RECEIPT = "Receipt" ":" boolean RECEIPT is an OPTIONAL, Boolean attribute that informs the server to return a message to the publisher that the message was successfully delivered to at least one subscriber. The values of the attribute are either YES or NO. By default, the server SHOULD assume no receipt is needed if the attribute is not provided in the header. Recipient messages are published to the login account's system topic/queue. REPLY = "Reply" ":" boolean REPLY is an OPTIONAL, Boolean attribute that informs the subscriber that the publisher is expecting some kind of reply message upon successful receipt of the published message. If the REPLY is set to YES, the subscriber SHOULD reply to the message appropriately. If the attribute is missing from the header, the subscriber MUST assume that no reply is needed. Reply messages are published to the login account's system topic/queue. TIMEOUT = "Timeout" ":" timeout TIMEOUT is the OPTIONAL period of time a message will persist on the server after the current subscribers have been sent the published message. If the attribute is missing from the header, the server will default to the timeout period defined by the topic's queue. Timeout of a negative value (<0) Tegen Internet Draft 26 Simple Message Queue Protocol (SMQP) October 2001 indicates a state message and the message will persist for an infinite period of time until the message is REMOVED. DEPTH = "Depth" ":" number DEPTH is an OPTIONAL, numeric value that determines how deep (number of hops) a published message will be routed to other SMQP servers. A depth of zero (0) will only route a message to local subscribers of the server. Depths greater than zero will allow the message to be routed to adjoining servers to the given depth, at which point, the message will no longer be routed. A depth of (-1) assumes no limit to the server depth. If the attribute is not included in the header, the server MUST assume a depth of zero, or only those subscribers on the local server. SEQUENCE = ( "Sequence" | "Seq" ) ":" positive-number SEQUENCE is an OPTIONAL, positive number that assists the subscriber in knowing the sequence of a series of messages from a particular publisher and topic/queue. If a publisher needs to ensure that published messages are received in a particular order, the publisher would increment the SEQUENCE value by one each time a new message is generated. It is the responsibility of the subscriber to cache messages that MAY have been received out of sequence. The SEQUENCE is unique for a HOST, TOPIC, and CMUID. The subscriber MAY also be able to use the CREATED attribute to help determine message sequential latency at the source of the message. GUARANTEE = ( "Guarantee" | "Guar" ) ":" boolean GUARANTEE is an OPTIONAL attribute that informs the server and the subscriber that the published message needs to be delivered unconditionally. By default, all implementations SHALL assume messages are guaranteed. The server acknowledges published, guaranteed messages. Messages delivered to subscribers have a two-phase commit acknowledgement. Non-guaranteed messages (set to false) avoid all acknowledgements (both publisher to server and server to subscriber). A publisher, sending a non-guaranteed message, SHOULD NOT wait for a reply. Likewise, subscribers SHOULD NOT reply with an acknowledgement nor expect any additional data for that particular message. Publishers who do not care if any subscribers ever receive the message use non-guaranteed messages. These publishers are usually sending out a large volume of messages, that any missed messages would not impact subscribers. Additionally, the removal of acknowledgement increases overall throughput. An example implementation of non-guaranteed messages could be a client publishing joystick or mouse movements. Tegen Internet Draft 27 Simple Message Queue Protocol (SMQP) October 2001 Additional extended attributes can be defined in the header. These attributes are prefixed with "X-" that indicates the attribute is not a part of the SMQP specifications. The last attribute in the header is followed by a before the data header begins. MIME-VERSION = "MIME-Version" ":" major "." minor MIME-VERSION is an OPTIONAL attribute that informs which version of the MIME specification is being supported with the current message. The subscriber MAY use this information to help it understand the CONTENT-TYPE of the data. CONTENT-TYPE = "Content-Type" ":" media-type CONTENT-TYPE is a REQUIRED attribute after the header. There is a content type for each data section in the message. The content type uses the MIME specification that describes the format of the data to follow. The CONTENT-TYPE belongs to the header section of the data. It is preceded by that separates the header from the data section. Example of this attribute is Content-Type: application/x-rft Content-Type: text/plain; charset="ISO-8859-4" CONTENT-LENGTH = "Content-Length" ":" 1*DIGIT The CONTENT-LENGTH is a REQUIRED attribute after the header. The content length is for each data section in the message. The content type is the number of bytes in the data to follow. CONTENT-ENCODING = "Content-Encoding" ":" 1#content-coding When present, its value indicates what additional content coding have been applied to the data, and thus what decoding mechanism must be applied in order to obtain the media-type referenced by the Content-Type. Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its underlying media type. Example of this attribute is Content-Encoding: zip ENCRYPTION = "Encryption" ":" encryption-scheme 1*SP encryption-scheme = token encryption-params = token "=" ( token | quoted-string ) Example of this attribute is Encryption: PGP version=2.6.2,encoding=ascii Additional extended attributes can be defined in the header of the data. These attributes are prefixed with "X-" that indicates the attribute is not a part of the SMQP specifications. Tegen Internet Draft 28 Simple Message Queue Protocol (SMQP) October 2001 The last attribute in the data header is followed by a before the data begins. The server acknowledges receipt of the published message after the reply code. The acknowledge command is followed by the CMUID that was in the header of the message, along with a server generated message unique identification (SMUID). The SMUID can be used to perform additional commands on the message that now resides on the server. The CMUID is returned so the publisher can be certain to know which response maps to which generated message. Example PUBLISH MESSAGE sequence: C: PUB MESSAGE /stocks/quotes/ibm A004 C: Priority: 1 C: Created: D20010815T08341245Z C: Receipt: yes C: Name: Stock quote for IBM C: Reply: NO C: Timeout: 00:01:00 C: Depth: 1 C: Sequence: 34 C: C: Content-Type: text/plain C: Content-Length: 5 C: C: 24.567 C: . C: S: 200-OK S: 200 A004 2001083408341156-1810 S: A message can have multiple data sections in one message. Examples of this MAY include plain and HTML text, or weather description along with a GIF satellite image. Example PUB MESSAGE with multiple data sections sequence: C: PUB MESS /stocks/quotes/ibm A005 C: Priority: 1 C: Name: IBM Quote C: Created: D20010815T08341245Z C: Receipt: yes C: Reply: NO C: Timeout: 00:01:00 C: Depth: 1 C: Sequence: 34 C: C: Content-Type: text/plain C: Content-Length: 5 C: C: 24.567 Tegen Internet Draft 29 Simple Message Queue Protocol (SMQP) October 2001 C: C: Content-Type: text/html C: Content-Length: 52 C: C: 24.567 C: . C: S: 200-OK S: 200 A005 2001083408392156-1830 S: 4.1.8.2. PUBLISH REPLY ( "PUBLISH" | "PUB" ) 1*SP "REPLY" 1*SP topic 1*SP cmuid A client has the option to reply to a published message without having to know who the publisher is. The command would issue a message to the topic the message was received from as well as the Client Message Unique Identification (CMUID) for the client replying to the message. This is not the same CMUID that is in the attribute list of the original message. For example, if a subscriber received and performed the following sequence: S: NOTIFY MESSAGE /stocks/quotes/ibm S: Created: D20010815T08032445Z S: Smuid: www.host.com/0834200108342156-1835 S: Cmuid: jtegen/jtegen497549/A004 S: Content-Type: text/plain S: Content-Length: 12 S: S: 34.456 S: . S: C: 310 ACK C: S: 310 ACK S: They would then be able to send a reply back to the publisher by: C: PUB REPLY /stocks/quotes/ibm CF0456 C: Created: D20010815T08035341Z C: Smuid: www.host.com/1835 C: Cmuid: jtegen/jtegen497549/A004 C: Priority: 1 C: Timeout: 00:01:00 C: Content-Type: text/plain c: Content-Length: 12 C: C: Thank you C: . Tegen Internet Draft 30 Simple Message Queue Protocol (SMQP) October 2001 C: S: 200-OK S: 200 CF0456 0834200108345156-1838 S: The CMUID field additionally indicates that this new message is a reply to a previously sent message. The server would then route the reply to the originating client publisher. At this point, a two-way communication between to end points can be achieved. The original publisher can now reply to the end point that sent the reply. Tegen Internet Draft 31 Simple Message Queue Protocol (SMQP) October 2001 4.1.9. SUBSCRIBE ( "SUBSCRIBE" | "SUB" ) 1*SP resource 1*SP topic SUBSCRIBE commands subscribe to a resource notification. Once subscribed, the subscriber will be notified by the server when a change to the current subscription has occurred. 4.1.9.1. SUBSCRIBE MESSAGE ( "SUBSCRIBE" | "SUB" ) 1*SP ("MESSAGE" | "MESS" ) 1*SP topic [ 1*SP date-time ] SUBSCRIBE MESSAGE allows a client to subscribe to message for a given, REQUIRED topic. Once subscribed, any message posted to that topic will be routed to the subscriber. The OPTIONAL, parameter allows the publisher to only subscribe to message since a given GMT time. This allows the client to filter out timeless messages that MAY have built upon over time. If the subscriber sets the parameter to only a few seconds earlier then the present time, then the number of waiting messages would be reduced. Additionally, this parameter can be used to wait to receive messages until some time is reached in the future. For example, a subscriber MAY only wish to subscribe to weather updates until after 0400 hours GMT the next day. Messages pending to that subscriber that are prior to the optional parameter SHALL be cleared for that subscriber. The parameter is informing the server that the subscriber does not care about older messages. The server replies with a code and then an acknowledgement of the subscription. Reply Codes: 200 OK, success 400 Bad request 401 Unauthorized 404 Not found (topic) 414 Resource too large (cannot subscribe to any more) Example SUBSCRIBE MESSAGE sequence: C: SUB MESSAGE /stocks/quotes/ibm C: S: 200-OK S: 200 /stocks/quotes/ibm S: Tegen Internet Draft 32 Simple Message Queue Protocol (SMQP) October 2001 At this point the client will need to wait to receive a message from the SMQP server. A client can use wild cards to subscribe to all topics under a certain leaf. This will allow them to receive new messages of publications that have yet to be published. For example. C: SUBSCRIBE MESSAGE /stocks/quotes/* C: S: 200-OK S: 200-/stocks/quotes/ibm S: 200-/stocks/quotes/msft S: 200 /stocks/quotes/sony S: The server SHALL NOT allow a subscription of all messages at the root topic as shown here: C: SUB MESSAGE /* C: S: 510 Maximum quantity exceeded S: Additionally, the server MAY implement other constraints to limit the number of subscriptions that can be requested at one time or entirely. See NOTIFY MESSAGE for the type of notification received by the client when subscribed to this resource. 4.1.9.2. SUBSCRIBE TOPIC ( "SUBSCRIBE" | "SUB" ) 1*SP "TOPIC" 1*SP topic A client MAY subscribe to changes that have occurred to a topic. Changes MAY include that a topic was added, renamed, or removed. C: SUBSCRIBE TOPIC /stocks/quotes/ibm C: The SUBSCRIBE TOPIC command MAY use a wildcard in the topic to subscribe to any changes to the topic and its children. C: SUB TOPIC /stocks/quotes/* C: See NOTIFY TOPIC for the type of notifications received by the client when subscribed to this resource. 4.1.9.3. SUBSCRIBE SUBSCRIBER Tegen Internet Draft 33 Simple Message Queue Protocol (SMQP) October 2001 ( "SUBSCRIBE" | "SUB" ) 1*SP ( "SUBSCRIBER" | "SUB" ) 1*SP topic A client MAY subscribe to changes with subscribers for a given topic. C: SUB SUB /stocks/quotes/ibm C: See NOTIFY SUBSCRIBERS for the type of notifications received by the client when subscribed to this resource. 4.1.9.4. SUBSCRIBE SERVER ( "SUBSCRIBE" | "SUB" ) 1*SP "SERVER" 1*SP attribute A client MAY subscribe to various attributes of the server. Changes to the server's subscribed attribute will then notify interested clients. SERVER subscribed messages are stateless messages with a zero timeout period. Only the currently connected clients will receive SERVER notification messages. This is to avoid a subscriber connecting later and receiving a server notification message that is obsolete. 4.1.9.4.1. SUBSCRIBE SERVER TIMEOUT ( "SUBSCRIBE" | "SUB" ) 1*SP "SERVER" 1*SP "TIMEOUT" Default timeout of messages by the server. By default, all clients are automatically subscribed to SUBSCRIBE SERVER BYE command. SERVER BYE notifies client when the server is shutting down. 4.1.10. UNSUBSCRIBE ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP resource 1*SP topic UNSUBSCRIBE commands unsubscribe previously subscribed resources by the client. If the client does not unsubscribe before terminating the session with the server, the SMQP server will retain messages until the client logs into the server again. Pending messages, that have not expired, will be delivered to the client. 4.1.10.1. UNSUBSCRIBE MESSAGE ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic A client MAY unsubscribe to messages of a topic. Tegen Internet Draft 34 Simple Message Queue Protocol (SMQP) October 2001 Reply codes: 200 OK, success 400 Bad request 404 Not found (topic) C: UNSUB MESSAGE /stocks/quotes/ibm C: S: 200-OK S: 200 MESSAGE /stocks/quotes/ibm S: The client can use wildcards to unsubscribe blocks of topics. For example, to unsubscribe to all topics a client would issue a command like C: UNSUB MESSAGE * C: S: 200-OK S: 200-MESSAGE /stocks/quotes/ibm S: 200-MESSAGE /stocks/quotes/msft S: 200 MESSAGE /stocks/quotes/sony S: The wildcard can be applied to any aspect of the topic hierarchy. For example if the client subscribed to the following: C: SUB MESSAGE /stocks/quotes/ibm C: SUB MESSAGE /stocks/quotes/sony C: SUB MESSAGE /weather/us/ca/san/forecast C: S: 200-OK S: 200-MESSAGE /stocks/quotes/ibm S: 200-MESSAGE /stocks/quotes/sony S: 200 MESSAGE /weather/us/ca/san/forecast S: The client could later unsubscribe to just the quote subscriptions as follows: C: UNSUB MESSAGE /stocks/* C: S: 200-OK S: 200-MESSAGE /stocks/quotes/ibm S: 200 MESSAGE /stocks/quotes/sony S: 4.1.10.2. UNSUBSCRIBE TOPIC ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP "TOPIC" 1*SP topic A client MAY unsubscribe to changes to a topic. Tegen Internet Draft 35 Simple Message Queue Protocol (SMQP) October 2001 Reply codes: 200 OK, success 400 Bad request 404 Not found (topic) C: UNSUB TOPIC /stocks/quotes/ibm C: S: 200-OK S: 200 TOPIC /stocks/quotes/ibm S: C: UNSUB TOPIC /stocks/quotes/* C: S: 200-OK S: 200-TOPIC /stocks/quotes/ibm S: 200 TOPIC /stocks/quotes/beos S: C: UNSUB TOPIC * C: S: 200-OK S: 200-TOPIC /stocks/quotes/ibm S: 200-TOPIC /stocks/quotes/beos S: 200 TOPIC /lists/news/os S: 4.1.10.3. UNSUBSCRIBE SUBSCRIBERS ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP ( "SUBSCRIBER" | "SUB" ) 1*SP topic A client MAY unsubscribe to changes to subscribers of a topic. Reply codes: 200 OK, success 400 Bad request 404 Not found (topic) Unsubscribe to all subscription, regardless of resource, can be done by wildcarding the resource C: UNSUB * C: S: 200-OK S: 200-MESSAGE /stocks/quotes/ibm S: 200-MESSAGE /stocks/quotes/sony S: 200-TOPIC /stocks/quotes/ibm S: 200-TOPIC /stocks/quotes/beos S: 200 SUB /stocks/quotes/ibm S: Tegen Internet Draft 36 Simple Message Queue Protocol (SMQP) October 2001 4.1.11. NOTIFY "NOTIFY" 1*SP resource The notification of a published resource is sent to the subscriber from the SMQP server. The notification is a two-phase commit operation. While the client is not sending a command, it SHOULD be listening for notification messages. 4.1.11.1. NOTIFY MESSAGE "NOTIFY" 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic SMQP does not concern itself with the contents of the data that is carried along with the message. The sender and receiver of the message are responsible for the creation, definition, and interpretation of the message data. Examples of message data could be plain text, images (JPEG, GIF), audio files, XML, or binary streams. The receiver MUST handle a message that it is unable to interpret based on its content type gracefully. Sending a reply back to the sender would not be a friendly behavior since the publisher is not responsible for putting the data in a format that all subscribers can understand. Data MUST be of a discrete length. Continuous stream of data, like audio broadcasts, are not supported under SMQP. Two-phase commit This is to ensure that the client properly receives the message and that the client knows that the server received acknowledgement of the receipt. The server will not send the next notification until it has received an acknowledgement by the client that it has received the message. The next publication notification sent to the client would occur after the server acknowledged the client's acknowledgement. Implementations MAY vary, but the example above would perform the following: S: NOTIFY MESSAGE S: ... S: Client saves the message (memory or disk) and sends the server an acknowledgement that it received the message. C: 310 ACK C: The server would save that this message was successfully sent to the client, and will not try to resend this message again ever. The server would then tell the client that it acknowledge receipt of the original acknowledgement. Tegen Internet Draft 37 Simple Message Queue Protocol (SMQP) October 2001 S: 310 ACK S: Now the client can act on the message by displaying it or forwarding it to a sub-system process. If the client does not receive acknowledgement from the server that the server knows the client received the message OK, it MUST assume that the server is likely to resend the message again. If it does not receive the message again in some period of time (client implementation dependent), it MAY proceed with the message that it has. Example NOTIFY MESSAGE sequence: S: NOTIFY MESSAGE /stocks/quotes/ibm S: Created: D20010815T08032445Z S: Smuid: www.host.com/0834200108342156-1835 S: Cmuid: jtegen/jtegen3454654/A004 S: Priority: 1 S: Receipt: yes S: Reply: NO S: Timeout: 00:01:00 S: Depth: 1 S: Sequence: 34 S: S: Content-Type: text/plain S: Content-Length: 12 S: S: 34.456 S: . S: C: 310 ACK C: S: 310 ACK S: Refer to PUBLISH MESSAGE command for attribute description. Additional attributes that are affixed to the message header by the server, include: SMUID = "Smuid" ":" host "/" positive-number SMUID is the REQUIRED Server Message Unique Identifier. This is the UID generated by the server, when the publisher first published the message. This UID is always globally unique for a particular server and does not get re-circulated over time. CMUID = "Cmuid" ":" account "/" guid "/" uid CMUID is the REQUIRED Client Message Unique Identifier. This is the account, GUID, and the UID generated by the publisher. This information is used to reply to the given message. Tegen Internet Draft 38 Simple Message Queue Protocol (SMQP) October 2001 4.1.11.2. NOTIFY TOPIC "NOTIFY" 1*SP "TOPIC" 1*SP topic Notification that a topic has been modified. Topic notification are followed with attributes that describe the change. ACTION = "Action" ":" ( ( "ADDED" | "ADD" ) | ( "RENAME" | "REN" ) | ( "DELETED" | "DEL" ) | ( "KEYWORDS" | "KEY" ) ) [value] ACTION attributes describes the action done to a topic. The value for ACTION are: o ADDED o RENAME o DELETED o KEYWORDS S: NOTIFY TOPIC /stocks/quotes/ibm S: ACTION: RENAME /stocks/quotes/big_blue S: 4.1.11.3. NOTIFY SUBSCRIBERS "NOTIFY" 1*SP ( "SUBSCRIBERS" | "SUB" ) 1*SP topic Notification that a change in the number of subscribers occurred for a topic. The publisher MAY use this to stop sending updates if they know there are not any subscribers wanting their data. This can dramatically reduce the network traffic of messages. COUNT 1*SP ":" 1*SP COUNT attribute returns the current number of subscribers to the topic. Example NOTIFY SUBSCRIBERS sequence: S: NOTIFY SUB /stocks/quotes/ibm S: COUNT: 34 S: 4.1.11.4. NOTIFY SERVER "NOTIFY" 1*SP ( "SERVER" | "SERV" ) 1*SP resource 4.1.11.4.1. NOTIFY SEVER TIMEOUT "NOTIFY" 1*SP ( "SERVER" | "SERV" ) 1*SP "TIMEOUT" 1*SP timeout Tegen Internet Draft 39 Simple Message Queue Protocol (SMQP) October 2001 4.1.11.4.2. NOTIFY SERVER BYE "NOTIFY" 1*SP ( "SERVER" | "SERV" ) 1*SP "BYE" [ 1*SP timeout ] NOTIFY BYE is a server notification to all currently connected clients. Clients are notified when the server MAY be shutting down. It will inform the clients that it will not be available by a certain period of time. S: NOTIFY SERVER BYE 00:05:00 S: This notifies the client that the server is shutting down in 5 minutes. If the server is shutting down right away, and the client really has no option but to shut down too, the client would receive either S: NOTIFY SERVER BYE 00:00:00 S: Or S: NOTIFY SERVER BYE S: Tegen Internet Draft 40 Simple Message Queue Protocol (SMQP) October 2001 4.1.12. GET 4.1.12.1. GET MESSAGE "GET" 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic 1*SP smuid GET MESSAGE allows a client to get a specific message that MAY still be in a queue on the server. A client can get a message even if they have already received the message. C: GET MESSAGE /stocks/quotes/ibm 1865 C: S: 200 OK S: Topic: /stocks/quotes/ibm S: Created: D20010815T08032445 S: SMUID: host.com/1835 S: CMUID: jtegen/jtegen005/A004 S: Content-Type: text/plain S: Content-Length: 12 S: S: 34.456 S: . S: The following are valid GET requests to the server: C: GET MESSAGE /stocks/quotes/ibm 1865 C: GET MESSAGE /stocks/quotes/ibm 1866 C: GET MESSAGE /stocks/quotes/sony 2007 C: C: GET MESSAGE /stocks/quotes/ibm 1865-2340 C: C: GET MESSAGE /stocks/quotes/ibm 1845-1890,1905,1920-1930 C: C: GET MESSAGE /stocks/quotes/ibm * C: 4.1.12.2. GET TOPIC KEYWORDS "GET" 1*SP "TOPIC" 1*SP ( "KEYWORDS" | "KEY" ) 1*SP topic GET TOPIC KEYWORDS returns the current keywords for the given topic. The client may set the keywords by using the SET commands. C: GET TOPIC KEYWORDS /stocks/quotes/ibm C: S: 200-OK S: 200 IBM,BIG BLUE,STOCKS,COMPUTERS S: Tegen Internet Draft 41 Simple Message Queue Protocol (SMQP) October 2001 4.1.13. NOOP "NOOP" This command does not affect any parameters or previously entered commands. It specifies no action other than that the server sends an reply code. Reply Codes: 200 OK, success 400 Bad request 501 Not implemented 4.1.14. QUIT "QUIT" QUIT discontinues a session with the SMQP server. Any subscribed resources are still subscribed to. Reply Codes: 200 OK, success 400 Bad request C: QUIT C: S: 200 OK S: Tegen Internet Draft 42 Simple Message Queue Protocol (SMQP) October 2001 5. Implementation Considerations This section discusses items to be considered when implementing either the client or server that supports SMQP. The protocol is independent of implementation, however there are certain capabilities that SHOULD be considered during design and development of both clients and server. 5.1. Server 1) Supply a default timeout for messages before deletion. 2) Retry timeout. 3) Maximum retry per message per client. 4) Server SHOULD be as stateless as possible, so in case of failure, it can be restarted without any loss of information. 5) Maximum file size to receive (overall and per queue), give error code. 6) Send server/client limits (file size, MIME type, ...). 7) Restrict number of subscriptions in one request. 8) Restrict total number of subscriptions by a user account. 9) The server should be designed to handle a large number of publishers and subscribers and a large volume of messages. Message throughput is a vital design concern of the server. 5.2. Client 1) Client SHOULD be as stateless as possible. 2) Client MAY wish to be multi-threaded to allow one thread to post commands and one thread to listen for server notifications. 6. Security Consideration Security is a vital consideration for any mission critical system that shares information between distributed users. Server operations, for each topic/queue are regulated by a User Access List (UAL). UALs are controlled by the system administrator of the server and cannot be accessed through the SMQP commands. Messages cannot be published to a topic if that user does not have permission to do so. Likewise, a subscriber cannot subscribe to a topic if they do not have permission to do so. Each topic/queue can be configured with different parameters. These parameters include: 1) User access to publish to. 2) User access to subscribe from. 3) User access to modify queue parameters. a. Expiration timeout b. Retry timeout c. Maximum retries d. Maximum message count e. Maximum message size f. Maximum queue size (total message size) 4) User access to create, rename, or delete topics at or below the current queue/topic. 5) User permission to reply to sent messages. 6) User permission to access remote servers. Tegen Internet Draft 43 Simple Message Queue Protocol (SMQP) October 2001 SMQP SHALL allow unsecured and secured protocols. The secured protocol (SMQPS) SHALL use public forms of encryption like PGP. SMQP does not enforce any type of data encryption or encoding of the data section of the message. The message header can be extended with additional name value attributes to allow the subscriber of the message to decrypt or decode the message data. Login password authentication CAN support any number of methods. This includes from passing a clients password in the clear, to stronger authentication methods like Kerberos. The client requests a method of authentication to the server. Depending on how the server is implemented and/or configured, the server MAY reject the authentication method requested. Upon a rejection from the server, the client may try other methods until accepted by the server. Upon agreeing upon a method, the client and server would interact until the server is satisfied on the authentication of the client based on the method used. Tegen Internet Draft 44 Simple Message Queue Protocol (SMQP) October 2001 7. Variable Definitions The syntax of the above argument fields (using BNF notation where applicable) is given below. The "..." notation indicates that a field MAY be repeated one or more times. ::= 720 ::= 721 ::= | "." ::= | "." ::= | ::= """ """ ::= "\" | "\" | | ::= | "\" ::= "." "." "." ::= | ::= greater than zero ::= ::= the carriage return character (ASCII code 13) ::= the line feed character (ASCII code 10) ::= the space character (ASCII code 32) ::= one, two, or three digits representing a decimal integer value in the range 0 through 255 ::= any one of the 52 alphabetic characters A through Z in upper case and a through z in lower case
::= ::= ::= ( "YES" | "NO" ) ::= any one of the 128 ASCII characters, but not any or Tegen Internet Draft 45 Simple Message Queue Protocol (SMQP) October 2001 ::= ::= any one of the ten digits 0 through 9 ::= "@" "." ::= ::= ::= ::= ::= identifier for a ::= "(" ,,...")" ::= ::= ::= ::= any one of the 128 ASCII characters except , , quote ("), or backslash (\) ::= command ::= "<" | ">" | "(" | ")" | "[" | "]" | "\" | "." | "," | ";" | ":" | "@" """ | the control characters (ASCII codes 0 through 31 inclusive and 127) ::= with a maximum of 32 characters. ::= without 's and characters. ::= ::= 1*DIGIT "." 1*DIGIT "."; . ::= without and ::= any one of the 128 ASCII characters (no exceptions) Note that the backslash, "\", is a quote character, which is used to indicate that the next character is to be used literally (instead of its normal interpretation). For example, "Joe\,Smith" could be used to indicate a single nine character user field with comma being the fourth character of the field. Tegen Internet Draft 46 Simple Message Queue Protocol (SMQP) October 2001 Hosts are generally known by names which are translated to addresses in each host. Note that the name elements of domains are the official names -- no use of nicknames or aliases is allowed. Sometimes a host is not known to the translation function and communication is blocked. To bypass this barrier two numeric forms are also allowed for host "names". One form is a decimal integer prefixed by a pound sign, "#", which indicates the number is the address of the host. Another form is four small decimal integers separated by dots and enclosed by brackets, e.g., "[123.255.37.2]", which indicates a 32-bit ARPA Internet Address in four 8-bit fields. ::= The standard names for protocols are registered with the Network Information Center. ::=