Request for Comments: not an RFC Obsoletes: protocol.txt Category: Standards Track |
Alex Russell Greg Wilkins David Davis Mark Nesbitt |
This document specifies a protocol for the Internet community, and requests discussion and suggestions for improvement. This memo is written in the style and spirit of an IETF RFC but is not, as of yet, an official IETF RFC. Distribution of this memo is unlimited. This memo is written in UK English.
Copyright © The Dojo Foundation (2007). All Rights Reserved
Bayeux is a protocol for routing JSON encoded events between clients and servers in a publish subscribe model. The protocol is designed to overcome the client/server nature of the internet in general and specifically of HTTP to allow asynchronous messaging between all participants.
Bayeux is a protocol for transporting asynchronous messages with low latency, primarialy over HTTP. The messages are routed via named channels and can be delivered: server to client, client to server and client to client (via the server). The primary purpose of Bayeux is to implement responsive user interactions for web clients using Ajax and the server-push technique called Comet.
Bayeux seeks to reduce the complexity of developing Comet-driven applications by allowing implementers to more easily interoperate, solve common message distribution and routing problems, and provide mechanisms for incremental improvement and extension.
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 RFC2119. An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."
This specification uses a number of terms to refer to the roles played by participants in, and objects of, Bayeux communication:
The HTTP protocol is a request/response protocol. A client sends a request to the server in the form of a request method, URI, and protocol version, followed by a MIME-like message containing request modifiers, client information, and optional body content over a connection with a server. The server responds with a status line, including the message's protocol version and a success or error code, followed by a MIME-like message containing server information, entity metainformation, and possible entity-body content.
The server may not initiate a connection with a client nor send an unrequested response to the client, thus asynchronous events cannot be delivered from server to client unless a previously issued request exists. In order to allow two way asynchronous communication, Bayeux supports the use of multiple HTTP connections between a client and server, so that previously issued requests are available to transport server to client messages.
The recommendation of section 8.1.4 of RFC 2616 is that a single user client SHOULD NOT maintain more than 2 connection with any server, thus the Bayeux protocol MUST NOT require any more than two HTTP requests to be simultaneously handled by a server in order to handle all application (Bayeux based or otherwise) running within a client.
While HTTP is the predominant transport protocol used on the internet, it is not intended that it will be the only transport for Bayeux. Other transports that support a request/response paradym may be used. However this document is written in assuming HTTP for reasons of clarity. When non-HTTP connection-level transport mechanisms are employed, conforming Bayeux servers and clients MUST still conform to the semantics of the JSON messages outlined in this document.
Several of the "transport types" described in this document are distinguished primarialy by how they wrap messages for delivery over HTTP and the sequence and content of the HTTP connections initiated by clients. While this may seem like a set of implementation concerns to observant readers, the difficulties of creating interoperable implementations without specifying these semantics fully is a primary motivation for the development of this specification. Were the deployed universe of servers and clients more flexible, it may not have been necessaray to develop Bayeux.
Regardless, care has been taken in the development of this specification to ensure that future clients and servers which implement differing connection-level strategies and encodings may still evolve and continue to be conforming Bayeux implementations so long as they implement the JSON-based public/subscribe semantics outlined herein.
The rest of this document speaks as though HTTP will be used for message transport.
The majority of Bayeux clients will be implemented in JavaScript and will be running within the security framework of a client browser. For applications that need to commicate with multiple servers, the client implementation MUST adhere to the single origin policy for security.
A Bayeux event is sent from the client to the server via a HTTP request initiated by a user agent and transmitted to an origin server via a chain of zero or more intermediaries (proxy, gateway or tunnel):
BC ---------- U ---------- P ------------ O ---------- BS | --M0(E)--> | | | | | | ---HTTP request(M0(E))--> | | | | | | --M0(E)--> | | | | | <---M1---- | | | <---HTTP response(M1)---- | | | <---M1--- | | | | | | | | |
The figure above represents a Bayeux event E encapsulted in a Bayeux message M0 being sent from a Bayeux client BC to a Bayeux server BS via HTTP request transmitted from a User Agent U to to an Origin server O via a proxy P. The HTTP response contains another Bayeux message M1 that will at least contain the protocol response to M0, but may contain other Bayeux events initiated on the server or on other clients.
A Bayeux event is sent from the server to the client via a HTTP response to a HTTP request sent in anticipation by a user agent and transmitted to an origin server via a chain of zero or more intermediaries (proxy, gateway or tunnel):
BC ---------- U ---------- P ------------ O ---------- BS | ---M0---> | | | | | | --- HTTP request(M0) ---> | | | | | | ----M0---> | ~ ~ ~ ~ ~ wait | | | | <--M1(E)-- | | | <--HTTP response(M1(E))-- | | | <--M1(E)-- | | | | ~ ~ ~ ~ ~
The figure above represents a Bayeux message M0 being sent from a Bayeux client BC to a Bayeux server BS via a HTTP request transmitted from a User Agent U to to an Origin server O via a proxy P. The message M0 is sent in anticipation of a Bayeux event to be delivered from server to client and the Bayeux server waits for such an event before sending a response. A Bayeux event E is shown being delivered via Bayeux message M1 in the HTTP response. M1 may contain zero, one or more Bayeux events destined for the Bayeux client.
The transport used may terminate the HTTP response after delivery of M1 or use techniques to leave the response open and stream additional messages to the client.
Polling transports will always terminate the HTTP response after sending all availabe Bayeux messages.
BC ---------- U ---------- P ------------ O ---------- BS | ---M0---> | | | | | | --- HTTP request(M0) ---> | | | | | | ----M0---> | ~ ~ ~ ~ ~ wait | | | | <--M1(E)-- | | | <--HTTP response(M1(E))-- | | | <--M1(E)-- | | | | | ---M2---> | | | | | | --- HTTP request(M2) ---> | | | | | | ----M2---> | ~ ~ ~ ~ ~ wait
On receipt of the HTTP response cotaining M1, the Bayeux client issues a new Bayeux message M2 either immediately or after an interval in anticipation of more events to be delivered from server to client.
Some Bayeux transports use a streaming technique (also called a forever response) that allows multiple messages to be sent over the same HTTP response:
BC ---------- U ---------- P ------------ O ---------- BS | ---M0---> | | | | | | --- HTTP request(M0) ---> | | | | | | ----M0---> | ~ ~ ~ ~ ~ wait | | | | <--M1(E0)- | | | <--HTTP response(M1(E0))- | | | <--M1(E0)- | | | | ~ ~ ~ ~ ~ wait | | | | <--M1(E1)- | | | <----(M1(E1))------------ | | | <--M1(E1)- | | | | ~ ~ ~ ~ ~ wait
Streaming techiques avoid the latency and extra messaging of anticipatory requests, but is subject to the implementation of user agents and proxies as it requires non complete HTTP responses to be delivered to the Bayeux client.
In order to achieve bi-directional communications, a Bayeux client will use two HTTP connections to a Bayeux server so that both server to client and client to server messaging may occur asynchronously:
BC ---------- U ---------- P ------------ O ---------- BS | ---M0---> | | | | | | ------ req0(M0) --------> | | | | | | ----M0---> | ~ ~ ~ ~ ~ wait | --M1(E1)-> | | | | | | ----- req1(M1(E1))------> | | | | | | --M1(E1)-> | | | | | <---M2---- | | | <---- resp1(M2)---------- | | | <---M2--- | | | | ~ ~ ~ ~ ~ wait | | | | <-M3(E2)-- | | | <-----resp2(M3(E2))------ | | | <-M3(E2)-- | | | | | ---M4---> | | | | | | ------req3(M4)----------> | | | | | | ----M4---> | ~ ~ ~ ~ ~ wait
HTTP requests req0 and req1 are sent on different TCP/IP connections, so that the response to req1 may be sent before the response to req0. Implementations MUST control HTTP pipelining so that req1 does not get queued behind req0 and thus enforce an ordering of responses.
Bayeux connections are negotiated between client and server with handshake messages that allow the connection type, authentication and other parameters to be agreed upon between the client and the server.
BC ----------------------------------------- BS | ------------------ handshake request ---> | | <---- handshake response ---------------- | | -------------------- connect request ---> | ~ ~ wait | <------ connect response ---------------- |
Connection negotiation may be iterative and several handshake messages may be exchanged before a successful connection is obtained. Servers may also request connection renegotiation by sending an unsuccessful connect response with advice to reconnect with a handshake message.
BC ----------------------------------------- BS | ------------------ handshake request ---> | | <-- unsuccessful handshake response ----- | | ------------------ handshake request ---> | | <-- successful handshake response ------- | | -------------------- connect request ---> | ~ ~ wait | <------ connect response ---------------- | | -------------------- connect request ---> | | <---- unsucessful connect response ------ | | ------------------ handshake request ---> | | <-- successful handshake response ------- | | -------------------- connect request ---> | ~ ~ wait | <------ connect response ---------------- |
OPTIONALLY, messages can be sent without a prior handshake (see 5.1 Publish event messages).
| ------------------- message request ----> | | <---- message response ------------------ |
This pattern is often useful when implementing non-browser clients for Bayeux servers. These clients often simply wish to address messages to other clients which the Bayeux server may be servicing, but do not wish to listen for events themselves.
-------------++------------+-------------+----------- +------------ State/Event || handshake | Timeout | Successful | Disconnect || request | | connect | request || sent | | response | sent -------------++------------+-------------+----------- +------------ UNCONNECTED || CONNECTING | UNCONNECTED | | CONNECTING || | UNCONNECTED | CONNECTED | UNCONNECTED CONNECTED || | UNCONNECTED | | UNCONNECTED -------------++------------+-------------+------------+------------
The characters used for Bayeux names and identifiers are defined by the BNF definitions:
alpha = lowalpha | upalpha lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" upalpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" alphanum = alpha | digit mark = "-" | "_" | "!" | "~" | "(" | ")" | "$" | "@" string = *( alphanum | mark | " " | "/" | "*" | "." ) token = ( alphanum | mark ) *( alphanum | mark ) integer = digit *( digit )
Channels are identified by names that are styled as absolute path component of a URI without parameters as defined by RFC2396.
channel_name = "/" channel_segments channel_segments = channel_segment *( "/" channel_segment ) channel_segment = token
The channel name consists of an initial "/" followed by an optional sequence of path segments separated by a single slash "/" character. Within a path segment, the character "/" is reserved.
Channel names commencing with "/meta/" are reserved protocol use. Example non-meta channel names are:
A set of channels may be specified with a channel globbing pattern:
channel_pattern = *( "/" channel_segment ) "/" wild_card wild_card = "*" | "**"
The channel patterns support only trailing wildcards of either "*" to match a single segment or "**" to match multiple segments. Example channel patterns are:
The channels within the "/meta/" segment are the channels used by the Bayeux protocol itself. Bayeux clients MAY NOT subscribe or create meta channels. Messages published to a meta channel are not distributed and are only delivered server side handlers of those channels and any privileged server-side clients that have subscribed. Handlers of meta channels MAY publish response messages that are delivered only to the client that sent the original request message. If a message published to a meta channel contains an id field, then any response messages delivered to the client MUST contain an id field with the same value.
The channels within the "/service/" channel segement are special channels designed to assist request/response style messaging. Messages published to service channels are not distributed to any client side Bayeux clients. Handlers of service channels MAY deliver response messages to the client that published the request message. Servers SHOULD NOT record any subscriptions they receive for service channels. If a message published to a meta channel contains an id field, then any response messages SHOULD contain an id field with the same value or a value derived from the request id. Request response operations are described in detail in section 9.
A protocol version is a integer followed by an optional "." separated sequence of alphanumeric elements:
version = integer *( "." version_element ) version_element = alphanum *( alphanum | "-" | "_" )
Versions are compared element by element, applying normal alphanumeric comparison to each element.
A client ID is an random, non predictable sequence of alpha numeric characters:
clientId = alphanum *( alphanum )
Client IDs are generated by the server and SHOULD be created with a strong random algorithm that contains at least 128 truly random bits. Servers MUST ensure that client IDs are unique and SHOULD attempt to avoid reuse of client IDs. Client IDs are encoded for delivery as JSON strings.
Bayeux messages are JSON encoded objects that contain an unordered sequence of name value pairs representing fields and values. Values may be a simple strings, numbers, boolean values, or complex JSON encoded objects. A Bayeux message MUST contain one and only one channel field which determines the type of the message and the allowable fields.
All Bayeux messages SHOULD be encapsulated in a JSON array so that multiple messages may be transported together. A Bayeux client or server MUST accept either array of messages and MAY accept a single message. The JSON message or array of messages is itself often encapsulated in transport specific formatting and encodings. Below is an example Bayeux message in a JSON array representing an event sent from a client to a server:
[ { "channel": "/some/name", "clientId": "83js73jsh29sjd92", "data": { "myapp" : "specific data", value: 100 } } ]
The channel message field MUST be included in every Bayeux message to specify the source or destination of the message. In a request, the channel specifies the destination of the message, and in a response it specifies the source of the message.
The version message field SHOULD be included in messages to/from the "/meta/handshake" channel to indicate the protocol version expected by the client/server.
The minimumVersion message field MAY be included in messages to/from the "/meta/handshake" channel to indicate the oldest protocol version that can be handled by the client/server.
The supportedConnectionTypes field is included in messages to/from the "/meta/handshake" channel to allow clients and servers to reveal the transports that are supported. The value is an array of strings, with each string representing a transport name. Defined connection types include:
All server and client implementations MUST support the "long-polling" connection type and SHOULD support "callback-polling". All other connection types are OPTIONAL.
The clientId message field uniquely identifies a client to a Bayeux server. The clientId message field MUST be included in every message sent to the server except for a messages sent to the "/meta/handshake" channel and a publish message(see 5.1 Publish event messages). The clientId field will be returned in every message response except for a failed handshake request and is OPTIONAL in a message delivery message.
The advice field provides a way for servers to inform clients of their preferred mode of client operation so that in conjunction with server-enforced limits, Bayeux implementations can prevent resource exhaustion and inelegant failure modes.
The advice field is a JSON map containing general and transport specific values that indicate modes of operation, timeouts and other potential transport specific parameters. Fields may occur either in the top level of an advice or within a transport specific section.
Unless otherwise specified in sections 5 and 6, any Bayeux response message may contain an advice field. Advice received always superceeds any previous received advice.
An example advice field is
"advice": { "reconnect": "retry", "interval": 1000, "callback-polling" : { "reconnect": "handshake" } }
The reconnection advice field is a string that indicates how the client should act in the case of a failure to connect. Defined reconnect values are:
An integer representing the period in milliseconds for a client to delay subsequent requests to the /meta/connect channel. A negative period indicates that the message should not be retried.
A client MUST implement interval support, but a client MAY exceed the interval provided by the server. A client SHOULD implement a backoff strategy to increase the interval if requests to the server fail without new advice being received from the server.
This is a boolean field, which if true indicates that the server has detected multiple Bayeux client instances running within the same HTTP client.
This is an array of strings field, which if present indicates a list of host names or IP addresses that MAY be used as alternate servers with which the client may connect. If a client receives advice to re handshake and the current server is not included in a supplied hosts list, then the client SHOULD try the hosts in order until a successful connection is establish. Advice received during handshakes with hosts in the list supercedes any previously received advice.
The connectionType message field specifies the type of transport the client requires for communication. The connectionType message field MUST be included in request messages to the "/meta/connect" channel. Connection types are defined in section 4.7.
An id field MAY be included in any Bayeux message with an alpha numeric value:
id = alphanum *( alphanum )
Generation of IDs is implementation specific and may be provided by the application. Messages published to /meta/** and /service/** SHOULD have id fields that are unique within the the connection.
Messages sent in response to messages delivered to /meta/** channels MUST use the same message id as the request message.
Messages sent in response to messages delivered to /service/** channels SHOULD use the same message id as the request message or an id derived from the request message id.
The timestamp message field SHOULD be specified in the following ISO 8601 profile: All times SHOULD be sent in GMT time.
YYYY-MM-DDThh:mm:ss.ssA timestamp message is OPTIONAL in all Bayeux messages.
The data message field is an arbitrary JSON object that contains event information. The data field MUST be included in publish requests, and a Bayeux server MUST include the data field in an event delivery message.
The connectionId field was used during development of the Bayeux protocol and it's use is now deprecated.
The successful boolean message field is used indicate success or failure and MUST be included in responses to the "/meta/handshake", "/meta/connect", "/meta/subscribe","/meta/unsubscribe", "/meta/disconnect", and publish channels.
The subscription message field specific the channels the client wishes to subscribe to or unsubscribe from. The subscription message field MUST be included in requests and responses to/from the "/meta/subscribe" or "/meta/unsubscribe" channels.
The error message field is OPTIONAL on any Bayeux response. The error message field MAY indicate the type of error that occurred when a request returns with a false successful message. The error message field should be sent as a string in the following format:
error = error_code ":" error_args ":" error_message | error_code ":" ":" error_message error_code = digit digit digit error_args = string * "," string ) error_message = string
An example error strings are:
401::No client ID 402:xj3sjdsjdsjad:Unknown Client ID 403:xj3sjdsjdsjad,/foo/bar:Subscription denied 404:/foo/bar:Unknown ChannelNeed to privide list of codes
An ext field MAY be included in any Bayeux message. It's value SHOULD be a JSON map with top level names distinguished by implementation names (eg. "org.dojo.Bayeux.field").
The contents of ext may be arbitrary values that allow extensions to be negotiated and implemented between server and client implementations.
A Bayeux client initiates a connection negotiation by sending a message to the "/meta/handshake" channel. For same domain connections, the Handshake requests MUST be sent to the server as the 'message' parameter of a application/x-www-form-urlencoded encoded POST request. For cross domain connections, the Handshake request MUST be sent to the server as the url encoded GET request with the jsonp parameter set for callback-polling.
A handshake request MUST contain the message fields:
A handshake request MAY contain the message fields:
A client SHOULD NOT send any other message in the request with a handshake message. A server MUST ignore any other message sent in the same request as a handshake message. An example handshake request is:
[ { "channel": "/meta/handshake", "version": 1.0, "minimumVersion": 1.0, "supportedConnectionTypes": ["long-polling", "callback-polling", "iframe"], } ]
A Bayeux server MUST respond to a handshake request with a handshake response message in the body content of the response. For cross domain connections that have the jsonp parameters set, the message body may be encapsulated in a jsonp callback method.
A successful handshake responses MUST contain the message fields:
A successful handshake response MAY contain the message fields:
[ { "channel": "/meta/handshake", "version": 1.0, "minimumVersion": 1.0, "supportedConnectionTypes": ["long-polling","callback-polling"], "clientId": "Un1q31d3nt1f13r", "successful": true, "authSuccessful": true, "advice": { "reconnect": "retry" } } ]
An unsuccessful handshake response MUST contain the message fields:
An unsuccessful handshake response MAY contain the message fields:
An example unsuccessful handshake response is:
[ { "channel": "/meta/handshake", "version": 1.0, "minimumVersion": 1.0, "supportedConnectionTypes": ["long-polling","callback-polling"], "successful": false, "error": "Authentication failed", "advice": { "reconnect": "none" } } ]
For complex connection negotiations, multiple handshake messages may be exchanged between the Bayeux client and server. The handshake response will set the "successful" field to false until the handshake processs is complete. The advice and ext fields may be used to communicate additional information needed to complete the handshake process. An unsuccessful handshake response with reconnect advice of "handshake" is used to continue the connection negotiation. An unsuccessful handshake response with reconnect advice of "none" is used to terminate connection negotiations.
After a Bayeux client has discovered the server's capabilities with a handshake exchange, a connection is established by sending a message to the "/meta/connect" channel. This message may be transported over any of the transports indicated as supported by the server in the handshake response.
A connect request MUST contain the message fields:
A connect request MAY contain the message fields:
A client MAY send other messages in the same http request with a connection message. A server MUST handle any other message sent in the same request as a connect message after the handling of the connect message is complete.
An example connect request is:
[ { "channel": "/meta/connect", "clientId": "Un1q31d3nt1f13r", "connectionType": "long-polling" } ]
A transport MUST maintain one and only one outstanding connect message. When a HTTP response that contains a /meta/connect response terminates, the client MUST wait at least the interval specified in the last received advice before following the advice to reestablish the connection
A Bayeux server MUST respond to a connect request with a connect response message over the same transport as used for the request.
A Bayeux server MAY wait to respond until there are event messages available in the subscribed channels for the client that need to be delivered to the client.
A Bayeux server MAY send event messages for the client in the same http response as the connect response, but the Bayeux server MUST NOT wait for any such messages before sending the connect response message.
A connect responses MUST contain the message fields:
A connect response MAY contain the message fields:
An example connect response is:
[ { "channel": "/meta/connect", "successful": true, "error": "", "clientId": "Un1q31d3nt1f13r", "timestamp": "12:00:00 1970", "advice": { "reconnect": "retry" } } ]
The client MUST maintain only a single outstanding connect message. If the server does not have a current outstanding connect and a connect is not received within a configured timeout, then the server SHOULD act as if a disconnect message has been received.
When a connected client wishes to cease operation it should send a request to the "/meta/disconnect" channel for the server to remove any client state. The server SHOULD release any waiting meta message handlers. Bayeux client applications should send a disconnect request when the user shuts down a browser window or leaves the current page. A Bayeux server SHOULD not rely solely on the client sending a disconnect message to remove client state information because a disconnect message might not be sent from the client or the disconnect request might not reach the server.
A disconnect request MUST contain the message fields:A disconnect request MAY contain the message fields:
[ { "channel": "/meta/disconnect", "clientId": "Un1q31d3nt1f13r" } ]
A Bayeux server must respond to a disconnect request with a disconnect response.
A disconnect response MUST contain the message fields:
A disconnect response MAY contain the message fields:
[ { "channel": "/meta/disconnect", "clientId": "Un1q31d3nt1f13r", "successful": true } ]
A connected Bayeux client may send subscribe messages to register interest in a channel and to request that messages published to the subscribe channel are delivered to the client.
A subscribe request MUST contain the message fields:
A subscribe request MAY contain the message fields:
An example subscribe request is:
[ { "channel": "/meta/subscribe", "clientId": "Un1q31d3nt1f13r", "subscription": "/foo/**" } ]
A Bayeux server MUST respond to a subscribe request with a subscribe response message.
A Bayeux server MAY send event messages for the client in the same http response as the subscribe response, including events for the channels just subscribed to.
A subscribe responses MUST contain the message fields:
[ { "channel": "/meta/subscribe", "clientId": "Un1q31d3nt1f13r", "subscription": "/foo/**", "successful": true, "error": "" } ]
A connected Bayeux client may send unsubscribe messages to cancel interest in a channel and to stop published message delivery from the server to the unsubscribe channel.
A unsubscribe request MUST contain the message fields:
A unsubscribe request MAY contain the message fields:
[ { "channel": "/meta/unsubscribe", "clientId": "Un1q31d3nt1f13r", "subscription": "/foo/**" } ]
A Bayeux server MUST respond to a unsubscribe request with a unsubscribe response message. A Bayeux server MAY send event messages for the client in the same http response as the unsubscribe response, including events for the channels just unsubscribed to as long as the event was processed before the unsubscribe request.
A unsubscribe responses MUST contain the message fields:[ { "channel": "/meta/unsubscribe", "clientId": "Un1q31d3nt1f13r", "subscription": "/foo/**", "successful": true, "error": "" } ]
A Bayeux client can publish events on a channel by sending event messages. An event message MAY be sent in new HTTP request or it MAY be sent in the same HTTP request as any message other than a handshake meta message.
A publish message may be sent from an unconnected client (that has not performed handshaking and thus does not have a client ID). It is OPTIONAL for a server to accept unconnected publish requests and they should apply server specific authentication and authourization before doing so.
A publish event message MUST contain the message fields:[ { "channel": "/some/channel", "clientId": "Un1q31d3nt1f13r", "data": "some application string or JSON object", "id": "some unique message id" } ]
A Bayeux server MAY respond to a publish event message with a publish event acknowlegement.
A publish event message MUST contain the message fields:[ { "channel": "/some/channel", "clientId": "Un1q31d3nt1f13r", "data": "some application string or JSON object", "id": "some unique message id" } ]
Event messages are delivered to clients if the client is subscribed to the channel of the event message. Event messages may be sent to the client in the same HTTP response as any other message other than a meta handshake response. If a Bayeux server has multiple HTTP requests from the same client, the server SHOULD deliver all available messages in HTTP response that will be sent immediately in preference to waking a waiting connect meta message handler. Event message deliver is not acknowlegded by the client.
A deliver event message MUST contain the message fields:
[ { "channel": "/some/channel", "data": "some application string or JSON object", "id": "some unique message id" } ]
Messages are sent to the server as the body of a POST, encoded either as "application/x-www-form-urlencoded" or as "text/json". If sent as form encoded, the Bayeux messages are sent as the "message" parameter in one of the following forms as:
Messages are sent to the client as unencapsulated body content of a POST response with content type "text/json" or "text/json-comment-filtered".
Messages are sent to the server either using POST requests as per long-polling transport or as the "message" URL parameter of a GET request.
Messages are sent to the client as JavaScript function call returned for script source GET requests. The function called will be determined by the "jsonp" field of any associated request messages, or "jsonpcallback" if not specified. The called function will be passed a JSON array of Bayeux messages.
For Bayeux authentication, no algorithm is specified for generating or validating security credentials or token. This version of the protocol only defines that the ext field may be used to exchange authentication challenges, credentials, and tokens and that the advice field may be used to control multiple iterations of the exchange.
The connection negotiation mechanism may be used to negotiate authentication or request re-authentication.
The Ajax hijacking vulnerability is when an attacking web site uses a script tag to execute JSON content obtained from an Ajax server. The Bayeux protocol is not vulnerable to this style of attack as cookies are not used for authentication and a valid client ID is needed before private client data is returned. The use of POST requests further protects against this style of attack.
To futher protect against this class of attack, it is RECOMMENDED that Bayeux clients and servers support JSON comment filtered format, where the outer JSON array is enclosed in a comment that will prevent execution of the JSON without explicit handling of the comment characters. An example of a commented message is:
/*[ { "channel": "/some/channel", "data": "some application string or JSON object", "id": "some unique message id" } ]*/
An extension field of json-comment-filtered should be sent by client and server to indicate that comment-filtering is supported. If it is, the content-type should be text/json-comment-filtered.
Current HTTP client implementations are RECOMMENDED to allow only two connections between a client and a server. This presents a problem when multiple instances of the Bayeux client are operating in multiple tabs or windows of the same browser instance. The two connection limit can be consumed by outstanding connect meta messages from each tab or window and thus prevent other messages from being delivered in a timely fashion.
It is RECOMMENDED that Bayeux server implementations use the cookie "Bayeux_HTTP_ID" to identify a HTTP client and to thus detect multiple Bayeux clients running within the same HTTP client. Once detected, the server SHOULD not wait for messages in connect and SHOULD use the advice interval mechanism to establish traditional polling.
It is RECOMMENDED that Bayeux client implementations use client side persistence or cookies to detect multiple intances of Bayeux clients running within the same HTTP client. Once detected, the user MAY be offered the option to disconnect all but one of the clients. It MAY be possible for client implementations to use client side persistence to share a Bayeux client instance.
The publish/subscribe paradigm that is directly supported by the Bayeux protocol is difficult to use to efficiently implement the request/response paradigm between a client and a server. The /service/** channel space has been designated as a special channel space to allow efficient transport of application request and responses over Bayeux channels. Messages published to service channels are not distributed to other Bayeux clients so these channels can be used for private requests between a Bayeux client and a server side handlers.
A trivial example would be an echo service, that sent any message received from a client back to that client unaltered. Bayeux clients would subscribe the the /service/echo channel, but the Bayeux server would not need to record this subscription. When a client publishes a message to the /service/echo channel, it will be delivered only to server-side subscribers (in an implementation depedent fashion). The server side handler for the echo service would handle each message received by publishing a response directly to the client regardless of any subscription. As the client has subscribed to /service/echo, the response message will be routed correctly within the client to the appropriate application handler.