What exactly does keepalive_timeout work?

[Aahan Krish]

Hi,

I'd like to understand how `keepalive_timeout` works. The description
in the documentation isn't very clear and I couldn't get an answer to
my satisfaction on #nginx IRC.

People seem to have their own understanding of how `keepalive_timeout`
works and they are very different.

1. For e.g. <https://github.com/roots/trellis/blob/master/roles/nginx/templates/nginx.conf.j2>
describes the directive like this:

    # How long to allow each connection to stay idle; longer values are better
    # for each individual client, particularly for SSL, but means that worker
    # connections are tied up longer. (Default: 65)

So according to the statement `keepalive_timeout` is to be used to
tell how long a server needs to keep the connection alive AFTER
serving all the requests.

And this commenter seems to agree:
<http://serverfault.com/q/331762#comment665957_331764>

> [It's] only a timeout during which server waits for another request
> up to [the limit set by] `keepalive_requests`. So it is not important
> how much time it takes for the full page to load [...] BTW the max.
> time connection is kept open is almost:
>
>     keepalive_timeout * keepalive_requests

2. Then there are people understand the function of
`keepalive_timeout` like so: http://stackoverflow.com/a/10202959

> HTTP Keep-Alive is a feature of HTTP protocol. The web-server,
> implementing Keep-Alive Feature, has to check the connection/socket
> periodically (for incoming HTTP request) for the time span since it
> sent the last HTTP response (in case there was corresponding HTTP
> Request). If no HTTP request is received by the time of the configured
> keep-alive time (seconds) the web server closes the connection.

Similar opinion from another: http://serverfault.com/a/331764

> There isn't a good one-size-fits-all answer; if most client browsers
> are able to load all the resources on a page in 5 seconds then 5
> seconds is just fine [...]

So according to these people the directive is to be calculated in such
a way that in that given time (on an average) a web page on your site
and its contents (HTML, CSS, JS, images) are completely loaded on most
clients.

THE QUESTION: So which one is it? (1) or (2)? Who's right?