The approach taken here is very similar to what browsers are
doing. A separate pool is created for each host/port/scope.
The authority (host header) is used to determine which pool
will execute requests. A connection process is semi-randomly
chosen, from the connections that have capacity. Maximum
capacity is determined by the protocol (the HTTP/2 setting
set by the server is used, for example). Multiple processes
can process requests/responses on the same connection
concurrently. There is no need to "give back" the response
to the pool, the number of ongoing streams is maintained via
an event handler.
The implementation is currently not strict, there may be
more attempts to create requests than there is capacity.
I'm not sure if it should be made strict or if Gun should
just wait before sending requests (it only matters in the
HTTP/2 case at the moment).
When there is no connection with capacity available in the
pool (because they have too many streams, or are reconnecting,
or any other reason), checking out fails. There is no timeout
to wait for a connection to be available. On the other hand
the checkout_retry option allows setting multiple timeouts
to retry checking out a connection. Each retry attempt's
wait time can have a different value.
The initial implementation of this work was sponsored by
Kobil and made at the suggestion of Ilya Khaprov.