reynard 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb92e6d5c262256cca1fa813ac8bdb730ab427eeb227dec64475567fe65f4707
-  data.tar.gz: dbe5b3b93ac2fd2e702b40f738650bbec0d7feb7ee908b49eab366c2b058723c
+  metadata.gz: 2942c304a1a9caaae88253e2bce40188b79bb8a5d25ccd93c8e9a04f7730e386
+  data.tar.gz: 12948419634f2926ae083ae364bd35f48a6b79b8f6308df95b80baafe061dce6
 SHA512:
-  metadata.gz: 8ce40599d474dc127b6354f55f8157cccfd26f0d3fc786eb599d4da399a4658a7ce5d3f2505c579e712a38413043f03a5f788f8ac352beb55982dbac4a644134
-  data.tar.gz: 79738aae0d48f599f0f123fd0eb9365ce6de15995b9b7208b516d7205ec1bb023d8b7d14d181f82c238fd3415ab5f77ab102fc7593cee2febdd1c915572604cf
+  metadata.gz: 2bcf669808d10dfff594861274b301ff77c99038ddea5e121b0ccd61336beb7089e6c20f4e566c9a29e5b813194f5b79d07c7c067c720b6b303de8c07e862944
+  data.tar.gz: 64f7877a9a9e44c77cb357ff36d2ecac691cfce668dc2ba2197f0b68a284e0127fab96c099ca3cb99c0390658466a4fcda3569a2e2479e643d73f95d06cf2a16

data/README.md

@@ -48,7 +48,7 @@ reynard.base_url(base_url)
 
 ## Calling endpoints
 
-Assuming there is an operation called `employeeByUuid` you can it as shown below.
+Assuming there is an operation with the `operationId` set to `employeeByUuid` you can perform a request as shown below. Note that `operationId` is a required property in the specs.
 
 ```ruby
 response = reynard.
@@ -57,7 +57,7 @@ response = reynard.
   execute
 ```
 
-When an operation requires a body, you can add it as structured data.
+When an operation requires a body, you can add it as structured data. It will be converted to JSON automatically.
 
 ```ruby
 response = reynard.
@@ -66,13 +66,7 @@ response = reynard.
   execute
 ```
 
-In case the response matches a response in the specification it will attempt to build an object using the specified schema.
-
-```ruby
-response.object.name #=> 'Sam Seven'
-```
-
-The response object shared much of its interface with `Net::HTTP::Response`.
+The response object shares much of its interface with `Net::HTTP::Response`.
 
 ```ruby
 response.code #=> '200'
@@ -82,6 +76,24 @@ response.body #=> '{"name":"Sam Seven"}'
 response.parsed_body #=> { "name" => "Sam Seven" }
 ```
 
+You can test for groups of response codes, basically matching `1xx` through `5xx`.
+
+```ruby
+response.informational?
+response.success?
+response.redirection?
+response.client_error?
+response.server_error?
+```
+
+In case the response status and content-type matches a response in the specification it will attempt to build an object using the specified schema.
+
+```ruby
+response.object.name #=> 'Sam Seven'
+```
+
+See below for more details about the object builder.
+
 ## 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.
@@ -152,6 +164,148 @@ For example, in case of an array item it would look at `books` and singularize i
 
 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.
 
