philiprehberger-http_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d11769686f37911e9a4273468d8ae3d525162853eef921c26fa1f73b73e23a93
+  data.tar.gz: 0f290ad715f1ed058381676b87e142c7c239fb8aefcd4c4b3e5bb833391017f7
+SHA512:
+  metadata.gz: ce4fe073d9cc426661e965f6c1c95e613265a82db24eebc20d82624107b511e6d9f07fd630e8740666895ce6ce6b3b573bc719b19dfccf56ed8163a058bbf4a5
+  data.tar.gz: 87f238755a902ff293774f7328697caf14b76f119545f7c1aa41525dadc7fd1753690d12c05d18d55836cec60a08e7f4f1a28fb76667ca824c55d429b675bc61

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-10
+
+### Added
+
+- Initial release
+- HTTP methods: GET, POST, PUT, PATCH, DELETE
+- Automatic retries on network errors with configurable delay
+- Request/response interceptors via `use` block
+- JSON request and response helpers
+- Response wrapper with `ok?` and `json` convenience methods
+- Zero dependencies — built on Ruby stdlib `net/http`
+
+[0.1.0]: https://github.com/philiprehberger/rb-http-client/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,127 @@
+# philiprehberger-http_client
+
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-http_client.svg)](https://badge.fury.io/rb/philiprehberger-http_client)
+[![CI](https://github.com/philiprehberger/rb-http-client/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-http-client/actions/workflows/ci.yml)
+
+Lightweight HTTP client wrapper with retries and interceptors. Zero dependencies — built on Ruby's stdlib `net/http`.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-http_client"
+```
+
+Or install directly:
+
+```sh
+gem install philiprehberger-http_client
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/http_client"
+
+client = Philiprehberger::HttpClient.new(base_url: "https://api.example.com")
+```
+
+### GET request
+
+```ruby
+response = client.get("/users", params: { page: 1 })
+
+puts response.status  # => 200
+puts response.ok?     # => true
+puts response.json    # => [{"id" => 1, "name" => "Alice"}, ...]
+```
+
+### POST with JSON body
+
+```ruby
+response = client.post("/users", json: { name: "Bob", email: "bob@example.com" })
+
+puts response.status  # => 201
+puts response.json    # => {"id" => 2, "name" => "Bob", ...}
+```
+
+### Default headers
+
+```ruby
+client = Philiprehberger::HttpClient.new(
+  base_url: "https://api.example.com",
+  headers: { "Authorization" => "Bearer token123" }
+)
+```
+
+### Interceptors
+
+Add request/response interceptors to log, modify, or inspect traffic:
+
+```ruby
+client = Philiprehberger::HttpClient.new(base_url: "https://api.example.com")
+
+client.use do |context|
+  if context[:response]
+    puts "Response: #{context[:response].status}"
+  else
+    puts "Request: #{context[:request][:method]} #{context[:request][:uri]}"
+  end
+end
+
+client.get("/health")
+# Prints:
+#   Request: GET https://api.example.com/health
+#   Response: 200
+```
+
+### Retries
+
+Automatically retry on network errors (connection refused, timeouts, etc.):
+
+```ruby
+client = Philiprehberger::HttpClient.new(
+  base_url: "https://api.example.com",
+  retries: 3,
+  retry_delay: 2
+)
+
+response = client.get("/unstable-endpoint")
+```
+
+### All HTTP methods
+
+```ruby
+client.get("/resource", params: { q: "search" })
+client.post("/resource", json: { key: "value" })
+client.put("/resource/1", json: { key: "updated" })
+client.patch("/resource/1", json: { key: "patched" })
+client.delete("/resource/1")
+```
+
+## API
+
+### `Philiprehberger::HttpClient.new(**options)`
+
+| Option        | Type    | Default | Description                          |
+|---------------|---------|---------|--------------------------------------|
+| `base_url`    | String  | —       | Base URL for all requests (required) |
+| `headers`     | Hash    | `{}`    | Default headers for every request    |
+| `timeout`     | Integer | `30`    | Read/open timeout in seconds         |
+| `retries`     | Integer | `0`     | Retry attempts on network errors     |
+| `retry_delay` | Numeric | `1`     | Seconds between retries              |
+
+### `Response`
+
+| Method    | Returns | Description                     |
+|-----------|---------|---------------------------------|
+| `status`  | Integer | HTTP status code                |
+| `body`    | String  | Raw response body               |
+| `headers` | Hash    | Response headers                |
+| `ok?`     | Boolean | `true` if status is 200-299     |
+| `json`    | Hash    | Parsed JSON body                |
+
+## License
+
+[MIT](LICENSE)

data/lib/philiprehberger/http_client/client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Philiprehberger
+  module HttpClient
+    class Client
+      include Connection
+
+      # @param base_url [String] Base URL for all requests
+      # @param headers [Hash] Default headers applied to every request
+      # @param timeout [Integer] Read/open timeout in seconds
+      # @param retries [Integer] Number of retry attempts on network errors
+      # @param retry_delay [Numeric] Seconds to wait between retries
+      def initialize(base_url:, headers: {}, timeout: 30, retries: 0, retry_delay: 1)
+        @base_url = base_url.chomp("/")
+        @default_headers = headers
+        @timeout = timeout
+        @retries = retries
+        @retry_delay = retry_delay
+        @interceptors = []
+      end
+
+      # Register a request/response interceptor.
+      #
+      # The block receives a Hash with :request and, after the request completes, :response.
+      # It is called twice: once before the request (with :request only) and once after
+      # (with both :request and :response).
+      #
+      # @yield [Hash] context hash with :request and optionally :response
+      # @return [self]
+      def use(&block)
+        @interceptors << block
+        self
+      end
+
+      # Perform a GET request.
+      #
+      # @param path [String] Request path appended to the base URL
+      # @param params [Hash] Query parameters
+      # @param headers [Hash] Additional headers for this request
+      # @return [Response]
+      def get(path, params: {}, headers: {})
+        uri = build_uri(path, params)
+        request = Net::HTTP::Get.new(uri)
+        execute(uri, request, headers)
+      end
+
+      # Perform a POST request.
+      #
+      # @param path [String] Request path
+      # @param body [String, nil] Raw body string
+      # @param json [Hash, Array, nil] JSON-serializable body (sets Content-Type automatically)
+      # @param headers [Hash] Additional headers
+      # @return [Response]
+      def post(path, body: nil, json: nil, headers: {})
+        uri = build_uri(path)
+        request = Net::HTTP::Post.new(uri)
+        set_body(request, body, json, headers)
+        execute(uri, request, headers)
+      end
+
+      # Perform a PUT request.
+      #
+      # @param path [String] Request path
+      # @param body [String, nil] Raw body string
+      # @param json [Hash, Array, nil] JSON-serializable body
+      # @param headers [Hash] Additional headers
+      # @return [Response]
+      def put(path, body: nil, json: nil, headers: {})
+        uri = build_uri(path)
+        request = Net::HTTP::Put.new(uri)
+        set_body(request, body, json, headers)
+        execute(uri, request, headers)
+      end
+
+      # Perform a PATCH request.
+      #
+      # @param path [String] Request path
+      # @param body [String, nil] Raw body string
+      # @param json [Hash, Array, nil] JSON-serializable body
+      # @param headers [Hash] Additional headers
+      # @return [Response]
+      def patch(path, body: nil, json: nil, headers: {})
+        uri = build_uri(path)
+        request = Net::HTTP::Patch.new(uri)
+        set_body(request, body, json, headers)
+        execute(uri, request, headers)
+      end
+
+      # Perform a DELETE request.
+      #
+      # @param path [String] Request path
+      # @param headers [Hash] Additional headers
+      # @return [Response]
+      def delete(path, headers: {})
+        uri = build_uri(path)
+        request = Net::HTTP::Delete.new(uri)
+        execute(uri, request, headers)
+      end
+    end
+  end
+end

data/lib/philiprehberger/http_client/connection.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HttpClient
+    # Internal helpers for building URIs, HTTP connections, executing requests,
+    # and constructing Response objects. Mixed into Client to keep it concise.
+    module Connection
+      private
+
+      def build_uri(path, params = {})
+        url = "#{@base_url}/#{path.sub(%r{^/}, '')}"
+        uri = URI.parse(url)
+        unless params.empty?
+          query = URI.encode_www_form(params)
+          uri.query = uri.query ? "#{uri.query}&#{query}" : query
+        end
+        uri
+      end
+
+      def set_body(request, body, json_body, headers)
+        if json_body
+          request.body = JSON.generate(json_body)
+          headers["content-type"] ||= "application/json"
+        elsif body
+          request.body = body
+        end
+      end
+
+      def apply_headers(request, extra_headers)
+        merged = @default_headers.merge(extra_headers)
+        merged.each { |key, value| request[key] = value }
+      end
+
+      def execute(uri, request, extra_headers)
+        apply_headers(request, extra_headers)
+
+        context = { request: { uri: uri, method: request.method, headers: request.to_hash } }
+        run_interceptors(context)
+
+        response = perform_with_retries(uri, request)
+        context[:response] = response
+        run_interceptors(context)
+
+        response
+      end
+
+      def perform_with_retries(uri, request)
+        attempts = 0
+        begin
+          perform_request(uri, request)
+        rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,
+               Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+          attempts += 1
+          raise e unless attempts <= @retries
+
+          sleep(@retry_delay)
+          retry
+        end
+      end
+
+      def perform_request(uri, request)
+        http = build_http(uri)
+        raw = http.request(request)
+        build_response(raw)
+      end
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http
+      end
+
+      def build_response(raw)
+        response_headers = {}
+        raw.each_header { |k, v| response_headers[k] = v }
+
+        Response.new(
+          status: raw.code.to_i,
+          body: raw.body || "",
+          headers: response_headers
+        )
+      end
+
+      def run_interceptors(context)
+        @interceptors.each { |interceptor| interceptor.call(context) }
+      end
+    end
+  end
+end

data/lib/philiprehberger/http_client/response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Philiprehberger
+  module HttpClient
+    class Response
+      attr_reader :status, :body, :headers
+
+      # @param status [Integer] HTTP status code
+      # @param body [String] Response body
+      # @param headers [Hash] Response headers
+      def initialize(status:, body:, headers: {})
+        @status = status
+        @body = body
+        @headers = headers
+      end
+
+      # Returns true if the status code is in the 2xx range.
+      #
+      # @return [Boolean]
+      def ok?
+        status >= 200 && status < 300
+      end
+
+      # Parses the response body as JSON.
+      #
+      # @return [Hash, Array] Parsed JSON
+      # @raise [JSON::ParserError] If the body is not valid JSON
+      def json
+        @json ||= JSON.parse(body)
+      end
+    end
+  end
+end

data/lib/philiprehberger/http_client/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HttpClient
+    VERSION = "0.1.0"
+  end
+end

data/lib/philiprehberger/http_client.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "http_client/version"
+require_relative "http_client/response"
+require_relative "http_client/connection"
+require_relative "http_client/client"
+
+module Philiprehberger
+  module HttpClient
+    # Convenience constructor.
+    #
+    # @param options [Hash] Forwarded to {Client#initialize}
+    # @return [Client]
+    def self.new(**options)
+      Client.new(**options)
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-http_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-10 00:00:00.000000000 Z
+dependencies: []
+description: A zero-dependency HTTP client built on Ruby's net/http with automatic
+  retries, request/response interceptors, and a clean API for JSON services.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/http_client.rb
+- lib/philiprehberger/http_client/client.rb
+- lib/philiprehberger/http_client/connection.rb
+- lib/philiprehberger/http_client/response.rb
+- lib/philiprehberger/http_client/version.rb
+homepage: https://github.com/philiprehberger/rb-http-client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-http-client
+  source_code_uri: https://github.com/philiprehberger/rb-http-client
+  changelog_uri: https://github.com/philiprehberger/rb-http-client/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Lightweight HTTP client wrapper with retries and interceptors
+test_files: []