reynard 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1655a999a92e83993f4fdba62a9eedc870b18ada0339278d1c899e24f087b3bc
+  data.tar.gz: 926420c57d99767386d9aea1ef50b5bda317ea437a11dc3646bf3a5cc8a902be
+SHA512:
+  metadata.gz: 6c9834fae550aae2557a6833e4491eed9d426c9fdb5b6c2cf31ff5c9fe80569a00070affdfb76e9c90611400f959df5a7e377dfe906a813655e6b28bc3ced4ac
+  data.tar.gz: a22f676bb82b37d6bceb87028aeae10a78f2fd394cdef990eea7661842d1b0a2644ac20e5188f29730c62d54ab36498b1fe7112ebc1ffe872b3f3b6dfa848aff

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © Manfred Stienstra <manfred@fngtps.com>
+
+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,62 @@
+# Reynard
+
+Reynard is an OpenAPI client for Ruby. It operates directly on the OpenAPI specification without the need to generate any source code.
+
+```ruby
+# A Client does not have a fixed state and creating a new
+# client will never incur a cost over creating the object
+# itself.
+reynard = Reynard.new(filename: 'openapi.yml')
+```
+
+## Installing
+
+Reynard is distributed as a gem called `reynard`.
+
+## Choosing a server
+
+An OpenAPI specification may specify multiple servers. There is no automated way to select the ‘correct’ server so Reynard uses the first one by default.
+
+For example:
+
+```yaml
+servers:
+  - url: http://production.example.com/v1
+  - url: http://staging.example.com/v1
+```
+
+Will cause Reynard to choose the production URL.
+
+```ruby
+reynard.url #=> "http://production.example.com/v1"
+```
+
+You can override the `base_url` if you want to use a different one.
+
+```ruby
+reynard.base_url('http://test.example.com/v1')
+```
+
+You also have access to all servers in the specification so you can automatically select one however you want.
+
+```ruby
+base_url = @reynard.servers.map(&:url).find do |url|
+  /staging/.match(url)
+end
+reynard.base_url(base_url)
+```
+
+## Calling endpoints
+
+Assuming there is an operation called `employeeByUuid` you can it as shown below.
+
+```ruby
+employee = reynard.
+  operation('employeeByUuid').
+  params(uuid: uuid).
+  execute
+```
+
+## Copyright and other legal
+
+See LICENCE.

data/lib/reynard.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'multi_json'
+require 'rack'
+require 'yaml'
+require 'uri'
+
+# Reynard is a convenience class for configuring an HTTP request against an
+# OpenAPI specification.
+class Reynard
+  extend Forwardable
+  def_delegators :build_context, :base_url, :operation, :headers, :params
+  def_delegators :@specification, :servers
+
+  autoload :Context, 'reynard/context'
+  autoload :Http, 'reynard/http'
+  autoload :MediaType, 'reynard/media_type'
+  autoload :Model, 'reynard/model'
+  autoload :Models, 'reynard/models'
+  autoload :ObjectBuilder, 'reynard/object_builder'
+  autoload :Operation, 'reynard/operation'
+  autoload :RequestContext, 'reynard/request_context'
+  autoload :Schema, 'reynard/schema'
+  autoload :Server, 'reynard/server'
+  autoload :Specification, 'reynard/specification'
+  autoload :Template, 'reynard/template'
+  autoload :GroupedParameters, 'reynard/grouped_parameters'
+  autoload :VERSION, 'reynard/version'
+
+  def initialize(filename:)
+    @specification = Specification.new(filename: filename)
+  end
+
+  private
+
+  def build_context
+    Context.new(specification: @specification)
+  end
+end

data/lib/reynard/context.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Exposes a public interface to build a request context.
+  class Context
+    extend Forwardable
+    def_delegators :@request_context, :verb, :path, :full_path, :url
+
+    def initialize(specification:, request_context: nil)
+      @specification = specification
+      @request_context = request_context || build_request_context
+    end
+
+    def base_url(base_url)
+      copy(base_url: base_url)
+    end
+
+    def operation(operation_name)
+      copy(operation: @specification.operation(operation_name))
+    end
+
+    def params(params)
+      params = params.transform_keys(&:to_s)
+      copy(params: @specification.build_grouped_params(@request_context.operation.node, params))
+    end
+
+    def headers(headers)
+      copy(headers: headers)
+    end
+
+    def execute
+      build_object(build_request.perform)
+    end
+
+    private
+
+    def build_request_context
+      RequestContext.new(base_url: @specification.default_base_url)
+    end
+
+    def copy(**properties)
+      self.class.new(
+        specification: @specification,
+        request_context: @request_context.copy(**properties)
+      )
+    end
+
+    def build_request
+      Reynard::Http::Request.new(request_context: @request_context)
+    end
+
+    def build_object(http_response)
+      media_type = @specification.media_type(
+        @request_context.operation.node,
+        http_response.code,
+        http_response['Content-Type'].split(';').first
+      )
+      ObjectBuilder.new(
+        media_type: media_type,
+        schema: @specification.schema(media_type.node),
+        http_response: http_response
+      ).call
+    end
+  end
+end

