jsapi 1.4 → 2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87f305e41facfb84c96e5e2406b636aa9e10a27545a25d42a5029f4d4dd93488
-  data.tar.gz: 6723179cd4981c590a4e8f0c45808d9b69a0436be48e1e89f06c7ef0a4b56ddb
+  metadata.gz: bbb6b0f27ef5b970e527367f2e918502d935765e4201ddbf5376fa4566ed5fde
+  data.tar.gz: d4764ceb8c1e32d0368a14d2d09370696f0329eb69f745ccdb9da67e5dcd0b1b
 SHA512:
-  metadata.gz: 7ddefbaaa678ed70e29055dbe4452ee0f4f738fa2386e8e3f5dbaa42e682ca973fa0bd04e5c6b22b2570bfd290fd4fcfbb42c8f7e50650ffda50d0cfbb160cc7
-  data.tar.gz: 3fc210ea9c236f319f1c94dcb741d7d910eb7edb90020aafcbbee2a033bd232a9bb88dd26fc306869f7c3be715487f4655a517e5968f63461a6bbad57074099a
+  metadata.gz: d996c4830b339e80c9de07bf379d239734de9f0df4d9f1cd0072ae358c755a07aeee5a54bbbbe6cb2dae4452e3fba0c8691d6a641a74ac8ef7014b00b64d51dd
+  data.tar.gz: ea2bf03ff17664bcb434f160e13e17e5d2eb341fb7c17ceddf6667d4fbcd6db297eee0c93c66a8d530a2da1032bf33b983385c05e88bd9a431a68b0062a4b08e

