Networking and HTTP

# frozen_string_literal: true

require "socket"

# A line-oriented protocol: the client sends an ISBN, the server answers with a title.
TITLES = { "9780596516178" => "The Ruby Programming Language" }.freeze

server = TCPServer.new("127.0.0.1", 0) # port 0: let the operating system pick a free port
port = server.addr[1]
server.addr.first # => "AF_INET"
server.local_address.ip_address # => "127.0.0.1"

acceptor = Thread.new do
  client = server.accept # blocks until a client connects; the GVL is released while waiting
  isbn = client.gets&.chomp
  client.puts TITLES.fetch(isbn, "unknown ISBN")
  client.close
end

TCPSocket.open("127.0.0.1", port) do |socket|
  socket.peeraddr[0] # => "AF_INET"
  socket.puts "9780596516178"
  socket.gets # => "The Ruby Programming Language\n"
end
acceptor.join

# A refused connection is an Errno::ECONNREFUSED (a SystemCallError); the port is closed now.
server.close
begin
  TCPSocket.new("127.0.0.1", port)
rescue SystemCallError => e
  puts "#{e.class}: #{e.message}" # prints Errno::ECONNREFUSED: Connection refused - connect(2) for "127.0.0.1" port ...
end

# Since Ruby 3.2 every IO has a timeout; reading past it raises IO::TimeoutError.
quiet = TCPServer.new("127.0.0.1", 0)
client = TCPSocket.new("127.0.0.1", quiet.addr[1])
peer = quiet.accept # accepted but never written to
client.timeout = 0.2
begin
  client.gets
rescue IO::TimeoutError => e
  puts "#{e.class}: #{e.message}" # prints IO::TimeoutError: Blocking operation timed out!
end
[client, peer, quiet].each(&:close)

Errno::ECONNREFUSED: Connection refused - connect(2) for "127.0.0.1" port PORT
IO::TimeoutError: Blocking operation timed out!

# frozen_string_literal: true

require "socket"
require "resolv"

# Socket.tcp_server_sockets binds every address of the host; "127.0.0.1" keeps it local.
listener = Socket.new(:INET, :STREAM)
listener.bind(Addrinfo.tcp("127.0.0.1", 0))
listener.listen(5)
port = listener.local_address.ip_port

acceptor = Thread.new do
  connection, remote = listener.accept # a Socket and the peer's Addrinfo
  remote.ip_address # => "127.0.0.1"
  connection.write(connection.readpartial(64).upcase)
  connection.close
end

# Socket.tcp with a block connects, yields the Socket and closes it afterwards.
reply = Socket.tcp("127.0.0.1", port, connect_timeout: 1) do |socket|
  socket.write("shelf")
  socket.read
end
puts reply # prints SHELF
acceptor.join

# Happy Eyeballs v2 (Ruby 3.4): Socket.tcp and TCPSocket.new race IPv6 and IPv4 attempts.
Socket.tcp_fast_fallback # => true
Socket.tcp_fast_fallback = false # the same switch as RUBY_TCP_NO_FAST_FALLBACK=1
Socket.tcp_fast_fallback # => false
Socket.tcp_fast_fallback = true

# Ruby 4.0: open_timeout bounds the whole connection phase.
client = TCPSocket.new("127.0.0.1", port, open_timeout: 1, fast_fallback: true) # the listener's backlog accepts it
client.close
listener.close

# Addrinfo describes an endpoint; Resolv resolves names in pure Ruby (hosts file first).
info = Addrinfo.tcp("127.0.0.1", 8080)
info.inspect # => "#<Addrinfo: 127.0.0.1:8080 TCP>"
info.ip_port # => 8080
info.ipv4_loopback? # => true
Resolv.getaddress("localhost").then { |ip| %w[127.0.0.1 ::1].include?(ip) } # => true

