Callbacks

Note: introduced in 1.2.0.

the :callbacks plugin exposes some session-level callbacks for the most common cases one would like to introspect around:

• connection_opened
• connection_closed
• request_started
• request_body_chunk
• request_completed
• response_started
• response_body_chunk
• response_completed
• request_error

For each of them, a session-level function exists to set up a callback:

HTTPX.plugin(:callbacks).on_connection_opened do |origin, socket|
  puts "connection opened!!"
end.on_request_completed do |request|
  puts "request to #{request.uri} sent"
end.on_response_completed do |request, response|
  puts "request to #{request.uri} finished with code #{response.status}"
end.get("https://example.com")

You can call the same function to establish multiple callbacks to the same event:

HTTPX.plugin(:callbacks).on_response_completed do |request, response|
  # callback 1
end.on_response_completed do |request, response|
  # callback 2
end

connection opened

The :connection_opened event gets called whenever a connection too a given origin is established. This happens after:

• An IP is successfully resolved (or retrieved from the cache) for the given origin;
• A TCP connection has been established;
• (When applicable) a TLS session has been successfully negotiated.

The callback exposes the origin uri and the socket object.

HTTPX.plugin(:callbacks).on_connection_opened do |origin, socket|
  _, port, _, ip = socket.peeraddr
  puts "connection to #{origin} opened (#{ip}:#{port})!!"
end

It’s worth noting that, if there are multiple requests to the same origin, which will share the connection, this callback will be called just once.

connection closed

The :connection_closed event gets called whenever a connection to a given origin is terminated. As with the above, the origin uri and the socket object:

HTTPX.plugin(:callbacks).on_connection_closed do |origin, _|
  puts "connection to #{origin} closed!!"
end

request started

The :request_started event gets called when a request is about to be buffered for sending. At this point, no bytes will have been sent to the origin yet.

It exposes a HTTPX::Request object (you can access attributes, but do not call functions in the callback which may change object state):

HTTPX.plugin(:callbacks).on_request_started do |request|
  puts "request #{request.uri} started!!"
end

request body chunk

The :request_body_chunk event gets called when a request body chunk has been buffered for sending. At this point, the exposed chunk has not been sent to the origin yet!

It exposes a HTTPX::Request object as well as the buffered chunk (a ruby string):

HTTPX.plugin(:callbacks).on_request_body_chunk do |request, chunk|
  puts "request body chunk for #{request.uri} buffered (#{chunk.bytesize} bytes)!!"
end

request completed

The :request_completed event gets called when a request has been considered “sent”, meaning, at this point, its last bits of information are buffered and ready to be sent!

It exposes a HTTPX::Request object:

HTTPX.plugin(:callbacks).on_request_completed do |request|
  puts "request #{request.uri} completed!!"
end

response started

The :response_started event gets called when the a response has been at least partially received, i.e. containing its HTTP headers.

It exposes a HTTPX::Request and its HTTPX::Response object (you can access attributes, but do not call functions in the callback which may change object state):

HTTPX.plugin(:callbacks).on_response_started do |request, response|
  puts "#{request.uri} received a response (status code #{response})!!"
end

Note: This callback is not called for partial response (i.e. 1xx status code). It’s also not called for 3xx redirect responses when using the :follow_redirects plugin.

response body chunk

The :response_body_chunk event gets called when the a response has received a body chunk from the origin server.

It exposes a HTTPX::Request, its HTTPX::Response object, and the received chunk (a ruby string):

HTTPX.plugin(:callbacks).on_response_body_chunk do |request, response, chunk|
  puts "#{request.uri} received a response chunk (#{chunk.bytesize} bytes)!!"
end

response completed

The :response_completed event gets called when the a response has been fully received.

It exposes a HTTPX::Request and its HTTPX::Response object:

HTTPX.plugin(:callbacks).on_response_completed do |request, response|
  puts "#{request.uri} completed (status code #{response}, #{response.body.bytesize} bytes)!!"
end

request error

The :request_error event gets called when an error occurred for a given request.

It exposes a HTTPX::Request and the error object (a ruby exception):

HTTPX.plugin(:callbacks).on_request_error do |request, error|
  puts "#{request.uri} failed (#{error.message})!!"
end

Next: Custom Plugins