What are the start and stop events for the OkHttp readTimeout?
My initial thoughts, which I now suspect are naive, were that the read timeout clock would:
From the OkHttp docs:
The read timeout is applied to both the TCP socket and for individual read IO operations including on Source of the Response
I gather from this description that readTimeout "is applied" in more than one context:
but this tells me nothing explicitly about the start and stop events for the timeout in each context. Perhaps the writer thought that information was so obvious that it wasn't necessary to state it. However, it's not obvious to me, hence this question.
Googling for an answer finds the web page "A Quick Guide to Timeouts in OkHttp", which presents the following description of readTimeout:
A read timeout is applied from the moment the connection between a client and a target host has been successfully established.
If this is true, then it means that readTimeout also applies to the writing of the request, which occurs after connection. I find this confusing in the context of a timeout for an HTTP client: I would expect such timeouts to align with HTTP-level events.
And:
It defines a maximum time of inactivity between two data packets when waiting for the server's response.
"Packet" as in TCP segment or as in IP packet?
Either way, if this is true, then it means that readTimeout violates the abstraction barrier. I shouldn't need to set an HTTP timeout based on the delay between the arrival of each turtle carrying a bit on its back.
But let's suppose it's true. "inactivity between two data packets"? When waiting for a response from the server, what's the first of those two data packets? Is it, implicitly, the last data packet of the request sent to the server? Or is "response"—bearing in mind the context: an HTTP client—being used here in a different, lower-level sense, not "HTTP response"? I'm left guessing.
Returning to my original question, then: what are the start and stop events for readTimeout?
I have a similar question about writeTimeout that I suppose I could ask in a separate question. When answering, please feel free to cover both readTimeout and writeTimeout.
The start event is an attempt by application code to fetch a single byte from the operating system’s TCP receive buffer. No read timeout can occur without an attempt to read from this buffer.
The end event is 1 or more bytes returned to the application (no timeout) or the timeout duration elapsing (timeout).
For HTTP/1 this capability is implemented by the OS in its TCP stack. When the application code wants to read data (the HTTP response metadata or any bytes of its body), this timeout is configured on the socket.
For HTTP/2 this capability is implemented in OkHttp’s multiplexing code on the response metadata and body.
This timeout is most useful in failing HTTP calls that stall due to application layer or network problems. For example, it can be used to fail if packets aren’t flowing.
I prefer the call timeout feature, which applies to the entire HTTP call.