github.com/wfusion/gofusion@v1.1.14/http/gracefully/README.md (about)

     1  # endless
     2  
     3  Zero downtime restarts for golang HTTP and HTTPS servers. (for golang 1.3+)
     4  
     5  [![GoDoc](https://godoc.org/github.com/fvbock/endless?status.svg)](https://godoc.org/github.com/fvbock/endless)
     6  
     7  ## Inspiration & Credits
     8  
     9  Well... it's what you want right - no need to hook in and out on a loadbalancer or something - just compile, SIGHUP, start new one, finish old requests etc.
    10  
    11  There is https://github.com/rcrowley/goagain and i looked at https://fitstar.github.io/falcore/hot_restart.html which looked easier to do, but still some assembly required. I wanted something that's ideally as simple as
    12  
    13      err := endless.ListenAndServe("localhost:4242", mux)
    14  
    15  I found the excellent post [Graceful Restart in Golang](http://grisha.org/blog/2014/06/03/graceful-restart-in-golang/) by [Grisha Trubetskoy](https://github.com/grisha) and took his code as a start. So a lot of credit to Grisha!
    16  
    17  
    18  ## Features
    19  
    20  - Drop-in replacement for `http.ListenAndServe` and `http.ListenAndServeTLS`
    21  - Signal hooks to execute your own code before or after the listened to signals (SIGHUP, SIGUSR1, SIGUSR2, SIGINT, SIGTERM, SIGTSTP)
    22  - You can start multiple servers from one binary and endless will take care of the different sockets/ports assignments when restarting
    23  
    24  
    25  ## Default Timeouts & MaxHeaderBytes
    26  
    27  There are three variables exported by the package that control the values set for `DefaultReadTimeOut`, `DefaultWriteTimeOut`, and `MaxHeaderBytes` on the inner [`http.Server`](https://golang.org/pkg/net/http/#Server):
    28  
    29  	DefaultReadTimeOut    time.Duration
    30  	DefaultWriteTimeOut   time.Duration
    31  	DefaultMaxHeaderBytes int
    32  
    33  The endless default behaviour is to use the same defaults defined in `net/http`.
    34  
    35  These have impact on endless by potentially not letting the parent process die until all connections are handled/finished.
    36  
    37  
    38  ### Hammer Time
    39  
    40  To deal with hanging requests on the parent after restarting endless will *hammer* the parent 60 seconds after receiving the shutdown signal from the forked child process. When hammered still running requests get terminated. This behaviour can be controlled by another exported variable:
    41  
    42      DefaultHammerTime time.Duration
    43  
    44  The default is 60 seconds. When set to `-1` `hammerTime()` is not invoked automatically. You can then hammer the parent manually by sending `SIGUSR2`. This will only hammer the parent if it is already in shutdown mode. So unless the process had received a `SIGTERM`, `SIGSTOP`, or `SIGINT` (manually or by forking) before `SIGUSR2` will be ignored.
    45  
    46  If you had hanging requests and the server got hammered you will see a log message like this:
    47  
    48      2015/04/04 13:04:10 [STOP - Hammer Time] Forcefully shutting down parent
    49  
    50  
    51  ## Examples & Documentation
    52  
    53      import "github.com/fvbock/endless"
    54  
    55  and then replacing `http.ListenAndServe` with `endless.ListenAndServe` or `http.ListenAndServeTLS` with `endless.ListenAndServeTLS`
    56  
    57  	err := endless.ListenAndServe("localhost:4242", handler)
    58  
    59  After starting your server you can make some changes, build, and send `SIGHUP` to the running process and it will finish handling any outstanding requests and serve all new incoming ones with the new binary.
    60  
    61  More examples are in [here](https://github.com/fvbock/endless/tree/master/examples)
    62  
    63  There is also [GoDoc Documentation](https://godoc.org/github.com/fvbock/endless)
    64  
    65  
    66  ## Signals
    67  
    68  The endless server will listen for the following signals: `syscall.SIGHUP`, `syscall.SIGUSR1`, `syscall.SIGUSR2`, `syscall.SIGINT`, `syscall.SIGTERM`, and `syscall.SIGTSTP`:
    69  
    70  `SIGHUP` will trigger a fork/restart
    71  
    72  `syscall.SIGINT` and `syscall.SIGTERM` will trigger a shutdown of the server (it will finish running requests)
    73  
    74  `SIGUSR2` will trigger [hammerTime](https://github.com/fvbock/endless#hammer-time)
    75  
    76  `SIGUSR1` and `SIGTSTP` are listened for but do not trigger anything in the endless server itself. (probably useless - might get rid of those two)
    77  
    78  You can hook your own functions to be called *pre* or *post* signal handling - eg. pre fork or pre shutdown. More about that in the [hook example](https://github.com/fvbock/endless/tree/master/examples#hooking-into-the-signal-handling).
    79  
    80  
    81  ## Limitation: No changing of ports
    82  
    83  Currently you cannot restart a server on a different port than the previous version was running on.
    84  
    85  ## PID file
    86  
    87  If you want to save actual pid file, you can change the `BeforeBegin` hook like this:
    88  
    89  	server := endless.NewServer("localhost:4242", handler)
    90  	server.BeforeBegin = func(add string) {
    91  		log.Printf("Actual pid is %d", syscall.Getpid())
    92  		// save it somehow
    93  	}
    94  	err := server.ListenAndServe()
    95  
    96  
    97  ## TODOs
    98  
    99  - tests
   100  - documentation
   101  - less ugly wrapping of the tls.listener