gorush

gorush

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

Contents

• Support Platform
• Features
• Basic Usage
  • Download a binary
  • Command Usage
  • Send Android notification
  • Send iOS notification
• Run gorush web server
• Web API
  • GET /api/stat/go
  • GET /api/stat/app
  • GET /sys/stats
  • POST /api/push
  • Request body
  • iOS alert payload
  • Android notification payload
  • iOS Example
  • Android Example
  • Response body
• Run gorush in Docker
• License

Support Platform

• APNS
• GCM

Features

• 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.
• Support p12 or pem formtat of iOS certificate file.
• Support /sys/stats show response time, status code count, etc.
• Support for HTTP proxy to Google server (GCM).

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

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"

ios:
  enabled: false
  key_path: "key.pem"
  password: "" # certificate password, default as empty string.
  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"
  hide_token: true

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.

With Go installed

$ go get -u github.com/appleboy/gorush

On linux

$ wget -qO- https://github.com/appleboy/gorush/releases/download/v1.6.0/gorush-v1.6.0-linux-amd64.tar.gz | tar xvz

On OS X

$ wget -qO- https://github.com/appleboy/gorush/releases/download/v1.6.0/gorush-v1.6.0-darwin-amd64.tar.gz | tar xvz

Command Usage

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)
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 Android notification

Send single notification with the following command.

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

• -m: Notification message.
• -k: Google cloud message api key
• -t: Device token.
• --proxy: Set http proxy url. (only working for GCM)

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 or p12 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

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

GET /sys/stats

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
}

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.

iOS alert payload

See more detail about APNs Remote Notification Payload.

Android notification payload

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:

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 using httpie command.

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

License

Copyright 2016 Bo-Yi Wu @appleboy.

Licensed under the MIT License.