data/lib/jsapi/controller/actions/class_methods.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    module Actions
+      module ClassMethods
+        ##
+        # :method: api_action
+        # :call-seq:
+        #   api_action(name, operation_name = nil, action: :index, **options)
+        #   api_action(operation_name = nil, action: :index, **options, &block)
+        #
+        # Defines a controller action that performs an API operation by wrapping
+        # the given method or block by +api_operation+.
+        #
+        #   # Invoke :foo to perform :bar
+        #   api_action :foo, :bar
+        #
+        #   # Call the given block to perform :bar
+        #   api_action :bar do |api_params|
+        #     # ...
+        #   end
+        #
+        # Raises an +ArgumentError+ when neither +name+ nor +block+ is given.
+        #
+        # +:action+ specifies the name of the controller action to be defined.
+        # The default is +:index+.
+        #
+        # All other options are passed to +api_operation+.
+
+        ##
+        # :method: api_action!
+        # :call-seq:
+        #   api_action!(name, operation_name = nil, action: :index, **options)
+        #   api_action!(operation_name = nil, action: :index, **options, &block)
+        #
+        # Like +api_action+, except that +api_operation!+ is used instead of
+        # +api_operation+.
+
+        ['', '!'].each do |suffix|
+          method = :"api_operation#{suffix}"
+
+          define_method(:"api_action#{suffix}") \
+          do |name = nil, operation_name = nil, action: nil, **options, &block|
+            raise ArgumentError, 'neither name nor block is given' if !name && !block
+
+            operation_name = name if operation_name.nil?
+
+            define_method(action || :index, &(
+              if block
+                -> { send(method, operation_name, **options, &block) }
+              else
+                -> { send(method, operation_name, **options) { |p| send(name, p) } }
+              end
+            ))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/actions.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'actions/class_methods'
+
+module Jsapi
+  module Controller
+    module Actions
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/jsapi/controller/authentication/class_methods.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    module Authentication
+      module ClassMethods
+        # :call-seq:
+        #   api_after_authentication(method_or_proc, **options)
+        #   api_after_authentication(**options, &block)
+        #
+        # Registers a callback triggered after a request has been authenticated
+        # successfully.
+        def api_after_authentication(method_or_proc = nil, **options, &block)
+          _api_add_callback(:after_authentication, method_or_proc, **options, &block)
+        end
+
+        # :call-seq:
+        #   api_authenticate(*scheme_names, with:)
+        #   api_authenticate(*scheme_names, &block)
+        #
+        # Registers a handler to authenticate requests according to the specified
+        # security schemes.
+        #
+        #   api_authenticate 'basic_auth', with: :authenticate
+        #
+        # If no scheme names are specified, the handler is used as fallback for all
+        # security schemes for which no handler is registered.
+        #
+        # The +:with+ option specifies the method to be called to authenticate
+        # requests. Alternatively, a block can be given as handler.
+        #
+        # If the handler returns a truthy value, the request is assumed to be
+        # authenticated successfully.
+        #
+        #   def authenticate(credentials)
+        #     credentials.username == 'api_user' &&
+        #       credentials.password == 'secret'
+        #   end
+        def api_authenticate(*scheme_names, with: nil, &block)
+          handler = with || block
+          raise ArgumentError, 'either the :with keyword argument or a block ' \
+                               'must be specified' unless handler
+
+          (scheme_names.presence || [nil]).each do |scheme_name|
+            _api_authentication_handlers[scheme_name&.to_s] = handler
+          end
+        end
+
+        def _api_authentication_handler(scheme_name) # :nodoc:
+          scheme_name = scheme_name&.to_s
+
+          _api_authentication_handlers[scheme_name] ||
+            superclass.try(:_api_authentication_handler, scheme_name) ||
+            (_api_authentication_handler(nil) unless scheme_name.nil?)
+        end
+
+        private
+
+        def _api_authentication_handlers
+          @_api_authentication_handlers ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/authentication/credentials/api_key.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    module Authentication
+      module Credentials
+        # Holds an API key.
+        class APIKey
+          # The API key as it was passed.
+          attr_reader :api_key
+
+          def initialize(api_key)
+            @api_key = api_key
+          end
+
+          # Returns true if the API Key is not nil.
+          def well_formed?
+            !api_key.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/authentication/credentials/http/base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    module Authentication
+      module Credentials
+        module HTTP
+          # Holds credentials passed according to \HTTP \Authentication.
+          class Base
+            attr_reader :auth_scheme, :auth_param
+
+            def initialize(authorization)
+              @auth_scheme, @auth_param = authorization.to_s.split(' ', 2)
+            end
+
+            # Returns true if the credentials are syntactically correct.
+            def well_formed?
+              auth_scheme.present? && auth_param.present?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/authentication/credentials/http/basic.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Jsapi
+  module Controller
+    module Authentication
+      module Credentials
+        module HTTP
+          # Holds a username and password passed according to \HTTP
+          # \Basic \Authentication.
+          class Basic < Base
+            # The decoded password.
+            attr_reader :password
+
+            # The decoded username.
+            attr_reader :username
+
+            def initialize(authorization)
+              super
+              @username, @password =
+                Base64.decode64(auth_param).split(':', 2) \
+                if auth_scheme == 'Basic' && auth_param.present?
+            end
+
+            def well_formed? # :nodoc:
+              !username.nil? && !password.nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/authentication/credentials/http/bearer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Jsapi
+  module Controller
+    module Authentication
+      module Credentials
+        module HTTP
+          # Holds a token passed according to \HTTP \Bearer \Authentication.
+          class Bearer < Base
+            # The decoded token.
+            attr_reader :token
+
+            def initialize(authorization)
+              super
+              @token =
+                Base64.decode64(auth_param) \
+                if auth_scheme == 'Bearer' && auth_param.present?
+            end
+
+            def well_formed? # :nodoc:
+              !token.nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/authentication/credentials/http.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'http/base'
+require_relative 'http/basic'
+require_relative 'http/bearer'

