sober_swag 0.1.0

data/lib/sober_swag/compiler.rb

@@ -0,0 +1,107 @@
+module SoberSwag
+  ##
+  # Compiler for an entire API.
+  #
+  # This compiler has a *lot* of state as we need to get
+  class Compiler
+    autoload(:Type, 'sober_swag/compiler/type')
+    autoload(:Error, 'sober_swag/compiler/error')
+    autoload(:Path, 'sober_swag/compiler/path')
+    autoload(:Paths, 'sober_swag/compiler/paths')
+
+    def initialize
+      @types = Set.new
+      @paths = Paths.new
+    end
+
+    ##
+    # Convert a compiler to the overall type definition.
+    def to_swagger
+      {
+        paths: path_schemas,
+        components: {
+          schemas: object_schemas
+        }
+      }
+    end
+
+    ##
+    # Add a path to be compiled.
+    # @param route [SoberSwag::Controller::Route] the route to add.
+    def add_route(route)
+      tap { @paths.add_route(route) }
+    end
+
+    def object_schemas
+      @types.map { |v| [v.ref_name, v.object_schema] }.to_h
+    end
+
+    ##
+    # The path section of the swagger schema.
+    def path_schemas
+      @paths.paths_list(self)
+    end
+
+    ##
+    # Compile a type to a new, path-params list.
+    # This will add all subtypes to the found types list.
+    def path_params_for(type)
+      with_types_discovered(type).path_schema
+    end
+
+    ##
+    # Get the query params list for a type.
+    # All found types will be added to the reference dictionary.
+    def query_params_for(type)
+      with_types_discovered(type).query_schema
+    end
+
+    ##
+    # Get the request body definition for a type.
+    # This will always be a ref.
+    def body_for(type)
+      add_type(type)
+      Type.new(type).schema_stub
+    end
+
+    ##
+    # Get the definition of a response type
+    def response_for(type)
+      body_for(type)
+    end
+
+    ##
+    # Get the existing schema for a given type
+    def schema_for(type)
+      @types.find { |type_comp| type_comp.type == type }&.object_schema
+    end
+
+    ##
+    # Add a type in the types reference dictionary, essentially
+    def add_type(type)
+      # use tap here to avoid an explicit self at the end of this
+      # which makes this method chainable
+      tap do
+        type_compiler = Type.new(type)
+
+        ##
+        # Do nothing if we already have a type
+        return self if @types.include?(type_compiler)
+
+        @types.add(type_compiler) if type_compiler.standalone?
+
+        type_compiler.found_types.each do |ft|
+          add_type(ft)
+        end
+      end
+    end
+
+    private
+
+    def with_types_discovered(type)
+      Type.new(type).tap do |type_compiler|
+        type_compiler.found_types.each { |ft| add_type(ft) }
+      end
+    end
+  end
+end

data/lib/sober_swag/controller/route.rb

