J. Tegen Internet Draft OmicronSoft Document: draft-tegen-smqp-09.txt September 2001 Expires: April 15, 2003 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. 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 memo defines an Experimental Protocol for the Internet community. This memo does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Derivations of this work are not granted. 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) November 2002 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 CONNECTTO ........................................ 15 4.1.2 COUNT ............................................ 16 4.1.2.1 TOPIC ....................................... 16 4.1.2.2 MESSAGE ..................................... 16 4.1.2.3 SUBSCRIBERS ................................. 16 4.1.3 LIST ............................................. 18 4.1.3.1 TOPIC ....................................... 18 4.1.3.2 MESSAGE ..................................... 18 4.1.3.3 SUBSCRIPTIONS ............................... 19 4.1.4 CREATE ........................................... 20 4.1.4.1 TOPIC ....................................... 20 4.1.5 REMOVE ........................................... 21 4.1.5.1 TOPIC ....................................... 21 4.1.5.2 MESSAGE ..................................... 21 4.1.6 MOVE ............................................. 22 4.1.6.1 MESSAGE ..................................... 22 4.1.7 SET .............................................. 22 4.1.7.1 TOPIC ....................................... 22 4.1.7.1.1 NAME ................................... 22 4.1.7.1.2 KEYWORDS ............................... 23 4.1.7.1.3 DELIVERY ............................... 23 4.1.7.2 LOGIN ....................................... 24 4.1.7.2.1 PASSWORD ............................... 24 4.1.7.2.2 CONTACT ................................ 25 4.1.7.3 NOTIFY ...................................... 25 4.1.7.3.1 SUSPEND ................................ 25 4.1.7.3.2 RESUME ................................. 26 4.1.8 FIND ............................................. 27 4.1.8.1 TOPIC ....................................... 27 4.1.9 PUBLISH .......................................... 28 4.1.9.1 MESSAGE (NEW) ............................... 28 REPLY .................................. 34 REPLACE ................................ 36 RECALL ................................. 36 4.1.10 SUBSCRIBE ........................................ 39 4.1.10.1 MESSAGE .................................... 39 4.1.10.2 TOPIC ...................................... 42 Tegen Internet Draft 2 Simple Message Queue Protocol (SMQP) November 2002 4.1.10.3 SUBSCRIBER ................................. 43 4.1.10.4 SERVER ..................................... 43 4.1.10.4.1 TIMEOUT ............................... 43 4.1.10.4.2 BYE ................................... 43 4.1.11 UNSUBSCRIBE ...................................... 44 4.1.11.1 MESSAGE ..................................... 44 4.1.11.2 TOPIC ....................................... 45 4.1.11.3 SUBSCRIBER .................................. 46 4.1.11.4 SERVER TIMEOUT .............................. 46 4.1.12 NOTIFY ........................................... 47 4.1.12.1 MESSAGE ..................................... 47 4.1.12.2 RECEIPT ..................................... 49 4.1.12.3 TOPIC ....................................... 50 4.1.12.4 SUBSCRIBER .................................. 50 4.1.12.5 SERVER ...................................... 51 4.1.12.5.1 TIMEOUT ................................ 51 4.1.12.5.2 BYE .................................... 51 4.1.13 GET .............................................. 52 4.1.13.1 MESSAGE ..................................... 52 4.1.13.2 TOPIC KEYWORDS .............................. 52 4.1.13.3 TOPIC DELIVERY .............................. 53 4.1.13.4 LOGIN CHANNEL ............................... 53 4.1.13.5 LOGIN CONTACT ............................... 54 4.1.14 NOOP ............................................. 54 4.1.15 QUIT ............................................. 54 5. Implementation Considerations .............................. 55 6. Security Consideration ..................................... 55 7. Variable Definitions ....................................... 57 8. Authors' Address ........................................... 60 APPENDIX A: Reply Codes ......................................... 61 APPENDIX B: Message Flow ........................................ 65 APPENDIX C: Revision History .................................... 66 References ...................................................... 69 Glossary ........................................................ 69 Full Copyright Statement ........................................ 71 Tegen Internet Draft 3 Simple Message Queue Protocol (SMQP) November 2002 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 4 Simple Message Queue Protocol (SMQP) November 2002 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 5 Simple Message Queue Protocol (SMQP) November 2002 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, listens to TCP port 720. the client informs the server what port it will listen to but is usually TCP port 721. 2.1 Goal of the Architecture The goal of the SMQP 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. 9) An individual topic, not the full path, SHALL NOT exceed 32 characters. Tegen Internet Draft 6 Simple Message Queue Protocol (SMQP) November 2002 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: 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 ("/"). 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. 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: Tegen Internet Draft 7 Simple Message Queue Protocol (SMQP) November 2002 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 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. Virtual topics can reference topics on a remote SMQP server (assuming proper permissions). An internal, Intranet SMQP server may be deployed to host internal chats and lists for employees but include virtual map to external SMQP servers that may provide published news, stocks and other chat topics. 4) Topics have various properties that govern various aspects of the topic/queue. These properties control access, state, delivery method, and more. 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. The login topic also includes context for a login channel. Tegen Internet Draft 8 Simple Message Queue Protocol (SMQP) November 2002 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, are 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 9 Simple Message Queue Protocol (SMQP) November 2002 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 ] The broker delivers the message based on the topic's property for delivery. The delivery may be none, all, or one subscriber(s). 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 re-login to the SMQP server and did not unsubscribe to the topic(s) previously, will receive pending messages that were published since the subscriber quit, 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 Tegen Internet Draft 10 Simple Message Queue Protocol (SMQP) November 2002 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), can have the messages 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 The login account and channel identifier identifies publishers and subscribers. The account name, plus channel will 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 11 Simple Message Queue Protocol (SMQP) November 2002 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 ":" channel 1*SP authentication-method "/" version The is the account name the client is logging into the server with. The user account has to be previously established by the server administrator. The provides the client the ability to specify a channel name that is associated with the . The channel is client specified and does not need to be administered by the server. The channel allows multiple clients use the same user account on the server. Client applications that login by the same and may interfere with one another in terms of subscriptions. The channel provides additional, unique context to a server account that is specified by the client application or end user. 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:orange CLEAR/1.0 S: 200 OK C: PASS jtegen mypasswd Tegen Internet Draft 12 Simple Message Queue Protocol (SMQP) November 2002 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:orange KERBEROS/5.0 S: 405 Not allowed KERBEROS authentication example (supported by server): C: LOGIN jtegen:orange KERBEROS/5.0 S: 200-OK S: 200-+ AmFYig== C: BAcAQU5EUkVXLkDFeFDERFCEFEFee/RETYEFE... S: + or//EoAADZI 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. In addition to the reply codes found in Appendix A, the meaning for: 311 Redirect request REDIRECT = ip-address ":" ip-port 401 authorized (password not correct) 403 Forbidden (too many concurrent logins) 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:orange 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 Tegen Internet Draft 13 Simple Message Queue Protocol (SMQP) November 2002 the redirect LOGIN request, the client would not experience any additional differences with the server farm. Guest Account SMQP servers SHOULD allow for guest clients to log into the server. Guest account name SHALL be "guest" with a blank password that can be sent using the CLEAR authentication method. It is up to the server deployment what permissions a guest account may have, if any. As with regular accounts, the server SHALL support multiple clients logged into the same account. Guest accounts are used for both end users as well as server-to- server access for relaying messages. 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 and associated channel. 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. Tegen Internet Draft 14 Simple Message Queue Protocol (SMQP) November 2002 SUID = "Suid" ":" suid The server shall return a Server Unique Identifier (SUID) that is network unique that identifies its instance to the client. This MAY be the server's host address, port, and other text concatenated together. The same SUID of the server is sent to each client login initiation. Server Connection To Client SMQP has bi-direction connections to allow for near real-time notification of events. The client, after it has been authenticated, can begin listening on a client specified port (usually 721). It can then notify the server what the port is and it will be ready for the server to connect to it by using the CONNECTTO command. CONNECTTO = "CONNECTTO" 1*SP account ":" channel 1*SP [ address ":" ] port The and is the same value as provided in the LOGIN command. The OPTIONAL
specifies the client address for the server to connect to. If the
is missing, the server will assume the same address the client is on. The is the port number for the server to connect to. The address is usually 721. Once the server connects to the client, the client will greet the server, the server will then authenticate itself with the SUID originally provided during the authentication interactions, and then the client will reply as being ready to process notifications. Example initialization sequence: Main Client Connection (Cnx) Client Listening Cnx ------------------------------------- ---------------------- C: C: LOGIN jtegen:orange CLEAR/1.0 S: 200 OK C: PASS jtegen rowe7kuy S: 200-OK S: 200-Topic: /accounts/jtegen/orange S: 200-Timeout: 00:24:00:00 S: 200-Time: D20010823T14451246Z S: 200 Suid: smqp.net/745/Z65e5y C: CONNECTTO jtegen:orange 721 S: C: SMQP/1.0 Ready. S: smqp.net/745/Z65e5y C: 200 OK S: 200 OK Tegen Internet Draft 15 Simple Message Queue Protocol (SMQP) November 2002 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. 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 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. Tegen Internet Draft 16 Simple Message Queue Protocol (SMQP) November 2002 Example COUNT SUBSCRIBERS sequence: C: COUNT SUB /stock/quote/ibm C: S: 200-OK S: 200 12 S: Tegen Internet Draft 17 Simple Message Queue Protocol (SMQP) November 2002 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 account does not have permission to access it. 4.1.3.1. LIST TOPIC "LIST" 1*SP "TOPIC" 1*SP topic LIST TOPIC returns a list of topics underneath the provided, REQUIRED . The server, except for any system topics like the "Trash" topic, will return all child topics of the given . The server reply is a multi-line reply with each topic on its own line. 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 . This is only a snap shot of the current messages, since those messages MAY change in the next fraction of a second. The 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: Tegen Internet Draft 18 Simple Message Queue Protocol (SMQP) November 2002 4.1.3.3. LIST SUBSCRIPTIONS "LIST" 1*SP ( "SUBSCRIPTIONS" | "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 19 Simple Message Queue Protocol (SMQP) November 2002 4.1.4. CREATE 4.1.4.1 CREATE TOPIC "CREATE" 1*SP "TOPIC" 1*SP topic [ 1*SP "(" keyword "," ... ")" ] [ 1*SP ">" 1*SP smqp-url ] 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. In addition to the reply codes found in Appendix A, the meaning for: 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. The topic being linked to may reside locally or remotely. Example CREATE TOPIC sequence for virtual, local topic: C: CREATE TOPIC /stocks/quotes/ibm > /stocks/ibm/quote C: S: 200 OK S: Example CREATE TOPIC sequence for virtual, remote topic: C: CREATE TOPIC /stocks/quotes/ibm > www.host.com/stocks/ibm C: S: 200 OK S: The linking to the remote topic will succeed if either the current account or "guest" account has permission to log into the remote server and has permission to access the remote topic. Tegen Internet Draft 20 Simple Message Queue Protocol (SMQP) November 2002 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: 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 4.1.5.1 REMOVE TOPIC ( "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 parameter is REQUIRED. Example REMOVE TOPIC sequence: C: REMOVE TOPIC /stocks/quotes/ibm S: 200-OK S: 200 12 messages pending S: 4.1.5.2 REMOVE MESSAGE ( "REMOVE" | "REM" ) 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic 1*SP smuid An explicit message, in a REQUIRED can be removed from the server. These messages may have a longer timeout period. Any subscribers that have not yet received the message will not receive it upon removal. Example REMOVE TOPIC sequence: C: REMOVE MESSAGE /stocks/quotes/ibm www.smqp.net/00202-127 Tegen Internet Draft 21 Simple Message Queue Protocol (SMQP) November 2002 S: 200 OK S: 4.1.6. MOVE 4.1.6.1 MOVE MESSAGE "MOVE" 1*SP ( "MESSAGE" | "MESS" ) 1*SP from-topic 1*SP smuid 1*SP to-topic The MOVE MESSAGE command allows a client to move an existing message, identified by the REQUIRED parameter, from the REQUIRED to the REQUIRED . Any clients subscribed to the will be notified. Example MOVE MESSAGE sequence: C: MOVE MESSAGE /chat/news/ www.smqp.net/202-128 /chat/news/old S: 200 OK S: 4.1.7. 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.7.1. SET TOPIC SET TOPIC family of commands allows the client to set various properties of a topic/queue. 4.1.7.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 and parameters are REQUIRED. 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. In addition to the reply codes found in Appendix A, the meaning for: Tegen Internet Draft 22 Simple Message Queue Protocol (SMQP) November 2002 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.7.1.2. SET TOPIC KEYWORDS "SET" 1*SP "TOPIC" 1*SP "KEYWORDS" 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. Both and are REQUIRED parameters. Example SET TOPIC KEYWORDS sequence: C: SET TOPIC KEYWORDS /stocks/ibm (BLUE,IBM,STOCKS) C: S: 200 OK S: 4.1.7.1.3. SET TOPIC DELIVERY "SET" 1*SP "TOPIC" 1*SP "DELIVERY" 1*SP topic 1*SP ( "NONE" | "ALL" | "ONE" ) SET TOPIC DELIVERY allows an authorized client to define how messages sent to the specified will be delivered to any subscribers. By default, the delivery method is "ALL". This allows the delivery state of all messages published to the topic. An individual message delivery option can be set as well. See the delivery option for publishing a message for more information. A message's delivery mode cannot over-ride the delivery mode of the topic. NONE : No messages will not be delivered to any subscribers. This method effectively deactivates messages to subscribers. Messages will reside in the queue until the delivery method changes. ALL : All messages will be delivered to any subscribers of the topic. This is the default method of delivery. ONE : A message posted to the topic will only be delivered to one subscriber. This method of delivery is for a topic where multiple subscribers are performing the same operation, but only one of those subscribers need to handle the message. For example, a point-of-sale transaction would set the topic for a single delivery. A single transaction based system may have many subscribers to balance Tegen Internet Draft 23 Simple Message Queue Protocol (SMQP) November 2002 the load of the quantity of transactions. The broker would send a message to the first available subscriber. If the transaction is successful, no other subscribers will receive the message. If the subscriber responds with not being available (416), the broker will try the next subscriber until the message is delivered. The server implementation SHALL handle the case where all subscribers respond with a 416 code. 4.1.7.2. SET LOGIN SET LOGIN command allows the client to set various properties of their user login account. 4.1.7.2.1. SET LOGIN PASSWORD "SET" 1*SP "LOGIN" 1*SP ( "PASSWORD" | "PASS" ) 1*SP authentication-method "/" version 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 KERBEROS/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 In a CLEAR authentication example, it is clearer to see how the passwords are exchanged with the server. For example: C: SET LOGIN PASSWORD CLEAR/1.0 S: 200 OK C: PASSWORD jtegen myoldpass S: 200 OK C: PASSWORD jtegen mynewpass Tegen Internet Draft 24 Simple Message Queue Protocol (SMQP) November 2002 S: 200 OK 4.1.7.2.2. SET LOGIN CONTACT "SET" 1*SP "LOGIN" 1*SP "CONTACT" 1*SP mime data SET LOGIN CONTACT allows a client to set the contact information associated with the login account. The type in the command defines the definition of the contact. The actual data associated with the contact identification follows the command and is bounded by control characters. Though the specification can support multiple types of contact formats, it is preferred to use the vCard Internet standard (RFC2424 and RFC2425). The vCard specification is similar in nature to the SMQP header definition. An example of this command, using the vCard format is: C: SET LOGIN CONTACT text/x-vcard C: begin:vcard C: version:2.1 C: n:Jayne;Smythe C: tel;home;voice;(201)555-1212 C: adr;work;postal;123 Main Street;Big Town;CA;92130 C: email;internet:jayne@smqp.net C: end:vcard C: vCard specification allows comments, pictures, URL's, multiple addresses, and multiple telephone numbers to just name a few. The full specification is available from the www.ietf.org web site. 4.1.7.3. SET NOTIFY "SET" 1*SP "NOTIFY" 1*SP resource 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.7.3.1. SET NOTIFY SUSPEND "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. Tegen Internet Draft 25 Simple Message Queue Protocol (SMQP) November 2002 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 *. 4.1.7.3.2. SET NOTIFY RESUME "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 *. Tegen Internet Draft 26 Simple Message Queue Protocol (SMQP) November 2002 4.1.8. FIND 4.1.8.1 FIND TOPIC "FIND" 1*SP "TOPIC" 1*SP topic [ 1*SP "(" keyword [ "," keyword ]... ")" ] [ 1*SP depth ] FIND TOPIC will return the topic(s) specified in the REQUIRED parameter. The return will provide any OPTIONAL keywords associated with the topic, encased in "(" and ")". The server SHALL return a list of topics that match the search. The OPTIONAL parameter allows the client to specify how many child layers it will search for matching the keywords. By default, the parameter is zero (0) which indicates only those immediate child topics are searched. 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: 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", but only four layers of topics deep. C: FIND TOPICS /stocks/* (BLUE) 4 C: S: 200-OK S: 200-/stocks/ibm (IBM,STOCKS,BIG BLUE) S: 200 /stocks/floral (FLOWERS,BLUE CARNATIONS) S: Tegen Internet Draft 27 Simple Message Queue Protocol (SMQP) November 2002 4.1.9. PUBLISH 4.1.9.1. PUBLISH MESSAGE ( "PUBLISH" | "PUB" ) 1*SP ( "MESSAGE" | "MESS" ) 1*SP [ ( "NEW" | "REPLY" | "REPLACE" | "RECALL" ) 1*SP ] topic 1*SP cmuid [ message ] "." The PUBLISH command publishes a message to a REQUIRED , by a REQUIRED client message unique identifier (cmuid). A message can be published one of four ways. NEW, the default method, informs the server that it is a new message. REPLY tells the server that the message is replying to a previously notified message and should manage the header's SMUID attributes accordingly. REPLACE informs the sever that this message is to replace an existing message in the topic. If the message were not present, or no longer present, it would be managed as a new message. RECALL allows a publisher to recall an already published message. RECALL message informs the SMQP server that a client is requesting a previously sent message to be recalled. A SMQP implementation may enforce some form of authorization enforcement on this command since all clients may wish not to recall other publisher's messages. For example, only the originator of the message can recall the message. If the message being recalled still exists in the topic, it would be removed and not further subscribers would be notified. Already notified subscribers would be notified of the recall. It is up to the client implementation to determine how to manage a recall request. In some instances it may be too late to recall an action already made. Example usages of recalling a message are: pulling back an improperly sent mail message to someone, moderating a chat room, or pulling back an order made. Recalling a message is not a guarantee. If the original message made it to subscribers or distributed to a remote SMQP server, it is less likely to be 100% recalled. Recall messages should be sent with a very high priority. Additionally, a recall message could request a subscriber to reply to the recall request to allow some feedback to the publisher of the success of the recall. 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 Tegen Internet Draft 28 Simple Message Queue Protocol (SMQP) November 2002 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 || || || || || |+----------------------------+| +------------------------------+ 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 higher priority numbers are sent before lower priority numbers (priority of 10 is sent before a priority of 2). 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" ":" ( "NONE" | "ONE" | "ALL" ) Tegen Internet Draft 29 Simple Message Queue Protocol (SMQP) November 2002 RECEIPT is an OPTIONAL attribute that informs the server to return a message to the publisher that the message was successfully delivered to none, one, or all subscriber(s). By default, the server SHOULD assume a value of "NONE" if the attribute is not provided in the header. Recipient messages are published to the login account's system topic/queue. NONE : No receipt is provided to the publisher; default. ONE : Receipt is provided to the publisher when the message is delivered to the first available subscriber within the timeout period. ALL : Receipt is provided to the publisher when the message is delivered to all subscribers within the timeout period. If subscriber(s) were unavailable by the time the message timeout period expires, the publisher would receive a receipt message informing the number of subscribers the server was trying to deliver to and the number of subscriber(s) that received the message in the form of "X/Y". For example "4/6" would indicate that the receipt was marked as "ALL", and only 4 of the possible 6 subscribers received the message. A receipt message will always be returned for ONE and ALL in at most the timeout period of the message. 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 ( "INFINITE" | "INF" ) 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 Tegen Internet Draft 30 Simple Message Queue Protocol (SMQP) November 2002 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 NO) 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. DELIVERY = "Delivery" ":" delivery-mode DELIVERY allows the message to define to how many subscribers of the topic the message is being sent to. The possible delivery-mode options are either "ALL" or "ONE". If the attribute is missing, the default mode is "ALL", meaning that all the subscribers, during the message's timeout period will receive the message. A delivery mode of "ONE" indicates that the message will only be sent to one subscriber. A message's delivery mode cannot over-ride the delivery mode of the topic as defined by the command SET TOPIC DELIVERY. HOPS = "Hops" ":" *domain Each time the message is routed to another SMQP server, shall append to the HOPS attribute. Each server would append its Tegen Internet Draft 31 Simple Message Queue Protocol (SMQP) November 2002 domain name/address to the value, separated by a comma (,). The HOPS attribute is to help prevent a message to be re- routed to a server that has already processed the message. An example of this attribute, after a few hops may look like: Hops:smqp.net,host.com,smqp.org:1232 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. The last attribute in the header is followed by a before the data header begins. CONTENT-DESCRIPTION = "Content-Description" ":" text CONTENT-DESCRIPTION is an OPTIONAL, one-line description of the content. Other content specific attributes describe the type, size, encryption, and compression, but this attribute allows a context to be added to the item. For example, the content description may be "Satellite image", or "30 day price index". CONTENT-ID = "Content-ID" ":" text CONTENT-ID is an OPTIONAL alpha-numeric identification with the content object. This may be used to reference the content from another content data. For example, a content section may represent an image that is referenced in the HTML body of another content section. 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 Tegen Internet Draft 32 Simple Message Queue Protocol (SMQP) November 2002 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 CONTENT-ENCRYPTION = "Content-Encryption" ":" method "/" version When present, its value indicates the type of encryption was used on the content data. This attribute would be used to decrypt the content section as well. Example of this attribute is Content-Encryption: PGP/2.6.2 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. 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-jrt:ch1@smqpt.net/A004(D20020820T09000000Z) S: 200 www.smqp.net/208341156-1810(D20020820T09000000Z) S: Tegen Internet Draft 33 Simple Message Queue Protocol (SMQP) November 2002 The CMUID and SMUID is defined by the source of the unique identifier, the unique identifier, and when the server created the received or generated the unique identifier. The date and time associated with these UID's should be maintained since they are used to determine the sequence of message in reply's and other server related events. 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: 6 C: C: 24.567 C: C: Content-Type: text/html C: Content-Length: 52 C: C: 24.567 C: . C: S: 200-OK S: 200-jrt:ch1@smqpt.net/A005(D20020820T09000000Z) S: 200 www.smqp.net/208342156-1833(D20020820T09000000Z) S: By default, a PUBLISH MESSAGE command is a new published message. There is no difference between PUBLISH MESSAGE and PUBLISH MESSAGE NEW Reply Message 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. Tegen Internet Draft 34 Simple Message Queue Protocol (SMQP) November 2002 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/8342156-1835(D20020815T075900Z) S: Cmuid: jtegen:orange@smqp.net/A004(D20020815T075900Z) 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: PUBLISH MESSAGE REPLY jtegen:orange@smqp.net CF0456 C: Created: D20010815T08035341Z C: Smuid: www.host.com/8342156-1835(D20020815T075900Z) C: Cmuid: jtegen:orange@smqp.net/A004(D20020815T075900Z) C: Priority: 1 C: Timeout: 00:01:00 C: Content-Type: text/plain C: Content-Length: 12 C: C: Thank you C: . C: S: 200-OK S: 200-jsmith:ch1@smqp.net/CF0456(D20020815T080000Z) S: 200 www.host.com/083345156-1838(D20020815T080000Z) 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, identified by the client username and channel context. 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. The server shall add the appropriate SMUID and CMUID just as if was a new published message. It will begin to show a message history with the identifiers. The replied message received would appear as a notification. For example, the following message notification has been replied to multiple times: Tegen Internet Draft 35 Simple Message Queue Protocol (SMQP) November 2002 S: NOTIFY MESSAGE /stocks/quotes/ibm S: Created: D20010815T08032445Z S: Smuid: www.host.com/8342156-1829(D20020815T075900Z) S: Smuid: www.host.com/8342156-1830(D20020815T080500Z) S: Smuid: www.host.com/8342156-1839(D20020815T093300Z) S: Cmuid: jtegen:orange@smqp.net/A003(D20020815T075900Z) S: Cmuid: jayne:turtle@smqp.net/TR012(D20020815T080500Z) S: Cmuid: jtegen:orange@smqp.net/A089(D20020815T093200Z) S: . S: C: 310 ACK C: S: 310 ACK S: The date/time stamps with each SMUID and CMUID is really the only method to determine the order of the message history. Replace Message Replacing a message allows for the new message to replace an existing message on the server. If the message is no longer present on the server, a replace message will appear as a new message to subscribers. The replace message needs to contain the SMUID attribute of the message that it is trying to replace. C: PUBLISH MESSAGE REPLACE /news/pub CF0458 C: Created: D20010815T08035341Z C: Smuid: www.host.com/8342156-1835 C: Priority: 1 C: Content-Type: text/plain C: Content-Length: 19 C: C: Thank you even more C: . C: S: 200-OK S: 200-jsmith:ch1@smqp.net/CF0458(D20020815T090000Z) S: 200 www.host.com/083345156-1839(D20020815T090000Z) S: In this case, the message in /news/pub identified as 8342156- 1835 is being replaced with this newer message. Recall Message As discussed earlier, recalling a message allows a publisher to attempt to recall a previously sent message. Only the header of the message needs to be sent. For example, if the following message was sent: C: PUBLISH MESSAGE NEW /news/pub CF0459 C: Created: D20010815T08035341Z C: Priority: 1 C: Content-Type: text/plain Tegen Internet Draft 36 Simple Message Queue Protocol (SMQP) November 2002 C: Content-Length: 19 C: C: Thank you even C: . C: S: 200-OK S: 200-jsmith:ch1@smqp.net/CF0459(D20020815T090000Z) S: 200 www.host.com/083345156-1839(D20020815T090000Z) S: To recall the message, the following command would be sent: C: PUBLISH MESSAGE RECALL /news/pub CF0460 C: Created: D20010815T08035345Z C: CMUID: jsmith:ch1@smqp.net/CF0459 C: SMUID: www.host.com/083345156-1839 C: Priority: 1 Tegen Internet Draft 37 Simple Message Queue Protocol (SMQP) November 2002 Point-to-point Message Publishing The PUBLISH MESSAGE command also supports point-to-point messaging. Instead of a topic destination, the publisher would designate the account of the recipient. The notation for the recipient is: username [ ":" channel ] "@" domain The is the server account of the recipient. The OPTIONAL allows the message to be routed to a particular instance of the . If the is not specified, all occurrences will receive the message. An example PUBLISH MESSAGE to a recipient is: C: PUBLISH MESSAGE jtegen@smqp.com B1735 C: priority: 1 C: Name: IBM Quote C: Created: D20010815T08341245Z C: Receipt: yes C: Reply: NO C: Depth: 1 C: Sequence: 34 C: C: Content-Type: text/plain C: Content-Length: 6 C: C: 24.567 A server receiving a point-to-point message not of their domain would forward the message to that server. An example point-to-point message to a particular account channel sequence: C: PUBLISH MESSAGE jtegen:orange@smqp.com B1735 C: priority: 1 C: Name: IBM Quote C: Created: D20010815T08341245Z C: Receipt: yes C: Reply: NO C: Depth: 1 C: Sequence: 34 C: C: Content-Type: text/plain C: Content-Length: 6 C: C: 24.567 Tegen Internet Draft 38 Simple Message Queue Protocol (SMQP) November 2002 4.1.10. SUBSCRIBE SUBSCRIBE commands subscribe to a resource notification. Once subscribed, the server will notify the subscriber when a change to the current subscription has occurred. When a client subscribes to a resource it does so by its username and channel context. More than one client application COULD use the same login username. Each client application SHOULD use unique channel identification. The channel association allows more than one client, logged in by the same username to subscribe to the same resource, independently of one another. 4.1.10.1. SUBSCRIBE MESSAGE ( "SUBSCRIBE" | "SUB" ) 1*SP ("MESSAGE" | "MESS" ) [ 1*SP ( "ALL" | [ "ADD" ] "," [ "MOVE" ] "," [ "DELETE" ] "," [ "REPLACE" ] ) ] 1*SP topic [ 1*SP "SINCE" 1*SP date-time ] [ 1*SP "UNTIL" 1*SP date-time ] SUBSCRIBE MESSAGE allows a client to subscribe to message for a given, REQUIRED . Once subscribed, any message posted to that topic will be routed to the subscriber. The client can subscribe to different types of message management. The OPTIONAL choices are ALL, ADD, DELETE, MOVE, and REPLACE. If not specified, the default is ALL. ALL informs the server that all changes to messages, for the given will notify the client. The client can use the ALL option as ALL = ADD + DELETE + MOVE + REPLACE. A client MAY subscribe to just one aspect of the message change as well. ADD : New message published to the topic. DELETE : Existing message was removed by a client. A client is not notified when a message timeouts. MOVE : Existing message was move to another topic by a client. REPLACE : Existing message was replaced with a newer message by a client. Tegen Internet Draft 39 Simple Message Queue Protocol (SMQP) November 2002 If a client chooses to subscribe to just DELETE and REPLACE changes it would add each attribute, separated by a comma. For example: C: SUBSCRIBE MESSAGE DELETE,REPLACE /news The OPTIONAL "SINCE" parameter allows the client to only subscribe to message since a given GMT time. This allows the client to filter out timeless messages that MAY have built up over time. If the subscriber sets the SINCE 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 SINCE parameter SHALL be cleared for that subscriber. The parameter is informing the server that the subscriber does not care about older messages. The OPTIONAL "UNTIL" parameter allows the client to only subscribe to message until a given GMT time. Without specifying this parameter, a client is subscribed to the until the client explicitly UNSUBSCRIBEs to it. When a message is posted to the topic and the UNTIL time has been reached, the message will not be delivered and the client will be unsubscribe to that topic. The UNTIL parameter can be re-defined or un-defined by issuing the SUBSCRIBE command to the server again with the new parameter state. The server SHALL return a 409 (conflict) error code if the UNTIL time precedes or is the same as the SINCE time. The server replies with a code and then aacknowledges of the subscription. In addition to the reply codes found in Appendix A, the meaning for: 409 Conflict (UNTIL time precedes or is the same as SINCE time) 413 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: At this point the client will need to wait to receive a message from the SMQP server. Tegen Internet Draft 40 Simple Message Queue Protocol (SMQP) November 2002 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 quantities exceeded S: Example SUBSCRIBE MESSAGE since a particular time sequence: C: SUB MESSAGE /stocks/quotes/ibm SINCE D20010915T080000 C: S: 200-OK S: 200 /stocks/quotes/ibm S: Example SUBSCRIBE MESSAGE until a particular time sequence: C: SUB MESSAGE /stocks/quotes/ibm UNTIL D20010915T123000 C: S: 200-OK S: 200 /stocks/quotes/ibm 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. Tegen Internet Draft 41 Simple Message Queue Protocol (SMQP) November 2002 4.1.10.2. SUBSCRIBE TOPIC ( "SUBSCRIBE" | "SUB" ) 1*SP "TOPIC" [ 1*SP ( "ALL" | [ "ADD" ] "," [ "RENAME" ] "," [ "DELETE" ] "," [ "KEYWORDS" ] ) ] 1*SP topic A client MAY subscribe to changes that have occurred to the REQUIRED . Changes MAY include that a topic was added, renamed, deleted, or keyword changes. The additional, OPTIONAL parameters may specify which type of topic changes should notify the client. The choices are ALL, ADD, RENAME, DELETE, and EKYWORDS. The default choice is ALL if omitted from the command. All informs the server that all changes to the specified topic should notify the client. ALL is equivalent to ADD + RENAME + DELETE + KEYWORDS. A client may specify a subset of ALL as well. ADD : New child topic added. RENAME : Topic was renamed by a client. DELETE : Topic was deleted by a client. KEYWORDS : Topic's keywords were changed. More than one option can be subscribed to. For example, a client wanting to be notified when a topic is either renamed or deleted would issue the command: C: SUBSCRIBE TOPIC RENAME,DELETE /news An example of a regular command is: 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. Tegen Internet Draft 42 Simple Message Queue Protocol (SMQP) November 2002 4.1.10.3. SUBSCRIBE SUBSCRIBER ( "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.10.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. Server attribute subscriptions are transitory. These subscriptions are only kept active for the duration of the client-server session. 4.1.10.4.1. SUBSCRIBE SERVER TIMEOUT ( "SUBSCRIBE" | "SUB" ) 1*SP "SERVER" 1*SP "TIMEOUT" Default timeout of messages by the server. 4.1.10.4.2. SUBSCRIBE SERVER BYE ( "SUBSCRIBE" | "SUB" ) 1*SP "SERVER" 1*SP "BYE" Allows the client to be notified when the server is about to quit. By default, all clients are automatically subscribed to SUBSCRIBE SERVER BYE command. SERVER BYE notifies client when the server is shutting down. Tegen Internet Draft 43 Simple Message Queue Protocol (SMQP) November 2002 4.1.11. 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 (those have not expired) will be delivered to the client. When a client unsubscribes to a resource, it does so by the current username and channel context. Without a unique channel identification for an account, one client COULD inadvertently unsubscribe not only their resource, but the other client's resources as well. 4.1.11.1. UNSUBSCRIBE MESSAGE ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic A client MAY unsubscribe to messages of a topic. All the type of notifications originally requested in the SUBSCRIBE MESSAGE command SHALL be unsubscribed to. C: UNSUB MESSAGE /stocks/quotes/ibm C: S: 200 OK 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-/stocks/quotes/ibm S: 200-/stocks/quotes/msft S: 200 /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 /stocks/quotes/ibm S: 200 OK C: SUB /stocks/quotes/sony S: 200 OK C: SUB /weather/us/ca/san/forecast Tegen Internet Draft 44 Simple Message Queue Protocol (SMQP) November 2002 S: 200 OK The client could later unsubscribe to just the quote subscriptions as follows: C: UNSUB MESSAGE /stocks/* C: S: 200-OK S: 200-/stocks/quotes/ibm S: 200 /stocks/quotes/sony S: 4.1.11.2. UNSUBSCRIBE TOPIC ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP "TOPIC" 1*SP topic A client MAY unsubscribe to changes to a topic. All the type of notifications originally requested in the SUBSCRIBE TOPIC command SHALL be unsubscribed to. C: UNSUB TOPIC /stocks/quotes/ibm C: S: 200 OK S: C: UNSUB TOPIC /stocks/quotes/* C: S: 200-OK S: 200-/stocks/quotes/ibm S: 200 /stocks/quotes/beos S: C: UNSUB TOPIC * C: S: 200-OK S: 200-/stocks/quotes/ibm S: 200-/stocks/quotes/beos S: 200 /lists/news/os S: Tegen Internet Draft 45 Simple Message Queue Protocol (SMQP) November 2002 4.1.11.3. UNSUBSCRIBE SUBSCRIBERS ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP ( "SUBSCRIBER" | "SUB" ) 1*SP topic A client MAY unsubscribe to changes to subscribers of a topic. 4.1.11.4. UNSUBSCRIBE SERVER TIMEOUT ( "UNSUBSCRIBE" | "UNSUB" ) 1*SP "SERVER" 1*SP "TIMEOUT" A client MAY unsubscribe to changes to the server timeout notification. 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 46 Simple Message Queue Protocol (SMQP) November 2002 4.1.12. NOTIFY "NOTIFY" 1*SP resource The notification of a published resource is sent to the subscriber from the SMQP server. While the client is not sending a command, it SHOULD be listening for notification messages. 4.1.12.1. NOTIFY MESSAGE "NOTIFY" 1*SP ( "MESSAGE" | "MESS" ) 1*SP topic 1*SP ( "ADD" | "DELETE" | "MOVE" | "REPLACE" ) message . NOTIFY MESSAGE informs the client that a message has changed in the REQUIRED . The possible message notification types are: ADD : New message published to the topic. This may occur from a published message or a move message command. DELETE : a client deleted an existing message. MOVE : An existing message was move from the topic, by a client. REPLACE: A new message has replaced an existing message by a client. For ADD and REPLACE, the entire message is sent. For DELETE and MOVE, only the message header is sent. 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 or XML. 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 Tegen Internet Draft 47 Simple Message Queue Protocol (SMQP) November 2002 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 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. S: 310 ACK 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 for a new message: S: NOTIFY MESSAGE /stocks/quotes/ibm ADD S: Created: D20010815T08032445Z S: Smuid: www.host.com/0834200108342156-1835 S: Cmuid: jtegen:orange@host.com /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: Tegen Internet Draft 48 Simple Message Queue Protocol (SMQP) November 2002 A subscriber may be unavailable to process the message by returning a 416 code. Subscribers may suspend additional messages from the same topic by responding with the 312 wait reply. This acknowledges receipt of the current message so the server SHALL still respond with the second acknowledgement of 310. This can be thought of a synchronous SET NOTIFY SUSPEND command. Message notification for this topic will resume when the client issues a SET NOTIFY RESUME command. Refer to PUBLISH MESSAGE command for attribute description. Additional attributes that are affixed to the message header by the server, include: SMUID = "Smuid" ":" host "/" uid 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 ":" channel "@" host "/" uid CMUID is the REQUIRED account information of the publisher of the message. is the REQUIRED Client Message Unique Identifier which is defined by the publisher. The server adds this information. This information is used to reply to the given message. The default mode of a message notification is a dual-phase acknowledgement as shown above. If the message attribute GUARANTEE exists and set to yes, the client does to reply with an acknowledgement or expect to received any additional reply codes from the server. 4.1.12.2. NOTIFY RECEIPT "NOTIFY" 1*SP "RECEIPT" 1*SP topic message . The NOTIFY RECEIPT command is almost identical to NOTIFY MESSAGE command. The server SHALL notify a client of a receipt when the client published a message requesting a receipt. Only header attributes of a message is returned to the client so it can associate the receipt to the original message. If the client needs the content of the original message, it will need to persist that information locally and associate the content with the CMUID and/or SMUID returned in the header of the receipt. Tegen Internet Draft 49 Simple Message Queue Protocol (SMQP) November 2002 4.1.12.3. NOTIFY TOPIC "NOTIFY" 1*SP "TOPIC" 1*SP topic 1*SP ( ( "ADD" ) | ( "RENAME" | "REN" ) | ( "DELETE" | "DEL" ) | ( "KEYWORDS" | "KEY" ) ) [value] Notification that a topic has been modified. Topic notification are followed with attributes that describe the change. o ADDED o RENAME o DELETE o KEYWORDS For example, a topic addition notification would appear as: S: NOTIFY TOPIC /stocks/quotes/ibm ADD /stocks/quotes/ibm/reports For example, a topic rename notification would appear as: S: NOTIFY TOPIC /stocks/quotes/ibm RENAME /stocks/quotes/big_blue For example, a topic deletion notification would appear as: S: NOTIFY TOPIC /stocks/quotes/ibm DELETE For example, a topic keyword notification would appear as: S: NOTIFY TOPIC /stocks/quotes/ibm KEYWORDS (BIG BLUE) 4.1.12.4. NOTIFY SUBSCRIBERS "NOTIFY" 1*SP ( "SUBSCRIBERS" | "SUB" ) 1*SP topic 1*SP count 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 no subscribers wanting their data. This can dramatically reduce the network traffic of messages. Example NOTIFY SUBSCRIBERS sequence: S: NOTIFY SUB /stocks/quotes/ibm 34 S: Tegen Internet Draft 50 Simple Message Queue Protocol (SMQP) November 2002 4.1.12.5. NOTIFY SERVER "NOTIFY" 1*SP ( "SERVER" | "SERV" ) 1*SP resource The server MAY automatically issues NOTIFY SERVER commands to all clients. It allows the server to notify the clients when some general server action is to occur or has occurred. 4.1.12.5.1. NOTIFY SEVER TIMEOUT "NOTIFY" 1*SP ( "SERVER" | "SERV" ) 1*SP "TIMEOUT" 1*SP timeout The NOTIFY SERVER TIMEOUT command informs the clients that the current default timeout period for all messages has changed. 4.1.12.5.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 51 Simple Message Queue Protocol (SMQP) November 2002 4.1.13. GET 4.1.13.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/1865 S: CMUID: jtegen:orange@host.com/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.13.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) Tegen Internet Draft 52 Simple Message Queue Protocol (SMQP) November 2002 4.1.13.3. GET TOPIC DELIVERY "GET" 1*SP "TOPIC" 1*SP "DELIVERY" 1*SP topic GET TOPIC DELIVERY returns the current delivery mode of the given topic. The client may set the delivery mode by using the SET DELIVERY commands. C: GET TOPIC DELIVERY /stocks/quotes/ibm C: S: 200-OK S: 200 ALL S: The possible return values on the multi-line reply is either "ALL", "NONE", or "ONE". 4.1.13.4. GET LOGIN CHANNEL "GET" 1*SP "LOGIN" 1*SP "CHANNEL" GET LOGIN CHANNEL returns the current channel of the session. The channel is defined with the LOGIN command. This command returns the context in case the client did not retain the information. C: GET LOGIN CHANNEL C: S: 200-OK S: 200 orange S: Tegen Internet Draft 53 Simple Message Queue Protocol (SMQP) November 2002 4.1.13.5. GET LOGIN CONTACT "GET" 1*SP "LOGIN" 1*SP "CONTACT" 1*SP mime [ 1*SP account ] GET LOGIN CONTACT returns the person identification in the requested format . The standard format for the SMQP specification is the vCard format (RFC2424 and RFC2425). However, other formats could be used or supported by the server. If the server cannot support the requested format, it SHALL return a reply code of 400 (bad request). The OPTIONAL parameter allows the client to obtain information about another person's account. The server SHALL restrict access to other account information as required; there is no formal contact restriction in the specification. An example of the command sequence is: C: GET LOGIN CONTACT text/x-vcard S: 200-OK S: 200-begin:vcard S: 200-version:2.1 S: 200-n:Jayne;Smythe S: 200-tel;home;voice:(201)555-1212 S: 200-adr;work;postal:123 Main Street;Big Town;CA;92139 S: 200-email;internet:jayne@host.com S: 200 end:vcard S: 4.1.14. 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. 4.1.15. QUIT "QUIT" QUIT discontinues a session with the SMQP server. Any subscribed resources are still subscribed to. C: QUIT C: S: 200 OK S: Tegen Internet Draft 54 Simple Message Queue Protocol (SMQP) November 2002 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 55 Simple Message Queue Protocol (SMQP) November 2002 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 56 Simple Message Queue Protocol (SMQP) November 2002 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 57 Simple Message Queue Protocol (SMQP) November 2002 ::= ::= 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) Tegen Internet Draft 58 Simple Message Queue Protocol (SMQP) November 2002 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. 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. ::=