开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

gorush

A push notification micro server using Gin framework written in Go (Golang) and see the demo app.

Contents

• gorush
  • Contents
  • Support Platform
  • Features
  • Memory Usage
  • Basic Usage
    • Download a binary
    • Install from source
      • Prerequisite Tools
      • Fetch from GitHub
    • Command Usage
    • Send Android notification
    • Send Huawei (HMS) notification
    • Send iOS notification
    • Send Android or iOS notifications using Firebase
  • Run gorush web server
  • Web API
    • GET /api/stat/go
    • GET /api/stat/app
    • GET /sys/stats
    • GET /metrics
    • POST /api/push
    • Request body
    • iOS alert payload
    • iOS sound payload
    • Android notification payload
    • Huawei notification
    • iOS Example
    • Android Example
    • Huawei Example
    • Response body
  • Run gRPC service
  • Run gorush in Docker
  • Run gorush in Kubernetes
    • Quick Start
    • Create the Service Controller for AWS ELB
    • Ingress Controller for AWS ALB
    • Clean up the gorush
  • Run gorush in AWS Lambda
    • Build gorush binary
    • Deploy gorush application
    • Without an AWS account
  • Stargazers over time
  • License

Support Platform

• APNS
• FCM
• HMS

A live demo on Netlify.

Features

• Support Firebase Cloud Messaging using go-fcm library for Android.
• Support HTTP/2 Apple Push Notification Service using apns2 library.
• Support HMS Push Service using go-hms-push library for Huawei Devices.
• Support YAML configuration.
• Support command line to send single Android or iOS notification.
• Support Web API to send push notification.
• 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, LevelDB or BadgerDB.
• Support p8, p12 or pem format of iOS certificate file.
• Support /sys/stats show response time, status code count, etc.
• Support for HTTP, HTTPS or SOCKS5 proxy.
• Support retry send notification if server response is fail.
• Support expose prometheus metrics.
• Support install TLS certificates from Let's Encrypt automatically.
• Support send notification through RPC protocol, we use gRPC as default framework.
• Support running in Docker, Kubernetes or AWS Lambda (Native Support in Golang)
• Support graceful shutdown that workers and queue have been sent to APNs/FCM before shutdown service.
• Support different Queue as backend like NSQ, NATS or Redis streams, defaut engine is local Channel.

See the default YAML config example:

core:
  enabled: true # enable httpd server
  address: "" # ip address to bind (default: any)
  shutdown_timeout: 30 # default is 30 second
  port: "8088" # ignore this port number if auto_tls is enabled (listen 443).
  worker_num: 0 # default worker number is runtime.NumCPU()
  queue_num: 0 # default queue number is 8192
  max_notification: 100
  sync: false # set true if you need get error message from fail push notification in API response.
  feedback_hook_url: "" # set a hook url if you need get error message asynchronously from fail push notification in API response.
  feedback_timeout: 10 # default is 10 second
  mode: "release"
  ssl: false
  cert_path: "cert.pem"
  key_path: "key.pem"
  cert_base64: ""
  key_base64: ""
  http_proxy: ""
  pid:
    enabled: false
    path: "gorush.pid"
    override: true
  auto_tls:
    enabled: false # Automatically install TLS certificates from Let's Encrypt.
    folder: ".cache" # folder for storing TLS certificates
    host: "" # which domains the Let's Encrypt will attempt

grpc:
  enabled: false # enable gRPC server
  port: 9000

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"
  metric_uri: "/metrics"
  health_uri: "/healthz"

android:
  enabled: true
  apikey: "YOUR_API_KEY"
  max_retry: 0 # resend fail notification, default value zero is disabled

huawei:
  enabled: false
  appsecret: "YOUR_APP_SECRET"
  appid: "YOUR_APP_ID"
  max_retry: 0 # resend fail notification, default value zero is disabled

queue:
  engine: "local" # support "local", "nsq", "nats" and "redis" default value is "local"
  nsq:
    addr: 127.0.0.1:4150
    topic: gorush
    channel: gorush
  nats:
    addr: 127.0.0.1:4222
    subj: gorush
    queue: gorush
  redis:
    addr: 127.0.0.1:6379
    group: gorush
    consumer: gorush
    stream_name: gorush

ios:
  enabled: false
  key_path: "key.pem"
  key_base64: "" # load iOS key from base64 input
  key_type: "pem" # could be pem, p12 or p8 type
  password: "" # certificate password, default as empty string.
  production: false
  max_concurrent_pushes: 100 # just for push ios notification
  max_retry: 0 # resend fail notification, default value zero is disabled
  key_id: "" # KeyID from developer account (Certificates, Identifiers & Profiles -> Keys)
  team_id: "" # TeamID from developer account (View Account -> Membership)

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:
    cluster: false
    addr: "localhost:6379" # if cluster is true, you may set this to "localhost:6379,localhost:6380,localhost:6381"
    password: ""
    db: 0
  boltdb:
    path: "bolt.db"
    bucket: "gorush"
  buntdb:
    path: "bunt.db"
  leveldb:
    path: "level.db"
  badgerdb:
    path: "badger.db"

