Snarl Network Protocol
FORWARD
NOTIFY
REGISTER
SUBSCRIBE
UNSUBSCRIBE
FAILED
SUCCESS
CALLBACK
GOODBYE
FORWARD
Name | Description |
---|---|
source |
The name of the application sending the forwarded notification |
app-id:
or event-id
parameters;SNP/3.1 FORWARD
source: My App
title: Daily Notice
text: The fire alarm will be tested at 11am today
icon: stock:system-info
END
SUBSCRIBE
Name | Description |
---|---|
forward-to |
The URL to send subsequent forwarded notifications to. |
reply-port |
The port to send subsequent forwarded notifications to. |
uid |
A unique identifier for the subscription. |
Name | Description |
---|---|
filter |
One or more application identifiers separated by semicolons. |
filter-type |
Either inclusive or exclusive . |
SUBSCRIBE
request, the client must check the returned status to ensure the server accepted the request;reply-port
and forward-to
is invalid and will return an error;A subscription is a request from a client to a server where the client asks to receive notifications from the server. The notifications will be sent as forwarded messages, rather than traditional notifications.
Subscriptions can take two forms: notifications can be forwarded to a URL as an HTTP POST
request, or they can be sent as an SNP 3.1 FORWARD
message to a port on the same computer as the client.
Subscriptions must include a unique identifier (uid) which is used when unsubscribing and should also be sent by the server when it needs to issue a GOODBYE
response.
Straightforward request which asks for notifications to be sent to port 5000:
SNP/3.1 SUBSCRIBE
uid: my_lame_uid
reply-port: 5000
END
Same, but using authentication:
SNP/3.1 SUBSCRIBE MD5:ABCDEF1234.9876543210
uid: my_lame_uid
reply-port: 5000
END
Request which asks for notifications to be sent to http://mysever:4444/bucket/
:
SNP/3.1 SUBSCRIBE
uid: my_lame_uid
forward-to: http://mysever:4444/bucket/
END
UNSUBSCRIBE
Name | Description |
---|---|
uid | The unique identifier used in the initial subscription. |
None.
SNP/3.1 UNSUBSCRIBE
uid: my_lame_uid
END
FAILED
A FAILED
response indicates the request could not be processed by the server for some reason.
Name | Requirement | Description |
---|---|---|
error-number |
Mandatory | The Snarl status code of the error as a positive integer |
error-name |
Mandatory | The Snarl status code as a string |
reason |
Mandatory | Further context or supporting information explaining the error. Must be included, but may be blank |
Servers may include additional information in the form of x-
header entries. Servers must not return data-
entries however.
None.
SNP/3.1 FAILED
error-number: 202
error-name: NotRegistered
reason:
END
SUCCESS
None.
A success response may contain additional information, however this will be relevant to the request the response pertains to.
Servers may include additional information in the form of x-
header entries. Servers should not return data-
entries however.
Example returning some data:
SNP/3.1 SUCCESS
data-example: some data here
data-value: 23
END
Example returning no extra data:
SNP/3.1 SUCCESS
END
CALLBACK
A callback message is sent either to a listening TCP port on the client machine that created the notification, or to a URL as an HTTP POST
request.
Due to the asynchronous nature that notifications may appear, and when a user may react to a notification (if at all), callback messages can arrive at any time and in any sequence. The receiving client can determine which callback message refers to which notification using the uid
parameter, any data-
values included in the notification, or a combination of the two.
None.
Name | Value |
---|---|
uid |
The uid supplied when the notification was created (if one was provided) |
data-* |
Any data parameters supplied when the notification was created |
x-
headers.The following callback message indicates that a notification was closed by the end user. The notification was created with a uid
of my_lame_uid
and included some additional data-
parameters:
SNP/3.1 CALLBACK
uid: my_lame_uid
data-guardian: Len
data-wossname: cheese
data-place: On The Bus
END
GOODBYE
A GOODBYE
message is sent by a subscription server when it is closing. This can be used to notify subscribers that they should no longer expect to received forwarded notifications from the server. The subscriber is free to attempt to reconnect (as the server may simply be restarting), but should wait a short period of time (at least 30 seconds) before doing so.
Name | Value |
---|---|
uid |
The UID specified by the subscriber when it originally subscribed. |
Name | Value |
---|---|
x-reason |
Human readable text indicating why the server is stopping |
x-retry-after |
Number of seconds clients should wait before retrying a connection to the server |
None.
SNP/3.1 GOODBYE
uid: some_uid
END