# UDP: connectionless datagrams, each recvfrom returns one whole message and the sender.
receiver = UDPSocket.new
receiver.bind("127.0.0.1", 0)
UDPSocket.new.send("ping", 0, "127.0.0.1", receiver.addr[1])
message, = receiver.recvfrom(16)
puts message # prints ping
receiver.close

# UNIXSocket.pair gives two connected local sockets without touching the network.
left, right = UNIXSocket.pair
left.write("ready")
right.readpartial(16) # => "ready"
[left, right].each(&:close)

# The error classes: name resolution failures are Socket::ResolutionError (3.3), a SocketError.
Socket::ResolutionError.ancestors.take(3) # => [Socket::ResolutionError, SocketError, StandardError]

SHELF
ping

# frozen_string_literal: true

require "socket"
require_relative "shelf_server"

# HTTP/1.1 is text over TCP. This is roughly what Net::HTTP does underneath.
ShelfServer.run do |server|
  TCPSocket.open("127.0.0.1", server.port) do |socket|
    socket.write("GET /books/9780596516178 HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n")
    status = socket.gets("\r\n").chomp
    puts status # prints HTTP/1.1 200 OK

    headers = {}
    while (line = socket.gets("\r\n")) && line != "\r\n"
      name, value = line.chomp.split(": ", 2)
      headers[name.downcase] = value
    end
    p headers # prints {"content-type" => "application/json", "content-length" => "86"}
    socket.read(headers["content-length"].to_i).bytesize # => 86
  end
end

HTTP/1.1 200 OK
{"content-type" => "application/json", "content-length" => "86"}

# frozen_string_literal: true

require "uri"

def message_of
  yield
rescue URI::Error => e
  "#{e.class}: #{e.message}"
end

# Unescaped spaces, nil and non-ASCII characters are invalid; the message names the input.
message_of { URI("http://shelf.example.com/my books") }
# => "URI::InvalidURIError: bad URI (is not URI?): \"http://shelf.example.com/my books\""
message_of { URI.parse(nil) } # => "URI::InvalidURIError: bad URI (is not URI?): nil"
message_of { URI("http://café.example/") }
# => "URI::InvalidURIError: URI must be ascii only \"http://caf\\u00E9.example/\""

# Percent-encode the parts you control instead of the whole string.
path = "/my books/#{URI.encode_uri_component('Ruby & Rails')}"
URI::HTTP.build(host: "shelf.example.com", path: path.gsub(" ", "%20")).to_s
# => "http://shelf.example.com/my%20books/Ruby%20%26%20Rails"

# A relative reference parses, but as URI::Generic: it has no host, so it cannot be fetched.
relative = URI("/books/1")
relative.class # => URI::Generic
relative.host # => nil
relative.absolute? # => false
relative.relative? # => true
URI("shelf.example.com/books").scheme # => nil
URI("shelf.example.com:8080/books").scheme # => "shelf.example.com"

# The scheme decides the class; unknown schemes are plain URI::Generic.
URI("urn:isbn:9780596516178").class # => URI::Generic
URI("urn:isbn:9780596516178").opaque # => "isbn:9780596516178"
URI("mailto:reader@example.com").class # => URI::MailTo
URI("file:///var/shelf/books.csv").class # => URI::File
URI("ws://shelf.example.com/cable").class # => URI::WS
URI.scheme_list.keys.sort # => ["FILE", "FTP", "HTTP", "HTTPS", "LDAP", "LDAPS", "MAILTO", "WS", "WSS"]

# Host names are not normalised until you ask, and HTTP-looking classes do not validate ports.
URI("HTTP://Shelf.Example.COM/").host # => "Shelf.Example.COM"
URI("HTTP://Shelf.Example.COM/").normalize.host # => "shelf.example.com"
URI("http://shelf.example.com:99999/").port # => 99999

# Required components are checked when you build or assign: a path must start with a slash.
message_of { URI::HTTP.build(host: "shelf.example.com", path: "books") }
# => "URI::InvalidComponentError: bad component(expected absolute path component): books"

