http_resource 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae3a2c83649ab50e44f3b85b70e223903788c31b8c1d3e738d87ae4154f1e716
+  data.tar.gz: 4807d9724ace0ad3b1cddedaa74c693454c4f1d0b29591a7f655228ea8a09a71
+SHA512:
+  metadata.gz: 5b6bffc9f723e5ad0e7c2c15917dd7a18b9064719c5b1c128f3aebe6f1d601390db7b83ed1c7abffe1e047e2293d3ee7f9524c85c0501d3e08ea2d67f05f7e72
+  data.tar.gz: bed8b7f03efd23d9f52a543bc07e6b0cd16b1429ce5df9f6373f29ab51fbdc100684720e47fb16fcc4c10d7489db70177a471a0cca67b97ae9f2c1e1147a5e78

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skiftet
+
+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,226 @@
+# HttpResource
+
+A tiny, **zero-dependency** Ruby framework for building typed REST-resource
+clients on top of `Net::HTTP`.
+
+You bring a `base_url` and an auth strategy; HttpResource gives you a transport
+with a **typed error hierarchy**, Rails-style **bang/non-bang resources**,
+**pluggable auth**, **per-call timeouts**, and **escape-safe URL building** so
+untrusted path segments can never escape the protocol.
+
+It is the generic core extracted from Skiftet's `mejla_api_client`: a small set
+of proven patterns you would otherwise hand-roll (and get subtly wrong) in every
+service-to-service client.
+
+## Why
+
+Most hand-rolled HTTP clients get three things wrong:
+
+1. **They mask deterministic bugs as retryable failures.** A bad URL or an
+   un-serializable payload gets caught by a broad `rescue` and turned into a
+   "transport error", so a background worker retries it forever. HttpResource
+   builds the request *outside* the network rescue, so those propagate.
+2. **They flatten every failure into one exception.** A 404, a 422 validation
+   rejection, an auth failure and a 5xx all need different handling. HttpResource
+   maps each to a distinct, rescue-by-parent error class.
+3. **They interpolate untrusted ids straight into URLs.** HttpResource encodes
+   each array path segment as a single RFC-3986 path component — see
+   [Escape safety](#escape-safety).
+
+## Install
+
+```ruby
+# Gemfile
+gem "http_resource"
+```
+
+```ruby
+require "http_resource"
+```
+
+Requires Ruby >= 3.2. No runtime dependencies.
+
+## Usage
+
+### Build a client
+
+```ruby
+client = HttpResource::Client.new(
+  base_url: "https://api.example.org",
+  auth: HttpResource::Auth.bearer(ENV.fetch("API_TOKEN")),
+  open_timeout: 5,   # optional, default 5
+  read_timeout: 15   # optional, default 15
+)
+
+client.get(["api", "contacts", id])          # GET, id escaped as ONE path segment
+client.post(["api", "actions"], { foo: 1 })  # POST a JSON body
+client.patch(["api", "contacts", email], { name: "Anna" })
+client.delete(["api", "contacts", id])
+```
+
+A `String` path is sent verbatim (`client.get("/api/ping")`); an `Array` path
+has each segment percent-encoded (see [Escape safety](#escape-safety)).
+
+Reads return parsed JSON (a `Hash`/`Array`, or `nil` on an empty body). Every
+call raises an `HttpResource::ApiError` subclass on a non-2xx response or a
+transport failure.
+
+### A process-wide default client
+
+```ruby
+HttpResource.configure do |c|
+  c.base_url = ENV.fetch("API_URL")
+  c.auth = HttpResource::Auth.basic(ENV.fetch("API_USER"), ENV.fetch("API_PASS"))
+end
+
+HttpResource.client.get(["api", "ping"])
+```
+
+`HttpResource.build_client(base_url: ..., auth: ...)` builds an independent
+client when you talk to more than one host.
+
+### Pluggable auth
+
+An auth strategy is any object responding to `#apply(request)`. Three are shipped:
+
+```ruby
+HttpResource::Auth.basic("user", "pass")   # Authorization: Basic <base64>
+HttpResource::Auth.bearer("token")         # Authorization: Bearer token
+HttpResource::Auth.header("X-Api-Key", k)  # X-Api-Key: k
+```
+
+Passing `username:`/`password:` (and no `auth:`) defaults to Basic. Bring your
+own strategy for anything else (HMAC signing, refreshing tokens, …).
+
+### Resources: the bang/non-bang pattern
+
+Subclass `HttpResource::Resource` to map an endpoint to typed verbs. Pair a
+non-bang method (returns `nil` on an expected 404 miss) with a bang method
+(raises on any failure):
+
+```ruby
+Contact = Data.define(:email, :name) do
+  extend HttpResource::ValueObject   # tolerant .from(payload)
+end
+
+class Contacts < HttpResource::Resource
+  def find(id)  = soft { find!(id) }   # nil on 404, raises on anything else
+
+  def find!(id)
+    data = @client.get(["api", "contacts", id])
+    data && Contact.from(data)         # empty 2xx -> nil, never a ghost object
+  end
+end
+
+contacts = Contacts.new(client)
+contacts.find("missing")  # => nil   (404 swallowed)
+contacts.find!("missing") # => raises HttpResource::NotFoundError
+```
+
+`soft { ... }` swallows **only** an `Expected` failure (a 404) to `nil`.
+Everything else — including a 422 validation rejection on a write — raises even
+from the non-bang form, so a sync job surfaces and retries the failure rather
+than silently dropping a write.
+
+`ValueObject#from` returns `nil` for a `nil` payload, unwraps a top-level
+`{ "data" => {...} }` envelope, tolerates string or symbol keys, and defaults
+missing keys to `nil`. Guarding `data && Contact.from(data)` means an empty 2xx
+yields `nil`, not a ghost value object.
+
+## Error hierarchy
+
+Every failure is an `HttpResource::ApiError` carrying `#status` (an `Integer`, or
+`nil` for transport failures) and `#body`. `ApiError.for_status` maps the HTTP
+status to the most specific class, so you can rescue broadly or narrowly:
+
+| Class | Status | `client_error?` | `server_error?` | `Expected` (→ nil) | Meaning |
+|---|---|---|---|---|---|
+| `ApiError` | any / other | by status | by status | no | base for all of the below |
+| `ClientError` | 400–499 | yes | no | no | caller's request won't succeed on retry — drop |
+| `NotFoundError` | 404 | yes | no | **yes** | resource missing; the only swallow-to-nil case |
+| `ValidationError` | 422 | yes | no | no | request rejected; a write must surface, not drop |
+| `AuthError` | 401, 403 | yes | no | no | bad/missing credentials — usually a config bug |
+| `RedirectError` | 300–399 | no | no | no | unfollowed redirect — usually a wrong base_url |
+| `ServerError` | 500–599 | no | yes | no | server failed a valid request — retryable |
+| `TransportError` | nil | no | no | no | network failure before/while talking — retryable |
+| `TimeoutError` | nil | no | no | no | connect/read exceeded the budget (a TransportError) |
+| `ConnectionError` | nil | no | no | no | refused/reset/DNS/TLS (a TransportError) |
+
+Because the tree nests, a worker can branch on intent:
+
+```ruby
+begin
+  client.post(["api", "actions"], payload)
+rescue HttpResource::ClientError       # 4xx — drop, don't retry
+  drop!
+rescue HttpResource::ServerError,      # 5xx + transport — retry
+       HttpResource::TransportError
+  retry_later!
+end
+```
+
+`ConfigurationError` (a sibling of `ApiError` under `Error`) is raised eagerly
+for a blank `base_url` — never on the network path.
+
+## Timeouts
+
+The client carries an `open_timeout` (default 5s) and `read_timeout` (default
+15s). Override either for a single call — e.g. a short read on a synchronous
+page render that must not stall:
+
+```ruby
+client.get(["api", "contacts", id], read_timeout: 2)
+```
+
+A connect or read that exceeds the budget raises `TimeoutError` (status `nil`).
+
+## Escape safety
+
+> **Path segments passed in an `Array` carry untrusted input** (ids, emails,
+> tokens). HttpResource builds URLs so that input can **never** escape the
+> protocol.
+
+In `build_uri`, every `Array` segment is encoded with **`ERB::Util.url_encode`**
+(RFC-3986 path-component encoding) before being joined with `/`. That encodes
+`/`, `?`, `#`, `:`, `@`, `;`, CR/LF and every other reserved character — and a
+space becomes `%20`, not `+` (which is why `CGI.escape` is *not* used: it
+mis-encodes space and is for form bodies, not path components). Query params go
+through `URI.encode_www_form`.
+
+Two inputs **cannot** be safely encoded and are **rejected** with an
+`ArgumentError` instead: a **blank/`nil`** segment (which would collapse into
+`//`) and a bare **`.`** or **`..`** dot-segment. No percent-encoding survives a
+strict normaliser (`%2E` decodes back to `.` per RFC 3986 §6.2.2.2, then
+`remove_dot_segments` traverses), and no legitimate id is a dot-segment — so a
+`.`/`..` id is an error, never a traversal.
+
+The result: an adversarial segment fed to `client.get(["api", "contacts", seg])`
+always lands as **one** percent-encoded path component on the **configured**
+host (or is rejected). None of the following can break out:
+
+| Adversarial segment | Cannot do |
+|---|---|
+| `../../etc/passwd` | introduce extra path segments / traverse (the `/` are encoded) |
+| bare `.` / `..` | climb the path — **rejected** (no encoding survives normalisation) |
+| `a/b?c#d` | add a path segment, query, or fragment |
+| `https://evil.com/x` | change scheme or host |
+| `x\r\nHost: evil.com` | inject CRLF / smuggle a header |
+| `%2e%2e%2f` | sneak a pre-encoded `../` through |
+| `a b`, `;semi`, `@host`, unicode | alter structure or authority |
+
+A **`String`** path is the trusted escape hatch and is sent **verbatim** — so
+**never interpolate untrusted input into a `String` path**; pass an `Array` and
+let the framework encode it. The guarantee is covered by a dedicated,
+adversarial spec (`spec/escape_safety_spec.rb`).
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE) © Skiftet.

data/lib/http_resource/auth/basic.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module HttpResource
+  module Auth
+    # HTTP Basic auth: sets the standard `Authorization: Basic <base64>` header
+    # via Net::HTTP's own `#basic_auth`.
+    class Basic
+      def initialize(username, password)
+        @username = username.to_s
+        @password = password.to_s
+      end
+
+      def apply(request)
+        request.basic_auth(@username, @password)
+      end
+    end
+  end
+end

data/lib/http_resource/auth/bearer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module HttpResource
+  module Auth
+    # Bearer-token auth: sets `Authorization: Bearer <token>`.
+    class Bearer
+      def initialize(token)
+        @token = token.to_s
+      end
+
+      def apply(request)
+        request["Authorization"] = "Bearer #{@token}"
+      end
+    end
+  end
+end

data/lib/http_resource/auth/header.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module HttpResource
+  module Auth
+    # Arbitrary-header auth: sets a custom header (e.g. `X-Api-Key: <value>`).
+    class Header
+      def initialize(name, value)
+        @name = name.to_s
+        @value = value.to_s
+      end
+
+      def apply(request)
+        request[@name] = @value
+      end
+    end
+  end
+end

data/lib/http_resource/auth.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "http_resource/auth/basic"
+require "http_resource/auth/bearer"
+require "http_resource/auth/header"
+
+module HttpResource
+  # Pluggable auth strategies. A strategy is any object responding to
+  # `#apply(request)` that mutates a Net::HTTP request to carry credentials.
+  # Three are shipped (Basic, Bearer, Header); bring your own for anything else.
+  module Auth
+    # Convenience builders so callers can write `Auth.basic("u", "p")`.
+
+    module_function
+
+    def basic(username, password)
+      Basic.new(username, password)
+    end
+
+    def bearer(token)
+      Bearer.new(token)
+    end
+
+    def header(name, value)
+      Header.new(name, value)
+    end
+  end
+end

data/lib/http_resource/client.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "erb"
+require "json"
+require "openssl"
+
+module HttpResource
+  # Net::HTTP transport for a single REST host. Resource-oriented: the verbs
+  # (get/post/patch/delete) are the primitives a Resource is built on, and also
+  # an escape hatch for endpoints not yet modelled.
+  #
+  #   client = HttpResource::Client.new(base_url: "https://api.example.org",
+  #                                     auth: HttpResource::Auth.bearer(token))
+  #   client.get(["api", "contacts", id])         # GET, id escaped as one segment
+  #   client.post(["api", "actions"], { ... })    # POST a JSON body
+  #
+  # Reads return parsed JSON (a Hash/Array, or nil on an empty body). Every call
+  # raises an HttpResource::ApiError subclass on a non-2xx response or a transport
+  # failure.
+  #
+  # SECURITY — path segments are UNTRUSTED. When `path` is an Array, each segment
+  # is percent-encoded as a single RFC-3986 path component, so an id/email/token
+  # can never escape into a second segment, the host, a query or a header. A
+  # String `path` is sent VERBATIM (trusted) — NEVER interpolate untrusted input
+  # into a String path; pass an Array.
+  class Client
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 15
+
+    attr_reader :base_url
+
+    def initialize(base_url:, auth: nil, username: nil, password: nil,
+                   open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      raise ConfigurationError, "base_url is required" if blank?(base_url)
+
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @auth = auth || default_auth(username, password)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Low-level REST verbs. `path` may be a String ("/api/foo") sent verbatim, or
+    # an Array of segments (["api", "contacts", email]) each individually escaped.
+    # Each verb accepts open_timeout:/read_timeout: to override the client's
+    # budget for that one call (e.g. a short read_timeout on a synchronous read).
+    def get(path, params: nil, **timeouts)
+      request(:get, path, params:, **timeouts)
+    end
+
+    def post(path, payload = nil, **timeouts)
+      request(:post, path, body: payload, **timeouts)
+    end
+
+    def patch(path, payload = nil, **timeouts)
+      request(:patch, path, body: payload, **timeouts)
+    end
+
+    def delete(path, **timeouts)
+      request(:delete, path, **timeouts)
+    end
+
+    private
+
+    def request(method, path, body: nil, params: nil, open_timeout: nil, read_timeout: nil)
+      # Build the URI + request OUTSIDE the network rescue: a URI::InvalidURIError
+      # (bad path) or JSON::GeneratorError (un-serializable payload, e.g. a NaN
+      # amount) is a deterministic caller bug, and must NOT be masked as a
+      # retryable TransportError — that would have a worker retry it forever.
+      uri = build_uri(path, params)
+      req = build_request(method, uri, body)
+      connection = http(uri, open_timeout:, read_timeout:)
+      begin
+        handle(connection.request(req))
+      rescue ApiError
+        raise
+      rescue Timeout::Error, Errno::ETIMEDOUT => e # Net::Open/ReadTimeout subclass Timeout::Error
+        raise TimeoutError, "Request timed out: #{e.class}: #{e.message}"
+      rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+        raise ConnectionError, "Connection failed: #{e.class}: #{e.message}"
+      rescue StandardError => e
+        raise TransportError, "Request failed: #{e.class}: #{e.message}"
+      end
+    end
+
+    # An Array path has each segment percent-encoded as ONE path component
+    # (RFC 3986). ERB::Util.url_encode encodes "/", "?", "#", ":", "@", ";",
+    # CR/LF, space (as %20, not "+") and every reserved char — so an untrusted
+    # segment cannot introduce a new path segment, change the host, or inject a
+    # query/fragment/CRLF. A String path is trusted and sent verbatim.
+    def build_uri(path, params)
+      joined =
+        if path.is_a?(Array)
+          path.map { encode_segment(_1) }.join("/")
+        else
+          path.to_s.sub(%r{\A/+}, "")
+        end
+      uri = URI.parse("#{@base_url}/#{joined}")
+      uri.query = URI.encode_www_form(params) if params && !params.empty?
+      uri
+    end
+
+    # Percent-encode one untrusted path segment as a single RFC-3986 path
+    # component. Two inputs can't be safely encoded and must be REJECTED:
+    #   - a BLANK segment would collapse into "//".
+    #   - "." / ".." are dot-segments a server/proxy resolves to climb the path,
+    #     and NO percent-encoding survives strict normalisation (%2E decodes back
+    #     to "." per RFC 3986 §6.2.2.2, THEN remove_dot_segments traverses). No
+    #     legitimate id is a dot-segment, so reject rather than (uselessly) encode.
+    def encode_segment(segment)
+      str = segment.to_s
+      raise ArgumentError, "path segment may not be blank" if str.empty?
+      raise ArgumentError, "path segment may not be a '.' or '..' dot-segment" if [".", ".."].include?(str)
+
+      ERB::Util.url_encode(str)
+    end
+
+    def build_request(method, uri, body)
+      klass = {
+        get: Net::HTTP::Get, post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
+      }.fetch(method)
+      request = klass.new(uri)
+      @auth&.apply(request)
+      request["Accept"] = "application/json"
+      if body
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+      request
+    end
+
+    def http(uri, open_timeout: nil, read_timeout: nil)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = open_timeout || @open_timeout
+      http.read_timeout = read_timeout || @read_timeout
+      http
+    end
+
+    def handle(response)
+      status = response.code.to_i
+      body = response.body.to_s
+      parsed = body.empty? ? nil : parse_json(body)
+      return parsed if status.between?(200, 299)
+
+      raise ApiError.for_status("HTTP request returned #{status}", status:, body:)
+    end
+
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::JSONError
+      body
+    end
+
+    def default_auth(username, password)
+      return nil if blank?(username) && blank?(password)
+
+      Auth::Basic.new(username, password)
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/http_resource/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module HttpResource
+  # Holds the settings for building a default client (HttpResource.client).
+  # Framework-generic: no app-specific env names. A host sets these explicitly in
+  # an initializer, mapping ITS own env vars onto them.
+  #
+  #   HttpResource.configure do |c|
+  #     c.base_url = ENV.fetch("API_URL")
+  #     c.auth = HttpResource::Auth.bearer(ENV.fetch("API_TOKEN"))
+  #   end
+  class Configuration
+    attr_accessor :base_url, :auth, :open_timeout, :read_timeout
+
+    def initialize
+      @base_url = nil
+      @auth = nil
+      @open_timeout = Client::DEFAULT_OPEN_TIMEOUT
+      @read_timeout = Client::DEFAULT_READ_TIMEOUT
+    end
+  end
+end

data/lib/http_resource/errors.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module HttpResource
+  # Base for every error the framework raises.
+  class Error < StandardError; end
+
+  # Missing/blank base_url, or other misconfiguration of a client.
+  class ConfigurationError < Error; end
+
+  # Marker for the ONE failure the non-bang resource methods (find, destroy)
+  # treat as an EXPECTED outcome and swallow to nil: a 404 not-found. Everything
+  # else — INCLUDING a 422 validation rejection on a write (which must surface,
+  # not silently drop the write) — is UNEXPECTED and raises even from the
+  # non-bang form. The bang form (find!, create!) raises on any failure.
+  module Expected; end
+
+  # Raised on a non-2xx response or a transport failure. Carries the HTTP status
+  # (an Integer, or nil for transport failures) + the raw body, so a background
+  # worker can branch its retry: drop on a 4xx (client_error?), retry on a 5xx
+  # (server_error?) or a transport failure (TransportError, status nil).
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || "HTTP error (status=#{status.inspect})")
+    end
+
+    def client_error?
+      status.is_a?(Integer) && status.between?(400, 499)
+    end
+
+    def server_error?
+      status.is_a?(Integer) && status.between?(500, 599)
+    end
+
+    def not_found?
+      status == 404
+    end
+
+    # Map an HTTP status to the most specific ApiError subclass.
+    def self.for_status(message, status:, body:)
+      klass =
+        case status
+        when 404 then NotFoundError
+        when 422 then ValidationError
+        when 401, 403 then AuthError
+        when 400..499 then ClientError
+        when 300..399 then RedirectError
+        when 500..599 then ServerError
+        else self
+        end
+      klass.new(message, status:, body:)
+    end
+  end
+
+  # 4xx — the caller's request won't succeed on retry; a background worker should
+  # drop, not retry. Parent of the specific 4xx below.
+  class ClientError < ApiError; end
+
+  # 404 — the resource does not exist. Expected: the non-bang form swallows it to nil.
+  class NotFoundError < ClientError
+    include Expected
+  end
+
+  # 422 — the request was rejected as invalid (the body holds the details). NOT
+  # Expected: a non-bang write raises this instead of silently dropping the
+  # write, so a sync job surfaces and retries the failure rather than losing data.
+  class ValidationError < ClientError; end
+
+  # 401/403 — bad or missing credentials. Almost always a config problem; raises
+  # even from the non-bang form.
+  class AuthError < ClientError; end
+
+  # 3xx — the server returned a redirect (Net::HTTP does not follow them). Almost
+  # always a misconfigured base_url (e.g. http:// hitting an https redirect); not
+  # retryable. Neither client_error? nor server_error?.
+  class RedirectError < ApiError; end
+
+  # 5xx — the server failed to handle a valid request. Retryable.
+  class ServerError < ApiError; end
+
+  # Network-level failure before/while talking to the server; status is nil. Retryable.
+  class TransportError < ApiError; end
+
+  # The connection or read exceeded the timeout budget.
+  class TimeoutError < TransportError; end
+
+  # Could not establish/keep the connection (refused, reset, DNS, TLS).
+  class ConnectionError < TransportError; end
+end

data/lib/http_resource/resource.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module HttpResource
+  # Base for the REST resource proxies hung off a Client. A subclass maps one
+  # endpoint to its verbs in a bang/non-bang pair (Rails-style):
+  #
+  #   find(id)   — returns the value object, or nil on an EXPECTED miss (404
+  #                not-found). Raises on the UNEXPECTED (validation, auth, 5xx,
+  #                timeout, connection).
+  #   find!(id)  — raises an HttpResource::ApiError on ANY failure.
+  #
+  # Sketch:
+  #
+  #   class Contacts < HttpResource::Resource
+  #     def find(id)  = soft { find!(id) }
+  #     def find!(id)
+  #       data = @client.get(["api", "contacts", id])
+  #       data && Contact.from(data)
+  #     end
+  #   end
+  class Resource
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    # Run the bang form, swallowing only EXPECTED failures (404) to nil.
+    def soft
+      yield
+    rescue Expected
+      nil
+    end
+  end
+end

data/lib/http_resource/value_object.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module HttpResource
+  # Mixin for response value objects, designed to pair with Ruby's Data.define.
+  # It gives a class a tolerant `.from(payload)` that:
+  #   - returns nil for a nil payload (so an empty 2xx -> nil, never a ghost),
+  #   - unwraps a top-level { "data" => {...} } envelope if present,
+  #   - normalises string OR symbol keys,
+  # then hands the inner hash to `build` (or the Data.define member names, when
+  # no `build` is defined) so missing keys arrive as nil instead of raising.
+  #
+  #   Contact = Data.define(:email, :name) do
+  #     extend HttpResource::ValueObject
+  #   end
+  #   Contact.from("data" => { "email" => "a@b.se" })  # => #<data Contact email="a@b.se", name=nil>
+  #   Contact.from(nil)                                 # => nil
+  #
+  # Resource methods should still guard `data && Contact.from(data)` so the
+  # caller never receives a ghost object from an empty body.
+  module ValueObject
+    def from(payload)
+      return nil if payload.nil?
+
+      data = unwrap(payload)
+      respond_to?(:build) ? build(data) : new(**slice_members(data))
+    end
+
+    private
+
+    def unwrap(payload)
+      hash = stringify(payload)
+      inner = hash["data"]
+      inner.is_a?(Hash) ? inner : hash
+    end
+
+    def stringify(payload)
+      return {} unless payload.is_a?(Hash)
+
+      payload.transform_keys(&:to_s)
+    end
+
+    # Pick exactly the Data members, defaulting missing ones to nil.
+    def slice_members(data)
+      members.to_h { |key| [key, data[key.to_s]] }
+    end
+  end
+end

data/lib/http_resource/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HttpResource
+  VERSION = "0.1.0"
+end

data/lib/http_resource.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "http_resource/version"
+require "http_resource/errors"
+require "http_resource/auth"
+require "http_resource/client"
+require "http_resource/configuration"
+require "http_resource/resource"
+require "http_resource/value_object"
+
+# A small, zero-dependency framework for building typed REST-resource clients on
+# top of Net::HTTP. Bring a base_url + an auth strategy; get a Net::HTTP
+# transport with a typed error hierarchy, bang/non-bang resources, per-call
+# timeouts and escape-safe URL building.
+#
+# Build a client directly:
+#
+#   client = HttpResource::Client.new(base_url: "https://api.example.org",
+#                                     auth: HttpResource::Auth.bearer(token))
+#
+# …or configure a process-wide default:
+#
+#   HttpResource.configure do |c|
+#     c.base_url = ENV.fetch("API_URL")
+#     c.auth = HttpResource::Auth.basic(ENV.fetch("API_USER"), ENV.fetch("API_PASS"))
+#   end
+#   HttpResource.client.get(["api", "ping"])
+module HttpResource
+  class << self
+    # Configure the process-wide default client, then (re)build it.
+    def configure
+      yield configuration
+      @client = build_client
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # The memoized default client, built from `configuration`.
+    def client
+      @client ||= build_client
+    end
+
+    # Build a fresh, independent client. Defaults to the configured base_url/auth,
+    # but every option can be overridden per call — handy for talking to more
+    # than one host without a global default.
+    def build_client(base_url: configuration.base_url, auth: configuration.auth,
+                     open_timeout: configuration.open_timeout, read_timeout: configuration.read_timeout)
+      Client.new(base_url:, auth:, open_timeout:, read_timeout:)
+    end
+
+    # Drop the memoized config + client (mainly for tests / reconfiguration).
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: http_resource
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Skiftet
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: HttpResource gives you a Net::HTTP transport with a typed error hierarchy
+  (NotFoundError, ValidationError, AuthError, ServerError, TimeoutError…), Rails-style
+  bang/non-bang resources, pluggable auth strategies (Basic/Bearer/Header), per-call
+  timeouts, and escape-safe URL building so untrusted path segments can never escape
+  the protocol. Bring a base_url and an auth strategy; build clients and resources
+  on top. Zero runtime dependencies (stdlib only).
+email:
+- joel.e.svensson@skiftet.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/http_resource.rb
+- lib/http_resource/auth.rb
+- lib/http_resource/auth/basic.rb
+- lib/http_resource/auth/bearer.rb
+- lib/http_resource/auth/header.rb
+- lib/http_resource/client.rb
+- lib/http_resource/configuration.rb
+- lib/http_resource/errors.rb
+- lib/http_resource/resource.rb
+- lib/http_resource/value_object.rb
+- lib/http_resource/version.rb
+homepage: https://github.com/Skiftet/http_resource
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Skiftet/http_resource
+  source_code_uri: https://github.com/Skiftet/http_resource
+  changelog_uri: https://github.com/Skiftet/http_resource/blob/main/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A tiny, zero-dependency framework for typed REST-resource clients on Net::HTTP.
+test_files: []