reynard 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 891b142e2ca908078c960db4b36040b407974da43395d02b7ee3f768a1c758b4
-  data.tar.gz: 5deefbad34c0364cfd3c3a04910b882499c3b96d7c4d642fdb10fbdcc3e9898f
+  metadata.gz: 149366d0bcc24959907a263c6223a2bb75cc7004a06cf153d1ef2dc35e26b91d
+  data.tar.gz: 8f698ffa4c958564a902d1039807324c9b1182e0a6638dedb16fc6eb3b6eb00f
 SHA512:
-  metadata.gz: 393b2cab7867c45c53b761f42b03e609e653600981aa1283cf3f7c0213379adb9a1eeb1530b3a0f826e07d1ceb5c3fab0d8afc114a2001ec773f71d2484bc109
-  data.tar.gz: c14ebcc55481c202c0c3c7b7dd36e68eb5b72f0297c0339867e6c298d4a3605284dff2e041d33b074c8c9e3b8064f450fdf481fa686e56c1e764af59a1050593
+  metadata.gz: 5de35106aeb06b3478d807d34f5da335684530f6f4f28c789fe52d8a0aafd7f13dab27154ac39cfdc354c4e65bd6da755ea16d669603eae280c027f12d54d152
+  data.tar.gz: ff64d0913efc4e8a2b7c5b8420f94cefcf13567633906d48459ce8a653f5a65f8bd9d8c24368c68a8445320012561a24ff42568065232703675af4944b59f301

data/README.md

@@ -79,8 +79,79 @@ response.code #=> '200'
 response.content_type #=> 'application/json'
 response['Content-Type'] #=> 'application/json'
 response.body #=> '{"name":"Sam Seven"}'
+response.parsed_body #=> { "name" => "Sam Seven" }
 ```
 
+## Schema and models
+
+Reynard has an object builder that allows you to get a value object backed by model classes based on the resource schema.
+
+For example, when the schema for a response is something like this:
+
+```yaml
+book:
+  type: object
+  properties:
+    name:
+      type: string
+    author:
+      type: object
+      properties:
+        name:
+          type: string
+```
+
+And the parsed body from the response is:
+
+```json
+{
+  "name": "Erebus",
+  "author": { "name": "Palin" }
+}
+```
+
+You should be able to access it using:
+
+```ruby
+response.object.class #=> Reynard::Models::Book
+response.object.author.class #=> Reynard::Models::Author
+response.object.author.name #=> 'Palin'
+```
+
+### Model name
+
+Model names are determined in order:
+
+1. From the `title` attribute of a schema
+2. From the `$ref` pointing to the schema
+3. From the path to the definition of the schema
+
+```yaml
+application/json:
+  schema:
+    $ref: "#/components/schemas/Book"
+components:
+  schemas:
+    Book:
+      type: object
+      title: LibraryBook
+```
+
+In this example it would use the `title` and the model name would be `LibraryBook`. Otherwise it would use `Book` from the end of the `$ref`.
+
+If neither of those are available it would look at the full expanded path. 
+
+```
+books:
+  type: array
+  items:
+    type: object
+```  
+
+For example, in case of an array item it would look at `books` and singularize it to `Book`.
+
+If you run into issues where Reynard doesn't properly build an object for a nested resource, it's probably because of a naming issue. It's advised to add a `title` property to the schema definition with a unique name in that case.
+
 ## Logging
 
 When you want to know what the Reynard client is doing you can enable logging.
@@ -97,6 +168,16 @@ The logging should be compatible with the Ruby on Rails logger.
 reynard.logger(Rails.logger).execute
 ```
 
+## Debugging
+
+You can turn on debug logging in `Net::HTTP` by setting the `DEBUG` environment variable. After setting this, all HTTP interaction will be written to STDERR.
+
+```sh
+env DEBUG=true ruby script.rb
+```
+
+Internally this will set `http.debug_output = $stderr` on the HTTP object in the client.
+
 ## Mocking
 
 You can mock Reynard requests by changing the HTTP implementation. The class **must** implement a single `request` method that accepts an URI and net/http request object. It **must** return a net/http response object or an object with the exact same interface.

data/lib/reynard/context.rb

@@ -14,7 +14,7 @@ class Reynard
     end
 
     def base_url(base_url)
-      copy(base_url: base_url)
+      copy(base_url:)
     end
 
     def operation(operation_name)
@@ -43,7 +43,7 @@ class Reynard
     end
 
     def logger(logger)
-      copy(logger: logger)
+      copy(logger:)
     end
 
     def execute
