sober_swag 0.21.0 → 0.24.0

data/lib/sober_swag/reporting/invalid_schema_error.rb

@@ -0,0 +1,21 @@
+module SoberSwag
+  module Reporting
+    ##
+    # Thrown we cannot generate a swagger schema for some reason.
+    #
+    # This typically only occurs if you use types that are too complicated.
+    # For example, an object type cannot be used as part of the path params.
+    class InvalidSchemaError < StandardError
+      def initialize(input)
+        @input = input
+
+        super("Could not generate schema for #{input}")
+      end
+
+      attr_reader :input
+
+      class InvalidForPathError < InvalidSchemaError; end
+      class InvalidForQueryError < InvalidSchemaError; end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/base.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Base type for simple outputs.
+      class Base
+        include Interface
+
+        ##
+        # Acceptable views to use with this output.
+        #
+        # @return [Set<Symbol>] the views
+        def views
+          %i[base].to_set
+        end
+
+        def view(view_key)
+          return self if view_key == :base
+
+          raise ArgumentError, "#{view_key} is not a view" unless views.include?(view_key)
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/bool.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output booleans.
+      class Bool < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not a boolean']) unless [true, false].include?(result)
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'boolean' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/defer.rb

@@ -0,0 +1,69 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Defer loading of an output for mutual recursion and/or loading time speed.
+      # Probably just do this for mutual recursion though.
+      #
+      # Note: this *does not* save you from infinite schema generation.
+      # This type *must* return some sort of {Referenced} type in order to do that!
+      #
+      # The common use case for this is mutual recursion.
+      # Something like...
+      #
+      # ```ruby
+      # class PersonOutput < SoberSwag::Reporting::Output::Struct
+      #   field :first_name, SoberSwag::Reporting::Output.text
+      #   view :detail do
+      #     field :classes, SoberSwag::Reporting::Output::Defer.new { ClassroomOutput.view(:base).array }
+      #   end
+      # end
+      #
+      # class ClassroomOutut < SoberSwag::Reporting::Output::Struct
+      #   field :class_name, SoberSwag::Reporting::Output.text
+      #
+      #   view :detail do
+      #     field :students, SoberSwag::Reporting::Output::Defer.new { PersonOutput.view(:base).array }
+      #   end
+      # end
+      # ```
+      class Defer < Base
+        ##
+        # Nicer initialization: uses a block.
+        #
+        # @yieldreturn [Interface] serializer to use.
+        def self.defer(&block)
+          new(block)
+        end
+
+        def initialize(other_lazy)
+          @other_lazy = other_lazy
+        end
+
+        attr_reader :other_lazy
+
+        ##
+        # @return [Interface]
+        def other
+          @other ||= other_lazy.call
+        end
+
+        def call(input)
+          other.call(input)
+        end
+
+        def serialize_report(input)
+          other.serialize_report(input)
+        end
+
+        def view(view)
+          other.view(view)
+        end
+
+        def swagger_schema
+          other.swagger_schema
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/described.rb

@@ -0,0 +1,42 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Add a description onto an object.
+      class Described < Base
+        def initialize(output, description)
+          @output = output
+          @description = description
+        end
+
+        ##
+        # @return [Interface] output to describe
+        attr_reader :output
+
+        ##
+        # @return [String] description of output
+        attr_reader :description
+
+        def call(value)
+          output.call(value)
+        end
+
+        def serialize_report(value)
+          output.serialize_report(value)
+        end
+
+        def swagger_schema
+          schema, found = output.swagger_schema
+
+          merged =
+            if schema.key?(:$ref)
+              { allOf: [schema] }
+            else
+              schema
+            end.merge(description: description)
+          [merged, found]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/dictionary.rb

