http_resource 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae3a2c83649ab50e44f3b85b70e223903788c31b8c1d3e738d87ae4154f1e716
-  data.tar.gz: 4807d9724ace0ad3b1cddedaa74c693454c4f1d0b29591a7f655228ea8a09a71
+  metadata.gz: 316f4111914f2024aa5e42083d0305a68f344a3bb5c0beb18b84d5e61228186a
+  data.tar.gz: 8851400609748c96c0380c5b0c9da199e41b988837bf79971dd5eba9196c52af
 SHA512:
-  metadata.gz: 5b6bffc9f723e5ad0e7c2c15917dd7a18b9064719c5b1c128f3aebe6f1d601390db7b83ed1c7abffe1e047e2293d3ee7f9524c85c0501d3e08ea2d67f05f7e72
-  data.tar.gz: bed8b7f03efd23d9f52a543bc07e6b0cd16b1429ce5df9f6373f29ab51fbdc100684720e47fb16fcc4c10d7489db70177a471a0cca67b97ae9f2c1e1147a5e78
+  metadata.gz: 36d4d4964057b673e712eebecd63594fbc222c3a6fe604f853f00c2e3af595ae55417a7701df6b6b6214e3b9ab389e083c2641a38b10aadd0b8f3e6fbaed9ea2
+  data.tar.gz: 9905e5472ea9ec3002ad82f4893e28b6a63f9672389f5a1c767da1e25f57b54cece01d797043488628c3bbeed173f8f40d982774818ceb2101bd917dfbfed27a

data/README.md

