The Melon Network Message Protocol (MNMP) is an extensible protocol designed to be used by a number of different products. It features:
An MNMP message consists of:
Additionally, the following:
Two types of message are currently defined: requests and responses.
An MNMP request is sent from a client (which may be Snarl but more likely will part of an application) to computer running Snarl. An MNMP request consists of:
The header, all request lines, and the terminator must all end with a CR/LF pair.
SNP 3.0 with no hashing:
SNP 3.0 with SHA-256 hashing:
id/version is always required and must be "SNP/3.0"; hash_type and cypher_type are optional, however if cypher_type is specified then hash_type must also be specified.
See Security for details of supported hashing and encryption algorithms.
Each action must be on a separate line and there must be at least one action contained within the message (otherwise you'll receive a MNMP_ERROR_BAD_PACKET response).
Actions follow the standard format, however there are some specific points to note:
An MNMP response is received by a client. An MNMP response consists of:
The header, all content lines, and the terminator all end with a CR/LF pair.
The MNMP response header is as follows:
A failure response provides the same content as a success reponse. In some cases, a "hint" line will indicate more specific information about the error that occurred.
Status codes are defined here.
A callback is a specialised type of response message.
Authorisation ensures only applications that share a common secret (in this case, a password) can communicate with Snarl. The password is entered on the remote computer running Snarl and is used in the construction of the key and key hash on the client, consequently it is never transmitted in clear text between the client and remote computer.
Currently, three forms of hashing are supported:
Due to deficiencies identified in both MD5 and SHA-1, it is recommended that SHA-256 should always be used when communication may occur over a WAN or across the Internet in an unsecured channel.
The authorisation type used is determined by the sender and is included in the SNP 3.0 header, along with the key hash and salt value used. A new salt value should be used for each request.
The key hash is computed as follows:
Using a password of "abcdef" and random salt of "1A2B3C4D5E6F" and MD5 and the hashing algorithm:
Resulting SNP 3.0 header:
Subscribing and forwarding achieve a similar end result but are subtly different.
As the name implies, a subscription is an open-ended connection initiated by a client to a known remote computer, both running Snarl. Some examples of subscriptions:
To summarise: a subscription takes place between two instances of Snarl, is initiated by the client computer and remains in place until the client unsubscribes.
Conversely, forwarding is effectively a wrapper for an SNP 3.0 register/notify action pair. Forwarding is still initiated by a client, however it's the client that is wishing to '''send''' notifications to an instance of Snarl, not receive them. The instance of Snarl may be running on the same computer, but more often than not it will be running on a remote computer. The client may use Snarl to send the register/notify message, although it's more likely it will be an application which creates the message itself. Some examples of forwarding:
The subscribe action is documented as part of the Snarl [[Generic_API#subscribe|generic API]]
Subscribe to notifications from all applications:
Subscribe to notifications from only the applications with signatures "foo/bar" and "bar/qux":
Subscribe to notifications from application "foo/bar" and attempt to subscribe to notifications from "wont/work" - the latter request will fail because the password supplied during the initial subscription was not provided:
Note that neither the IP address or the port number of the subscriber are required - these are derived directly from the subscriber's socket in order to avoid IP address spoofing.
Future revisions of the SNP 3.0 specification may allow the subscriber to provide a friendly name that the remote instance of Snarl will display in the subscriber list. The friendly name would be most likely be passed as a message parameter, as follows: