net/http: the comment of Server.IdleTimeout doesn't describe its behavior correctly

[spacewander]

What version of Go are you using (go version)?

$ go version
go version go1.12.5 linux/amd64

Does this issue reproduce with the latest release?

Yes.

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/lzx/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/lzx/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/go"
GOTMPDIR=""
GOTOOLDIR="/usr/local/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="/usr/bin/gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build730423934=/tmp/go-build -gno-record-gcc-switches"

What did you see instead?

The comment of IdleTimeout says:

If IdleTimeout is zero, the value of ReadTimeout is used. If both are zero, ReadHeaderTimeout is used.

https://github.com/golang/go/blob/master/src/net/http/server.go#L2524

However, after reading:
https://github.com/golang/go/blob/master/src/net/http/server.go#L3008
https://github.com/golang/go/blob/master/src/net/http/server.go#L1913

It seems that IdleTimeout doesn't take account of ReadHeaderTimeout. Maybe I have missed something?

[bradfitz]

Thanks. That does look like a mistake.

[jamdagni86]

@bradfitz can I send a CL for this?

[bradfitz]

@jamdagni86, sure? But I haven't looked at it yet. It might be a code change or a doc fix. I don't know. So you should investigate and your commit message should explain.

[jamdagni86]

@bradfitz the current documentation is slightly incorrect. The earlier comment was

IdleTimeout is the maximum amount of time to wait for the
next request when keep-alives are enabled. If IdleTimeout
is zero, the value of ReadTimeout is used. If both are
zero, there is no timeout.

This got changed to the current version in this CL as a fix for this.

The correct sequence is this. At the end of the current request, it sets deadline for IdleTimeout or ReadTimeout, whichever is non zero. At the beginning of the next request, it sets deadline for ReadHeaderTimeout or ReadTimeout, whichever is non zero. The missing piece in the documentation is the last part where ReadTimeout is considered yet again.

In case IdleTimeout and ReadHeaderTimeout are both zeros and ReadTimeout is non zero, it sets up two timeouts with ReadTimeout duration and if none of the former two are zeros, it would end up setting two timeouts - IdleTimeout & ReadHeaderTimeout.

I'm not sure if this was the intended behaviour. And assuming that the code is working as intended, I guess it is enough if we revert the IdleTimeout documentation to the previous version and add a line in the ReadHeaderTimeout to mention that it falls back to ReadTimeout in case the former is zero.

Please let me know if this sounds good; I will send a CL.

[gopherbot]

Change https://golang.org/cl/178337 mentions this issue: net/http: the comment of Server.IdleTimeout doesn't describe its behavior correctly