Skip to content
fullphat edited this page Apr 26, 2017 · 69 revisions

Introduction

The Snarl Network Protocol (pronounced as "snap", abbreviated to "SNP") is a platform-agnostic network protocol used to transmit notifications between computers on the same network, or even across the Internet. It's highly extensible and is both easy to read and easy to implement. (There are libraries available for .net and Python.).

This is an example SNP 3.1 request:

SNP/3.1 NOTIFY
title: Hello, world!
text: Notifications are easy...
icon: stock:system-info
END

And this is an example response:

SNP/3.1 SUCCESS
END

Communication Overview

Communication takes place between a client and server over TCP and follows the standard approach where the client initiates a connection to a server, sends a request, receives a response and then closes the connection. Unlike most client/server communications however, Snarl provides the ability for applications to receive feedback on whether the user acknowledged the notification or not. These "out-of-cycle" responses can be received by the client separately.

In summary, the low-level communication process is therefore:

  1. Client creates a socket
  2. Client connects to a server running on a remote computer
  3. Client sends a request to the server
  4. Client receives a reply from the server
  5. Client ends the connection
  6. Steps 3, 4 and 5 repeat

Out-of-cycle responses, such as whether the notification expired or was actioned by the user are received on a different port specified by the client when the notification request was sent.

      • diagram showing simple client/server requests - - -
      • diagram showing client/server request with reply-port - - -
      • diagram showing client/server request with forward-to - - -

Protocol Versions

There are various versions of SNP available, however only SNP 3.1 and SNP/HTTP v2 are in active development. Both of these will feature in Snarl R5.0, which itself is currently in Beta release. New applications which are able to target Snarl R5.0 (that is, those which are suitable for use with beta software) are strongly encouraged to target SNP 3.1 or SNP/HTTP v2 if at all possible.

Previous versions of SNP will remain supported for now, however all but SNP 2.0 are deprecated:

Version Details
SNP 1 The original version of the protocol. Any applications still using SNP 1.x should be migrated to SNP 3.1 if possible, with an alternative of SNP 2.
SNP 2 This replaced SNP 1 when the Snarl API was revised to use a URL path?query format. SNP 2 simply wraps the raw API with a network protocol. This has advantages - it allows for full access to the raw Snarl API, making it largely future-proof - but also some challenges - it does not support authorisation or encryption.
SNP 3.0 This variant is considered deprecated (see here for commentary on why we've made this decision). Applications should target SNP 3.1 once it is released, and SNP 2.0 in the meantime.
SNP 3.1 This will be introduced in Snarl 5.0 and features a much more structured request/response cycle. You are strongly advised to target this variant over 3.0.
SNP/HTTP An HTTP-based variant. There are three iterations of SNP/HTTP: v0, v1 and v2 with version 2 following a RESTful approach. SNP/HTTP is considered the platform of choice for applications which work better using HTTP rather than raw TCP/IP sockets.

Message Structure

A SNP message consists of lines of UTF-8 encoded text separated by CRLF (\r\n) pairs. Each message contains:

  • A header
  • Some content (optional for some messages)
  • A terminator

The header, content and terminator vary depending on the version of the protocol used.

Message Types

Four types of message are currently defined:

  • Request
  • Response
  • Callback
  • Goodbye

Request Message

A SNP request is sent from a client to a server. A request requires the server to take some of action, however the server may choose to accept or reject it. Either way, the server sends a response message indicating success or failure.

Response Message

A SNP response is received by a client from a server in response to a previous request. The response will typically indicate the result (success or failure) of a previous request and may provide further information (for example, extended error information in the case of a failure) depending on the nature of the request.

Callback

A callback is sent either when the user takes action on a notification, or when another event occurs - for example, a notification expires without any user interaction. Because notifications may be interacted with in any order, callbacks may therefore arrive at the client in any order and at any time.

Goodbye

Goodbye messages are received by clients that are subscribed to notifications. See subscriptions for more details.

Forward

      • just a request - - -

A forward message is sent once a client has successfully subscribed to notifications from a server. The message will contain information about the notification, where it came from, and the notification's content. Like callbacks, forwarded messages can arrive at any time and need special consideration.

Clone this wiki locally