A push notification micro server using Gin framework written in Go (Golang).
- Support Google Cloud Message (Firebase Cloud Messaging now) using go-gcm library for Android.
- Support HTTP/2 Apple Push Notification Service using apns2 library.
- Support YAML configuration.
- Support command line to send single Android or iOS notification.
- Support Web API to send push notification.
- Support graceful restart & zero downtime deploy using facebook grace.
- Support HTTP/2 or HTTP/1.1 protocol.
- Support notification queue and multiple workers.
- Support
/api/stat/app
show notification success and failure counts. - Support
/api/config
show your YAML config. - Support store app stat to memory, Redis, BoltDB, BuntDB or LevelDB.
- Support
p12
orpem
formtat of iOS certificate file. - Support
/sys/stats
show response time, status code count, etc. - Support for HTTP proxy to Google server (GCM).
- Support retry send notification if server response is fail.
See the YAML config example:
core:
port: "8088"
worker_num: 8
queue_num: 8192
max_notification: 100
mode: "release"
ssl: false
cert_path: "cert.pem"
key_path: "key.pem"
http_proxy: "" # only working for GCM server
pid:
enabled: true
path: "gorush.pid"
override: true
api:
push_uri: "/api/push"
stat_go_uri: "/api/stat/go"
stat_app_uri: "/api/stat/app"
config_uri: "/api/config"
sys_stat_uri: "/sys/stats"
android:
enabled: true
apikey: "YOUR_API_KEY"
max_retry: 0 # resend fail notification, default value zero is disabled
ios:
enabled: false
key_path: "key.pem"
password: "" # certificate password, default as empty string.
production: false
max_retry: 0 # resend fail notification, default value zero is disabled
log:
format: "string" # string or json
access_log: "stdout" # stdout: output to console, or define log path like "log/access_log"
access_level: "debug"
error_log: "stderr" # stderr: output to console, or define log path like "log/error_log"
error_level: "error"
hide_token: true
stat:
engine: "memory" # support memory, redis, boltdb, buntdb or leveldb
redis:
addr: "localhost:6379"
password: ""
db: 0
boltdb:
path: "bolt.db"
bucket: "gorush"
buntdb:
path: "bunt.db"
leveldb:
path: "level.db"
How to send push notification using gorush
command? (Android or iOS)
The pre-compiled binaries can be downloaded from release page.
With Go
installed
$ go get -u -v github.com/appleboy/gorush
On linux
$ wget https://github.com/appleboy/gorush/releases/download/v1.7.3/gorush-v1.7.3-linux-amd64 -O gorush
On OS X
$ wget https://github.com/appleboy/gorush/releases/download/v1.7.3/gorush-v1.7.3-darwin-amd64 -O gorush
On Windows
$ wget https://github.com/appleboy/gorush/releases/download/v1.7.3/gorush-v1.7.3-windows-amd64.exe -O gorush.exe
________ .__
/ _____/ ____ _______ __ __ ______| |__
/ \ ___ / _ \\_ __ \| | \/ ___/| | \
\ \_\ \( <_> )| | \/| | /\___ \ | Y \
\______ / \____/ |__| |____//____ >|___| /
\/ \/ \/
Usage: gorush [options]
Server Options:
-p, --port <port> Use port for clients (default: 8088)
-c, --config <file> Configuration file
-m, --message <message> Notification message
-t, --token <token> Notification token
--proxy <proxy> Proxy URL (only for GCM)
--pid <pid path> Process identifier path
iOS Options:
-i, --key <file> certificate key file path
-P, --password <password> certificate key password
--topic <topic> iOS topic
--ios enabled iOS (default: false)
--production iOS production mode (default: false)
Android Options:
-k, --apikey <api_key> Android API Key
--android enabled android (default: false)
Common Options:
-h, --help Show this message
-v, --version Show version
Send single notification with the following command.
$ gorush -android -m="your message" -k="API Key" -t="Device token"
-m
: Notification message.-k
: Firebase Cloud Messaging api key-t
: Device token.--proxy
: Set http proxy url. (only working for GCM)
Send single notification with the following command.
$ gorush -ios -m="your message" -i="your certificate path" -t="device token" -topic="apns topic"
-m
: Notification message.-i
: Apple Push Notification Certificate path (pem
orp12
file).-t
: Device token.-topic
: The topic of the remote notification.-password
: The certificate password.
The default endpoint is APNs development. Please add -production
flag for APNs production push endpoint.
$ gorush -ios -m="your message" -i="your certificate path" -t="device token" -production
Please make sure your config.yml exist. Default port is 8088
.
$ gorush -c config.yml
Get go status of api server using httpie tool:
$ http -v --verify=no --json GET https://localhost:8088/api/stat/go
Gorush support the following API.
- GET
/api/stat/go
Golang cpu, memory, gc, etc information. Thanks for golang-stats-api-handler. - GET
/api/stat/app
show notification success and failure counts. - GET
/api/config
show server yml config file. - POST
/api/push
push ios and android notifications.
Golang cpu, memory, gc, etc information. Response with 200
http status code.
{
"time": 1460686815848046600,
"go_version": "go1.6.1",
"go_os": "darwin",
"go_arch": "amd64",
"cpu_num": 4,
"goroutine_num": 15,
"gomaxprocs": 4,
"cgo_call_num": 1,
"memory_alloc": 7455192,
"memory_total_alloc": 8935464,
"memory_sys": 12560632,
"memory_lookups": 17,
"memory_mallocs": 31426,
"memory_frees": 11772,
"memory_stack": 524288,
"heap_alloc": 7455192,
"heap_sys": 8912896,
"heap_idle": 909312,
"heap_inuse": 8003584,
"heap_released": 0,
"heap_objects": 19654,
"gc_next": 9754725,
"gc_last": 1460686815762559700,
"gc_num": 2,
"gc_per_second": 0,
"gc_pause_per_second": 0,
"gc_pause": [
0.326576,
0.227096
]
}
Show success or failure counts information of notification.
{
"version": "v1.6.2",
"queue_max": 8192,
"queue_usage": 0,
"total_count": 77,
"ios": {
"push_success": 19,
"push_error": 38
},
"android": {
"push_success": 10,
"push_error": 10
}
}
Show response time, status code count, etc.
{
"pid": 80332,
"uptime": "1m42.428010614s",
"uptime_sec": 102.428010614,
"time": "2016-06-26 12:27:11.675973571 +0800 CST",
"unixtime": 1466915231,
"status_code_count": { },
"total_status_code_count": {
"200": 5
},
"count": 0,
"total_count": 5,
"total_response_time": "10.422441ms",
"total_response_time_sec": 0.010422441000000001,
"average_response_time": "2.084488ms",
"average_response_time_sec": 0.0020844880000000002
}
Simple send iOS notification example, the platform
value is 1
:
{
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 1,
"message": "Hello World iOS!"
}
]
}
Simple send Android notification example, the platform
value is 2
:
{
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 2,
"message": "Hello World Android!"
}
]
}
Send multiple notifications as below:
{
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 1,
"message": "Hello World iOS!"
},
{
"tokens": ["token_a", "token_b"],
"platform": 2,
"message": "Hello World Android!"
},
{
"tokens": ["token_a", "token_b"],
"platform": 2,
"message": "Hello World!"
},
.....
]
}
See more example about iOS or Android.
Request body must has a notifications array. The following is a parameter table for each notification.
name | type | description | required | note |
---|---|---|---|---|
tokens | string array | device tokens | o | |
platform | int | platform(iOS,Android) | o | 1=iOS, 2=Android |
message | string | message for notification | - | |
title | string | notification title | - | |
priority | string | Sets the priority of the message. | - | normal or high |
content_available | bool | data messages wake the app by default. | - | |
sound | string | sound type | - | |
data | string array | extensible partition | - | |
retry | int | retry send notification if fail response from server. Value must be small than max_retry field. |
- | |
api_key | string | Android api key | - | only Android |
to | string | The value must be a registration token, notification key, or topic. | - | only Android |
collapse_key | string | a key for collapsing notifications | - | only Android |
delay_while_idle | bool | a flag for device idling | - | only Android |
time_to_live | uint | expiration of message kept on GCM storage | - | only Android |
restricted_package_name | string | the package name of the application | - | only Android |
dry_run | bool | allows developers to test a request without actually sending a message | - | only Android |
notification | string array | payload of a GCM message | - | only Android. See the detail |
expiration | int | expiration for notification | - | only iOS |
apns_id | string | A canonical UUID that identifies the notification | - | only iOS |
topic | string | topic of the remote notification | - | only iOS |
badge | int | badge count | - | only iOS |
category | string | the UIMutableUserNotificationCategory object | - | only iOS |
alert | string array | payload of a iOS message | - | only iOS. See the detail |
name | type | description | required | note |
---|---|---|---|---|
title | string | Apple Watch & Safari display this string as part of the notification interface. | - | |
body | string | The text of the alert message. | - | |
subtitle | string | Apple Watch & Safari display this string as part of the notification interface. | - | |
action | string | The label of the action button. This one is required for Safari Push Notifications. | - | |
action-loc-key | string | If a string is specified, the system displays an alert that includes the Close and View buttons. | - | |
launch-image | string | The filename of an image file in the app bundle, with or without the filename extension. | - | |
loc-args | array of strings | Variable string values to appear in place of the format specifiers in loc-key. | - | |
loc-key | string | A key to an alert-message string in a Localizable.strings file for the current localization. | - | |
title-loc-args | array of strings | Variable string values to appear in place of the format specifiers in title-loc-key. | - | |
title-loc-key | string | The key to a title string in the Localizable.strings file for the current localization. | - |
See more detail about APNs Remote Notification Payload.
name | type | description | required | note |
---|---|---|---|---|
icon | string | Indicates notification icon. | - | |
tag | string | Indicates whether each notification message results in a new entry on the notification center on Android. | - | |
color | string | Indicates color of the icon, expressed in #rrggbb format | - | |
click_action | string | The action associated with a user click on the notification. | - | |
body_loc_key | string | Indicates the key to the body string for localization. | - | |
body_loc_args | string | Indicates the string value to replace format specifiers in body string for localization. | - | |
title_loc_key | string | Indicates the key to the title string for localization. | - | |
title_loc_args | string | Indicates the string value to replace format specifiers in title string for localization. | - |
See more detail about GCM server reference.
Send normal notification.
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 1,
"message": "Hello World iOS!"
}
]
The following payload asks the system to display an alert with a Close button and a single action button.The title and body keys provide the contents of the alert. The “PLAY” string is used to retrieve a localized string from the appropriate Localizable.strings file of the app. The resulting string is used by the alert as the title of an action button. This payload also asks the system to badge the app’s icon with the number 5.
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 1,
"badge": 5,
"alert": {
"title" : "Game Request",
"body" : "Bob wants to play poker",
"action-loc-key" : "PLAY"
}
}
]
The following payload specifies that the device should display an alert message, plays a sound, and badges the app’s icon.
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 1,
"message": "You got your emails.",
"badge": 9,
"sound": "bingbong.aiff"
}
]
Add other fields which user defined via data
field.
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 1,
"message": "Hello World iOS!",
"data": {
"key1": "welcome",
"key2": 2
}
}
]
Send normal notification.
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 2,
"message": "Hello World Android!",
"title": "You got message"
}
]
Add notification
payload.
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 2,
"message": "Hello World Android!",
"title": "You got message",
"notification" : {
"icon": "myicon",
"color": "#112244"
}
}
]
Add other fields which user defined via data
field.
"notifications": [
{
"tokens": ["token_a", "token_b"],
"platform": 2,
"message": "Hello World Android!",
"title": "You got message",
"data": {
"Nick" : "Mario",
"body" : "great match!",
"Room" : "PortugalVSDenmark"
}
}
]
Error response message table:
status code | message |
---|---|
400 | Missing notifications field. |
400 | Notifications field is empty. |
400 | Number of notifications(50) over limit(10) |
Success response:
{
"success": "ok"
}
Set up gorush
in the cloud in under 5 minutes with zero knowledge of Golang or Linux shell using our gorush Docker image.
$ docker pull appleboy/gorush
$ docker run --name gorush -p 80:8088 appleboy/gorush
Run gorush
with your own config file.
$ docker pull appleboy/gorush
$ docker run --name gorush -v ${PWD}/config.yml:/config.yml -p 80:8088 appleboy/gorush
Testing your gorush server using httpie command.
$ http -v --verify=no --json GET http://your.docker.host/api/stat/go
Copyright 2016 Bo-Yi Wu @appleboy.
Licensed under the MIT License.