diamond

README

DIAMOND ⋄

Runlevels for your web application

Diamond provides a UNIX socket for administrators to gracefully shutdown an application, such as a web server.

Apart from only shutting down, the admin can change gears, triggering functions and killing/starting listeners.

The "KICK" feature allows upgrading a program with minimal downtime, kicking the old running process gracefully.

If diamond-admin doesn't run on your platform (bsd?) you can still use the client library!

⚡ telinit 3

Using diamond-admin

You can open admin interface by using no arguments:

diamond-admin -s diamond.sock

Start all listeners and http servers

diamond-admin -s diamond.sock RUNLEVEL 3

Stop all listeners, cut http connections

diamond-admin -s diamond.sock RUNLEVEL 1

Using the library

Diamond requires a recent version of Go

// New creates a new admin socket and starts listening for commands
s, err := diamond.New("/tmp/diamond.socket")
if err != nil {
    log.Fatalln(err)
}

// Add variety of http handlers and their addr to listen on
// They won't start listening right away, so they could be
// occupied by other servers
s.AddHTTPHandler(":8080", http.HandlerFunc(myHandler))
s.AddHTTPHandler(":8081", http.HandlerFunc(handler2))
s.AddHTTPHandler(":8082", handler3)

// start in multiuser mode, serving http
// without calling Runlevel(3) you must
// connect via socket and issue the RUNLEVEL 3 command
s.Runlevel(3) 

// serve forever
log.Fatalln(s.Wait())

See the examples

Read more:

aerth.github.io/diamond

github.com/aerth/diamond

CAUTION

API may change without notice! (it already has two times!)

Contributing

Submit new issue or pull request

Old version

import "gopkg.in/aerth/diamond.v1"

Documentation

Overview

Diamond package provides runlevels to an application

API is considered unstable until further notice

Index

• Constants
• type Server
  • func New(socketpath string, fnPointers ...interface{}) (*Server, error)
  • func (s *Server) AddHTTPHandler(addr string, h http.Handler) int
  • func (s *Server) AddListener(l net.Listener) int
  • func (s Server) Log() *logg.Logger
  • func (s *Server) Runlevel(level int) error
  • func (s *Server) Wait() error

Constants

const (
	SINGLEUSER = 1
	MULTIUSER  = 3
)

Types

type Server

type Server struct {
	HookLevel0 func() []net.Listener
	HookLevel1 func() []net.Listener
	HookLevel2 func() []net.Listener
	HookLevel3 func() []net.Listener
	HookLevel4 func() []net.Listener
	// contains filtered or unexported fields
}

Server ...

func New

func New(socketpath string, fnPointers ...interface{}) (*Server, error)

New creates a new Server, with a socket at socketpath, and starts listening.

Optional ptrs are pointers to types (`new(t)`) that contain methods Each given of given ptrs must satisfy the criteria in the net/rpc package See https://godoc.org/net/rpc for these criteria.

func (*Server) AddHTTPHandler

func (s *Server) AddHTTPHandler(addr string, h http.Handler) int

AddHTTPHandler can restart, returns how many http handlers will be used (for shutdown and restarts)

func (*Server) AddListener

func (s *Server) AddListener(l net.Listener) int

AddListener listeners can only shutdown a port, not restart, returns total number of listeners (for shutdown)

func (Server) Log

func (s Server) Log() *logg.Logger

func (*Server) Runlevel

func (s *Server) Runlevel(level int) error

func (*Server) Wait

func (s *Server) Wait() error

Wait can be called to wait for the program to finish and remove the socket file. It is not necessary to call Wait() if your program catches signals and cleans up the socket file on it's own.