http_resource 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d9fe8b0aeb930b24273f354fa958c855392cbc7169178aff012fc55c9349bc0
-  data.tar.gz: c59a5d2b61d6b759f494fc15619b14a26f1040425c6d1d9eb43c90a67218e2d8
+  metadata.gz: 316f4111914f2024aa5e42083d0305a68f344a3bb5c0beb18b84d5e61228186a
+  data.tar.gz: 8851400609748c96c0380c5b0c9da199e41b988837bf79971dd5eba9196c52af
 SHA512:
-  metadata.gz: 882a09948d72787115e9dde41bf305269355f16bc431e929e2b13d7d28372a48fbaa695682b0e73be030412d1e402cde6fe339d946db1991317e3e19be4e16d7
-  data.tar.gz: e12dcb9fbb52ea78a319a1fa19c27f906a88c66079e03f0ec3f97dc358e7dafc48772a329509934c24cc9475809d58915d81614c8c06a10e75af886b9a672868
+  metadata.gz: 36d4d4964057b673e712eebecd63594fbc222c3a6fe604f853f00c2e3af595ae55417a7701df6b6b6214e3b9ab389e083c2641a38b10aadd0b8f3e6fbaed9ea2
+  data.tar.gz: 9905e5472ea9ec3002ad82f4893e28b6a63f9672389f5a1c767da1e25f57b54cece01d797043488628c3bbeed173f8f40d982774818ceb2101bd917dfbfed27a

data/README.md

@@ -159,6 +159,68 @@ than silently dropping a write.
 missing keys to `nil`. Guarding `data && Contact.from(data)` means an empty 2xx
 yields `nil`, not a ghost value object.
 
