1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
graceful [](http://godoc.org/github.com/tylerb/graceful) [](https://travis-ci.org/tylerb/graceful) [](https://coveralls.io/r/tylerb/graceful) [](https://gitter.im/tylerb/graceful?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
========
Graceful is a Go 1.3+ package enabling graceful shutdown of http.Handler servers.
## Using Go 1.8?
If you are using Go 1.8, you may not need to use this library! Consider using `http.Server`'s built-in [Shutdown()](https://golang.org/pkg/net/http/#Server.Shutdown)
method for graceful shutdowns.
## Installation
To install, simply execute:
```
go get gopkg.in/tylerb/graceful.v1
```
I am using [gopkg.in](http://labix.org/gopkg.in) to control releases.
## Usage
Using Graceful is easy. Simply create your http.Handler and pass it to the `Run` function:
```go
package main
import (
"gopkg.in/tylerb/graceful.v1"
"net/http"
"fmt"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
graceful.Run(":3001",10*time.Second,mux)
}
```
Another example, using [Negroni](https://github.com/codegangsta/negroni), functions in much the same manner:
```go
package main
import (
"github.com/codegangsta/negroni"
"gopkg.in/tylerb/graceful.v1"
"net/http"
"fmt"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.Classic()
n.UseHandler(mux)
//n.Run(":3000")
graceful.Run(":3001",10*time.Second,n)
}
```
In addition to Run there are the http.Server counterparts ListenAndServe, ListenAndServeTLS and Serve, which allow you to configure HTTPS, custom timeouts and error handling.
Graceful may also be used by instantiating its Server type directly, which embeds an http.Server:
```go
mux := // ...
srv := &graceful.Server{
Timeout: 10 * time.Second,
Server: &http.Server{
Addr: ":1234",
Handler: mux,
},
}
srv.ListenAndServe()
```
This form allows you to set the ConnState callback, which works in the same way as in http.Server:
```go
mux := // ...
srv := &graceful.Server{
Timeout: 10 * time.Second,
ConnState: func(conn net.Conn, state http.ConnState) {
// conn has a new state
},
Server: &http.Server{
Addr: ":1234",
Handler: mux,
},
}
srv.ListenAndServe()
```
## Behaviour
When Graceful is sent a SIGINT or SIGTERM (possibly from ^C or a kill command), it:
1. Disables keepalive connections.
2. Closes the listening socket, allowing another process to listen on that port immediately.
3. Starts a timer of `timeout` duration to give active requests a chance to finish.
4. When timeout expires, closes all active connections.
5. Closes the `stopChan`, waking up any blocking goroutines.
6. Returns from the function, allowing the server to terminate.
## Notes
If the `timeout` argument to `Run` is 0, the server never times out, allowing all active requests to complete.
If you wish to stop the server in some way other than an OS signal, you may call the `Stop()` function.
This function stops the server, gracefully, using the new timeout value you provide. The `StopChan()` function
returns a channel on which you can block while waiting for the server to stop. This channel will be closed when
the server is stopped, allowing your execution to proceed. Multiple goroutines can block on this channel at the
same time and all will be signalled when stopping is complete.
### Important things to note when setting `timeout` to 0:
If you set the `timeout` to `0`, it waits for all connections to the server to disconnect before shutting down.
This means that even though requests over a connection have finished, it is possible for the client to hold the
connection open and block the server from shutting down indefinitely.
This is especially evident when graceful is used to run HTTP/2 servers. Clients like Chrome and Firefox have been
observed to hold onto the open connection indefinitely over HTTP/2, preventing the server from shutting down. In
addition, there is also the risk of malicious clients holding and keeping the connection alive.
It is understandable that sometimes, you might want to wait for the client indefinitely because they might be
uploading large files. In these type of cases, it is recommended that you set a reasonable timeout to kill the
connection, and have the client perform resumable uploads. For example, the client can divide the file into chunks
and reupload chunks that were in transit when the connection was terminated.
## Contributing
If you would like to contribute, please:
1. Create a GitHub issue regarding the contribution. Features and bugs should be discussed beforehand.
2. Fork the repository.
3. Create a pull request with your solution. This pull request should reference and close the issues (Fix #2).
All pull requests should:
1. Pass [gometalinter -t .](https://github.com/alecthomas/gometalinter) with no warnings.
2. Be `go fmt` formatted.
|