+### Properties and model attributes
+
+Reynard provides access to JSON properties on the model in a number of ways. There are some restrictions because of Ruby, so it's good to understand them.
+
+Let's assume there is a payload for an `Author` model that looks like this:
+
+```json
+{"first_name":"Marcél","lastName":"Marcellus","1st-class":false}
+```
+
+Reynard attemps to give access to these properties as much as possible by sanitizing and normalizing them, so you can do the following:
+
+```ruby
+response.object.first_name #=> "Marcél"
+response.object.last_name #=> "Marcellus"
+```
+
+But it's also possible to use the original casing for `lastName`.
+
+```ruby
+response.object.lastName #=> "Marcellus"
+```
+
+However, a method can't start with a number and can't contain dashes in Ruby so the following is not possible:
+
+```
+# Not valid Ruby syntax:
+response.object.1st-class
+```
+
+There are two alternatives for accessing this property:
+
+```ruby
+# The preferred solution for accessing raw property values is through the
+# parsed JSON on the response object.
+response.parsed_body["1st-class"]
+# When you are processing nested models and you don't have access to the
+# response object, you can choose to use the `[]` method.
+response.object["1st-class"]
+# Don't use `send` to access the property, this may not work in future
+# versions.
+response.object.send("1st-class")
+```
+
+#### Mapping properties
+
+In case you are forced to access a property through a method, you could choose to map irregular property names to method names globally for all models:
+
+```ruby
+reynard.snake_cases({ "1st-class" => "first_class" })
+```
+
+This will allow you to access the property through the `first_class` method without changing the behavior of the rest of the object.
+
+```ruby
+response.object.first_class #=> false
+response.object["1st-class"] #=> false
+```
+
+Don't use this to map common property names that would work fine otherwise, because you could make things really confusing.
+
+```ruby
+# Don't do this.
+reynard.snake_cases({ "name" => "naem" })
+```
+
+### Optional properties
+
+The current version of Reynard does not read or enforce the properties defined in the schema, instead it builds the response object based on the properties returned by the service. This was done deliberately to make it easier to access a server with a newer or older schema than the one used to build the Reynard instance.
+
+In the code that means that you may have to check if you are receiving certain attributes, you can do this in a number of ways:
+
+```ruby
+response.object.respond_to?(:name)
+response.parsed_body["name"]
+response.object["name"]
+```
+
+### Taking control of a model
+
+As noted earlier there is a deterministic way in which Reynard decides on a model name. This means that you can define the model name before Reynard gets to it.
+
+The easiest way to find out how Reynard does this, is to actually perform the operation and look at the response. Let's look at an example where Reynard creates  a `Library` model:
+
+```ruby
+response.object.class #=> Reynard::Models::Library
+response.parsed_body #=> {"name" => "Alexandria"}
+```
+
+One way to ensure that the response object has the required attributes is to defined a `valid?` method on it:
+
+
+```ruby
+class Reynard
+  module Models
+    class Library < Reynard::Model
+      def valid?
+        (%w[name] - @attributes.keys).empty?
+      end
+    end
+  end
+end
+```
+
+Next time you perform a request you can use your version of `Library`:
+
+```ruby
+if response.object.valid?
+  puts "The library is valid!"
+else
+  puts "The library is not valid :-( #{response.parsed_object.inspect}"
+end
+```
+
+Another way to do this is to override the `attributes=` method.
+
+```ruby
+def attributes=(attributes)
+  super # call super or nested attributes and other features will break
+  raise_invalid unless valid?
+end
+
+private
+
+def raise_invalid
+  return if valid?
+
+  raise(
+    ArgumentError,
+    "Library may not be initialized without all required attributes."
+  )
+end
+```
+
+A third way of dealing with optional attributes is to define an accessor yourself.
+
+```ruby
+def name
+  @attributes.fetch("name") { "Unnnamed library" }
+end
+```
+
 ## Logging
 
 When you want to know what the Reynard client is doing you can enable logging.