+## Simulation mode (test without a backend)
+
+Opt-in, in-memory stand-in for the transport: your resource proxies, value
+objects and error handling run **unchanged** against seeded state — no server,
+no WebMock stubs. Nothing is loaded unless you ask:
+`require "http_resource"` never pulls simulation in; the `simulation:` kwarg does.
+
+```ruby
+# 1. In your client gem: subclass the backend and register path handlers on it.
+class MyGem::Simulation::Backend < HttpResource::Simulation::Backend; end
+
+class ContactsHandler
+  def initialize(store) = @store = store
+
+  def call(verb, segments, payload:, params:)
+    contact = @store[:contacts].find { _1["id"].to_s == segments.first }
+    raise HttpResource::ApiError.for_status("not found", status: 404, body: nil) unless contact
+
+    contact
+  end
+end
+MyGem::Simulation::Backend.register("api/contacts", ContactsHandler)
+
+# 2. Build a simulated client — or inject a prepared backend instance.
+client = HttpResource::Client.new(base_url: "https://irrelevant.test", simulation: true)
+client.simulation.seed(contacts: [{ id: 1, email: "a@b.se" }])
+
+client.get(["api", "contacts", 1])   # => { "id" => 1, "email" => "a@b.se" } — no network
+client.get(["api", "contacts", 9])   # => raises NotFoundError (from your handler)
+
+# 3. Inject failures to exercise error paths.
+client.simulation.fail_next(status: 422, body: '{"errors":["bad"]}', on: "contacts")
+```
+
+The pieces:
+
+- **`Simulation::Backend`** — same verb surface as `Client` (signatures,
+  `params:`/`form:`/timeouts) and the same deterministic-bug guards: blank/dot
+  path segments, URI-invalid String paths, payload+`form:` together, and
+  unserializable payloads raise exactly as they would in production, so
+  simulation can't mask a caller bug. Handlers see **what a real server sees**:
+  JSON payloads parsed (string keys), form bodies and query params as decoded
+  string pairs (`params: {}` converges to `nil`, as on the wire). Responses
+  come back as **fresh parsed-JSON copies** — mutating one can't corrupt the
+  store. An unhandled path raises a loud 501 `ServerError` (never `nil`).
+- **Per-subclass registry** — `register(prefix, handler_class)` stores on the
+  receiving subclass; lookup walks the inheritance chain (nearest class with a
+  match wins, longest whole-segment prefix within it). Two client gems can
+  never leak handlers into each other. Handlers are `HandlerClass.new(store)`,
+  memoized per backend instance.
+- **`Simulation::Store`** — collection-agnostic: `store[:anything]`
+  auto-vivifies, `next_id(:collection)` allocates per-collection Integer ids
+  (seeding an explicit id reserves it; duplicates raise), `deep_stringify` is
+  public for handlers building records from payloads.
+- **`fail_next(status:, body:, on:)`** — FIFO one-shot failure injection,
+  checked before handler lookup; `on:` scopes it to paths containing the
+  (slash-normalized) fragment. `reset!` clears store + injections + handlers.
+- **Client seam** — `simulation: true` instantiates
+  `self.class.simulation_backend_class` (override in your Client subclass);
+  `simulation: backend_instance` injects a prepared one. `client.simulation`
+  returns the backend (`nil` in real mode).
+
 ## Error hierarchy
 
 Every failure is an `HttpResource::ApiError` carrying `#status` (an `Integer`, or
@@ -247,6 +309,14 @@ adversarial spec (`spec/escape_safety_spec.rb`).
 
 ## Changelog
 
+### 0.3.0
+
+- Add opt-in **simulation mode**: `HttpResource::Simulation::Backend`/`Store` +
+  a `simulation:` kwarg on `Client` — exercise a client with no live backend
+  and no stubs. Per-subclass handler registries, collection-agnostic seeded
+  store, FIFO failure injection, full transport parity (same guards, same
+  typed errors). Lazy-loaded: plain `require "http_resource"` is unchanged.
+
 ### 0.2.0
 
 - Add a `form:` keyword to `post`/`put`/`patch` for `application/x-www-form-urlencoded`

data/lib/http_resource/client.rb

@@ -32,14 +32,27 @@ module HttpResource
 
     attr_reader :base_url
 
+    # The simulation backend when built with simulation:; nil in real mode.
+    attr_reader :simulation
+
+    # The Backend class `simulation: true` instantiates. Client-gem subclasses
+    # override this to point at their own Backend subclass (with its own
+    # registered handlers). Only called after the lazy require, so the
+    # constant resolves.
+    def self.simulation_backend_class
+      Simulation::Backend
+    end
+
     def initialize(base_url:, auth: nil, username: nil, password: nil,
-                   open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+                   open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+                   simulation: nil)
       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
+      @simulation = setup_simulation(simulation)
     end
 
     # Low-level REST verbs. `path` may be a String ("/api/foo") sent verbatim, or
@@ -78,6 +91,11 @@ module HttpResource
     private
 
     def request(method, path, body: nil, form: nil, params: nil, open_timeout: nil, read_timeout: nil)
+      # In simulation the verb call is handed to the backend BEFORE any URI
+      # build or network I/O — the backend enforces the same deterministic-bug
+      # guards, so a call that raises in production raises identically here.
+      return simulate(method, path, body:, form:, params:) if @simulation
+
       # Build the URI + request OUTSIDE the network rescue: a URI::InvalidURIError
       # (bad path), JSON::GeneratorError (un-serializable payload, e.g. a NaN
       # amount) or an ArgumentError (both a JSON and a form body) is a
@@ -182,6 +200,27 @@ module HttpResource
       body
     end
 
+    def simulate(method, path, body:, form:, params:)
+      # The public verbs only pass params: on get; reaching this with params
+      # on another verb means private-seam misuse — fail loud, don't drop it.
+      raise ArgumentError, "params: is only supported on get in simulation" if params && method != :get
+
+      case method
+      when :get then @simulation.get(path, params:)
+      when :delete then @simulation.delete(path)
+      else @simulation.public_send(method, path, body, form:)
+      end
+    end
+
+    # Lazy: the simulation machinery is test-facing and never loaded unless
+    # asked for — plain `require "http_resource"` must not pull it in.
+    def setup_simulation(simulation)
+      return nil unless simulation
+
+      require "http_resource/simulation"
+      simulation == true ? self.class.simulation_backend_class.new : simulation
+    end
+
     def default_auth(username, password)
       return nil if blank?(username) && blank?(password)
 

data/lib/http_resource/simulation/backend.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "http_resource/errors"
+require "http_resource/simulation/store"
+
+module HttpResource
+  module Simulation
+    # In-memory stand-in for Client's transport. Same verb surface (signatures
+    # including params:/form:/timeouts), same deterministic-bug guards, and it
+    # answers with parsed-JSON-shaped Hashes (string keys) or nil, or raises
+    # via ApiError.for_status — so every resource proxy, value object and
+    # error path above it runs UNCHANGED against seeded in-memory state.
+    #
+    # Client gems SUBCLASS Backend and let handlers self-register on the
+    # subclass at file load:
+    #
+    #   class MyGem::Simulation::Backend < HttpResource::Simulation::Backend; end
+    #   MyGem::Simulation::Backend.register("api/contacts", ContactsHandler)
+    #
+    # Each subclass owns its OWN registry (one gem's handlers can never leak
+    # into another's); lookup walks the inheritance chain — the NEAREST class
+    # with any matching prefix wins (a subclass registration shadows the
+    # parent's wholesale), longest whole-segment prefix within that class.
+    # Handlers are HandlerClass.new(store), memoized per backend instance, and
+    # receive handler.call(verb, segments, payload:, params:).
+    class Backend
+      class << self
+        def register(prefix, handler_class)
+          registry[prefix_segments(prefix)] = handler_class
+        end
+
+        # This class's OWN registrations ({segments => handler_class}), NOT
+        # including inherited ones — dispatch walks the ancestry explicitly.
+        def registry
+          @registry ||= {}
+        end
+
+        private
+
+        def prefix_segments(prefix)
+          prefix.to_s.gsub(%r{\A/+|/+\z}, "").split("/").freeze
+        end
+      end
+
+      attr_reader :store
+
+      def initialize
+        @store = Store.new
+        @handlers = {}
+        @injections = []
+      end
+
+      # The timeout kwargs are accepted AND ignored on purpose: the surface
+      # must match Client's verbs exactly so calling code runs unchanged.
+      # rubocop:disable Lint/UnusedMethodArgument
+      def get(path, params: nil, open_timeout: nil, read_timeout: nil)
+        dispatch(:get, path, params: normalize_params(params))
+      end
+
+      def post(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+        dispatch(:post, path, payload:, form:)
+      end
+
+      def put(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+        dispatch(:put, path, payload:, form:)
+      end
+
+      def patch(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+        dispatch(:patch, path, payload:, form:)
+      end
+
+      def delete(path, open_timeout: nil, read_timeout: nil)
+        dispatch(:delete, path)
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+
+      def seed(collections)
+        @store.seed(collections)
+      end
+
+      # Queue a one-shot failure: the next call whose normalized path contains
+      # `on:` (any call when omitted) raises the mapped ApiError, then the
+      # injection is consumed. Non-matching injections are skipped over and
+      # STAY queued (FIFO among matches). `body:` is coerced to the String a
+      # real transport error carries (a Hash/Array is JSON-encoded).
+      def fail_next(status:, body: nil, on: nil)
+        @injections << { status:, body: string_body(body), on: normalize_on(on) }
+        nil
+      end
+
+      def reset!
+        @store.reset!
+        @handlers.clear
+        @injections.clear
+        nil
+      end
+
+      private
+
+      # Guard order mirrors production exactly: path first (build_uri), body
+      # second (build_request), only then the "network" (injections + handler)
+      # — so a doubly-broken call raises the SAME error in both modes.
+      def dispatch(verb, path, payload: nil, form: nil, params: nil)
+        segments = normalize_path(path)
+        body = body_for(payload, form)
+        consume_injection!(segments.join("/"))
+
+        prefix, handler_class = match(segments)
+        unless handler_class
+          raise ApiError.for_status("no simulation handler for #{verb.to_s.upcase} /#{segments.join('/')}",
+                                    status: 501, body: nil)
+        end
+
+        # Memoized on the RESOLVED class (not the prefix), so a same-prefix
+        # registration on a nearer class can never serve a stale instance.
+        handler = (@handlers[handler_class] ||= handler_class.new(@store))
+        result = handler.call(verb, segments.drop(prefix.size), payload: body, params:)
+        # The response is a FRESH parsed-JSON copy, like a real body parse:
+        # callers can't corrupt the store by mutating it, and a handler's
+        # symbol keys are normalized to the contract's string keys.
+        result.nil? ? nil : JSON.parse(JSON.generate(result))
+      end
+
+      # Same guard as the real transport (Client#apply_body), and the payload
+      # reaches the handler the way a REAL server would see it: a JSON payload
+      # as its parsed-JSON form (string keys; an unserializable payload raises
+      # JSON::GeneratorError exactly like the real build_request), a form
+      # payload as the string pairs a form decoder yields (values to_s'd,
+      # repeated keys last-wins, matching a bare-key Rack parse).
+      def body_for(payload, form)
+        raise ArgumentError, "pass either a JSON payload or form:, not both" if payload && form
+
+        if form
+          URI.decode_www_form(URI.encode_www_form(form)).to_h
+        elsif payload
+          JSON.parse(JSON.generate(payload))
+        end
+      end
+
+      # Array segments arrive raw (the backend replaces the transport BEFORE
+      # any percent-encoding) but pass the SAME validation as the real
+      # encoder: blank and dot-segments are caller bugs there and stay caller
+      # bugs here. A String path may carry encoded bytes, so its segments are
+      # decoded to what a server-side router sees; a malformed %-escape raises
+      # URI::InvalidURIError, exactly as the real URI build would.
+      def normalize_path(path)
+        if path.is_a?(Array)
+          path.map { validate_segment(_1) }
+        else
+          stripped = path.to_s.gsub(%r{\A/+|/+\z}, "")
+          validate_string_path(stripped)
+          stripped.split("/").map { decode_segment(_1) }
+        end
+      end
+
+      # Parity: the real transport URI.parses the String path, so a
+      # URI-invalid character (raw space, "|", a malformed %-escape, …) raises
+      # URI::InvalidURIError there — it must raise here too. Note simulation
+      # treats a String as a PURE path (no query/fragment splitting).
+      def validate_string_path(stripped)
+        URI.parse("http://sim.invalid/#{stripped}")
+      rescue URI::InvalidURIError
+        raise URI::InvalidURIError, "invalid String path for simulation: #{stripped.inspect}"
+      end
+
+      # Query params reach the handler the way a real server sees them:
+      # string pairs (repeated keys last-wins), with an empty hash — which
+      # produces no query string on the wire — converging to nil, exactly
+      # like build_uri's `params && !params.empty?` guard.
+      def normalize_params(params)
+        return nil if params.nil? || params.empty?
+
+        URI.decode_www_form(URI.encode_www_form(params)).to_h
+      end
+
+      def validate_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)
+
+        str
+      end
+
+      def decode_segment(segment)
+        URI.decode_uri_component(segment)
+      rescue ArgumentError
+        raise URI::InvalidURIError, "malformed percent-encoding in path segment #{segment.inspect}"
+      end
+
+      # Nearest class with ANY match wins; longest prefix within that class.
+      def match(segments)
+        klass = self.class
+        while klass.respond_to?(:registry)
+          hit = klass.registry
+                     .select { |prefix, _| segments.first(prefix.size) == prefix }
+                     .max_by { |prefix, _| prefix.size }
+          return hit if hit
+
+          klass = klass.superclass
+        end
+        nil
+      end
+
+      def consume_injection!(joined_path)
+        index = @injections.index { _1[:on].nil? || joined_path.include?(_1[:on]) }
+        return unless index
+
+        injection = @injections.delete_at(index)
+        raise ApiError.for_status("injected failure", status: injection[:status], body: injection[:body])
+      end
+
+      def normalize_on(on)
+        on&.to_s&.gsub(%r{\A/+|/+\z}, "")
+      end
+
+      def string_body(body)
+        return body if body.nil? || body.is_a?(String)
+
+        JSON.generate(body)
+      end
+    end
+  end
+end

data/lib/http_resource/simulation/store.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module HttpResource
+  module Simulation
+    # Per-Backend in-memory record store. Collection-agnostic: ANY name
+    # auto-vivifies an empty collection on first access. Records are Hashes
+    # with STRING keys — they stand in for parsed JSON, so the value objects
+    # and resource proxies above read them exactly as they would a live
+    # response body.
+    class Store
+      def initialize
+        @collections = Hash.new { |hash, key| hash[key] = [] }
+        @sequences = Hash.new(0)
+      end
+
+      # store[:contacts] — the collection's Array (auto-vivified, live
+      # reference: handlers mutate it in place).
+      def [](collection)
+        @collections[collection.to_sym]
+      end
+
+      # Allocate the next Integer id for a collection. MUTATING — every call
+      # consumes an id. Never call it from a test assertion; read the
+      # records' "id" values instead.
+      def next_id(collection)
+        @sequences[collection.to_sym] += 1
+      end
+
+      # Append records under ANY collection names, assigning "id" via next_id
+      # when absent: seed(contacts: [...], "invoices" => [...]). Symbol- or
+      # string-keyed records; all keys are normalized (deeply) to strings.
+      def seed(collections)
+        collections.each do |name, records|
+          unless records.is_a?(Array)
+            raise ArgumentError,
+                  "records for #{name.inspect} must be an Array of Hashes, got #{records.class}"
+          end
+
+          records.each { append(name, _1) }
+        end
+        nil
+      end
+
+      # Clears the collections IN PLACE, so previously-obtained collection
+      # references (see #[]) stay live across a reset.
+      def reset!
+        @collections.each_value(&:clear)
+        @sequences.clear
+        nil
+      end
+
+      # Public because handlers need the same JSON-shaping for records they
+      # build from request payloads.
+      def deep_stringify(value)
+        case value
+        when Hash then value.to_h { |key, val| [key.to_s, deep_stringify(val)] }
+        when Array then value.map { deep_stringify(_1) }
+        else value
+        end
+      end
+
+      private
+
+      def append(collection, record)
+        record = deep_stringify(record)
+        if record["id"]
+          reserve_id(collection, record["id"])
+        else
+          record["id"] = next_id(collection)
+        end
+        self[collection] << record
+      end
+
+      # An explicitly seeded id is RESERVED: it must be unique within its
+      # collection — compared as STRINGS, the way handlers look ids up from
+      # path segments — and a duplicate is a test-authoring bug that raises.
+      # The sequence advances past integer-LIKE ids (5 and "5" alike) so a
+      # later next_id can never hand out an id that aliases a reserved one.
+      # Non-numeric String ids (UUIDs…) are kept as-is.
+      def reserve_id(collection, id)
+        raise ArgumentError, "duplicate id #{id.inspect} in #{collection.inspect}" if
+          self[collection].any? { _1["id"].to_s == id.to_s }
+
+        key = collection.to_sym
+        @sequences[key] = [@sequences[key], id.to_i].max if id.to_s.match?(/\A\d+\z/)
+      end
+    end
+  end
+end

data/lib/http_resource/simulation.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Test-facing, opt-in machinery: exercise an http_resource-based client with NO
+# live backend. NOT loaded by `require "http_resource"` — Client requires this
+# file lazily, only when built with a truthy `simulation:` kwarg.
+require "http_resource/simulation/store"
+require "http_resource/simulation/backend"

data/lib/http_resource/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http_resource
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Skiftet
@@ -32,6 +32,9 @@ files:
 - lib/http_resource/configuration.rb
 - lib/http_resource/errors.rb
 - lib/http_resource/resource.rb
+- lib/http_resource/simulation.rb
+- lib/http_resource/simulation/backend.rb
+- lib/http_resource/simulation/store.rb
 - lib/http_resource/value_object.rb
 - lib/http_resource/version.rb
 homepage: https://github.com/Skiftet/http_resource