# RQPush

A library to assist with pushing notifications to [RQueue](https://github.com/jeremyandrews/rqueue).

## RQPush Overview

RQPush is only useful as a library for pushing notifications into [RQueue](https://github.com/jeremyandrews/rqueue). For this purpose, it provides the following functionality:

- Builds notifications with support for Handlebar templating
- Calculates a sha256 hash of each notification, optionally salted with a shared secret
- (@TODO) Routes notifications to the appropriate queue via SRV records

## Notifications Overview

Notifications require the following three fields:

- `app`: _application name_
- `title`: _the title of the notification, for example used as an email subject_
- `short_text`: _the body of the notification_

The following fields can optionally be defined as well:

- `url`: _ie, the URL of the project generating the notification, or a URL to view more information_
- `tagline`: _a description of the project generating the notification_
- `category`: _allows arbitrary categorization of notifications, primarily used for filtering and routing_
- `lang`: _two letter language code, defaults to "en"_
- `short_text_template`: _allows handlebar variable replacement, for example `{{foo}}`_
- `short_html`: _html version of short_text_
- `short_html_template`: _allows handlebar variable replacement and wraps in appropriate HTML tags_
- `long_text`: _optional extended version of `short_text`_
- `long_html_template`: _allows handlebar variable replacement and wraps in appropriate HTML tags_
- `values`: _key-value pairs for handlebars-style templating_

## Working With Notifications

Notifications are created as follows:

```Rust
use rqpush::Notification;

let mut notification: Notification = Notification::init("app name", "title", "short text");
```

This is enough to generate a basic notification, however additional customization is possible. For example, to set a project URL on a notification that was created per the earlier example:

```Rust
notification.set_title("https://github.com/jeremyandrews/rqpush");
```

And finally, a notification can be sent as follows:

```Rust
notification.send("127.0.0.1:8000", 42, 0, None);
```

In this example, we send the notification to port 8000 on localhost, with a priority of 42. We don't set a TTL so the notification or a shared secret.

### Netgrasp Example

The following example shows a real-world example, sending a notification with [Netgrasp](https://github.com/jeremyandrews/netgrasp).

```Rust
use rqpush::Notification;

let mut notification: Notification = Notification::init("Netgrasp", "[netgrasp] new device: {{device}}", "A new device joined your network: {{device}}");
notification.set_category("first_seen_device");
```

@TODO: Finish:

```json
{
    "app": "Netgrasp",
    "category": "first_seen_device",
    "lang": "en",
    "title": "[netgrasp] new device: iPhone",
    "short_text": "A new device joined your network: iPhone",
    "short_html": "<P>A new device joined your network: <EM>iPhone</EM></P>",
    "long_text": "A new device joined your network:
     * iPhone
     * ip: 10.202.14.37 [ff:ff:ff:ff:ff:ff]
     * previously seen: never
     * first seen: now

    In the past 24 hours this device talked to 1 device:
     * Gateway: 10.202.14.1

    Email generated by Netgrasp passive network observation tool.",
    "long_html": "<P><UL>
     <LI>iPhone</LI>
     <LI>ip: 10.202.14.37 [ff:ff:ff:ff:ff:ff]</LI>
     <LI>previously seen: never</LI>
     <LI>first seen: now</LI>
    </UL>
    In the past 24 hours this device talked to 1 device:
    <UL>
     <LI>Gateway: 10.202.14.1</LI>
    </UL></P>
    <DIV ID="footer">
     <P><SMALL><EM>Email generated by Netgrasp passive network observation tool.</EM></SMALL></P>
    </DIV>",
}
```