@@ -168,6 +322,19 @@ The logging should be compatible with the Ruby on Rails logger.
 reynard.logger(Rails.logger).execute
 ```
 
+## Headers
+
+You can add request headers at any time to a Reynard context, these are additive so you can easily have global headers for all requests and specific ones for an operation.
+
+```ruby
+reynard = reynard.headers(
+  {
+    "User-Agent" => "MyApplication/12.1.1 Reynard/#{Reynard::VERSION}",
+    "Accept" => "application/json"
+  }
+)
+```
+
 ## 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.

data/lib/reynard/context.rb

@@ -8,8 +8,9 @@ class Reynard
     extend Forwardable
     def_delegators :@request_context, :verb, :path, :full_path, :url
 
-    def initialize(specification:, request_context: nil)
+    def initialize(specification:, inflector:, request_context: nil)
       @specification = specification
+      @inflector = inflector
       @request_context = request_context || build_request_context
     end
 
@@ -59,6 +60,7 @@ class Reynard
     def copy(**properties)
       self.class.new(
         specification: @specification,
+        inflector: @inflector,
         request_context: @request_context.copy(**properties)
       )
     end
@@ -70,6 +72,7 @@ class Reynard
     def build_response(http_response)
       Reynard::Http::Response.new(
         specification: @specification,
+        inflector: @inflector,
         request_context: @request_context,
         http_response: http_response
       )

data/lib/reynard/external.rb

@@ -8,6 +8,7 @@ class Reynard
     def initialize(path:, ref:)
       @path = path
       @relative_path, @anchor = ref.split('#', 2)
+      @filename = File.expand_path(@relative_path, @path)
     end
 
     def path
@@ -22,11 +23,14 @@ class Reynard
       end
     end
 
+    def filesystem_path
+      File.dirname(@filename)
+    end
+
     private
 
     def filename
-      filename = File.expand_path(@relative_path, @path)
-      return filename if filename.start_with?(@path)
+      return @filename if @filename.start_with?(@path)
 
       raise 'You are only allowed to reference files relative to the specification file.'
     end

data/lib/reynard/http/response.rb

@@ -8,8 +8,9 @@ class Reynard
       extend Forwardable
       def_delegators :@http_response, :code, :content_type, :[], :body
 
-      def initialize(specification:, request_context:, http_response:)
+      def initialize(specification:, inflector:, request_context:, http_response:)
         @specification = specification
+        @inflector = inflector
         @request_context = request_context
         @http_response = http_response
       end
@@ -71,6 +72,7 @@ class Reynard
       def build_object_with_media_type(media_type)
         ObjectBuilder.new(
           schema: @specification.schema(media_type.node),
+          inflector: @inflector,
           parsed_body: parsed_body
         ).call
       end

data/lib/reynard/inflector.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Transforms property names so they are value Ruby identifiers or more readable to users.
+  class Inflector
+    def initialize
+      @snake_case = {}
+    end
+
+    # Registers additional exceptions to the regular snake-case algorithm. Registering is additive
+    # so you can call this multiple times without losing previously registered exceptions.
+    def snake_cases(exceptions)
+      @snake_case.merge!(exceptions)
+    end
+
+    # Returns the string in snake-case, taking previously registered exceptions into account.
+    def snake_case(property)
+      @snake_case[property] || self.class.snake_case(property)
+    end
+
+    # Returns the string in snake-case.
+    def self.snake_case(property)
+      property
+        .to_s
+        .gsub(/([A-Z])(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) { (Regexp.last_match(1) || Regexp.last_match(2)) << '_' }
+        .tr("'\"-", '___')
+        .downcase
+    end
+  end
+end

data/lib/reynard/model.rb

@@ -3,30 +3,45 @@
 class Reynard
   # Superclass for dynamic classes generated by the object builder.
   class Model
+    extend Forwardable
+    def_delegators :@attributes, :[]
+
     class << self
       # Holds references to the full schema for the model if available.
       attr_accessor :schema
+      # The inflector to use on properties.
+      attr_writer :inflector
     end
 
     def initialize(attributes)
+      @attributes = {}
+      @snake_cases = self.class.snake_cases(attributes.keys)
       self.attributes = attributes
     end
 
     def attributes=(attributes)
       attributes.each do |name, value|
-        instance_variable_set("@#{name}", self.class.cast(name, value))
+        @attributes[name.to_s] = self.class.cast(name, value)
       end
     end
 
     # Until we can set accessors based on the schema
     def method_missing(attribute_name, *)
-      instance_variable_get("@#{attribute_name}")
-    rescue NameError
+      attribute_name = attribute_name.to_s
+      if @attributes.key?(attribute_name)
+        @attributes[attribute_name]
+      else
+        @attributes.fetch(@snake_cases.fetch(attribute_name))
+      end
+    rescue KeyError
       raise NoMethodError, "undefined method `#{attribute_name}' for #{inspect}"
     end
 
     def respond_to_missing?(attribute_name, *)
-      instance_variable_defined?("@#{attribute_name}")
+      attribute_name = attribute_name.to_s
+      return true if @attributes.key?(attribute_name)
+
+      @snake_cases.key?(attribute_name) && @attributes.key?(@snake_cases[attribute_name])
     rescue NameError
       false
     end
@@ -37,7 +52,20 @@ class Reynard
       property = schema.property_schema(name)
       return value unless property
 
-      Reynard::ObjectBuilder.new(schema: property, parsed_body: value).call
+      Reynard::ObjectBuilder.new(schema: property, inflector: inflector, parsed_body: value).call
+    end
+
+    def self.inflector
+      @inflector ||= Inflector.new
+    end
+
+    def self.snake_cases(property_names)
+      property_names.each_with_object({}) do |property_name, snake_cases|
+        snake_case = inflector.snake_case(property_name)
+        next if snake_case == property_name
+
+        snake_cases[snake_case] = property_name
+      end
     end
   end
 end

data/lib/reynard/object_builder.rb