# Ruby 3.4 switched the default parser from RFC 2396 to RFC 3986. The old one is still there.
URI::DEFAULT_PARSER.class # => URI::RFC3986_Parser
URI::RFC2396_PARSER.class # => URI::RFC2396_Parser
URI::RFC2396_PARSER.extract("see http://a.example and https://b.example/x")
# => ["http://a.example", "https://b.example/x"]

# frozen_string_literal: true

require "net/http"
require "json"
require_relative "shelf_server"

ShelfServer.run do |server|
  uri = URI("#{server.base_url}/books")

  # Net::HTTP.get returns the body as a String; get_response returns the response object.
  body = Net::HTTP.get(uri)
  JSON.parse(body).map { |book| book["title"] }
  # => ["The Ruby Programming Language", "Refactoring Shelves"]

  # The same request with the host, path and port as separate arguments.
  Net::HTTP.get("127.0.0.1", "/books/9780596516178", server.port).size # => 86

  response = Net::HTTP.get_response(uri)
  response.class # => Net::HTTPOK
  response.code # => "200"
  response.message # => "OK"
  response.content_type # => "application/json"
  response["Content-Length"] # => "167"
  response.is_a?(Net::HTTPSuccess) # => true
  response.to_hash.keys.sort # => ["content-length", "content-type"]

  # A 404 is not an exception: it is a response whose class is Net::HTTPNotFound.
  missing = Net::HTTP.get_response(URI("#{server.base_url}/books/9780000000002"))
  missing.class.ancestors.take(3) # => [Net::HTTPNotFound, Net::HTTPClientError, Net::HTTPResponse]
  missing.code # => "404"

  # Response#value (alias error!) turns every non-2xx response into an exception.
  begin
    missing.value
  rescue Net::HTTPClientException => e
    puts "#{e.class}: #{e.message}" # prints Net::HTTPClientException: 404 "Not Found"
    e.response.equal?(missing) # => true
  end

  # Redirects are not followed; a 3xx is a Net::HTTPRedirection with a Location header.
  moved = Net::HTTP.get_response(URI("#{server.base_url}/old"))
  moved.class # => Net::HTTPMovedPermanently
  moved["Location"] # => "/books"
  moved.is_a?(Net::HTTPRedirection) # => true
end

Net::HTTPClientException: 404 "Not Found"

# frozen_string_literal: true

require "net/http"
require "json"
require_relative "shelf_server"

# Net::HTTP.start opens the connection, yields the session and closes it afterwards.
# Several requests inside the block share one persistent (keep-alive) connection.
ShelfServer.run do |server|
  Net::HTTP.start("127.0.0.1", server.port, read_timeout: 5) do |http|
    http.started? # => true
    http.get("/books").code # => "200"
    http.get("/books/9780596516178", { "Accept" => "application/json" }).code # => "200"
    http.head("/books")["Content-Type"] # => "application/json"
  end
  server.connections # => 1

  # Without start, every one-shot call such as Net::HTTP.get connects again.
  2.times { Net::HTTP.get(URI("#{server.base_url}/books")) }
  server.connections # => 3
end

# A request object gives full control over method, headers and body.
ShelfServer.run do |server|
  uri = URI("#{server.base_url}/books")
  request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json", "Accept" => "application/json")
  request.body = JSON.generate({ isbn: "9780134757599", title: "Refactoring", author: "Ada Reader" })
  response = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(request) }
  response.code # => "201"
  JSON.parse(response.body).values_at("title", "received_type")
  # => ["Refactoring", "application/json"]

  # Ruby 4.0 (net-http 0.9): no default Content-Type for a request that has a body.
  bare = Net::HTTP::Post.new(uri)
  bare.body = JSON.generate({ title: "Anonymous" })
  bare["Content-Type"] # => nil
  response = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(bare) }
  JSON.parse(response.body)["received_type"] # => nil
