kms

README

##KMS

KMS(Killing Me Softly) is a library that aids in graceful shutdown of a process/application.

Why does this even exist? Aren't there other graceful shutdown librarys?

Sure there are other libraries, but they are focused on handling graceful shutdown a specific portion of code such as graceful shutdown of an http server, but this library allows you to glue together multiple unrelated(or related) services running within the same process/application.

eg.

// start CRON service running tasks..
go startCRON()

// listen for shutdown signal(s), non-blocking
kms.Listen(false)

// serve http site ( using built in http listener)
// this site also has WebSocket functionality
kmshttp.ListenAndServe(":3007", nil)

This library will allow you to gracefully shutdown the http server, any WebSockets and any CRON jobs that may be running using the following:

kms.Wait()
kms.Done()

// chaining is also supported eg. defer kms.Wait().Done()

<-kms.ShutdownInitiated()

and is some cases

<-kms.ShutdownComplete()

Installation

Use go get

go get -u github.com/go-playground/kms

Built In

There are a few built in graceful shutdown helpers using the kms package for TCP, Unix Sockets and HTTP graceful shutdown.

Example

package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/go-playground/kms"
	"github.com/go-playground/kms/kmsnet/kmshttp"
)

var (
	// simple variable to prove the CRON job finishes gracefully.
	complete bool
)

func main() {

	go fakeWebsocketHandler()
	go cronJob()

	kms.Listen(false)

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Home"))
	})

	kmshttp.ListenAndServe(":3007", nil)

	fmt.Println("CRON completed gracefully? ", complete)
}

// crude CRON job examples
func cronJob() {

	// a long running job that fires every x minutes
	for {
		time.Sleep(time.Second * 1)
		kms.Wait()
		complete = false

		// long running DB calls
		time.Sleep(time.Second * 10)

		complete = true
		kms.Done()
	}
}

// faking a single WebSocket, just to show how
func fakeWebsocketHandler() {

	message := make(chan []byte)

FOR:
	for {
		select {
		case <-kms.ShutdownInitiated():
			close(message)
			// close WebSocket connection here
			break FOR
		case b := <-message:
			fmt.Println(string(b))
		}
	}

}

Package Versioning

I'm jumping on the vendoring bandwagon, you should vendor this package as I will not be creating different version with gopkg.in like allot of my other libraries.

Why? because my time is spread pretty thin maintaining all of the libraries I have + LIFE, it is so freeing not to worry about it and will help me keep pouring out bigger and better things for you the community.

I am open versioning with gopkg.in should anyone request it, but this should be stable going forward.

Licenses

• MIT License (MIT), Copyright (c) 2016 Dean Karn

Documentation

Index

• func AllowSignalHardShutdown(allow bool)
• func Done()
• func Listen(block bool)
• func ListenTimeout(block bool, wait time.Duration)
• func SetSignalFn(fn SignalFn)
• func ShutdownComplete() <-chan struct{}
• func ShutdownInitiated() <-chan struct{}
• type KillingMeSoftly
  • func Wait() KillingMeSoftly
• type SignalFn

Functions

func AllowSignalHardShutdown

func AllowSignalHardShutdown(allow bool)

AllowSignalHardShutdown allows you to set whether the application should allow hard shutdown of the application if two signals for shutdown should cause a hard shutdown. eg. user running application from the command line types CTRL + C, the application begins to shut down gracefully, if the user types another CTRL + C should the application shut down hard?

Default: true

func Done

func Done()

Done signifies that your application is done performing an operation. it is different from the chained version as it does not need to be connected the the wait object.

func Listen

func Listen(block bool)

Listen sets up signals to listen for interrupt or kill signals in an attempt to wait for all operations to complete before letting the process die.

func ListenTimeout

func ListenTimeout(block bool, wait time.Duration)

ListenTimeout sets up signals to listen for interrupt or kill signals in an attempt to wait for all operations to complete before letting the process die.

the wait duration is how long to wait before forcefully shutting everything down.

func SetSignalFn

func SetSignalFn(fn SignalFn)

SetSignalFn allows registering of a custom signal function if you wish to listen for different signals, or even your own custom logic not related to signals. By default this function listens for syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP

func ShutdownComplete

func ShutdownComplete() <-chan struct{}

ShutdownComplete returns a notification channel for the package which will be closed/notified once termination is imminent.

func ShutdownInitiated

func ShutdownInitiated() <-chan struct{}

ShutdownInitiated returns a notification channel for the package which will be closed/notified once a termination signal is received.

useful when other code, such as a custom TCP connection listener needs to be notified to stop listening for new connections.

Types

type KillingMeSoftly

type KillingMeSoftly interface {
	Done()
}

KillingMeSoftly interface contains all functions needed for operation and method chaining

func Wait

func Wait() KillingMeSoftly

Wait signifies that your application is busy performing an operation.

best to chain using defer kms.Wait().Done()

type SignalFn

type SignalFn func() <-chan os.Signal

SignalFn is the function type used to signal kms of a shutdown siganl. by default this library listens for syscall.SIGINT, syscall.SIGTERMand syscall.SIGHUP os.Signal's but you can override with whatever signals or logic you wish.