@@ -7,8 +7,9 @@ class Reynard
   class ObjectBuilder
     attr_reader :schema, :parsed_body
 
-    def initialize(schema:, parsed_body:, model_name: nil)
+    def initialize(schema:, inflector:, parsed_body:, model_name: nil)
       @schema = schema
+      @inflector = inflector
       @parsed_body = parsed_body
       @model_name = model_name
     end
@@ -21,7 +22,8 @@ class Reynard
       return @model_class if defined?(@model_class)
 
       @model_class =
-        self.class.model_class_get(model_name) || self.class.model_class_set(model_name, schema)
+        self.class.model_class_get(model_name) ||
+        self.class.model_class_set(model_name, schema, @inflector)
     end
 
     def call
@@ -41,11 +43,11 @@ class Reynard
       nil
     end
 
-    def self.model_class_set(model_name, schema)
+    def self.model_class_set(model_name, schema, inflector)
       if schema.type == 'array'
         array_model_class_set(model_name)
       else
-        object_model_class_set(model_name, schema)
+        object_model_class_set(model_name, schema, inflector)
       end
     end
 
@@ -55,11 +57,12 @@ class Reynard
       ::Reynard::Models.const_set(model_name, Class.new(Array))
     end
 
-    def self.object_model_class_set(model_name, schema)
+    def self.object_model_class_set(model_name, schema, inflector)
       return Reynard::Model unless model_name
 
       model_class = Class.new(Reynard::Model)
       model_class.schema = schema
+      model_class.inflector = inflector
       ::Reynard::Models.const_set(model_name, model_class)
     end
 
@@ -73,6 +76,7 @@ class Reynard
       parsed_body.each do |item|
         array << self.class.new(
           schema: item_schema,
+          inflector: @inflector,
           parsed_body: item
         ).call
       end

data/lib/reynard/specification.rb

@@ -14,7 +14,7 @@ class Reynard
 
     # Digs a value out of the specification, taking $ref into account.
     def dig(*path)
-      dig_into(@data, @data, path.dup)
+      dig_into(@data, @data, path.dup, File.dirname(@filename))
     end
 
     def servers
@@ -103,7 +103,7 @@ class Reynard
     # rubocop:disable Metrics/AbcSize
     # rubocop:disable Metrics/CyclomaticComplexity
     # rubocop:disable Metrics/MethodLength
-    def dig_into(data, cursor, path)
+    def dig_into(data, cursor, path, filesystem_path)
       while path.length.positive?
         cursor = cursor[path.first]
         return unless cursor
@@ -118,7 +118,8 @@ class Reynard
           cursor = data
         # References another file, with an optional anchor to an element in the data.
         when %r{\A\./}
-          external = External.new(path: File.dirname(@filename), ref: cursor['$ref'])
+          external = External.new(path: filesystem_path, ref: cursor['$ref'])
+          filesystem_path = external.filesystem_path
           path = external.path + path
           cursor = external.data
         end

data/lib/reynard/version.rb

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

data/lib/reynard.rb

@@ -13,11 +13,13 @@ class Reynard
   extend Forwardable
   def_delegators :build_context, :logger, :base_url, :operation, :headers, :params
   def_delegators :@specification, :servers
+  def_delegators :@inflector, :snake_cases
 
   autoload :Context, 'reynard/context'
   autoload :External, 'reynard/external'
   autoload :GroupedParameters, 'reynard/grouped_parameters'
   autoload :Http, 'reynard/http'
+  autoload :Inflector, 'reynard/inflector'
   autoload :Logger, 'reynard/logger'
   autoload :MediaType, 'reynard/media_type'
   autoload :Model, 'reynard/model'
@@ -34,6 +36,7 @@ class Reynard
 
   def initialize(filename:)
     @specification = Specification.new(filename: filename)
+    @inflector = Inflector.new
   end
 
   class << self
@@ -61,6 +64,6 @@ class Reynard
   private
 
   def build_context
-    Context.new(specification: @specification)
+    Context.new(specification: @specification, inflector: @inflector)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reynard
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Manfred Stienstra
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-28 00:00:00.000000000 Z
+date: 2023-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -70,6 +70,7 @@ files:
 - lib/reynard/http.rb
 - lib/reynard/http/request.rb
 - lib/reynard/http/response.rb
+- lib/reynard/inflector.rb
 - lib/reynard/media_type.rb
 - lib/reynard/model.rb
 - lib/reynard/models.rb