Resin Documentation

jsmp (json message protocol)

See JSON Actor Message Protocol for a revised protocol based on actions with parameters, replacing the object-based messaging of JSMP.

The following drafts are available for JSON Message Protocol (most recent first).

draft-ferg-jsmp-v1 [txt | html]

draft-ferg-jsmp-v0 [txt | html]

JSMP adds a small amount of standard structure to any JSON/WebSockets application. Since it's a simple structure on top of JSON and WebSockets, applications can follow JSMP as a convention without needing an explicit JSMP implementation.

JSMP is a JSON message payload with additional

• typed payloads: enabling object-oriented messages
• addresses: allowing servers to be decomposed into messages
• unidirectional and RPC queries: both unidirectional messaging styles and query-response styles are supported

As a motivational example, a server might support a tic-tac-toe game. Each client would join a game, send moves, and receive game updates from the server.

A possible message might be a player move to place an "X" at location 4 in the game. The specific game instance id might be "tictactoe@example.com/game73". The player's login might be "user1@example.com/ipad13". And the class for a movement message might be com.example.TicTacToeMove.

["message",
 "tictactoe@example.com/game73",
 "user1@example.com/ipad13",
 "com.example.TicTacToeMove",
 {"location": "4", "side": "X"}]

A possible query might be a player joining a new game. In this query, the user asks the game-manager to join the game. The query "to" address is the game-manager. The "from" is the player's login. The payload class is com.example.JoinGame.

The query has a query-id 13 to match up queries and responses. JMTP allows any ordering or interleaving of messages, queries, and responses as long as the query eventually returns a result (or query_error).

["query",
 "game-manager@example.com",
 "user1@example.com/ipad13",
 13,
 "com.example.JoinGame",
 {"game": "tictactoe"}]

The response has a matching query-id of 13, and the "to" and "from" addresses are swapped for the response. The type of the payload is com.example.GameStart.

["response",
 "user1@example.com/ipad13",
 "game-manager@example.com",
 13,
 "com.example.GameStart",
 {"game": "tictactoe",
  "address": "tictactoc@example.com/game89",
  "side": "X"}]

Because JSMP is designed as an application protocol, you can use only those parts you need from JSMP. For example, an application might only need unidirectional messages. Or might only need query-response.

For example, if an application needs object-oriented messages, but not addresses or queries, it can just send null values for the addresses.

["message",
 null,
 null,
 "com.example.TicTacToeMove",
 {"location": "4", "side": "X"}]