Class: Async::HTTP::Client

Inherits:
Protocol::HTTP::Methods
  • Object
show all
Includes:
Proxy::Client
Defined in:
lib/async/http/client.rb

Overview

An HTTP client that manages persistent connections to a specific endpoint, with automatic retries for idempotent requests.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Proxy::Client

#proxied_client, #proxied_endpoint, #proxy

Constructor Details

#initialize(endpoint, protocol: endpoint.protocol, scheme: endpoint.scheme, authority: endpoint.authority, retries: DEFAULT_RETRIES, **options) ⇒ Client

Provides a robust interface to a server.

  • If there are no connections, it will create one.
  • If there are already connections, it will reuse it.
  • If a request fails, it will retry it up to N times if it was idempotent. The client object will never become unusable. It internally manages persistent connections (or non-persistent connections if that's required).

Parameters:

  • endpoint (Endpoint) —

    the endpoint to connnect to.

  • protocol (Protocol::HTTP1 | Protocol::HTTP2 | Protocol::HTTPS) (defaults to: endpoint.protocol) —

    the protocol to use.

  • scheme (String) (defaults to: endpoint.scheme) —

    The default scheme to set to requests.

  • authority (String) (defaults to: endpoint.authority) —

    The default authority to set to requests.



32
33
34
35
36
37
38
39
40
41
 
# File 'lib/async/http/client.rb', line 32

def initialize(endpoint, protocol: endpoint.protocol, scheme: endpoint.scheme, authority: endpoint.authority, retries: DEFAULT_RETRIES, **options)
	@endpoint = endpoint
	@protocol = protocol
	
	@retries = retries
	@pool = make_pool(**options)
	
	@scheme = scheme
	@authority = authority
end

Instance Attribute Details

#authority ⇒ Object (readonly)

Returns the value of attribute authority.



66
67
68
 
# File 'lib/async/http/client.rb', line 66

def authority
  @authority
end

#endpoint ⇒ Object (readonly)

Returns the value of attribute endpoint.



59
60
61
 
# File 'lib/async/http/client.rb', line 59

def endpoint
  @endpoint
end

#pool ⇒ Object (readonly)

Returns the value of attribute pool.



63
64
65
 
# File 'lib/async/http/client.rb', line 63

def pool
  @pool
end

#protocol ⇒ Object (readonly)

Returns the value of attribute protocol.



60
61
62
 
# File 'lib/async/http/client.rb', line 60

def protocol
  @protocol
end

#retries ⇒ Object (readonly)

Returns the value of attribute retries.



62
63
64
 
# File 'lib/async/http/client.rb', line 62

def retries
  @retries
end

#scheme ⇒ Object (readonly)

Returns the value of attribute scheme.



65
66
67
 
# File 'lib/async/http/client.rb', line 65

def scheme
  @scheme
end

Class Method Details

.open(*arguments, **options, &block) ⇒ Object

Open a client and optionally yield it, ensuring it is closed afterwards.



76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/async/http/client.rb', line 76

def self.open(*arguments, **options, &block)
	client = self.new(*arguments, **options)
	
	return client unless block_given?
	
	begin
		yield client
	ensure
		client.close
	end
end

Instance Method Details

#as_json ⇒ Object 



44
45
46
47
48
49
50
51
52
 
# File 'lib/async/http/client.rb', line 44

def as_json(...)
	{
		endpoint: @endpoint.to_s,
			protocol: @protocol,
			retries: @retries,
			scheme: @scheme,
			authority: @authority,
	}
end

#call(request) ⇒ Object

Send a request to the remote server, with automatic retries for idempotent requests.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/async/http/client.rb', line 100

def call(request)
	request.scheme ||= self.scheme
	request.authority ||= self.authority
	
	attempt = 0
	
	# We may retry the request if it is possible to do so. https://tools.ietf.org/html/draft-nottingham-httpbis-retry-01 is a good guide for how retrying requests should work.
	begin
		attempt += 1
		
		# As we cache pool, it's possible these pool go bad (e.g. closed by remote host). In this case, we need to try again. It's up to the caller to impose a timeout on this. If this is the last attempt, we force a new connection.
		connection = @pool.acquire
		
		response = make_response(request, connection, attempt)
		
		# This signals that the ensure block below should not try to release the connection, because it's bound into the response which will be returned:
		connection = nil
		return response
	rescue ::Protocol::HTTP::RefusedError
		# This is a specific case where the request was not processed by the server. So, we can resend even non-idempotent requests.
		if connection
			@pool.release(connection)
			connection = nil
		end
		
		if attempt < @retries and request.rewind!
			retry
		else
			raise
		end
	rescue ::Protocol::HTTP::RemoteError, SocketError, IOError, EOFError, Errno::ECONNRESET, Errno::EPIPE
		if connection
			@pool.release(connection)
			connection = nil
		end
		
		if attempt < @retries and request.retry!
			retry
		else
			raise
		end
	ensure
		if connection
			@pool.release(connection)
		end
	end
end

#close ⇒ Object

Close the client and all associated connections.



89
90
91
92
93
94
95
 
# File 'lib/async/http/client.rb', line 89

def close
	@pool.wait_until_free do
		Console.warn(self){"Waiting for #{@protocol} pool to drain: #{@pool}"}
	end
	
	@pool.close
end

#inspect ⇒ Object 



149
150
151
 
# File 'lib/async/http/client.rb', line 149

def inspect
	"#<#{self.class} authority=#{@authority.inspect}>"
end

#secure? ⇒ Boolean

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/async/http/client.rb', line 69

def secure?
	@endpoint.secure?
end

#to_json ⇒ Object 



55
56
57
 
# File 'lib/async/http/client.rb', line 55

def to_json(...)
	as_json.to_json(...)
end