@@ -54,6 +54,7 @@ client = HttpResource::Client.new(
 
 client.get(["api", "contacts", id])          # GET, id escaped as ONE path segment
 client.post(["api", "actions"], { foo: 1 })  # POST a JSON body
+client.put(["api", "contacts", id], { name: "Anna" })
 client.patch(["api", "contacts", email], { name: "Anna" })
 client.delete(["api", "contacts", id])
 ```
@@ -65,6 +66,37 @@ 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.
 
+### Form-encoded bodies (OAuth)
+
+`post`/`put`/`patch` take a `form:` keyword to send an
+`application/x-www-form-urlencoded` body instead of JSON — for the form-encoded
+endpoints OAuth consumers hit (RFC 6749 token, RFC 7662 introspection, …):
+
+```ruby
+token = client.post(["oauth", "token"], form: {
+  grant_type: "client_credentials",
+  scope: "read write"
+})
+token["access_token"]   # a 2xx still returns parsed JSON
+```
+
+The response side is identical to a JSON call — parsed JSON on a 2xx, a typed
+`ApiError` on a non-2xx — so an OAuth failure is just a rescue-able error whose
+`#body` carries the payload:
+
+```ruby
+begin
+  client.post(["oauth", "token"], form: { grant_type: "authorization_code", code: bad })
+rescue HttpResource::ClientError => e
+  e.status                    # => 400
+  JSON.parse(e.body)["error"] # => "invalid_grant"
+end
+```
+
+Pass **either** a JSON `payload` **or** `form:`, never both (it raises
+`ArgumentError`). Form keys/values are percent-encoded, so untrusted input can't
+inject a header or an extra field.
+
 ### A process-wide default client
 
 ```ruby
@@ -127,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
@@ -213,6 +307,30 @@ A **`String`** path is the trusted escape hatch and is sent **verbatim** — so
 let the framework encode it. The guarantee is covered by a dedicated,
 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`
+  bodies (OAuth token/introspection and other form-encoded endpoints). Responses
+  stay resty: parsed JSON on a 2xx, a typed `ApiError` (with `#body`) on a non-2xx.
+- Add a first-class `put` verb (JSON or `form:` body).
+- Passing both a JSON `payload` and `form:` raises `ArgumentError`; the bodyless
+  verbs (`get`/`delete`) reject `form:`.
+
+### 0.1.0
+
+- Initial release: Net::HTTP transport, typed `ApiError` hierarchy, bang/non-bang
+  resources, pluggable auth, per-call timeouts, escape-safe URL building.
+
 ## Development
 
 ```sh

data/lib/http_resource/client.rb

@@ -8,13 +8,14 @@ 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.
+  # (get/post/put/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
+  #   client.get(["api", "contacts", id])            # GET, id escaped as one segment
+  #   client.post(["api", "actions"], { ... })       # POST a JSON body
+  #   client.post(["oauth", "token"], form: { ... }) # POST a form body (OAuth, RFC 6749)
   #
   # 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
@@ -31,45 +32,77 @@ 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
     # 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)
+    #
+    # The body-bearing verbs (post/put/patch) send EITHER a JSON body — the
+    # positional `payload` — or a form body — `form: {...}`, encoded as
+    # application/x-www-form-urlencoded (for the form-encoded endpoints OAuth
+    # consumers hit: RFC 6749 token, RFC 7662 introspection, …). Passing both is
+    # a caller bug and raises ArgumentError. The response side is identical either
+    # way: parsed JSON on a 2xx, a typed ApiError (with #status + #body) on a
+    # non-2xx — so a "400 invalid_grant" is a rescue-able ClientError whose #body
+    # carries the error payload.
+    def get(path, params: nil, open_timeout: nil, read_timeout: nil)
+      request(:get, path, params:, open_timeout:, read_timeout:)
+    end
+
+    def post(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+      request(:post, path, body: payload, form:, open_timeout:, read_timeout:)
     end
 
-    def post(path, payload = nil, **timeouts)
-      request(:post, path, body: payload, **timeouts)
+    def put(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+      request(:put, path, body: payload, form:, open_timeout:, read_timeout:)
     end
 
-    def patch(path, payload = nil, **timeouts)
-      request(:patch, path, body: payload, **timeouts)
+    def patch(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+      request(:patch, path, body: payload, form:, open_timeout:, read_timeout:)
     end
 
-    def delete(path, **timeouts)
-      request(:delete, path, **timeouts)
+    def delete(path, open_timeout: nil, read_timeout: nil)
+      request(:delete, path, open_timeout:, read_timeout:)
     end
 
     private
 
-    def request(method, path, body: nil, params: nil, open_timeout: nil, read_timeout: nil)
+    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) 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.
+      # (bad path), JSON::GeneratorError (un-serializable payload, e.g. a NaN
+      # amount) or an ArgumentError (both a JSON and a form body) 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)
+      req = build_request(method, uri, body, form)
       connection = http(uri, open_timeout:, read_timeout:)
       begin
         handle(connection.request(req))
@@ -116,19 +149,32 @@ module HttpResource
       ERB::Util.url_encode(str)
     end
 
-    def build_request(method, uri, body)
+    def build_request(method, uri, body, form = nil)
       klass = {
-        get: Net::HTTP::Get, post: Net::HTTP::Post,
+        get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put,
         patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
       }.fetch(method)
       request = klass.new(uri)
       @auth&.apply(request)
       request["Accept"] = "application/json"
-      if body
+      apply_body(request, body, form)
+      request
+    end
+
+    # A request carries EITHER a JSON body (`payload`) or a form body (`form:`),
+    # never both — passing both is a caller bug. Form values are percent-encoded
+    # by URI.encode_www_form (the same encoder used for query params), so an
+    # untrusted key/value can't inject a header, a second field, or CRLF.
+    def apply_body(request, body, form)
+      raise ArgumentError, "pass either a JSON payload or form:, not both" if body && form
+
+      if form
+        request["Content-Type"] = "application/x-www-form-urlencoded"
+        request.body = URI.encode_www_form(form)
+      elsif body
         request["Content-Type"] = "application/json"
         request.body = JSON.generate(body)
       end
-      request
     end
 
     def http(uri, open_timeout: nil, read_timeout: nil)
@@ -154,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.1.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.1.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