grace

README

This package is used in conjunction with socketmaster to provide graceful restart.

Genesis

Its not easy to fork and do graceful restarts in golang, the same way they are done in C. There is no equivalent for the fork syscall.

While there are several alternative strategies, such as facebooks grace, they suffer from some limitations. Primary among those is that the new process is not related to the old. This means if you are using a monitor like upstart or monit, they lose the ability to track the process status (unless you use a pid file). This affects ability to restart on crash, but also other things such as logrotation.

Our solution to this is to

• use a C binary named socketmaster. socketmaster binds to the listening socket, with the -listen tcp:// directive.
• socketmaster starts the go program (-command ) and passes the socket to it.
• when the go program exits, socketmaster starts a new instance, and passes the socket to the new program

The grace library makes this transparent. Generally, in your go program, all that you need to do is to import grace, and then use grace.Serve instead of http.Serve

Example

Sample Upstart config with socketmaster

start on (net-device-up
          and local-filesystems
          and runlevel [2345])
stop on runlevel [016]

respawn
respawn limit 5 60

limit nofile 4096 4096

exec socketmaster -command=/usr/bin/goapp -listen tcp://:9000 -- -l /var/log/goapp/goapp.access.log -e /var/log/goapp/goapp.error.log >> /var/log/goapp/goapp.upstart.log

Sample Go app

import (
  "log"
  "net/http"
  grace "github.com/b3bas/grace"
)

func main() {
  // install handlers
  http.Handle("/foo/bar", fooBarHandler)
  log.Fatal(grace.Serve(":9000", nil))
}

Documentation

Overview

grace provides for graceful restart for go http servers. There are 2 parts to graceful restarts 1. Share listening sockets (this is done via socketmaster binary) 2. Close listener gracefully (via graceful)

Index

• func GetListenPort(hport string) string
• func Listen(hport string) (net.Listener, error)
• func Run(addr string, timeout time.Duration, n http.Handler)
• func RunWithErr(addr string, timeout time.Duration, n http.Handler) error
• func Serve(hport string, handler http.Handler) error
• func ServeWithConfig(hport string, config Config, handler http.Handler) error
• func ServerFastHTTP(hport string, handler fasthttp.RequestHandler) error
• type Config

Examples

• Serve

Functions

func GetListenPort

func GetListenPort(hport string) string

GetListenPort applications need some way to access the port TODO: this method will work only after grace.Serve is called.

func Listen

func Listen(hport string) (net.Listener, error)

Listen This method can be used for any TCP Listener, e.g. non HTTP

func Run

func Run(addr string, timeout time.Duration, n http.Handler)

Run exports Run() from grace package

func RunWithErr

func RunWithErr(addr string, timeout time.Duration, n http.Handler) error

RunWithErr exports RunWithErr from grace package

func Serve

func Serve(hport string, handler http.Handler) error

Serve start serving on hport. If running via socketmaster, the hport argument is ignored. Also, if a port was specified via -p, it takes precedence on hport

Example

package main

import (
	"log"
	"net/http"

	grace "github.com/b3bas/grace"
)

func main() {
	http.HandleFunc("/foo/bar", foobarHandler)
	log.Fatal(grace.Serve(":9000", nil))
}

func foobarHandler(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("foobar"))
}

func ServeWithConfig

func ServeWithConfig(hport string, config Config, handler http.Handler) error

ServeWithConfig serve using package config

func ServerFastHTTP

func ServerFastHTTP(hport string, handler fasthttp.RequestHandler) error

ServerFastHTTP use fasthttp server

Types

type Config

type Config struct {
	Timeout          time.Duration
	HTTPReadTimeout  time.Duration
	HTTPWriteTimeout time.Duration
}

Config grace package config