apia 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 834322a8dd87426fd34415e096964a331ca3fefd5101e05e23a216da197e1820
+  data.tar.gz: d422b240f990920a61e520e360d15414aef1b8c0f39021684fa32d31d0aaf1a9
+SHA512:
+  metadata.gz: 6a42e4aaf195d8bd6dc7053a473bbc107ff4303d184bfae3c5bf1e7bb25ef618f57dbc86436c697b06786847f67077d9a06ae9451c6211fbf6072a5cfd6b755e
+  data.tar.gz: 73762ac070550ec052ffa79f2a5e8fdbb0317b8cdb62020b74d494706a1f2e63a65d52691fed82da4f2ba60ed2d66a2572686d3e0c9fef237ec2632a67bc339b

data/VERSION

@@ -0,0 +1 @@
+3.0.0

data/lib/apia.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'apia/api'
+require 'apia/argument_set'
+require 'apia/authenticator'
+require 'apia/controller'
+require 'apia/endpoint'
+require 'apia/enum'
+require 'apia/error'
+require 'apia/lookup_argument_set'
+require 'apia/scalar'
+require 'apia/object'
+require 'apia/polymorph'
+
+require 'apia/scalars/string'
+require 'apia/scalars/integer'
+require 'apia/scalars/boolean'
+require 'apia/scalars/date'
+require 'apia/scalars/unix_time'
+require 'apia/scalars/decimal'
+require 'apia/scalars/base64'

data/lib/apia/api.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'apia/defineable'
+require 'apia/definitions/api'
+require 'apia/helpers'
+require 'apia/manifest_errors'
+require 'apia/object_set'
+require 'apia/errors/standard_error'
+require 'apia/mock_request'
+
+module Apia
+  class API
+
+    extend Defineable
+
+    class << self
+
+      # Return the definition for this API
+      #
+      # @return [Apia::Definitions::API]
+      def definition
+        @definition ||= Definitions::API.new(Helpers.class_name_to_id(name))
+      end
+
+      # Return all objects which are referenced by the API. This list is used for the purposes
+      # of validating all objects and generating schemas.
+      #
+      # @param include_apia_controller [Boolean] whether the schema/internal API should be included
+      # @return [Apia::ObjectSet]
+      def objects
+        set = ObjectSet.new([self])
+        if definition.authenticator
+          set.add_object(definition.authenticator)
+        end
+
+        definition.route_set.controllers.each do |con|
+          set.add_object(con)
+        end
+
+        definition.route_set.endpoints.each do |endpoint|
+          set.add_object(endpoint)
+        end
+
+        set
+      end
+
+      # Validate all objects in the API and return details of any issues encountered
+      #
+      # @return [Apia::ManifestErrors]
+      def validate_all
+        errors = ManifestErrors.new
+        objects.each do |object|
+          next unless object.respond_to?(:definition)
+
+          object.definition.validate(errors)
+        end
+        errors
+      end
+
+      # Return the schema hash for this API
+      #
+      # @param host [String]
+      # @param namespace [String]
+      # @return [Hash]
+      def schema(host:, namespace:)
+        require 'apia/schema/controller'
+        Schema::Controller.definition.endpoints[:schema].definition.fields.generate_hash({
+          schema_version: 1,
+          host: host,
+          namespace: namespace,
+          api: definition.id,
+          objects: objects.map(&:definition).select(&:schema?)
+        })
+      end
+
+      # Execute a request for a given controller & endpoint
+      #
+      # @param controller [Apia::Controller]
+      # @param endpoint_name [Symbol]
+      # @return [Apia::Response]
+      def test_endpoint(endpoint, controller: nil)
+        if controller && endpoint.is_a?(Symbol) || endpoint.is_a?(String)
+          endpoint_name = endpoint
+          endpoint = controller.definition.endpoints[endpoint.to_sym]
+          if endpoint.nil?
+            raise Apia::StandardError, "Invalid endpoint name '#{endpoint_name}' for '#{controller.name}'"
+          end
+        end
+
+        endpoint.test do |r|
+          r.api = self
+          r.controller = controller
+          yield r if block_given?
+        end
+      end
+
+    end
+
+  end
+end

