notify

README

Package notify provides simple way to create notify server.

Creating a server is easy as

1. Select and initialize a db driver (see ./model/mysqldrv)
2. Select and initialize few notify drivers (see ./drivers/...)
3. Create a configuration (see SenderOptions)
4. Create a server with SenderOptions, and Register() your drivers
5. Start(), enjoy it

Predefined binaries

There're two predefined binaries here. Both enables httpdrv.* drivers by default. You can enable sendgriddrv.* / tgdrv.* by setting environment variables.

The only difference between notify-api and notify-api-pg is database driver, fore one uses MySQL, the other uses PosgreSQL.

There're automated built Docker images on docker hub. Tag latest is for notify-api and pg for notify-api-pg.

FAQ

This is not well tested.

PR plz.

Is this safe to use in production?

For small scale, yes. I'm using it in production for few months, about few thousands of notifications per day, and few dozens per minute at peak.

Not tested in larger scale.

Can you add xxxx driver?

PR of driver that depends on external service (like mail driver with mailgun) will not be accepted, since I have no chance/spare time to test/maintain. Create your own repo and notify me via issue, I'll add a link in readme.

PR of DB driver is welcome if it can be tested using docker. See ./model/mysqldrv/mysql_test.go for example.

License

MPL version 2.0

Documentation

Overview

Package notify provides simple way to create notify server.

Creating a server is easy as

1. Select and initialize a db driver (see ./model/mysqldrv)
2. Select and initialize few notify driver (see ./drivers/...)
3. Create a configuration (see SenderOptions)
4. Create a server with SenderOptions, and Register() your drivers
5. ListenAndServe(), enjoy it

Index

• func DefaultScheduler(driver, notifyID string, lastExec time.Time, tried uint32) (next time.Time, stop bool)
• type APIServer
  • func NewAPI(opt SenderOptions) (ret APIServer, err error)
• type SenderOptions

Functions

func DefaultScheduler

func DefaultScheduler(driver, notifyID string, lastExec time.Time, tried uint32) (next time.Time, stop bool)

DefaultScheduler retries every minute at first 10 tries, and doubles wait time each time

Types

type APIServer

type APIServer interface {
	// register supported drivers, you *MUST* register all needed drivers
	// before starting server.
	Register(types.Driver)
	// start the api server and bind it to addr. It also starts internal worker
	// to send notification.
	Start() error
	// start the api server and bind it to addr, with basic TLS settings. It
	// also starts internal worker to send notification.
	StartTLS(certFile, keyFile string) error
	// gracefully shutdown the api server and internal worker.
	Shutdown(ctx context.Context) (err error)
	// returns the http.Server so you can customize it. Do not start it by
	// yourself, or internal worker will not start.
	GetHTTPServer() (ret *http.Server)
}

APIServer defines an API server to accept notification-sending requests.

API format

Parameters are passed in JSON format using HTTP POST request. "Content-Type" header is ignored. The result of request is returned in HTTP status code.

API Endpoints

• /send: Send notification and retry automatically if not delivered. See types. Params struct for details of parameters.
• /sendOnce: Send notification, does not retry. See Params struct for details of parameters.
• /resend: Force resend a notification, does not retry. The only accpeted parameter is {"id": string}.
• /result: Retrieve latest sending result. The only accpeted parameter is {"id": string}.
• /status: Retrieve status of a notification, see types.Status for detail. It accepts only one parameter {"id": string}.
• /detail: Retrieve detail of a notification, see types.Detail for detail. It accepts only one parameter {"id": string}.
• /delete: Deletes a notification, does not interrupt if worker is sending it. The only accpeted parameter is {"id": string}.
• /clear: Deletes outdated, finished jobs (status IN(SUCCESS, FAILED)). The only accepted parameter is {"before": unix timestamp}.
• /forceClear: Deletes all outdated jobs The only accepted parameter is {"before": unix timestamp}.

Jobs allocated by a worker will not be deleted by /delete, /clear nor /forceClear.

func NewAPI

func NewAPI(opt SenderOptions) (ret APIServer, err error)

NewAPI creates an APIServer

type SenderOptions

type SenderOptions struct {
	// how many times to retry before considering as FAILED.
	// which means 1 = do not resend.
	// besides, 0 = math.MaxUint32.
	MaxTries uint32
	// user provided scheduler. nil uses DefaultScheduler
	Scheduler types.Scheduler
	// how many goroutines to do the sending job.
	// 0 will be updated to 1 when creating sender.
	MaxThreads uint16
	// db driver, required
	model.DBDrv
}

SenderOptions defines configurations of internal worker