end

# Forms: set_form_data and Net::HTTP.post_form use application/x-www-form-urlencoded.
form = Net::HTTP::Post.new("/loans")
form.set_form_data("isbn" => "9780596516178", "member" => "Grace Stacks")
form["Content-Type"] # => "application/x-www-form-urlencoded"
form.body # => "isbn=9780596516178&member=Grace+Stacks"

# Header helpers on the request: [] is case-insensitive, basic_auth builds Authorization.
probe = Net::HTTP::Get.new("/books")
probe["Accept-Language"] = "en"
probe["accept-language"] # => "en"
probe.basic_auth("reader", "placeholder-password")
probe["Authorization"] # => "Basic cmVhZGVyOnBsYWNlaG9sZGVyLXBhc3N3b3Jk"
probe.key?("x-missing") # => false
probe.method # => "GET"
probe.path # => "/books"
probe.request_body_permitted? # => false

# frozen_string_literal: true

require "net/http"
require_relative "shelf_server"

# The defaults of a fresh session: 60 s for opening, reading and writing, no TLS, one retry.
http = Net::HTTP.new("127.0.0.1", 80)
http.open_timeout # => 60
http.read_timeout # => 60
http.write_timeout # => 60
http.keep_alive_timeout # => 2
http.max_retries # => 1
http.use_ssl? # => false

ShelfServer.run do |server|
  # read_timeout bounds each wait for data, not the whole response. The /slow route sleeps 2 s.
  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  begin
    Net::HTTP.start("127.0.0.1", server.port, read_timeout: 0.3) { |session| session.get("/slow") }
  rescue Net::ReadTimeout => e
    puts "#{e.class}: #{e.message}" # prints Net::ReadTimeout: Net::ReadTimeout with #<TCPSocket:(closed)>
  end
  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
  elapsed.between?(0.6, 1.2) # => true (two attempts of 0.3 s: GET is idempotent and retried once)
  server.connections # => 2
end

# max_retries applies to idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, TRACE) when the
# connection fails in a retryable way: a dropped connection (EOFError), a reset, a timeout.
ShelfServer.run do |server|
  [0, 1, 3].each do |retries|
    before = server.connections
    begin
      Net::HTTP.start("127.0.0.1", server.port, max_retries: retries) { |session| session.get("/drop") }
    rescue EOFError => e
      puts "max_retries #{retries}: #{e.message}, #{server.connections - before} connection(s)"
    end
  end
end

Net::ReadTimeout: Net::ReadTimeout with #<TCPSocket:(closed)>
max_retries 0: end of file reached, 1 connection(s)
max_retries 1: end of file reached, 2 connection(s)
max_retries 3: end of file reached, 4 connection(s)

# frozen_string_literal: true

require "net/http"
require "json"
require_relative "shelf_server"

# Net::HTTP never follows redirects by itself. This follows a bounded number of them, resolves
# a relative Location against the current URI and refuses to leave https for plain http.
def get_following(uri, limit: 5)
  raise ArgumentError, "too many redirects" if limit.zero?

  response = Net::HTTP.get_response(uri)
  return response unless response.is_a?(Net::HTTPRedirection)

  target = uri.merge(response.fetch("Location")) # Location may be relative
  raise SecurityError, "refusing https to http downgrade" if uri.scheme == "https" && target.scheme == "http"

  get_following(target, limit: limit - 1)
end

ShelfServer.run do |server|
  response = get_following(URI("#{server.base_url}/old"))
  response.code # => "200"
  response.uri.path # => "/books" (the final request URI)
  JSON.parse(response.body).size # => 2
end

# frozen_string_literal: true

require "net/http"
require_relative "shelf_server"