data/lib/apia/argument_set.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'apia/defineable'
+require 'apia/definitions/argument_set'
+require 'apia/errors/invalid_argument_error'
+require 'apia/errors/missing_argument_error'
+require 'apia/helpers'
+
+module Apia
+  class ArgumentSet
+
+    # This is a constant that represents a missing value where `nil` means
+    # the user actually wanted to send null/nil.
+    class MissingValue
+
+      def self.singleton
+        @singleton ||= new
+      end
+
+    end
+
+    extend Defineable
+
+    class << self
+
+      # Return the definition for this argument set
+      #
+      # @return [Apia::Definitions::ArgumentSet]
+      def definition
+        @definition ||= Definitions::ArgumentSet.new(Helpers.class_name_to_id(name))
+      end
+
+      # Finds all objects referenced by this argument set and add them
+      # to the provided set.
+      #
+      # @param set [Apia::ObjectSet]
+      # @return [void]
+      def collate_objects(set)
+        definition.arguments.each_value do |argument|
+          set.add_object(argument.type.klass) if argument.type.usable_for_argument?
+        end
+      end
+
+      # Create a new argument set from a request object
+      #
+      # @param request [Apia::Request]
+      # @return [Apia::ArgumentSet]
+      def create_from_request(request)
+        new(request.json_body || request.params || {}, request: request)
+      end
+
+    end
+
+    # Create a new argument set by providing a hash containing the raw
+    # arguments
+    #
+    # @param hash [Hash]
+    # @param path [Array]
+    # @return [Apia::ArgumentSet]
+    def initialize(hash, path: [], request: nil)
+      unless hash.is_a?(Hash)
+        raise Apia::RuntimeError, 'Hash was expected for argument'
+      end
+
+      @path = path
+      @request = request
+      @source = self.class.definition.arguments.each_with_object({}) do |(arg_key, argument), source|
+        given_value = lookup_value(hash, arg_key, argument, request)
+
+        if argument.required? && (given_value.nil? || given_value.is_a?(MissingValue))
+          raise MissingArgumentError.new(argument, path: @path + [argument])
+        end
+
+        # If the given value is missing, we'll just skip adding this to the hash
+        next if given_value.is_a?(MissingValue)
+
+        given_value = parse_value(argument, given_value)
+        validation_errors = argument.validate_value(given_value)
+        unless validation_errors.empty?
+          raise InvalidArgumentError.new(argument, issue: :validation_errors, errors: validation_errors, path: @path + [argument])
+        end
+
+        source[argument.name.to_sym] = given_value
+      end
+    end
+
+    # Return an item from the argument set
+    #
+    # @param value [String, Symbol]
+    # @return [Object, nil]
+    def [](value)
+      @source[value.to_sym]
+    end
+
+    # Return an item from this argument set
+    #
+    # @param values [Array<String, Symbol>]
+    # @return [Object, nil]
+    def dig(*values)
+      @source.dig(*values)
+    end
+
+    # Return the source object
+    #
+    # @return [Hash]
+    def to_hash
+      @source.transform_values do |value|
+        value.is_a?(ArgumentSet) ? value.to_hash : value
+      end
+    end
+
+    # Return whether an argument has been provided or not?
+    #
+    # @param name [Symbol]
+    # @return [Boolean]
+    def has?(key)
+      @source.key?(key.to_sym)
+    end
+
+    # Validate an argument set and return any errors as appropriate
+    #
+    # @param argument [Apia::Argument]
+    def validate(argument, index: nil)
+    end
+
+    private
+
+    def lookup_value(hash, key, argument, request)
+      if hash.key?(key.to_s)
+        hash[key.to_s]
+      elsif hash.key?(key.to_sym)
+        hash[key.to_sym]
+      else
+        route_value = value_from_route(argument, request)
+        return route_value unless route_value.is_a?(MissingValue)
+        return argument.default unless argument.default.nil?
+
+        MissingValue.singleton
+      end
+    end
+
+    def parse_value(argument, value, index: nil, in_array: false)
+      if value.nil?
+        nil
+
+      elsif argument.array? && value.is_a?(Array)
+        value.each_with_index.map do |v, i|
+          parse_value(argument, v, index: i, in_array: true)
+        end
+
+      elsif argument.array? && !in_array
+        raise InvalidArgumentError.new(argument, issue: :array_expected, index: index, path: @path + [argument])
+
+      elsif argument.type.scalar?
+        begin
+          type = argument.type.klass.parse(value)
+        rescue Apia::ParseError => e
+          # If we cannot parse the given input, this is cause for a parse error to be raised.
+          raise InvalidArgumentError.new(argument, issue: :parse_error, errors: [e.message], index: index, path: @path + [argument])
+        end
+
+        unless argument.type.klass.valid?(type)
+          # If value we have parsed is not actually valid, we 'll raise an argument error.
+          # In most cases, it is likely that an integer has been provided to string etc...
+          raise InvalidArgumentError.new(argument, issue: :invalid_scalar, index: index, path: @path + [argument])
+        end
+
+        type
+
+      elsif argument.type.argument_set?
+        unless value.is_a?(Hash)
+          raise InvalidArgumentError.new(argument, issue: :object_expected, index: index, path: @path + [argument])
+        end
+
+        value = argument.type.klass.new(value, path: @path + [argument], request: @request)
+        value.validate(argument, index: index)
+        value
+
+      elsif argument.type.enum?
+        unless argument.type.klass.definition.values[value]
+          raise InvalidArgumentError.new(argument, issue: :invalid_enum_value, index: index, path: @path + [argument])
+        end
+
+        value
+      end
+    end
+
+    def check_for_missing_required_arguments
+      self.class.definition.arguments.each_value do |arg|
+        next unless arg.required?
+        next if self[arg.name]
+      end
+    end
+
+    def value_from_route(argument, request)
+      return MissingValue.singleton if request.nil?
+      return MissingValue.singleton if request.route.nil?
+
+      route_args = request.route.extract_arguments(request.api_path)
+      unless route_args.key?(argument.name.to_s)
+        return MissingValue.singleton
+      end
+
+      value_for_arg = route_args[argument.name.to_s]
+      return nil if value_for_arg.nil?
+
+      if argument.type.argument_set?
+        # If the argument is an argument set, we'll just want to try and
+        # populate the first argument.
+        if first_arg = argument.type.klass.definition.arguments.keys.first
+          { first_arg.to_s => value_for_arg }
+        else
+          {}
+        end
+      else
+        value_for_arg
+      end
+    end
+
+  end
+end