data/lib/jsapi/controller/authentication/credentials.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'credentials/api_key'
+require_relative 'credentials/http'
+
+module Jsapi
+  module Controller
+    module Authentication
+      # Provides classes to pass credentials to an authentication handler.
+      module Credentials
+        class << self
+          # Creates credentials from +request+ according to the specified
+          # security scheme.
+          def create(request, security_scheme)
+            case security_scheme
+            when Meta::SecurityScheme::APIKey
+              name = security_scheme.name
+              APIKey.new(
+                case security_scheme.in
+                when 'header'
+                  request.headers[name]
+                when 'query'
+                  request.query_parameters[name]
+                end
+              )
+            when Meta::SecurityScheme::HTTP::Basic
+              HTTP::Basic.new(request.authorization)
+            when Meta::SecurityScheme::HTTP::Bearer
+              HTTP::Bearer.new(request.authorization)
+            when Meta::SecurityScheme::HTTP::Other
+              HTTP::Base.new(request.authorization)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/authentication.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'authentication/credentials'
+require_relative 'authentication/class_methods'
+
+module Jsapi
+  module Controller
+    # The \Authentication add-on.
+    #
+    #   class FooController < Jsapi::Controller::Base
+    #     include Jsapi::Controller::Authentication
+    #
+    #     api_authenticate 'basic_auth' do |credentials|
+    #       # Implement authentication handler here
+    #     end
+    #
+    #     api_security_scheme 'basic_auth', type: 'http', scheme: 'basic'
+    #
+    #     api_security_requirement do
+    #       scheme 'basic_auth'
+    #     end
+    #   end
+    module Authentication
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+      end
+
+      # Returns true if and only if the current request satisfies at least one of
+      # the security requirements applied to the specified operation. A security
+      # requirement is satisfied if it is empty ({}) or all of the referred
+      # security schemes are satisfied.
+      #
+      # +operation_name+ can be omitted if the controller handles one operation only.
+      # If the operation isn't defined, an OperationNotDefined exception is raised.
+      def api_authenticated?(operation_name = nil)
+        _api_authenticated?(_api_operation(operation_name))
+      end
+
+      private
+
+      def _api_authenticated?(operation)
+        security_requirements = operation.security_requirements
+        return true if security_requirements.blank?
+
+        security_requirements.any? do |security_requirement|
+          security_requirement.schemes.keys.all? do |scheme_name|
+            # Find the most appropriate authentication handler
+            authentication_handler = self.class._api_authentication_handler(scheme_name)
+            next false unless authentication_handler
+
+            # Find the appropriate security scheme
+            security_scheme = api_definitions.find_security_scheme(scheme_name)
+            next false unless security_scheme
+
+            # Create the credentials to be passed to the authenticator
+            credentials = Credentials.create(request, security_scheme)
+            next false unless credentials&.well_formed?
+
+            # Call authentication handler
+            if authentication_handler.is_a?(Proc)
+              instance_exec(credentials, &authentication_handler)
+            else
+              send(authentication_handler, credentials)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/base.rb

@@ -4,16 +4,17 @@ module Jsapi
   module Controller
     # The base API controller class.
     #
+    # A minimal API controller responding with "Hello world" looks like:
+    #
     #   class FooController < Jsapi::Controller::Base
     #     api_operation do
     #       response type: 'string'
     #     end
     #
-    #     def index
-    #       api_operation { 'Hello world' }
-    #     end
-    #   end
+    #     api_action { 'Hello world' }
+    #
     class Base < ActionController::API
+      include Actions
       include DSL
       include Methods
     end