# Proxies: Net::HTTP reads http_proxy / https_proxy / no_proxy (lowercase) when you build a session
# from a host name. The proxy only matters on connect, so nothing is sent here.
ENV["http_proxy"] = "http://proxy.invalid:3128"
ENV["no_proxy"] = "localhost,127.0.0.1"
Net::HTTP.new("127.0.0.1", 8080).proxy? # => false
Net::HTTP.new("shelf.example.com", 80).proxy? # => true
Net::HTTP.new("shelf.example.com", 80).proxy_address # => "proxy.invalid"
Net::HTTP.new("shelf.example.com", 80, nil).proxy? # => false (nil as proxy address: never use one)
Net::HTTP.new("shelf.example.com", 80, "other.invalid", 8888).proxy_port # => 8888
ENV.delete("http_proxy")
ENV.delete("no_proxy")

# Encodings: the body is bytes. Without a charset the String comes back as ASCII-8BIT (BINARY).
accents = ->(_request) { [200, { "Content-Type" => "text/plain; charset=iso-8859-1" }, "café".encode("ISO-8859-1")] }
ShelfServer.run(handler: accents) do |server|
  Net::HTTP.start("127.0.0.1", server.port) do |http|
    raw = http.get("/").body
    raw.encoding # => #<Encoding:BINARY (ASCII-8BIT)>
    raw.bytes # => [99, 97, 102, 233]
    raw.force_encoding("ISO-8859-1").encode("UTF-8") # => "café"

    http.response_body_encoding = true # take the charset parameter of Content-Type
    http.get("/").body.encoding # => #<Encoding:ISO-8859-1>
  end
end

# frozen_string_literal: true

require "net/http"
require_relative "shelf_server"

# set_debug_output logs the wire traffic to any object that responds to <<. Call it before
# starting the session, and never log it in production: it includes Authorization headers and bodies.
ShelfServer.run do |server|
  wire = +""
  http = Net::HTTP.new("127.0.0.1", server.port)
  http.set_debug_output(wire)
  http.start { http.get("/books/9780596516178", "Accept" => "application/json") }
  puts wire.lines.grep(/\A(<-|->)/).map { |line| line.gsub(":#{server.port}", ":PORT") }.first(7)
end

<- "GET /books/9780596516178 HTTP/1.1\r\nAccept: application/json\r\nAccept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3\r\nUser-Agent: Ruby\r\nHost: 127.0.0.1:PORT\r\n\r\n"
-> "HTTP/1.1 200 OK\r\n"
-> "Content-Type: application/json\r\n"
-> "Content-Length: 86\r\n"
-> "\r\n"
-> "{\"isbn\":\"9780596516178\",\"title\":\"The Ruby Programming Language\",\"author\":\"Ada Reader\"}"

# frozen_string_literal: true

require "net/http"
require "openssl"
require "socket"

# A throw-away certificate authority-less setup: one self-signed certificate for 127.0.0.1,
# generated in memory (nothing is written to disk and there is nothing secret in it).
key = OpenSSL::PKey::EC.generate("prime256v1")
cert = OpenSSL::X509::Certificate.new
cert.version = 2
cert.serial = 1
cert.subject = cert.issuer = OpenSSL::X509::Name.parse("/CN=shelf-localhost")
cert.public_key = key
cert.not_before = Time.now - 60
cert.not_after = Time.now + 3600
factory = OpenSSL::X509::ExtensionFactory.new(cert, cert)
cert.add_extension(factory.create_extension("subjectAltName", "IP:127.0.0.1"))
cert.add_extension(factory.create_extension("basicConstraints", "CA:TRUE", true))
cert.sign(key, OpenSSL::Digest.new("SHA256"))

# An HTTPS server in a few lines: SSLServer wraps a TCPServer and does the handshake in accept.
context = OpenSSL::SSL::SSLContext.new
context.add_certificate(cert, key)
tcp = TCPServer.new("127.0.0.1", 0)
tls = OpenSSL::SSL::SSLServer.new(tcp, context)
tls.start_immediately = true
acceptor = Thread.new do
  loop do
    socket = tls.accept
    socket.gets("\r\n\r\n")
    socket.write("HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok")
    socket.close
  rescue OpenSSL::SSL::SSLError, SystemCallError
    next # a client that rejected our certificate hangs up during the handshake
  end
