|
Seastar
High performance C++ framework for concurrent servers
|
Class client wraps communications using HTTP protocol.
The class allows making HTTP requests and handling replies. It's up to the caller to provide a transport, though for simple cases the class provides out-of-the-box facilities.
The main benefit client provides against connection is the transparent support for Keep-Alive transport sockets.
#include <seastar/http/client.hh>
Public Types | |
| using | reply_handler = noncopyable_function< future<>(const reply &, input_stream< char > &&body)> |
| using | retry_requests = bool_class< struct retry_requests_tag > |
Public Member Functions | |
| client (socket_address addr) | |
| Construct a simple client. More... | |
| client (socket_address addr, shared_ptr< tls::certificate_credentials > creds, sstring host={}) | |
| Construct a secure client. More... | |
| client (std::unique_ptr< connection_factory > f, unsigned max_connections=default_max_connections, retry_requests retry=retry_requests::no) | |
| Construct a client with connection factory. More... | |
| future | make_request (request &&req, reply_handler &&handle, std::optional< reply::status_type > &&expected=std::nullopt, abort_source *as=nullptr) |
| Send the request and handle the response. More... | |
| future | make_request (request &req, reply_handler &handle, std::optional< reply::status_type > expected=std::nullopt, abort_source *as=nullptr) |
| Send the request and handle the response (abortable), same as make_request() More... | |
| future | set_maximum_connections (unsigned nr) |
| Updates the maximum number of connections a client may have. More... | |
| future | close () |
| Closes the client. More... | |
| unsigned | connections_nr () const noexcept |
| Returns the total number of connections. | |
| unsigned | idle_connections_nr () const noexcept |
| Returns the number of idle connections. | |
| unsigned long | total_new_connections_nr () const noexcept |
| Returns the total number of connection factory invocations made so far. More... | |
|
explicit |
Construct a simple client.
This creates a simple client that connects to provided address via plain (non-TLS) socket
| addr | – host address to connect to |
| seastar::http::experimental::client::client | ( | socket_address | addr, |
| shared_ptr< tls::certificate_credentials > | creds, | ||
| sstring | host = {} |
||
| ) |
Construct a secure client.
This creates a client that connects to provided address via TLS socket with given credentials. In simple words – this makes an HTTPS client
| addr | – host address to connect to |
| creds | – credentials |
| host | – optional host name |
|
explicit |
Construct a client with connection factory.
This creates a client that uses factory to get connected_socket that is then used as transport. The client may withdraw more than one socket from the factory and may re-use the sockets on its own
| f | – the factory pointer |
| max_connections | – maximum number of connection a client is allowed to maintain (both active and cached in pool) |
| retry | – whether or not to retry requests on connection IO errors |
The client uses connections provided by factory to send requests over and receive responses back. Once request-response cycle is over the connection used for that is kept by a client in a "pool". Making another http request may then pick up the existing connection from the pool thus avoiding the extra latency of establishing new connection. Pool may thus accumulate more than one connection if user sends several requests in parallel.
HTTP servers may sometimes want to terminate the connections it keeps. This can happen in one of several ways.
The "gentle" way is when server adds the "connection: close" header to its response. In that case client would handle the response and will just close the connection without putting it to pool.
Less gentle way a server may terminate a connection is by closing it, so the underlying TCP stack would communicate regular TCP FIN-s. If the connection happens to be in pool when it happens the client would just clean the connection from pool in the background.
Sometimes the least gentle closing occurs when server closes the connection on the fly and TCP starts communicating FIN-s in parallel with client using it. In that case, user would receive exception from the make_request() call and will have to do something about it. Client provides a transparent way of handling it called "retry".
When enabled, it makes client catch the transport error, close the broken connection, open another one and retry the very same request one more time over this new connection. If the second attempt fails, this error is reported back to user.
| future seastar::http::experimental::client::close | ( | ) |
Closes the client.
Client must be closed before destruction unconditionally
| future seastar::http::experimental::client::make_request | ( | request && | req, |
| reply_handler && | handle, | ||
| std::optional< reply::status_type > && | expected = std::nullopt, |
||
| abort_source * | as = nullptr |
||
| ) |
Send the request and handle the response.
Sends the provided request to the server and calls the provided callback to handle the response when it arrives. If the expected status is specified and the response's status is not the expected one, the handler is not called and the method resolves with exceptional future. Otherwise returns the handler's future
| req | – request to be sent |
| handle | – the response handler |
| expected | – the optional expected reply status code, default is std::nullopt |
| as | – abort source that aborts the request |
Note that the handle callback should be prepared to be called more than once, because client may restart the whole request processing in case server closes the connection in the middle of operation
| future seastar::http::experimental::client::make_request | ( | request & | req, |
| reply_handler & | handle, | ||
| std::optional< reply::status_type > | expected = std::nullopt, |
||
| abort_source * | as = nullptr |
||
| ) |
Send the request and handle the response (abortable), same as make_request()
request and thehandle`, it caller's responsibility the make sure they are referencing valid instances | future seastar::http::experimental::client::set_maximum_connections | ( | unsigned | nr | ) |
Updates the maximum number of connections a client may have.
If the new limit is less than the amount of connections a client has, they will be closed. The returned future resolves when all excessive connections get closed
| nr | – the new limit on the number of connections |
|
inlinenoexcept |
Returns the total number of connection factory invocations made so far.
This is the monotonically-increasing counter describing how "frequently" the client kicks its factory for new connections.
1.9.4