@@ -0,0 +1,136 @@
+require 'sober_swag/blueprint'
+
+module SoberSwag
+  module Controller
+    class Route
+
+      def initialize(method, action_name, path)
+        @method = method
+        @path = path
+        @action_name = action_name
+        @response_serializers = {}
+        @response_descriptions = {}
+      end
+
+      attr_reader :response_serializers
+      attr_reader :response_descriptions
+      attr_reader :controller
+      attr_reader :method
+      attr_reader :path
+      attr_reader :action_name
+      ##
+      # What to parse the request body in to.
+      attr_reader :request_body_class
+      ##
+      # What to parse the request query_params in to
+      attr_reader :query_params_class
+
+      ##
+      # What to parse the path params into
+      attr_reader :path_params_class
+
+      ##
+      # Define the request body, using SoberSwag's type-definition scheme.
+      # The block passed will be used to define the body of a new sublcass of `base` (defaulted to {Dry::Struct}.)
+      # If you want, you can also define utility methods in here
+      def request_body(base = Dry::Struct, &block)
+        @request_body_class = make_struct!(base, &block)
+        action_module.const_set('ResponseBody', @request_body_class)
+      end
+
+      ##
+      # Does this route have a body defined?
+      def request_body?
+        !request_body_class.nil?
+      end
+
+      ##
+      # Define the shape of the query_params parameters, using SoberSwag's type-definition scheme.
+      # The block passed is the body of the newly-defined type.
+      # You can also include a base type.
+      def query_params(base = Dry::Struct, &block)
+        @query_params_class = make_struct!(base, &block)
+        action_module.const_set('QueryParams', @query_params_class)
+      end
+
+      ##
+      # Does this route have query params defined?
+      def query_params?
+        !query_params_class.nil?
+      end
+
+      ##
+      # Define the shape of the *path* parameters, using SoberSwag's type-definition scheme.
+      # The block passed will be the body of a new subclass of `base` (defaulted to {Dry::Struct}).
+      # Names of this should match the names in the path template originally passed to {SoberSwag::Controller::Route.new}
+      def path_params(base = Dry::Struct, &block)
+        @path_params_class = make_struct!(base, &block)
+        action_module.const_set('PathParams', @path_params_class)
+      end
+
+      ##
+      # Does this route have path params defined?
+      def path_params?
+        !path_params_class.nil?
+      end
+
+      ##
+      # Define the body of the action method in the controller.
+      def action(&body)
+        return @action if body.nil?
+
+        @action ||= body
+      end
+
+      def description(desc = nil)
+        return @description if desc.nil?
+
+        @description = desc
+      end
+
+      def summary(sum = nil)
+        return @summary if sum.nil?
+
+        @summary = sum
+      end
+
+      ##
+      # The container module for all the constants this will eventually define.
+      # Each class generated by this Route will be defined within this module.
+      def action_module
+        @action_module ||= Module.new
+      end
+
+      ##
+      # Define a serializer for a response with the given status code.
+      # You may either give a serializer you defined elsewhere, or define one inline as if passed to
+      # {SoberSwag::Blueprint.define}
+      def response(status_code, description, serializer = nil, &block)
+        status_key = Rack::Utils.status_code(status_code)
+
+        raise ArgumentError, 'Response defiend!' if @response_serializers.key?(status_key)
+
+        serializer ||= SoberSwag::Blueprint.define(&block)
+        response_module.const_set(status_code.to_s.classify, serializer)
+        @response_serializers[status_key] = serializer
+        @response_descriptions[status_key] = description
+      end
+
+      ##
+      # What you should call the module of this action in your controller
+      def action_module_name
+        action_name.to_s.classify
+      end
+
+      private
+
+      def response_module
+        @response_module ||= Module.new.tap { |m| action_module.const_set(:Response, m) }
+      end
+
+      def make_struct!(base, &block)
+        Class.new(base, &block).tap { |e| e.transform_keys(&:to_sym) if base == Dry::Struct }
+      end
+    end
+  end
+end

data/lib/sober_swag/controller/undefined_body_error.rb

@@ -0,0 +1,6 @@
+module SoberSwag
+  module Controller
+    class UndefinedBodyError < Error
+    end
+  end
+end

data/lib/sober_swag/controller/undefined_path_error.rb

@@ -0,0 +1,6 @@
+module SoberSwag
+  module Controller
+    class UndefinedPathError < Error
+    end
+  end
+end

data/lib/sober_swag/controller/undefined_query_error.rb

@@ -0,0 +1,6 @@
+module SoberSwag
+  module Controller
+    class UndefinedQueryError < Error
+    end
+  end
+end

data/lib/sober_swag/controller.rb

