apia 3.0.0

data/lib/apia/controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'apia/defineable'
+require 'apia/definitions/controller'
+require 'apia/helpers'
+
+module Apia
+  class Controller
+
+    extend Defineable
+
+    class << self
+
+      # Return the definition object for the controller
+      #
+      # @return [Apia::Definitions::Controller]
+      def definition
+        @definition ||= Definitions::Controller.new(Helpers.class_name_to_id(name))
+      end
+
+      # Collate all objects that this controller references and add them to the
+      # given object set
+      #
+      # @param set [Apia::ObjectSet]
+      # @return [void]
+      def collate_objects(set)
+      end
+
+    end
+
+  end
+end

data/lib/apia/defineable.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Apia
+  module Defineable
+
+    # Inspect an object
+    #
+    # @return [String]
+    def inspect
+      type = ancestors.find { |c| c.name =~ /\AApia::/ }
+      "<#{definition.id} [#{type}]>"
+    end
+
+    # Create a new object
+    #
+    # @param id [String]
+    # @return [Class]
+    def create(id, &block)
+      klass = Class.new(self)
+      klass.definition.id = id
+      if block_given?
+        klass.definition.dsl.instance_eval(&block)
+      end
+      klass
+    end
+
+    # Ability to set a name (for DSL purposes) but also returns a name
+    # of the actual class if no new value is provided
+    #
+    # @param new_name [String, nil]
+    # @return [String]
+    def name(new_name = nil)
+      if new_name
+        definition.name = new_name
+        return new_name
+      end
+
+      super()
+    end
+
+    # Passes all other values through to the DSL for the definition if
+    # the DSL supoprts it.
+    def method_missing(name, *args, **kwargs, &block)
+      if definition.dsl.respond_to?(name)
+        if kwargs.empty?
+          definition.dsl.send(name, *args, &block)
+        else
+          definition.dsl.send(name, *args, **kwargs, &block)
+        end
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      definition.dsl.respond_to?(name) || super
+    end
+
+  end
+end

data/lib/apia/definition.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Apia
+  class Definition
+
+    attr_accessor :id
+    attr_accessor :name
+    attr_accessor :description
+    attr_accessor :schema
+
+    def initialize(id)
+      @id = id
+      setup
+    end
+
+    def schema?
+      @schema != false
+    end
+
+    def validate(errors)
+    end
+
+    def setup
+    end
+
+  end
+end