@@ -0,0 +1,46 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output a dictionary of key-value pairs.
+      class Dictionary < Base
+        def self.of(valout)
+          new(valout)
+        end
+
+        def initialize(value_output)
+          @value_output = value_output
+        end
+
+        attr_reader :value_output
+
+        def call(item)
+          item.transform_values { |v| value_output.call(v) }
+        end
+
+        def serialize_report(item)
+          return Report::Base.new(['was not a dict']) unless item.is_a?(Hash)
+
+          bad, good = item.map { |k, v|
+            [k, value_output.serialize_report(v)]
+          }.compact.partition { |(_, v)| v.is_a?(Report::Base) }
+
+          return Report::Object.new(bad.to_h) if bad.any?
+
+          good.to_h
+        end
+
+        def swagger_schema
+          schema, found = value_output.swagger_schema
+          [
+            {
+              type: :object,
+              additionalProperties: schema
+            },
+            found
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/enum.rb

@@ -0,0 +1,47 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Models outputting an enum.
+      class Enum < Base
+        def initialize(output, values)
+          @output = output
+          @values = values
+        end
+
+        ##
+        # @return [Interface]
+        attr_reader :output
+
+        ##
+        # @return [Array]
+        attr_reader :values
+
+        def call(value)
+          output.call(value)
+        end
+
+        def serialize_report(value)
+          rep = output.serialize_report(value)
+
+          return rep if rep.is_a?(Report::Base)
+
+          return Report::Value.new(['was not an acceptable enum member']) unless values.include?(rep)
+
+          rep
+        end
+
+        def swagger_schema
+          schema, found = output.swagger_schema
+          merged =
+            if schema.key?(:$ref)
+              { allOf: [schema] }
+            else
+              schema
+            end.merge(enum: values)
+          [merged, found]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/in_range.rb

@@ -0,0 +1,64 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Specify that an output will be within a certain range.
+      # This gets translated to `minimum` and `maximum` keys in swagger.
+      class InRange < Base
+        def initialize(output, range)
+          @output = output
+          @range = range
+        end
+
+        ##
+        # @return [Interface]
+        attr_reader :output
+
+        ##
+        # @return [Range]
+        attr_reader :range
+
+        def call(value)
+          output.call(value)
+        end
+
+        def serialize_report(value)
+          rep = output.serialize_report(value)
+
+          return rep if rep.is_a?(Report::Base)
+
+          return Report::Value.new(['was not in minimum/maximum range']) unless range.member?(rep)
+
+          rep
+        end
+
+        def swagger_schema
+          schema, found = output.swagger_schema
+
+          merged =
+            if schema.key?(:$ref)
+              { allOf: [schema] }
+            else
+              schema
+            end.merge(maximum_portion).merge(minimum_portion)
+
+          [merged, found]
+        end
+
+        def maximum_portion
+          return {} unless range.end
+
+          res = { maximum: range.end }
+          res[:exclusiveMaximum] = true if range.exclude_end?
+          res
+        end
+
+        def minimum_portion
+          return {} unless range.begin
+
+          { minimum: range.begin }
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/interface.rb

@@ -0,0 +1,98 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Interface methods for all outputs.
+      module Interface
+        def call!(item)
+          res = serialize_report(item)
+
+          raise Report::Error.new(res) if res.is_a?(Report::Base) # rubocop:disable Style/RaiseArgs
+
+          res
+        end
+
+        ##
+        # Show off that this is a reporting output.
+        def reporting?
+          true
+        end
+
+        ##
+        # Delegates to {#call}
+        def serialize(item)
+          call(item)
+        end
+
+        def via_map(&block)
+          raise ArgumentError, 'block argument required' unless block
+
+          ViaMap.new(self, block)
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Output::Enum]
+        def enum(*cases)
+          Enum.new(self, cases)
+        end
+
+        def referenced(name)
+          Referenced.new(self, name)
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Output::InRange]
+        # Constrained values: must be within the given range.
+        def in_range(range)
+          raise ArgumentError, 'need a range' unless range.is_a?(Range)
+
+          InRange.new(self, range)
+        end
+
+        def list
+          List.new(self)
+        end
+
+        ##
+        # Partition this serializer into two potentials.
+        # If the block given returns *false*, we will use `other` as the serializer.
+        # Otherwise, we will use `self`.
+        #
+        # This might be useful to serialize a sum type:
+        #
+        # ```ruby
+        # ResolutionOutput = TransferOutput.partitioned(RefundOutput) { |to_serialize| to_serialize.is_a?(Transfer)
+        # ```
+        #
+        # @param other [Interface] serializer to use if the block returns false
+        # @yieldreturn [true,false] false if we should use the other serializer
+        # @return [Interface]
+        def partitioned(other, &block)
+          raise ArgumentError, 'need a block' if block.nil?
+
+          Partitioned.new(
+            block,
+            self,
+            other
+          )
+        end
+
+        def nilable
+          Partitioned.new(
+            :nil?.to_proc,
+            Null.new,
+            self
+          )
+        end
+
+        def array
+          List.new(self)
+        end
+
+        def described(description)
+          Described.new(self, description)
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/list.rb