@@ -0,0 +1,157 @@
+require 'active_support/concern'
+
+module SoberSwag
+  ##
+  # Controller concern
+  module Controller
+    extend ActiveSupport::Concern
+
+    autoload :UndefinedBodyError, 'sober_swag/controller/undefined_body_error'
+    autoload :UndefinedPathError, 'sober_swag/controller/undefined_path_error'
+    autoload :UndefinedQueryError, 'sober_swag/controller/undefined_query_error'
+
+    module Types
+      include ::Dry::Types()
+    end
+
+    class_methods do
+      ##
+      # Define a new action with the given HTTP method, action name, and path.
+      # This will eventaully delegate to making an actual method on your controller,
+      # so you can use controllers as you wish with no harm.
+      #
+      # This method takes a block, evaluated in the context of a {SoberSwag::Controller::Route}.
+      # Used like:
+      #     define(:get, :show, '/posts/{id}') do
+      #       path_params do
+      #         attribute :id, Types::Integer
+      #       end
+      #       action do
+      #         @post = Post.find(parsed_path.id)
+      #         render json: @post
+      #       end
+      #     end
+      #
+      # This will define an "action module" on this class to contain the generated types.
+      # In the above example, the following constants will be deifned on the controller:
+      #     PostsController::Show # the container module for everything in this action
+      #     PostsController::Show::PathParams # the dry-struct type for the path attribute.
+      # So, in the same controller, you can refer to Show::PathParams to get the type created by the 'path_params' block above.
+      def define(method, action, path, &block)
+        r = Route.new(method, action, path)
+        r.instance_eval(&block)
+        const_set(r.action_module_name, r.action_module)
+        defined_routes << r
+        define_method(action, r.action) if r.action
+      end
+
+      ##
+      # All the routes that this controller knows about.
+      def defined_routes
+        @defined_routes ||= []
+      end
+
+      ##
+      # Find a route with the given name.
+      def find_route(name)
+        defined_routes.find { |r| r.action_name.to_s == name.to_s }
+      end
+
+      ##
+      # A swagger definition for *this controller only*.
+      def swagger_info
+        @swagger_info ||=
+          begin
+            res = defined_routes.reduce(SoberSwag::Compiler.new) { |c, r| c.add_route(r) }
+            {
+              openapi: '3.0.0',
+              info: {
+                version: '1',
+                title: self.name
+              }
+            }.merge(res.to_swagger)
+          end
+      end
+    end
+
+    ##
+    # Action to get the singular swagger for this entire API.
+    def swagger
+      render json: self.class.swagger_info
+    end
+
+    ##
+    # Get the path parameters, parsed into the type you defined with {SoberSwag::Controller.define}
+    # @raise [UndefinedPathError] if there's no path params defined for this route
+    # @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.
+    def parsed_path
+      @parsed_path ||=
+        begin
+          r = current_action_def
+          raise UndefinedPathError unless r&.path_params_class
+          r.path_params_class.new(request.path_parameters)
+        end
+    end
+
+    ##
+    # Get the request body, parsed into the type you defined with {SoberSwag::Controller.define}.
+    # @raise [UndefinedBodyError] if there's no request body defined for this route
+    # @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.
+    def parsed_body
+      @parsed_body ||=
+        begin
+          r = current_action_def
+          raise UndefinedBodyError unless r&.request_body_class
+          r.request_body_class.new(body_params)
+        end
+    end
+
+    ##
+    # Get the query params, parsed into the type you defined with {SoberSwag::Controller.define}
+    # @raise [UndefinedQueryError] if there's no query params defined for this route
+    # @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.
+    def parsed_query
+      @parsed_query ||=
+        begin
+          r = current_action_def
+          raise UndefinedQueryError unless r&.query_params_class
+          r.query_params_class.new(request.query_parameters)
+        end
+    end
+
+    ##
+    # Respond with the serialized type that you defined for this route.
+    # @todo figure out how to specify views and other options for the serializer here
+    # @param status [Symbol] the HTTP status symbol to use for the status code
+    # @param entity the thing to serialize
+    def respond!(status, entity)
+      r = current_action_def
+      serializer = r.response_serializers[Rack::Utils.status_code(status)]
+      serializer ||= serializer.new if serializer.respond_to?(:new)
+      render json: serializer.serialize(entity)
+    end
+
+    ##
+    # Obtain a parameters hash of *only* those parameters which come in the hash.
+    # These will be *unsafe* in the sense that they will all be allowed.
+    # This kinda violates the "be liberal in what you accept" principle,
+    # but it keeps the docs honest: parameters sent in the body *must* be
+    # in the body.
+    def body_params
+      bparams = params.reject do |k, _|
+        request.query_parameters.key?(k) || request.path_parameters.key?(k)
+      end
+      bparams.permit(bparams.keys)
+    end
+
+    ##
+    # Get the action-definition for the current action.
+    # Under the hood, delegates to the `:action` key of rails params.
+    def current_action_def
+      self.class.find_route(params[:action])
+    end
+
+  end
+end
+
+require 'sober_swag/controller/route'

data/lib/sober_swag/nodes/array.rb

@@ -0,0 +1,30 @@
+module SoberSwag
+  module Nodes
+    ##
+    # Base class for nodes that contain arrays of other nodes.
+    # This is very different from an attribute representing a node which *is* an array of some element type!!
+    class Array < Base
+      def initialize(elements)
+        @elements = elements
+      end
+
+      attr_reader :elements
+
+      def map(&block)
+        self.class.new(elements.map { |elem| elem.map(&block) })
+      end
+
+      def cata(&block)
+        block.call(self.class.new(elements.map { |elem| elem.cata(&block) }))
+      end
+
+      def deconstruct
+        @elements
+      end
+
+      def deconstruct_keys(keys)
+        { elements: @elements }
+      end
+    end
+  end
+end

data/lib/sober_swag/nodes/attribute.rb

@@ -0,0 +1,31 @@
+module SoberSwag
+  module Nodes
+    ##
+    # One attribute of an object.
+    class Attribute
+      def initialize(key, required, value)
+        @key = key
+        @required = required
+        @value = value
+      end
+
+      def deconstruct
+        [key, required, value]
+      end
+
+      def deconstruct_keys
+        { key: key, required: required, value: value }
+      end
+
+      attr_reader :key, :required, :value
+
+      def map(&block)
+        self.class.new(key, required, value.map(&block))
+      end
+
+      def cata(&block)
+        block.call(self.class.new(key, required, value.cata(&block)))
+      end
+    end
+  end
+end

data/lib/sober_swag/nodes/base.rb

