Module socketutil
This module contains miscellaneous helper functions specific to our usage of LuaSocket/LuaSec.
Functions
| set_timeout (block_timeout, total_timeout) | Update the timeout values. |
| reset_timeout () | Reset timeout values to LuaSocket defaults. |
| describe_error (code, block_timeout, total_timeout) | Translate a LuaSocket/LuaSec error code into a human-readable explanation. |
| file_sink (handle, io_err) | Custom version of ltn12.sink.file that honors total_timeout |
Fields
| LARGE_BLOCK_TIMEOUT | Common timeout values Large content |
| TIMEOUT_CODE | Various timeout return codes |
Functions
- set_timeout (block_timeout, total_timeout)
-
Update the timeout values.
Note that this only affects socket polling,
c.f., LuaSocket's timeout_getretry @ src/timeout.c & usage in src/usocket.c
Moreover, the timeout is actually reset between polls (via timeoutmarkstart, e.g. in buffermeth_receive).
So, in practice, this timeout only helps very bad connections (on one end or the other),
and you'd be hard-pressed to ever hit the total timeout, since the starting point is reset extremely often.
In our case, we want to enforce an actual limit on how much time we're willing to block for, start to finish.
We do that via the custom sinks below, which will start ticking as soon as the first chunk of data is received.
To simplify, in most cases, the socket timeout matters before we receive data,
and the sink timeout once we've started receiving data (at which point the socket timeout is reset every chunk).
In practice, that means you don't want to set blocktimeout too low,
as that's what the socket timeout will end up using most of the time.
Note that name resolution happens earlier and one level lower (e.g., glibc),
so name resolution delays will fall outside of these timeouts.
Returns the block & total timeouts now in effect, so callers can report them later (e.g., via describeerror()).
Parameters:
- block_timeout
- total_timeout
- reset_timeout ()
- Reset timeout values to LuaSocket defaults.
- describe_error (code, block_timeout, total_timeout)
-
Translate a LuaSocket/LuaSec error code into a human-readable explanation.
Returns nil for codes it doesn't know about (e.g., HTTP status codes), so callers can fall back to their own text.
Parameters:
- code The error code returned by LuaSocket/LuaSec (e.g., the first return value of http.request)
- block_timeout (required) The block timeout (in seconds) that was in effect for the request.
- total_timeout
(required) The total timeout (in seconds) that was in effect for the request. NOTE: Don't read socketutil.blocktimeout/totaltimeout here: callers usually call reset_timeout()
right after the request, so by the time we get here those hold the defaults, not what was in effect. Use the values returned by set_timeout(). If they're missing anyway, the duration is just omitted.
- file_sink (handle, io_err)
-
Custom version of
ltn12.sink.filethat honors total_timeoutParameters:
- handle
- io_err