data/lib/apia/definitions/api.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/api'
+require 'apia/hook_set'
+require 'apia/route_set'
+
+module Apia
+  module Definitions
+    class API < Definition
+
+      attr_accessor :authenticator
+      attr_reader :controllers
+      attr_reader :route_set
+      attr_reader :exception_handlers
+      attr_reader :scopes
+
+      def setup
+        @route_set = RouteSet.new
+        @controllers = {}
+        @exception_handlers = HookSet.new
+        @scopes = {}
+      end
+
+      def dsl
+        @dsl ||= DSLs::API.new(self)
+      end
+
+      # Validate the API to ensure that everything within is acceptable for use
+      #
+      # @param errors [Apia::ManifestErrors]
+      # @return [void]
+      def validate(errors)
+        if @authenticator && !(@authenticator.respond_to?(:ancestors) && @authenticator.ancestors.include?(Apia::Authenticator))
+          errors.add self, 'InvalidAuthenticator', 'The authenticator must be a class that inherits from Apia::Authenticator'
+        end
+
+        @controllers.each do |name, controller|
+          unless name.to_s =~ /\A[\w\-]+\z/i
+            errors.add self, 'InvalidControllerName', "The controller name #{name} is invalid. It can only contain letters, numbers, underscores, and hyphens"
+          end
+
+          unless controller.respond_to?(:ancestors) && controller.ancestors.include?(Apia::Controller)
+            errors.add self, 'InvalidController', "The controller for #{name} must be a class that inherits from Apia::Controller"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/argument.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/argument'
+require 'apia/helpers'
+
+module Apia
+  module Definitions
+    class Argument < Definition
+
+      attr_reader :options
+      attr_reader :validations
+      attr_accessor :required
+      attr_accessor :array
+      attr_accessor :default
+      attr_writer :type
+
+      def initialize(name, id: nil)
+        @id = id
+        @name = name
+        @validations = []
+      end
+
+      def dsl
+        @dsl ||= DSLs::Argument.new(self)
+      end
+
+      def validate(errors)
+        if @name.nil?
+          errors.add self, 'MissingName', 'Arguments must have a name'
+        elsif @name.to_s !~ /\A[a-z0-9\-_]+\z/i
+          errors.add self, 'InvalidName', 'Argument name must only include letters, numbers, hyphens and underscores'
+        end
+
+        if @type.nil?
+          errors.add self, 'MissingType', 'Arguments must have a type'
+        elsif !type.usable_for_argument?
+          errors.add self, 'InvalidType', 'Type must be an argument set, scalar or enum'
+        end
+      end
+
+      # Return the type of object (either a ArgumentSet or a Scalar) which
+      # this argument represents.
+      #
+      # @return [Class]
+      def type
+        Type.new(@type)
+      end
+
+      # Is this argument required?
+      #
+      # @return [Boolean]
+      def required?
+        @required == true
+      end
+
+      # Is this an array?
+      #
+      # @return [Boolean]
+      def array?
+        @array == true
+      end
+
+      # Validate a given value through all validations and
+      # return an array of all errors
+      #
+      # @param value [Object]
+      # @return [Array]
+      def validate_value(value)
+        @validations.each_with_object([]) do |validation, errors|
+          errors << validation[:name] unless validation[:block].call(value)
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/argument_set.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/error_set'
+require 'apia/dsls/argument_set'
+
+module Apia
+  module Definitions
+    class ArgumentSet < Definition
+
+      attr_reader :arguments
+
+      def setup
+        @arguments = {}
+      end
+
+      def dsl
+        @dsl ||= DSLs::ArgumentSet.new(self)
+      end
+
+      def validate(errors)
+        @arguments.each do |name, argument|
+          if argument.is_a?(Apia::Definitions::Argument)
+            argument.validate(errors)
+          else
+            errors.add self, 'InvalidArgument', "The argument '#{name}' is not an instance of Apia::Definitions::Argument"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/authenticator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/authenticator'
+
+module Apia
+  module Definitions
+    class Authenticator < Definition
+
+      TYPES = [:bearer, :anonymous].freeze
+
+      attr_accessor :type
+      attr_accessor :action
+      attr_accessor :scope_validator
+      attr_reader :potential_errors
+
+      def setup
+        @id = id
+        @potential_errors = []
+      end
+
+      def dsl
+        @dsl ||= DSLs::Authenticator.new(self)
+      end
+
+      def validate(errors)
+        if @type.nil?
+          errors.add self, 'MissingType', 'A type must be defined for authenticators'
+        elsif !TYPES.include?(@type)
+          errors.add self, 'InvalidType', "The type must be one of #{TYPES.join(', ')} (was: #{@type.inspect})"
+        end
+
+        if @action && !@action.is_a?(Proc)
+          errors.add self, 'InvalidAction', 'The action provided must be a Proc'
+        end
+
+        @potential_errors.each_with_index do |error, index|
+          unless error.respond_to?(:ancestors) && error.ancestors.include?(Apia::Error)
+            errors.add self, 'InvalidPotentialError', "Potential error at index #{index} must be a class that inherits from Apia::Error"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/controller'
+
+module Apia
+  module Definitions
+    class Controller < Definition
+
+      attr_accessor :authenticator
+      attr_reader :endpoints
+      attr_reader :helpers
+
+      def setup
+        @endpoints = {}
+        @helpers = {}
+      end
+
+      def dsl
+        @dsl ||= DSLs::Controller.new(self)
+      end
+
+      def validate(errors)
+        if @authenticator && !(@authenticator.respond_to?(:ancestors) && @authenticator.ancestors.include?(Apia::Authenticator))
+          errors.add self, 'InvalidAuthenticator', 'The authenticator must be a class that inherits from Apia::Authenticator'
+        end
+
+        @endpoints.each do |name, endpoint|
+          unless name.to_s =~ /\A[\w-]+\z/i
+            errors.add self, 'InvalidEndpointName', "The endpoint name #{name} is invalid. It can only contain letters, numbers, underscores, and hyphens"
+          end
+
+          unless endpoint.respond_to?(:ancestors) && endpoint.ancestors.include?(Apia::Endpoint)
+            errors.add self, 'InvalidEndpoint', "The endpoint for #{name} must be a class that inherits from Apia::Endpoint"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/endpoint.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/argument_set'
+require 'apia/dsls/endpoint'
+require 'apia/field_set'
+require 'apia/error_set'
+require 'rack/utils'
+
+module Apia
+  module Definitions
+    class Endpoint < Definition
+
+      attr_accessor :authenticator
+      attr_accessor :action
+      attr_accessor :http_status
+      attr_accessor :paginated_field
+      attr_reader :fields
+      attr_reader :scopes
+
+      def setup
+        @fields = FieldSet.new
+        @http_status = 200
+        @scopes = []
+      end
+
+      def argument_set
+        @argument_set ||= begin
+          as = Apia::ArgumentSet.create("#{@id}/BaseArgumentSet")
+          as.definition.schema = schema?
+          as
+        end
+      end
+
+      def potential_errors
+        @potential_errors ||= Apia::ErrorSet.new
+      end
+
+      def dsl
+        @dsl ||= DSLs::Endpoint.new(self)
+      end
+
+      def http_status_code
+        if @http_status.is_a?(Symbol)
+          ::Rack::Utils::SYMBOL_TO_STATUS_CODE[@http_status]
+        else
+          @http_status
+        end
+      end
+
+      def validate(errors)
+        if @action && !@action.is_a?(Proc)
+          errors.add self, 'InvalidAction', 'The action provided must be a Proc'
+        end
+
+        if http_status_code.is_a?(Integer) && ::Rack::Utils::HTTP_STATUS_CODES[http_status_code]
+          # OK
+        elsif http_status_code.is_a?(Integer)
+          errors.add self, 'InvalidHTTPStatus', "The HTTP status is not valid (must be one of #{::Rack::Utils::HTTP_STATUS_CODES.keys.join(', ')})"
+        else
+          errors.add self, 'InvalidHTTPStatus', 'The HTTP status is not valid (must be an integer)'
+        end
+
+        if @authenticator && !(@authenticator.respond_to?(:ancestors) && @authenticator.ancestors.include?(Apia::Authenticator))
+          errors.add self, 'InvalidAuthenticator', 'The authenticator must be a class that inherits from Apia::Authenticator'
+        end
+
+        @fields.validate(errors, self)
+        @potential_errors&.validate(errors, self)
+      end
+
+    end
+  end
+end