gorush

gorush

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

Support Platform

• APNS
• GCM

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

• -m: Notification message.
• -k: Google cloud message api key
• -t: Device token.

Send iOS notification

Send single notification with the following command.

$ gorush -ios -m="your message" -i="API Key" -t="Device token"

• -m: Notification message.
• -i: Apple Push Notification Certificate path (pem file).
• -t: Device token.

The default endpoint is APNs development. Please add -production flag for APNs production push endpoint.

$ gorush -ios -m="your message" -i="API Key" -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.

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.

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