data/lib/jsapi/controller/methods/callbacks/callback.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    module Methods
+      module Callbacks
+        # Represents a callback to be triggered.
+        class Callback
+          # The method or +Proc+ to be called.
+          attr_reader :method_or_proc
+
+          # Creates a callback that executes +method_or_proc+.
+          #
+          # The following options can be specified:
+          #
+          # - +:if+ - The conditions under which the callback is triggered only.
+          # - +:unless+ - The conditions under which the callback isn't triggered.
+          # - +:only+ - The operations on which the callback is triggered only.
+          # - +:except+ - The operations on which the callback isn't triggered.
+          #
+          # +:if+ and +:unless+ can be a symbol, a +Proc+ or an array of symbols
+          # and +Proc+s.
+          def initialize(method_or_proc, **options)
+            @method_or_proc = method_or_proc
+
+            @if, @unless =
+              %i[if unless].map do |key|
+                value = options[key]
+                Array.wrap(value) if value
+              end
+
+            @only, @except =
+              %i[only except].map do |key|
+                value = options[key]
+                Array.wrap(value).map(&:to_s) if value
+              end
+          end
+
+          def inspect # :nodoc:
+            "#<#{self.class} #{@method_or_proc.inspect}#{
+              {
+                if: @if,
+                unless: @unless,
+                only: @only,
+                except: @except
+              }.filter_map do |key, value|
+                next if value.nil?
+
+                value = value.sole if value.one?
+                ", #{key}: #{value.inspect}"
+              end.join
+            }>"
+          end
+
+          # Returns true if and only if the callback must not be triggered on
+          # +controller+ and +operation_name+.
+          def skip_on?(controller, operation_name)
+            operation_name = operation_name.to_s
+
+            @only&.exclude?(operation_name) ||
+              @except&.include?(operation_name) ||
+              @if&.any? { |condition| !evaluate(condition, controller) } ||
+              @unless&.any? { |condition| evaluate(condition, controller) } ||
+              false
+          end
+
+          private
+
+          def evaluate(condition, context)
+            if condition.is_a?(Proc)
+              context.instance_exec(&condition)
+            else
+              context.send(condition)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/methods/callbacks/class_methods.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    module Methods
+      module Callbacks
+        module ClassMethods
+          # :call-seq:
+          #   api_after_validation(method_or_proc, **options)
+          #   api_after_validation(**options, &block)
+          #
+          # Registers a callback that is triggered by +api_operation!+ after the
+          # parameters have been validated successfully.
+          #
+          #   api_after_validation do |api_params|
+          #     # ...
+          #   end
+          #
+          # When calling an +api_after_validation+ callback, the parameters are
+          # passed.
+          def api_after_validation(method_or_proc = nil, **options, &block)
+            _api_add_callback(:after_validation, method_or_proc, **options, &block)
+          end
+
+          # :call-seq:
+          #   api_before_rendering(method_or_proc, **options)
+          #   api_before_rendering(**options, &block)
+          #
+          # Registers a callback that is triggered by +api_operation+ and
+          # +api_operation!+ before the response body is rendered.
+          #
+          #   api_before_rendering do |result, api_params|
+          #     { request_id: api_params.request_id, payload: result }
+          #   end
+          #
+          # When calling an +api_before_rendering+ callback, the result and
+          # parameters are passed. The value returned by the callback replaces
+          # the result to be rendered.
+          def api_before_rendering(method_or_proc = nil, **options, &block)
+            _api_add_callback(:before_rendering, method_or_proc, **options, &block)
+          end
+
+          def _api_add_callback(kind, method_or_proc = nil, **options, &block) # :nodoc:
+            method_or_proc ||= block
+            raise ArgumentError, 'either a method or a block must be ' \
+                                  'specified' unless method_or_proc
+
+            ((@_api_callbacks ||= {})[kind] ||= []) <<
+              Callback.new(method_or_proc, **options)
+          end
+
+          def _api_callbacks(kind) # :nodoc:
+            callbacks = @_api_callbacks&.fetch(kind, nil) || []
+            return callbacks unless superclass.respond_to?(:_api_callbacks)
+
+            superclass._api_callbacks(kind) + callbacks
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/methods/callbacks.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'callbacks/callback'
+require_relative 'callbacks/class_methods'
+
+module Jsapi
+  module Controller
+    module Methods
+      module Callbacks
+        def self.included(base) # :nodoc:
+          base.extend(ClassMethods)
+        end
+
+        private
+
+        def _api_callback(name, operation_name, *args)
+          operation_name = operation_name.to_s
+
+          self.class._api_callbacks(name).each do |callback|
+            next if callback.skip_on?(self, operation_name)
+
+            _api_exec(callback.method_or_proc, operation_name, *args)
+          end
+          nil
+        end
+
+        def _api_before_rendering(operation_name, result, *args)
+          operation_name = operation_name.to_s
+          args = [args, operation_name].flatten
+
+          self.class._api_callbacks(:before_rendering).reduce(result) do |memo, callback|
+            next memo if callback.skip_on?(self, operation_name)
+
+            _api_exec(callback.method_or_proc, memo, operation_name, *args)
+          end
+        end
+
+        def _api_exec(method_or_proc, *args)
+          if method_or_proc.is_a?(Proc)
+            arity = method_or_proc.arity
+            args = args.take(arity) if arity < args.count
+
+            instance_exec(*args, &method_or_proc)
+          else
+            arity = self.class.instance_method(method_or_proc).arity
+            args = args.take(arity) if arity < args.count
+
+            send(method_or_proc, *args)
+          end
+        end
+      end
+    end
+  end
+end