data/lib/reynard/grouped_parameters.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Groups parameters based on the parameters specification.
+  class GroupedParameters
+    def initialize(specification, params)
+      @specification = pivot(specification)
+      @params = params
+    end
+
+    def to_h
+      @params.each_with_object({}) do |(name, value), grouped|
+        group_name = @specification.dig(name, 'in') || 'query'
+        grouped[group_name] ||= {}
+        grouped[group_name].merge!({ name => value })
+      end
+    end
+
+    private
+
+    def pivot(specification)
+      return {} unless specification
+
+      specification.each_with_object({}) do |attribute, pivot|
+        pivot[attribute['name']] = attribute
+      end
+    end
+  end
+end

data/lib/reynard/http.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Reynard
+  class Http
+    autoload :Request, 'reynard/http/request'
+  end
+end

data/lib/reynard/http/request.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'rack'
+
+class Reynard
+  class Http
+    # Configures and performs an HTTP request.
+    class Request
+      attr_reader :uri
+
+      def initialize(request_context:)
+        @request_context = request_context
+        @uri = URI(@request_context.url)
+      end
+
+      def perform
+        build_http.request(build_request)
+      end
+
+      private
+
+      def build_request
+        case @request_context.verb
+        when 'get'
+          build_http_get
+        when 'post'
+          build_http_post
+        end
+      end
+
+      def build_http
+        http = Net::HTTP.new(uri.hostname, uri.port)
+        http.set_debug_output($stderr) if ENV['DEBUG']
+        http
+      end
+
+      def build_http_get
+        Net::HTTP::Get.new(uri, @request_context.headers)
+      end
+
+      def build_http_post
+        post = Net::HTTP::Post.new(uri, @request_context.headers)
+        post.body = @request_context.body
+        post
+      end
+    end
+  end
+end

data/lib/reynard/media_type.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Holds node reference and schema name to a media type in the API specification.
+  class MediaType
+    attr_reader :node, :schema_name
+
+    def initialize(node:, schema_name:)
+      @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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Superclass for dynamic classes generated by the object builder.
+  class Model
+    def initialize(attributes)
+      self.attributes = attributes
+    end
+
+    def attributes=(attributes)
+      attributes.each do |name, value|
+        instance_variable_set("@#{name}", value)
+      end
+    end
+
+    # Until we can set accessors based on the schema
+    def method_missing(attribute_name, *)
+      instance_variable_get("@#{attribute_name}")
+    end
+
+    def respond_to_missing?(attribute_name, *)
+      !!instance_variable_get("@#{attribute_name}")
+    end
+  end
+end

data/lib/reynard/models.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Contains all dynamically generated classes.
+  module Models
+  end
+end

data/lib/reynard/object_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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
+      @schema = schema
+      @http_response = http_response
+    end
+
+    # Object.const_set(@media_type.schema_name, Class.new(Reynard::Model))
+    def object_class
+      if @media_type.schema_name
+        self.class.model_class(@media_type.schema_name)
+      else
+        OpenStruct
+      end
+    end
+
+    def call
+      case @media_type.media_type
+      when 'application/json'
+        object_class.new(MultiJson.load(@http_response.body))
+      else
+        FailedRequest.new
+      end
+    end
+
+    def self.model_class(name)
+      Reynard::Models.const_get(name)
+    rescue NameError
+      Reynard::Models.const_set(name, Class.new(Reynard::Model))
+    end
+  end
+end

data/lib/reynard/operation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Holds the node reference to an operation in the API specification.
+  class Operation
+    DEFAULT_MEDIA_TYPE = 'application/json'
+
+    attr_reader :node
+
+    def initialize(node:)
+      @node = node
+    end
+
+    def path
+      @node[1]
+    end
+
+    def verb
+      @node[2]
+    end
+  end
+end

data/lib/reynard/request_context.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Value class for details about the request.
+  RequestContext = Struct.new(
+    :base_url,
+    :operation,
+    :headers,
+    :params,
+    keyword_init: true
+  ) do
+    def verb
+      operation&.verb
+    end
+
+    def query
+      Rack::Utils.build_query(params['query']) if query_params?
+    end
+
+    def path
+      return unless operation&.path
+
+      Template.new(operation.path, params ? params.fetch('path', {}) : {}).result
+    end
+
+    def full_path
+      query_params? ? "#{path}?#{query}" : path
+    end
+
+    def url
+      return unless base_url
+
+      "#{base_url}#{full_path}"
+    end
+
+    def copy(**properties)
+      copy = dup
+      properties.each { |attribute, value| copy.send("#{attribute}=", value) }
+      copy
+    end
+
+    private
+
+    def query_params?
+      return false unless params
+
+      !params.fetch('query', {}).empty?
+    end
+
+    def path_params?
+      params&.key?('path')
+    end
+  end
+end

