Push Service is a Python implementation of the Push API.
It allows users to create push channels, subscribe to them, and send notifications. The service is designed to be flexible, implementing both a command line interface and a web user interface.
It includes a web user interface inspired to notify.run, but its main design feature is the separation of the subscription web interface from the notification logic. This allows users to send notifications without requiring a running web server.
The web interface supports SSL, which is required to enable subscriptions to servers listening on non-localhost addresses.
pip install push_serviceChannels can be created, listed, and deleted using the command line interface. The commands are as follows:
push_service list
push_service create my_channel
push_service delete my_channelSubscriptions to channels can be managed using the subscription command. This command starts a temporary web interface for subscribing to a specific channel:
push_service subscription my_channelPush service webui enabled for subscription to the following channels:
http://127.0.0.1:8000/my_channel
█▀▀▀▀▀█ █ █▄▄▀██▀▄ █▀▀▀▀▀█
█ ███ █ █▀ ▀█▄▄▀▀▄▀▀ █ ███ █
█ ▀▀▀ █ ▄▄ ▄ ██ ▀▀ ▄█ █ ▀▀▀ █
▀▀▀▀▀▀▀ ▀▄▀ █ █ ▀▄█ ▀ ▀▀▀▀▀▀▀
█ █▄█▀ █ █ ▀ ▄█ ▀▄ ▀█▄█ ▄ ▄
▄▀▀██ ▀ ▄▄▀▄ ▄▄▀▀▄████ ▀███
▄▀▄ ▀▀█▀▄▀▀ ▄▀█ ▄ ▀█ ▀▄▀▀
▀▀▄▄▄▀▀█▀█▀▄█▄▄▀█▄█▄ ▄▀▀▄▄▀█▀
▀▀▀▀▄ ▀ █▄▄█▀▀▀█ █ ▀▄▄▄ ▀ ▀▄
▀ ▀█ ▀▀██ █▀█ ▄▀▄▀ ▀█ ▀ ▀ ██
▀ ▀ ▀ ▀ ▄▀█ ▄▀▀█▄ ▀█▀▀▀█ █▄▄
█▀▀▀▀▀█ ▄██▄▀█▀▄█ █▄█ ▀ █▄▄█
█ ███ █ ▄▄█▀█ █ ▀▀ ███▀█▀ ▄▀
█ ▀▀▀ █ ▀ ██▄ █▄ ██ ███ ▄▀
▀▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀ ▀ ▀▀▀ ▀ ▀
Press Enter to stop the subscription webui...
This command will start a web server that allows users to subscribe to the specified channel.
The web interface will be available at http[s]://<host>:<port>/subscribe/my_channel, where <host> and <port> are specified by the --host and --port parameters, respectively.
The web interface supports SSL, which is required to enable subscriptions to URLs different from localhost.
SSL certificates must be provided by the user, and can be specified using the --ssl_certificate, --ssl_private_key, and --ssl_chain parameters.
Subscription is the only moment when the web server is required. Once a device is subscribed to a channel, it can receive messages even if the web server is not running, as the logic for sending messages is independent of the web interface.
To help users choose the host for the web interface and subscription commands, the iplist command can be used to list the IP addresses of the host:
push_service iplistAvailable IPs for the host:
Available IP addresses:
All IPV4 interfaces: 0.0.0.0
All IPV6 interfaces: ::
Ethernet: xxx.yyy.wwww.zzz
Ethernet: [xxxx:yyyy:ww:zz:xxxx:yyyy:wwww:zzzz]
Wi-Fi: xxx.yyy.wwww.zzz
Wi-Fi: [xxxx:yyyy:ww:zz:xxxx:yyyy:wwww:zzzz]
...
Pushing a message requires only the access to the database file and the encryption password. No web server is required to send messages, which makes it easy to integrate the push service into other applications.
push_service message my_channel "Hello, world!"Messages can be sent as simple text string or in JSON format, allowing for structured data to be pushed to subscribers. The message should be a valid JSON string in the following format:
{
"title": "Notification Title",
"body": "Notification Body",
"icon": "https://example.com/icon.png",
"url": "https://example.com"
}This package also implement a complete web user interface in the style of the notify.run website, allowing users to create channels, subscribe to thems and sending notification messages.
It can be started using the webui command:
push_service webuiThe web interface can be configured to enable admin features (login/logout, channel deletion) and channel creation by setting the --show_home, the --enable_admin, and --enable_channel_creation parameters, respectively.
The admin account is protected by a password, which is asked at the first login and stored (crypted) in a file specified by the --admin_password_file parameter (or, by default in the .push_service/admin_password file in user's home directory).
A two-factor authentication is mandatory, based on a one-time password (OTP) stored in a file specified by the --otp_secret_file parameter (or, by default in the .push_service/otp_secret file in user's home directory).
The OTP secret is created if it does not exist and shown at the first login as a QR code in the web interface, so that it can be scanned by an authenticator app (e.g., Google Authenticator, Authy).
In the case of losing the OTP authentication access, deleting the OTP secret file will present the admin with a new QR code at the next login.
Keep the access to the password and otp files safe and limited to ensure the security of admin access!
The data related to the channels is stored in a SQLite database file, which by default is named channels.db and it is stored in the .push_service subdirectory of user's home directory.
Thanks to the use of SQLAlchemy, the actual database can be replaced with many other database types by changing the --db_url parameter.
The data in the database is encrypted using a password stored in a file, which is created if it does not exist.
The password file is created by default as .push_service/channel_db_encryption_password in the user's home directory, but it can be changed using the --encryption_password_file parameter.
Keep the access to this file safe and limited to ensure the security of your channels!
Command-line arguments can be set in a configuration file, which allows for easier management of the service settings.
Any -- prefixed argument can be set in the configuration file, which is then passed to the push_service command using the -c or --config option.
An example of configuration file setting all the parameters is as follows:
db_url = sqlite:///my_dir/channels.db
encryption_password_file = /my_dir/channel_db_encryption_password
push_service_email = push_service@example.com
log_dir = /my_dir/logs
host = 192.168.0.1
port = 9876
otp_secret_file = /my_dir/otp_secret
admin_password_file = /my_dir/admin_password
ssl_certificate = /my_dir/server-crt.pem
ssl_chain = /my_dir/server-chain.pem
ssl_private_key = /my_dir/server-key.pemUsage of the configuration file:
push_service -c config_file.yaml webuiThis is the help message for the push_service command, which details the available commands and options:
push_service -husage: push_service [-h] [-c CONFIG] [-s SAVE] [--db_url DB_URL] [--encryption_password_file ENCRYPTION_PASSWORD_FILE] [--push_service_email PUSH_SERVICE_EMAIL] [--log_dir LOG_DIR] [--host HOST] [--port PORT] [--ssl_certificate SSL_CERTIFICATE] [--ssl_private_key SSL_PRIVATE_KEY]
[--ssl_chain SSL_CHAIN] [--enable_admin] [--show_home] [--enable_channel_creation] [--otp_secret_file OTP_SECRET_FILE] [--admin_password_file ADMIN_PASSWORD_FILE]
{list,create,delete,subscription,message,webui,iplist} ...
positional arguments:
{list,create,delete,subscription,message,webui,iplist}
command to execute
list list all channel names
create create a new channel
delete delete a channel
subscription start a temporary webui for a channel
message send a message to a channel
webui start the full webui for the push service
iplist list the IPs of the host, to help choosing the host for webui and subscription commands
options:
-h, --help print a detailed help message
-c CONFIG, --config CONFIG
read configuration from a file (default: None)
-s SAVE, --save SAVE saves configuration to a file (default: None)
--db_url DB_URL database connection string (default: sqlite:////home/user/.push_service/channels.db)
--encryption_password_file ENCRYPTION_PASSWORD_FILE
file storing the encryption password (created if missing) (default: /home/user/pushservice/channels_db_encryption_password)
--push_service_email PUSH_SERVICE_EMAIL
email address associated with the push service (default: push_service@example.com)
--log_dir LOG_DIR local directory for log files {subscription,webui} (default: D:\Users\esuli\Documents\Software\push_service\push_service_logs)
--host HOST host server address {subscription,webui} (default: 127.0.0.1)
--port PORT host server port {subscription,webui} (default: 8000)
--ssl_certificate SSL_CERTIFICATE
SSL certificate file {subscription,webui} (default: None)
--ssl_private_key SSL_PRIVATE_KEY
SSL private key file {subscription,webui} (default: None)
--ssl_chain SSL_CHAIN
SSL chain file {subscription,webui} (default: None)
--enable_admin enable admin features (login/logout, channel deletion) {webui} (default: False)
--show_home shows the home page {webui} (default: False)
--enable_channel_creation
enable channel creation feature {webui} (default: False)
--otp_secret_file OTP_SECRET_FILE
path to file storing OTP secret (created if missing) {webui} (default: /home/user/.push_service/otp_secret)
--admin_password_file ADMIN_PASSWORD_FILE
path to file storing admin password (created if missing) {webui} (default: /home/user/.push_service/admin_password)
Args that start with '--' can also be set in a config file (specified via -c). Config file syntax allows: key=value, flag=true, stuff=[a,b,c] (for details, see syntax at https://goo.gl/R74nmi). In general, command-line values override config file values which override defaults.
Command 'list'
usage: push_service list
Command 'create'
usage: push_service create [name]
positional arguments:
name name of the channel to create, if not given, a random name is generated
Command 'delete'
usage: push_service delete name
positional arguments:
name name of the channel to delete
Command 'subscription'
usage: push_service subscription name
positional arguments:
name name of the channel to subscribe to
Command 'message'
usage: push_service message name message
positional arguments:
name name of the channel to send the message to
message message to send to the channel
Command 'webui'
usage: push_service webui
Command 'iplist'
usage: push_service iplist
See the LICENSE file.