A Rust API and command-line notification pusher for the Pushover notification service
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
Cargo.lock
Cargo.toml
LICENSE
README.md

README.md

po

po is a third-party (not affiliated with Superblock, LLC) Rust API and command-line notification pusher for the Pushover push notification service.

libpo, the Rust API, safely wraps the Pushover REST API and tries to handle all corner cases and error conditions, for reliable push message sending to any Pushover client device (iOS, Android, desktop, Open Client). It also supports linking message bodies too long for Pushover as supplementary URLs sent with the rest of the notification.

po is a utility that uses libpo to provide a multi-platform, POSIX-y, command-line interface for push notification sending. It exposes all of the features of libpo, and also supports API token and user key storage. It can receive message body input as a command line argument, or from standard input.

Compiling

You will need libcurl; everything else is pulled in by Cargo. Run cargo build to compile both the libpo library and the po command-line pusher; they will each be in the target/debug subdirectory. Run cargo build --release to compile optimized builds of each, which end up in target/release. If you want, copy po to someplace in your path.

Using po

First, run po --setup to receive instructions on how to store a Pushover API token and user key for use by the command-line client.

To push a simple message with its title set to the hostname of the sending computer:

po --title `hostname` "Hello"

To do the same but with the message body taken from standard input:

echo Hello | po --title `hostname`

To push the output of ls -la and link the full output as a Gist if it exceeds Pushover's maximum length (1024 characters):

ls -la | po --gist

Using libpo

Add po = "*" to the [dependencies] section of your project's Cargo.toml.

Use po::send_basic to send a basic message with API token, user key, and message body strings. po::send supports more complicated messages with optional parameters, and po::send_gist posts the full text of each message to GitHub Gist and links it as a supplementary URL (useful if messages exceed the maximum Pushover length).

For a more flexible (and simpler if you have many parameters) API, use po::push. This function accepts strings representing an API token, user key, and message body string just like the po::send_* family of functions, but accepts as its last parameter an array of po::Parameters types representing every optional parameter supported by the library.

libpo also exposes a po::gist function which uploads a string to GitHub Gist with an optional title.

Todo

  • More complete error handling
  • Make emergency priority messaging actually work
  • Verify the stored API token and user key
  • Retry sending the notification if a transient error is encountered
  • Markdown output support for Gists
  • Asynchronous sending for po via daemonization
  • More testing

To be done as Rust features stabilize

  • Use the tee trait to pipe input to output as it's received
  • Re-add proper exit statuses
  • Work on config file read/write error reporting
  • Better error handling for config file/directory creation
  • Actually use semantic versions for dependencies as they leave 0..