data/lib/reynard/schema.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Holds reference and object type for a schema in the API specification.
+  class Schema
+    attr_reader :node, :object_type
+
+    def initialize(node:, object_type:)
+      @node = node
+      @object_type = object_type
+    end
+  end
+end

data/lib/reynard/server.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Holds information about a server definition in the specification.
+  class Server < Model
+  end
+end

data/lib/reynard/specification.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Wraps the YAML representation of an OpenAPI specification.
+  class Specification
+    def initialize(filename:)
+      @filename = filename
+      @data = read
+    end
+
+    # Digs a value out of the specification, taking $ref into account.
+    def dig(*path)
+      dig_into(@data, @data, path.dup)
+    end
+
+    def servers
+      dig('servers').map { |attributes| Server.new(attributes) }
+    end
+
+    def default_base_url
+      servers.first&.url
+    end
+
+    # The specification tells us where a parameter should be included, they can be placed in path,
+    # query, header, or cookie. In order to get them in the correct place, we group them by their
+    # location.
+    #
+    #   build_grouped_params(operation_node, { 'q' => 'face' }) #=>
+    #     { 'query' => { 'q' => 'face' } }
+    def build_grouped_params(operation_node, params)
+      return {} unless params
+
+      GroupedParameters.new(dig(*operation_node, 'parameters'), params).to_h
+    end
+
+    def operation(operation_name)
+      dig('paths').each do |path, operations|
+        operations.each do |verb, operation|
+          return Operation.new(node: ['paths', path, verb]) if operation_name == operation['operationId']
+        end
+      end
+      nil
+    end
+
+    def media_type(operation_node, response_code, media_type)
+      responses = dig(*operation_node, 'responses')
+      response_code = responses.key?(response_code) ? response_code : 'default'
+      response = responses.dig(response_code, 'content', media_type)
+      return unless response
+
+      MediaType.new(
+        node: [*operation_node, 'responses', response_code, 'content', media_type],
+        schema_name: schema_name(response)
+      )
+    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'])
+    end
+
+    private
+
+    def read
+      File.open(@filename, encoding: 'UTF-8') do |file|
+        YAML.safe_load(file)
+      end
+    end
+
+    def dig_into(data, cursor, path)
+      while path.length.positive?
+        cursor = cursor[path.first]
+        return unless cursor
+
+        path.shift
+        next unless cursor.respond_to?(:key?) && cursor&.key?('$ref')
+
+        # We currenly only supply references inside the document starting with #/.
+        path = cursor['$ref'][2..].split('/') + path
+        cursor = data
+      end
+      cursor
+    end
+
+    def schema_name(response)
+      ref = response.dig('schema', '$ref')
+      ref&.split('/')&.last
+    end
+
+    def object_name(_schema)
+      'Book'
+    end
+  end
+end

data/lib/reynard/template.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Basic implementation of URI templates.
+  #
+  # See: RFC6570
+  class Template
+    VARIABLE_RE = /\{([^}]+)\}/.freeze
+
+    def initialize(template, params)
+      @template = template
+      @params = params
+    end
+
+    def result
+      @template.gsub(VARIABLE_RE) do
+        Rack::Utils.escape_path(@params.fetch(Regexp.last_match(1)).to_s)
+      end
+    end
+  end
+end

data/lib/reynard/version.rb

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

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: reynard
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Manfred Stienstra
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-08-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+    Reynard is an OpenAPI client for Ruby. It operates directly on the OpenAPI specification without
+    the need to generate any source code.
+email:
+- manfred@fngtps.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/reynard.rb
+- lib/reynard/context.rb
+- lib/reynard/grouped_parameters.rb
+- lib/reynard/http.rb
+- lib/reynard/http/request.rb
+- lib/reynard/media_type.rb
+- lib/reynard/model.rb
+- lib/reynard/models.rb
+- lib/reynard/object_builder.rb
+- lib/reynard/operation.rb
+- lib/reynard/request_context.rb
+- lib/reynard/schema.rb
+- lib/reynard/server.rb
+- lib/reynard/specification.rb
+- lib/reynard/template.rb
+- lib/reynard/version.rb
+homepage: https://github.com/Manfred/reynard
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Minimal OpenAPI client.
+test_files: []