@@ -0,0 +1,51 @@
+module SoberSwag
+  module Nodes
+    ##
+    # Base Node that all other nodes inherit from.
+    # All nodes should define the following:
+    #
+    # - #deconstruct, which returns an array of *everything needed to idenitfy the node.*
+    #   We base comparisons on the result of deconstruction.
+    # - #deconstruct_keys, which returns a hash of *everything needed to identify the node*.
+    #   We use this later.
+    class Base
+
+      include Comparable
+
+      ##
+      # Value-level comparison.
+      def <=>(other)
+        return other.class.name <=> self.class.name unless other.class == self.class
+
+        deconstruct <=> other.deconstruct
+      end
+
+      def eql?(other)
+        deconstruct == other.deconstruct
+      end
+
+      def hash
+        deconstruct.hash
+      end
+
+      ##
+      # Perform a catamorphism, or, a deep-first recursion.
+      #
+      # The basic way this works is deceptively simple: When you use 'cata' on a node,
+      # it will call the block you gave it with the *deepest* nodes in the tree first.
+      # It will then use the result of that block to reconstruct their *parent* node, and then
+      # *call cata again* on the parent, and so on until we reach the top.
+      #
+      # When working with these definition nodes, we very often want to transform something recursively.
+      # This method allows us to do so by focusing on a single level at a time, keeping the actual recursion *abstract*.
+      def cata(&block)
+        raise ArgumentError, 'Base is abstract'
+      end
+
+      def map(&block)
+        raise ArgumentError, 'Base is abstract'
+      end
+
+    end
+  end
+end

data/lib/sober_swag/nodes/binary.rb

@@ -0,0 +1,44 @@
+module SoberSwag
+  module Nodes
+    ##
+    # A
+    #
+    # It's cool I promise.
+    class Binary < Base
+      def initialize(lhs, rhs)
+        @lhs = lhs
+        @rhs = rhs
+      end
+
+      attr_reader :lhs, :rhs
+      ##
+      # Map the root values of the node.
+      # This just calls map on the lhs and the rhs
+      def map(&block)
+        self.class.new(
+          lhs.map(&block),
+          rhs.map(&block)
+        )
+      end
+
+      def deconstruct
+        [lhs, rhs]
+      end
+
+      def deconstruct_keys(keys)
+        { lhs: lhs, rhs: rhs }
+      end
+
+      ##
+      # Perform a catamorphism on this node.
+      def cata(&block)
+        block.call(
+          self.class.new(
+            lhs.cata(&block),
+            rhs.cata(&block)
+          )
+        )
+      end
+    end
+  end
+end

data/lib/sober_swag/nodes/enum.rb

@@ -0,0 +1,28 @@
+module SoberSwag
+  module Nodes
+    class Enum < Base
+
+      def initialize(values)
+        @values = values
+      end
+
+      attr_reader :values
+
+      def map(&block)
+        self.class.new(@values.map(&block))
+      end
+
+      def deconstruct
+        [values]
+      end
+
+      def deconstruct_keys(keys)
+        { values: values }
+      end
+
+      def cata(&block)
+        block.call(dup)
+      end
+    end
+  end
+end

data/lib/sober_swag/nodes/list.rb

@@ -0,0 +1,40 @@
+module SoberSwag
+  module Nodes
+    ##
+    # A List of the contained element types.
+    #
+    # Unlike {SoberSwag::Nodes::Array}, this actually models arrays.
+    # The other one is a node that *is* an array in terms of what it contains.
+    # Kinda confusing, but oh well.
+    class List < Base
+      def initialize(element)
+        @element = element
+      end
+
+      attr_reader :element
+
+      def deconstruct
+        [element]
+      end
+
+      def deconstruct_keys(_)
+        { element: element }
+      end
+
+      def cata(&block)
+        block.call(
+          self.class.new(
+            element.cata(&block)
+          )
+        )
+      end
+
+      def map(&block)
+        self.class.new(
+          element.map(&block)
+        )
+      end
+
+    end
+  end
+end

data/lib/sober_swag/nodes/nullable_primitive.rb

@@ -0,0 +1,6 @@
+module SoberSwag
+  module Nodes
+    class NullablePrimitive < Primitive
+    end
+  end
+end

data/lib/sober_swag/nodes/object.rb

@@ -0,0 +1,12 @@
+module SoberSwag
+  module Nodes
+    ##
+    # Objects might have attribute keys, so they're
+    # basically a list of attributes
+    class Object < SoberSwag::Nodes::Array
+      def deconstruct_keys(_)
+        { attributes: @elements }
+      end
+    end
+  end
+end

data/lib/sober_swag/nodes/one_of.rb

@@ -0,0 +1,12 @@
+module SoberSwag
+  module Nodes
+    ##
+    # Swagges uses an array of OneOf types, so we
+    # transform our sum nodes into this
+    class OneOf < ::SoberSwag::Nodes::Array
+      def deconstruct_keys(_)
+        { alternatives: @elemenets }
+      end
+    end
+  end
+end