Memory Usage

Memory average usage: 28Mb (the total bytes of memory obtained from the OS.)

Test Command (We use bat as default cli tool.):

for i in {1..9999999}; do bat -b.N=1000 -b.C=100 POST localhost:8088/api/push notifications:[email protected]; sleep 1;  done

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 -v github.com/appleboy/gorush

On linux

wget https://github.com/appleboy/gorush/releases/download/v1.15.0/gorush-v1.15.0-linux-amd64 -O gorush

On OS X

wget https://github.com/appleboy/gorush/releases/download/v1.15.0/gorush-v1.15.0-darwin-amd64 -O gorush

On Windows

wget https://github.com/appleboy/gorush/releases/download/v1.15.0/gorush-v1.15.0-windows-amd64.exe -O gorush.exe

On macOS, use Homebrew.

brew install --HEAD https://github.com/appleboy/gorush/raw/master/HomebrewFormula/gorush.rb

Install from source

Prerequisite Tools

• Git
• Go (at least Go 1.11)

Fetch from GitHub

Gorush uses the Go Modules support built into Go 1.11 to build. The easiest way to get started is to clone Gorush in a directory outside of the GOPATH, as in the following example:

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/appleboy/gorush.git
cd gorush
go install

or you can use the go get command to install the latest or specific verison.

Note: such go get installation aren't guaranteed to work. We recommend using binary installation.

# Go 1.16+
go install github.com/appleboy/gorush@latest

# Go version < 1.16
go get -u github.com/appleboy/gorush@latest

Command Usage

  ________                              .__
 /  _____/   ____ _______  __ __  ______|  |__
/   \  ___  /  _ \\_  __ \|  |  \/  ___/|  |  \
\    \_\  \(  <_> )|  | \/|  |  /\___ \ |   Y  \
 \______  / \____/ |__|   |____//____  >|___|  /
        \/                           \/      \/

Usage: gorush [options]

Server Options:
    -A, --address <address>          Address to bind (default: any)
    -p, --port <port>                Use port for clients (default: 8088)
    -c, --config <file>              Configuration file path
    -m, --message <message>          Notification message
    -t, --token <token>              Notification token
    -e, --engine <engine>            Storage engine (memory, redis ...)
    --title <title>                  Notification title
    --proxy <proxy>                  Proxy URL (support http, https, or socks5)
    --pid <pid path>                 Process identifier path
    --redis-addr <redis addr>        Redis addr (default: localhost:6379)
iOS Options:
    -i, --key <file>                 certificate key file path
    -P, --password <password>        certificate key password
    --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)
Huawei Options:
    -hk, --hmskey <hms_key>          HMS App Secret
    -hid, --hmsid <hms_id>           HMS App ID
    --huawei                         enabled huawei (default: false)
Common Options:
    --topic <topic>                  iOS or Android topic message
    -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"

Send messages to topics.

gorush --android --topic "/topics/foo-bar" \
  -m "This is a Firebase Cloud Messaging Topic Message" \
  -k your_api_key

• -m: Notification message.
• -k: Firebase Cloud Messaging api key
• -t: Device token.
• --title: Notification title.
• --topic: Send messages to topics. note: don't add device token.
• --proxy: Set http, https or socks5 proxy url.

Send Huawei (HMS) notification

Send single notification with the following command.

gorush -huawei -title "Gorush with HMS" -m "your message" -hk "API Key" -hid "App ID" -t "Device token"

Send messages to topics.

gorush --huawei --topic "foo-bar" \
  -title "Gorush with HMS" \
  -m "This is a Huawei Mobile Services Topic Message" \
  -hk "API Key" \
  -hid "App ID"

• -m: Notification message.
• -hk: Huawei Mobile Services api secret key
• -t: Device token.
• --title: Notification title.
• --topic: Send messages to topics. note: don't add device token.
• --proxy: Set http, https or socks5 proxy url.

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.
• --title: Notification title.
• --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

Send Android or iOS notifications using Firebase

Send single notification with the following command:

gorush -android -m "your message" -k "API key" -t "Device token"

Run gorush web server

Please make sure your config.yml exist. Default port is 8088.

# for default config
$ gorush
# for custom config file
$ gorush -c config.yml

Get go status of api server using httpie tool:

http -v --verify=no --json GET http://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, android or huawei 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.

{
  "version": "v1.6.2",
  "busy_workers": 0,
  "success_tasks": 32,
  "failure_tasks": 49,
  "submitted_tasks": 81,
  "total_count": 81,
  "ios": {
    "push_success": 19,
    "push_error": 38
  },
  "android": {
    "push_success": 10,
    "push_error": 10
  },
  "huawei": {
    "push_success": 3,
    "push_error": 1
  }
}

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,