Go to file
Bo-Yi Wu 859a24d049 fix gofmt.
Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>
2016-05-02 11:05:32 +08:00
certificate Add tls and normal server listen testing. 2016-04-02 00:37:58 +08:00
config Feature #58 support BoltDB engine 2016-04-23 15:13:57 +08:00
docker add init redis func. 2016-04-22 23:01:01 +08:00
gorush fix gofmt. 2016-05-02 11:05:32 +08:00
screenshot bump 1.0.0 and add status screenshot. 2016-04-11 15:13:13 +08:00
script rename to gorush 2016-04-13 15:22:04 +08:00
storage/memory Fixed #66 Support memory interface. 2016-05-02 11:04:19 +08:00
.editorconfig add editor config 2016-03-24 16:10:46 +08:00
.gitignore Feature #58 support BoltDB engine 2016-04-23 15:13:57 +08:00
.travis.yml remove 1.3 and 1.4 testing for redis go. 2016-04-22 23:17:03 +08:00
LICENSE Initial commit 2016-03-22 15:15:20 +08:00
Makefile Add HTML presentation for code coverage. 2016-05-02 11:01:07 +08:00
README.md update readme for topic flag. 2016-04-28 14:45:25 +08:00
doc.go [ci skip] update google doc. 2016-04-17 13:21:17 +08:00
gorush.go Fixed #67 Support iOS apns-topic flag. 2016-04-28 14:39:34 +08:00

README.md

gorush

A push notification server using Gin framework written in Go (Golang).

GoDoc Build Status Coverage Status Go Report Card codebeat badge

Support Platform

Feature

  • Support Google Cloud Message 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 zero downtime restarts for go servers using endless.
  • 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 or BoltDB.

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"

api:
  push_uri: "/api/push"
  stat_go_uri: "/api/stat/go"
  stat_app_uri: "/api/stat/app"
  config_uri: "/api/config"

android:
  enabled: true
  apikey: "YOUR_API_KEY"

ios:
  enabled: false
  pem_cert_path: "cert.pem"
  pem_key_path: "key.pem"
  production: false

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"

stat:
  engine: "memory" # support memory, redis or boltdb
  redis:
    addr: "localhost:6379"
    password: ""
    db: 0
  boltdb:
    path: "gorush.db"
    bucket: "gorush"

Basic Usage

How to send push notification using gorush command? (Android or iOS)

Download a binary

The pre-compiled binaries can be downloaded from release page.

Send Android notification

Send single notification with the following command.

$ gorush -android -m="your message" -k="API Key" -t="Device token"

Send iOS notification

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 file).
  • -t: Device token.
  • -topic: The topic of the remote notification.

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

Run gorush web server

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

Web API

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.

GET /api/stat/go

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
  ]
}

GET /api/stat/app

Show success or failure counts information of notification.

{
  "queue_max": 8192,
  "queue_usage": 0,
  "total_count": 77,
  "ios": {
    "push_success": 19,
    "push_error": 38
  },
  "android": {
    "push_success": 10,
    "push_error": 10
  }
}

POST /api/push

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

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 o
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 -
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 int 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

iOS alert payload

name type description required note
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.

Android 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.

iOS Example

Send normal notification.

  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!",
      "title": "You got message"
    }
  ]

The app icon be badged with the number 9 and that a bundled alert sound be played when the notification is delivered.

  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!",
      "title": "You got message",
      "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!",
      "title": "You got message",
      "data": {
        "key1": "welcome",
        "key2": 2
      }
    }
  ]

Android Example

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"
      }
    }
  ]

Response body

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"
}

Run gorush in Docker

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

Testing your gorush server.

$ http -v --verify=no --json GET http://your.docker.host/api/stat/go

statue screenshot

License

Copyright 2016 Bo-Yi Wu @appleboy.

Licensed under the MIT License.