@@ -0,0 +1,54 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Serialize a list of some other output type.
+      # Passes views down.
+      class List < Base
+        def initialize(element_output)
+          @element_output = element_output
+        end
+
+        attr_reader :element_output
+
+        def view(view)
+          List.new(element_output.view(view))
+        end
+
+        def views
+          element_output.views
+        end
+
+        def call(input)
+          input.map { |i| element_output.call(i) }
+        end
+
+        def swagger_schema
+          schema, found = element_output.swagger_schema
+          [
+            {
+              type: 'array',
+              items: schema
+            },
+            found
+          ]
+        end
+
+        def serialize_report(input)
+          return Report::Value.new(['could not be made an array']) unless input.respond_to?(:map)
+
+          errs = {}
+          mapped = input.map.with_index do |item, idx|
+            element_output.serialize_report(item).tap { |e| errs[idx] = e if e.is_a?(Report::Base) }
+          end
+
+          if errs.any?
+            Report::List.new(errs)
+          else
+            mapped
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/merge_objects.rb

@@ -0,0 +1,97 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Represents object that are marged with `allOf` in swagger.
+      #
+      # These *have* to be objects, due to how `allOf` works.
+      # This expresses a subtyping relationship.
+      #
+      # Note: non-careful use of this can generate impossible objects,
+      # IE, objects where a certain field has to be *both* a string and an integer or something.
+      # Subtyping is dangerous and should be used with care!
+      #
+      # This class is used in the implementation of {SoberSwag::Reporting::Output::Struct},
+      # in order to model the inheritence relationship structs have.
+      class MergeObjects < Base
+        ##
+        # @param parent [Interface] parent interface to use.
+        #   Should certainly be some sort of object, or a reference to it.
+        # @param child [Interface] child interface to use.
+        #   Should certainly be some sort of object, or a reference to it.
+        def initialize(parent, child)
+          @parent = parent
+          @child = child
+        end
+
+        ##
+        # @return [Interface] first object to merge
+        attr_reader :parent
+        ##
+        # @return [Interface] second object to merge
+        attr_reader :child
+
+        ##
+        # Serialize with the parent first, then merge in the child.
+        # This *does* mean that parent keys override child keys.
+        #
+        # If `parent` or `child` does not serialize some sort of object, this will result in an error.
+        def call(input)
+          parent.call(input).merge(child.call(input))
+        end
+
+        ##
+        # Child views.
+        def views
+          child.views
+        end
+
+        ##
+        # Passes on view to the *child object*.
+        def view(view)
+          MergeObjects.new(parent, child.view(view))
+        end
+
+        def serialize_report(value)
+          parent_attrs = parent.serialize_report(value)
+
+          return parent_attrs if parent_attrs.is_a?(Report::Value)
+
+          child_attrs = child.serialize_report(value)
+
+          return child_attrs if child_attrs.is_a?(Report::Value)
+
+          merge_results(parent_attrs, child_attrs)
+        end
+
+        ##
+        # Swagger schema.
+        #
+        # This will collapse 'allOf' keys, so a chain of parent methods will be
+        def swagger_schema # rubocop:disable Metrics/MethodLength
+          found = {}
+          mapped = [parent, child].flat_map do |i|
+            schema, item_found = i.swagger_schema
+            found.merge!(item_found)
+            if schema.key?(:allOf)
+              schema[:allOf]
+            else
+              [schema]
+            end
+          end
+          [{ allOf: mapped }, found]
+        end
+
+        private
+
+        def merge_results(par, chi)
+          return Report::MergedObject.new(par, chi) if [par, chi].all? { |c| c.is_a?(Report::Base) }
+          return par if par.is_a?(Report::Base)
+          return chi if chi.is_a?(Report::Base)
+
+          par.to_h.merge(chi.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/null.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output JSON nulls.
+      class Null < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not null']) unless result.nil?
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'null' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/number.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output numbers of some variety.
+      class Number < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not a number']) unless result.is_a?(Numeric)
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'number' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/object/property.rb

@@ -0,0 +1,45 @@
+module SoberSwag
+  module Reporting
+    module Output
+      class Object
+        ##
+        # Definitions for a specific property of an object.
+        class Property
+          def initialize(output, description: nil)
+            @output = output
+            @description = description
+          end
+          ##
+          # @return [Interface]
+          attr_reader :output
+
+          ##
+          # @return [String,nil]
+          attr_reader :description
+
+          def call(item, view: :base)
+            output.call(item, view: view)
+          end
+
+          def property_schema
+            direct, refined = output.swagger_schema
+
+            if description
+              [add_description(direct), refined]
+            else
+              [direct, refined]
+            end
+          end
+
+          def add_description(dir)
+            if dir.key?(:$ref)
+              { allOf: [dir] }
+            else
+              dir
+            end.merge(description: description)
+          end
+        end
+      end
+    end
+  end
+end