@@ -71,7 +71,7 @@ class Reynard
       Reynard::Http::Response.new(
         specification: @specification,
         request_context: @request_context,
-        http_response: http_response
+        http_response:
       )
     end
   end

data/lib/reynard/http/response.rb

@@ -14,6 +14,38 @@ class Reynard
         @http_response = http_response
       end
 
+      # True when the response code is in the 1xx range.
+      def informational?
+        code.start_with?('1')
+      end
+
+      # True when the response code is in the 2xx range.
+      def success?
+        code.start_with?('2')
+      end
+
+      # True when the response code is in the 3xx range.
+      def redirection?
+        code.start_with?('3')
+      end
+
+      # True when the response code is in the 4xx range.
+      def client_error?
+        code.start_with?('4')
+      end
+
+      # True when the response code is in the 5xx range.
+      def server_error?
+        code.start_with?('5')
+      end
+
+      # Returns the parsed response body.
+      def parsed_body
+        return @parsed_body if defined?(@parsed_body)
+
+        @parsed_body = MultiJson.load(@http_response.body)
+      end
+
       # Instantiates an object based on the schema that fits the response.
       def object
         return @object if defined?(@object)
@@ -37,10 +69,9 @@ class Reynard
       end
 
       def build_object_with_media_type(media_type)