end
port = tcp.addr[1]

# 1. use_ssl turns on TLS, and verification is on by default (VERIFY_PEER) with the system trust store.
untrusting = Net::HTTP.new("127.0.0.1", port)
untrusting.use_ssl = true
untrusting.verify_mode # => nil (VERIFY_PEER is applied when the connection is made)
begin
  untrusting.get("/")
rescue OpenSSL::SSL::SSLError => e
  # The full message starts with SSL_connect returned=1 errno=0 peeraddr=127.0.0.1:PORT state=error.
  puts e.message.split(": ").last # prints certificate verify failed (self-signed certificate)
end

# 2. Trust exactly this certificate through a cert_store (or ca_file with a PEM path).
store = OpenSSL::X509::Store.new
store.add_cert(cert)
trusting = Net::HTTP.new("127.0.0.1", port)
trusting.use_ssl = true
trusting.cert_store = store
trusting.get("/").body # => "ok"
trusting.min_version = OpenSSL::SSL::TLS1_2_VERSION
trusting.max_version = OpenSSL::SSL::TLS1_3_VERSION

# 3. Net::HTTP.start with use_ssl: true does the same in one call; https URIs set it for you.
Net::HTTP.start("127.0.0.1", port, use_ssl: true, cert_store: store) { |http| http.get("/").body } # => "ok"
URI("https://127.0.0.1:#{port}/").scheme # => "https"

# VERIFY_NONE accepts any certificate, including an attacker's: only ever a local experiment.
Net::HTTP.start("127.0.0.1", port, use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_NONE) do |http|
  http.get("/").body # => "ok"
end
acceptor.kill
acceptor.join
tcp.close

certificate verify failed (self-signed certificate)

# frozen_string_literal: true

require "net/http"
require "open-uri"
require "openssl"
require "socket"
require_relative "shelf_server"

# The superclass chains of the errors a network call can raise (modules left out).
[
  Net::OpenTimeout, Net::HTTPBadResponse, Net::HTTPClientException, Net::HTTPFatalError, Net::HTTPError,
  Errno::ECONNREFUSED, EOFError, IO::TimeoutError, Socket::ResolutionError, OpenSSL::SSL::SSLError,
  OpenURI::HTTPError, URI::InvalidURIError
].each do |klass|
  chain = klass.ancestors.take_while { |ancestor| ancestor != StandardError }.reject { |a| a.instance_of?(Module) }
  puts chain.join(" < ")
end

# Net::HTTPExceptions (a module) is what the status-code errors share. Net::HTTPError is a
# different class that only 1xx and unknown statuses raise, so rescuing it misses a 404.
Net::HTTPClientException.include?(Net::HTTPExceptions) # => true
Net::HTTPClientException.ancestors.include?(Net::HTTPError) # => false

ShelfServer.run do |server|
  response = Net::HTTP.get_response(URI("#{server.base_url}/boom"))
  begin
    response.value
  rescue Net::HTTPError
    puts "never reached"
  rescue Net::HTTPExceptions => e
    puts "#{e.class}: #{e.message}" # prints Net::HTTPFatalError: 500 "Internal Server Error"
    e.response.code # => "500"
  end
end

Net::OpenTimeout < Timeout::Error < RuntimeError
Net::HTTPBadResponse
Net::HTTPClientException < Net::ProtoServerError < Net::ProtocolError
Net::HTTPFatalError < Net::ProtoFatalError < Net::ProtocolError
Net::HTTPError < Net::ProtocolError
Errno::ECONNREFUSED < SystemCallError
EOFError < IOError
IO::TimeoutError < IOError
Socket::ResolutionError < SocketError
OpenSSL::SSL::SSLError < OpenSSL::OpenSSLError
OpenURI::HTTPError
URI::InvalidURIError < URI::Error
Net::HTTPFatalError: 500 "Internal Server Error"