data/lib/apia/authenticator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'apia/defineable'
+require 'apia/definitions/authenticator'
+require 'apia/helpers'
+require 'apia/callable_with_environment'
+
+module Apia
+  class Authenticator
+
+    extend Defineable
+    include CallableWithEnvironment
+
+    class << self
+
+      # Return the definition for this authenticator
+      #
+      # @return [Apia::Definitions::Authenticator]
+      def definition
+        @definition ||= Definitions::Authenticator.new(Helpers.class_name_to_id(name))
+      end
+
+      # Finds all objects referenced by this authenticator and add them
+      # to the provided set.
+      #
+      # @param set [Apia::ObjectSet]
+      # @return [void]
+      def collate_objects(set)
+        definition.potential_errors.each do |error|
+          set.add_object(error)
+        end
+      end
+
+      # Execute this authenticator within the given environment
+      #
+      # @param environment [Apia::RequestEnvironment]
+      # @return [void]
+      def execute(environment)
+        new(environment).call
+      end
+
+      # If any of the given scopes are valid
+      #
+      # @param environment [Apia::RequestEnvironment]
+      # @param scope [String]
+      # @return [Boolean]
+      def authorized_scope?(environment, scopes)
+        return true if definition.scope_validator.nil?
+        return true if scopes.empty?
+
+        scopes.any? { |s| environment.call(s, &definition.scope_validator) }
+      end
+
+    end
+
+  end
+end

data/lib/apia/callable_with_environment.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Apia
+  module CallableWithEnvironment
+
+    def initialize(environment, action_name: :action)
+      @environment = environment
+      @action_name = action_name
+    end
+
+    def call
+      action = self.class.definition.send(@action_name)
+      return if action.nil?
+
+      instance_exec(@environment.request, @environment.response, &action)
+    end
+
+    # rubocop:disable Lint/RescueException
+    def call_with_error_handling
+      call
+    rescue Exception => e
+      raise_exception(e)
+    end
+    # rubocop:enable Lint/RescueException
+
+    def respond_to_missing?(name, _include_private = false)
+      @environment.respond_to?(name) || super
+    end
+
+    def method_missing(name, *args, **kwargs, &block)
+      if @environment.respond_to?(name)
+        if kwargs.empty?
+          return @environment.send(name, *args, &block)
+        end
+
+        return @environment.send(name, *args, **kwargs, &block)
+      end
+
+      super
+    end
+
+  end
+end