-        ObjectBuilder.new(
-          media_type: media_type,
+        ::Reynard::ObjectBuilder.new(
           schema: @specification.schema(media_type.node),
-          http_response: @http_response
+          parsed_body:
         ).call
       end
 

data/lib/reynard/media_type.rb

@@ -1,21 +1,12 @@
 # frozen_string_literal: true
 
 class Reynard
-  # Holds node reference and schema name to a media type in the API specification.
+  # Holds node reference a media type in the API specification.
   class MediaType
-    attr_reader :node, :schema_name
+    attr_reader :node
 
-    def initialize(node:, schema_name:)
+    def initialize(node:)
       @node = node
-      @schema_name = schema_name
-    end
-
-    def media_type
-      @node[6]
-    end
-
-    def response_code
-      @node[4]
     end
   end
 end

data/lib/reynard/model.rb

@@ -3,13 +3,18 @@
 class Reynard
   # Superclass for dynamic classes generated by the object builder.
   class Model
+    class << self
+      # Holds references to the full schema for the model if available.
+      attr_accessor :schema
+    end
+
     def initialize(attributes)
       self.attributes = attributes
     end
 
     def attributes=(attributes)
       attributes.each do |name, value|
-        instance_variable_set("@#{name}", value)
+        instance_variable_set("@#{name}", self.class.cast(name, value))
       end
     end
 
@@ -21,9 +26,18 @@ class Reynard
     end
 
     def respond_to_missing?(attribute_name, *)
-      !instance_variable_get("@#{attribute_name}").nil?
+      instance_variable_defined?("@#{attribute_name}")
     rescue NameError
       false
     end
+
+    def self.cast(name, value)
+      return value unless schema
+
+      property = schema.property_schema(name)
+      return value unless property
+
+      Reynard::ObjectBuilder.new(schema: property, parsed_body: value).call
+    end
   end
 end

data/lib/reynard/object_builder.rb

@@ -5,60 +5,78 @@ require 'ostruct'
 class Reynard
   # Defines dynamic classes based on schema and instantiates them for a response.
   class ObjectBuilder
-    def initialize(media_type:, schema:, http_response:)
-      @media_type = media_type
+    attr_reader :schema, :parsed_body
+
+    def initialize(schema:, parsed_body:, model_name: nil)
       @schema = schema
-      @http_response = http_response
+      @parsed_body = parsed_body
+      @model_name = model_name
     end
 
-    def object_class
-      if @media_type.schema_name
-        self.class.model_class(@media_type.schema_name, @schema.object_type)
-      elsif @schema.object_type == 'array'
-        Array
-      else
-        Reynard::Model
-      end
+    def model_name
+      @model_name || @schema.model_name
     end
 
-    def item_object_class
-      if @schema.item_schema_name
-        self.class.model_class(@schema.item_schema_name, 'object')
-      else
-        Reynard::Model
-      end
+    def model_class
+      return @model_class if defined?(@model_class)
+
+      @model_class =
+        self.class.model_class_get(model_name) || self.class.model_class_set(model_name, schema)
     end
 
     def call
-      if @schema.object_type == 'array'
-        array = object_class.new
-        data.each { |attributes| array << item_object_class.new(attributes) }
-        array
+      case schema.type
+      when 'object'
+        model_class.new(parsed_body)
+      when 'array'
+        cast_array
       else
-        object_class.new(data)
+        parsed_body
       end
     end
 
-    def data
-      @data ||= MultiJson.load(@http_response.body)
+    def self.model_class_get(model_name)
+      Kernel.const_get("::Reynard::Models::#{model_name}")
+    rescue NameError
+      nil
     end
 
-    def self.model_class(name, object_type)
-      model_class_get(name) || model_class_set(name, object_type)
+    def self.model_class_set(model_name, schema)
+      if schema.type == 'array'
+        array_model_class_set(model_name)
+      else
+        object_model_class_set(model_name, schema)
+      end
     end
 
-    def self.model_class_get(name)
-      Kernel.const_get("::Reynard::Models::#{name}")
-    rescue NameError
-      nil
+    def self.array_model_class_set(model_name)
+      return Array unless model_name
+
+      ::Reynard::Models.const_set(model_name, Class.new(Array))
     end
 
-    def self.model_class_set(name, object_type)
-      if object_type == 'array'
-        Reynard::Models.const_set(name, Class.new(Array))
-      else
-        Reynard::Models.const_set(name, Class.new(Reynard::Model))
+    def self.object_model_class_set(model_name, schema)
+      return Reynard::Model unless model_name
+
+      model_class = Class.new(Reynard::Model)
+      model_class.schema = schema
+      ::Reynard::Models.const_set(model_name, model_class)
+    end
+
+    private
+
+    def cast_array
+      return unless parsed_body
+
+      item_schema = schema.item_schema
+      array = model_class.new
+      parsed_body.each do |item|
+        array << self.class.new(
+          schema: item_schema,
+          parsed_body: item
+        ).call
       end
+      array
     end
   end
 end

data/lib/reynard/schema.rb

@@ -1,14 +1,110 @@
 # frozen_string_literal: true
 
 class Reynard
-  # Holds reference and object type for a schema in the API specification.
+  # Holds a references to a schema definition in the specification.
   class Schema
-    attr_reader :node, :object_type, :item_schema_name
+    attr_reader :node, :namespace
 
-    def initialize(node:, object_type:, item_schema_name:)
+    def initialize(specification:, node:, namespace: nil)
+      @specification = specification
       @node = node
-      @object_type = object_type
-      @item_schema_name = item_schema_name
+      @namespace = namespace
+    end
+
+    def type
+      return @type if defined?(@type)
+
+      @type = @specification.dig(*node, 'type')
+    end
+
+    def model_name
+      return @model_name if defined?(@model_name)
+
+      @model_name = find_model_name
+    end
+
+    # Returns the schema for items when the current schema is an array.
+    def item_schema
+      return unless type == 'array'
+
+      self.class.new(
+        specification: @specification,
+        node: [*node, 'items'],
+        namespace: [*namespace, model_name]
+      )
+    end
+
+    # Returns the schema for a propery in the schema.
+    def property_schema(name)
+      property_node = [*node, 'properties', name.to_s]
+      return unless @specification.dig(*property_node)
+
+      self.class.new(
+        specification: @specification,
+        node: property_node,
+        namespace: [*namespace, model_name]
+      )
+    end
+
+    def self.title_model_name(model_name)
+      return unless model_name
+
+      model_name
+        .gsub(/[^[:alpha:]]/, ' ')
+        .gsub(/\s{2,}/, ' ')
+        .gsub(/(\s+)([[:alpha:]])/) { Regexp.last_match(2).upcase }
+        .strip
+    end
+
+    # Extracts a model name from a ref when there is a usable value.
+    #
+    #   ref_model_name("#/components/schemas/Library") => "Library"
+    def self.ref_model_name(ref)
+      return unless ref
+
+      normalize_ref_model_name(ref.split('/')&.last)
+    end
+
+    def self.normalize_ref_model_name(model_name)
+      # 1. Unescape encoded characters to create an UTF-8 string
+      # 2. Remove extensions for regularly used external schema files
+      # 3. Replace all non-alphabetic characters with a space (not allowed in Ruby constant)
+      # 4. Camelcase
+      Rack::Utils.unescape_path(model_name)
+                 .gsub(/(.yml|.yaml|.json)\Z/, '')
+                 .gsub(/[^[:alpha:]]/, ' ')
+                 .gsub(/(\s+)([[:alpha:]])/) { Regexp.last_match(2).upcase }
+                 .gsub(/\A(.)/) { Regexp.last_match(1).upcase }
+    end
+
+    private
+
+    # Returns a model name based on the schema's title or $ref.
+    def find_model_name
+      title_model_name || ref_model_name || node_model_name
+    end
+
+    def title_model_name
+      title = @specification.dig(*node, 'title')
+      return unless title
+
+      self.class.title_model_name(title)
+    end
+
+    def ref_model_name
+      parent = @specification.dig(*node[..-2])
+      ref = parent.dig('schema', '$ref') || parent.dig('items', '$ref')
+      return unless ref
+
+      self.class.ref_model_name(ref)
+    end
+
+    def node_model_name
+      self.class.title_model_name(node_property_name.capitalize.gsub(/[_-]/, ' '))
+    end
+
+    def node_property_name
+      node.last == 'items' ? node.at(-2).chomp('s') : node.last
     end
   end
 end

data/lib/reynard/specification.rb

@@ -66,10 +66,7 @@ class Reynard
       response, media_type = media_type_response(responses, response_code, media_type)
       return unless response
 
-      MediaType.new(
-        node: [*operation_node, 'responses', response_code, 'content', media_type],
-        schema_name: schema_name(response)
-      )
+      MediaType.new(node: [*operation_node, 'responses', response_code, 'content', media_type])
     end
 
     def media_type_response(responses, response_code, media_type)
@@ -83,14 +80,9 @@ class Reynard
     end
 
     def schema(media_type_node)
-      schema = dig(*media_type_node, 'schema')
-      return unless schema
-
-      Schema.new(
-        node: [*media_type_node, 'schema'],
-        object_type: schema['type'],
-        item_schema_name: item_schema_name(schema)
-      )
+      return unless dig(*media_type_node, 'schema')
+
+      Schema.new(specification: self, node: [*media_type_node, 'schema'])
     end
 
     def self.media_type_matches?(media_type, expression)
@@ -100,26 +92,6 @@ class Reynard
       false
     end
 
-    def self.normalize_model_name(name)
-      # 1. Unescape encoded characters to create an UTF-8 string
-      # 2. Remove extensions for regularly used external schema files
-      # 3. Replace all non-alphabetic characters with a space (not allowed in Ruby constant)
-      # 4. Camelcase
-      Rack::Utils.unescape_path(name)
-                 .gsub(/(.yml|.yaml|.json)\Z/, '')
-                 .gsub(/[^[:alpha:]]/, ' ')
-                 .gsub(/(\s+)([[:alpha:]])/) { Regexp.last_match(2).upcase }
-                 .gsub(/\A(.)/) { Regexp.last_match(1).upcase }
-    end
-
-    def self.normalize_model_title(title)
-      title
-        .gsub(/[^[:alpha:]]/, ' ')
-        .gsub(/\s{2,}/, ' ')
-        .gsub(/(\s+)([[:alpha:]])/) { Regexp.last_match(2).upcase }
-        .strip
-    end
-
     private
 
     def read
@@ -156,27 +128,5 @@ class Reynard
     # rubocop:enable Metrics/AbcSize
     # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/MethodLength
-
-    def schema_name(response)
-      extract_schema_name(response['schema'])
-    end
-
-    def item_schema_name(schema)
-      if schema['type'] == 'array'
-        extract_schema_name(schema['items'])
-      else
-        extract_schema_name(schema)
-      end
-    end
-
-    def extract_schema_name(definition)
-      ref = definition['$ref']
-      return self.class.normalize_model_name(ref&.split('/')&.last) if ref
-
-      title = definition['title']
-      return unless title
-
-      self.class.normalize_model_title(title)
-    end
   end
 end

data/lib/reynard/template.rb

@@ -5,7 +5,7 @@ class Reynard
   #
   # See: RFC6570
   class Template
-    VARIABLE_RE = /\{([^}]+)\}/.freeze
+    VARIABLE_RE = /\{([^}]+)\}/
 
     def initialize(template, params)
       @template = template

data/lib/reynard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Reynard
-  VERSION = '0.5.1'
+  VERSION = '0.6.0'
 end

data/lib/reynard.rb

@@ -33,7 +33,7 @@ class Reynard
   autoload :VERSION, 'reynard/version'
 
   def initialize(filename:)
-    @specification = Specification.new(filename: filename)
+    @specification = Specification.new(filename:)
   end
 
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reynard
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Manfred Stienstra
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-05 00:00:00.000000000 Z
+date: 2022-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -143,7 +143,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -151,15 +151,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: Minimal OpenAPI client.
 test_files: []