# frozen_string_literal: true

require "net/http"
require "openssl"
require "json"

module Shelf
  class RemoteError < StandardError; end

  # The request never produced a usable HTTP response (DNS, TCP, TLS, timeout, broken reply).
  class NetworkError < RemoteError; end

  # The server answered with 4xx or 5xx.
  class HttpError < RemoteError
    attr_reader :status

    def initialize(status, message = "HTTP #{status}")
      super(message)
      @status = status
    end
  end

  class RemoteCatalog
    # Everything that can go wrong below the HTTP status line. Order does not matter for
    # rescue lists, but every entry must be here: Net::HTTPError is NOT one of them.
    NETWORK_ERRORS = [
      SocketError, SystemCallError, IOError, # Errno::ECONNREFUSED/ECONNRESET/EPIPE, EOFError, IO::TimeoutError
      Timeout::Error,                        # Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
      OpenSSL::SSL::SSLError,
      Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError
    ].freeze

    def initialize(base_url, attempts: 3, pause: 0.05)
      @base = URI(base_url)
      @attempts = attempts
      @pause = pause
    end

    def books = JSON.parse(get("/books"))

    def book(isbn) = JSON.parse(get("/books/#{isbn}"))

    def get(path)
      tries = 0
      begin
        tries += 1
        request(path)
      rescue NetworkError, HttpError => e
        raise unless retryable?(e) && tries < @attempts

        sleep(@pause * tries) # linear back-off; add jitter when many clients retry together
        retry
      end
    end

    private

    def retryable?(error) = error.is_a?(NetworkError) || error.status >= 500

    def request(path)
      response = Net::HTTP.start(@base.host, @base.port, open_timeout: 1, read_timeout: 1) do |http|
        http.get(path)
      end
      return response.body if response.is_a?(Net::HTTPSuccess)

      raise HttpError.new(response.code.to_i, "#{response.code} #{response.message}")
    rescue *NETWORK_ERRORS => e
      raise NetworkError, "#{e.class}: #{e.message}"
    end
  end
end

# frozen_string_literal: true

require_relative "remote_catalog"
require_relative "shelf_server"

def attempt
  yield
rescue Shelf::RemoteError => e
  cause = e.cause ? " (cause: #{e.cause.class})" : ""
  puts "#{e.class}: #{e.message}#{cause}"
end

ShelfServer.run do |server|
  catalog = Shelf::RemoteCatalog.new(server.base_url)
  catalog.books.map { |book| book["title"] } # => ["The Ruby Programming Language", "Refactoring Shelves"]
  catalog.book("9780596516178")["author"] # => "Ada Reader"

  attempt { catalog.book("9780000000002") } # a 404 is final: only 5xx and transport errors are retried
  attempt { catalog.get("/boom") }
  attempt { catalog.get("/drop") }
  server.connections # => 12 (1 + 1 + 1 for the 404, 3 for /boom, 3 attempts x 2 for /drop)
end

# Nothing listens on this port any more: the failure is a NetworkError wrapping Errno::ECONNREFUSED.
closed_port = ShelfServer.run(&:port)
attempt { Shelf::RemoteCatalog.new("http://127.0.0.1:#{closed_port}").books }

Shelf::HttpError: 404 Not Found
Shelf::HttpError: 500 Internal Server Error
Shelf::NetworkError: EOFError: end of file reached (cause: EOFError)
Shelf::NetworkError: Errno::ECONNREFUSED: Failed to open TCP connection to 127.0.0.1:PORT (Connection refused - connect(2) for "127.0.0.1" port PORT) (cause: Errno::ECONNREFUSED)