omniauth-identity 3.0.4 → 3.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5de20f544ddaf124fc1b80a0ea15d97d56572034cc985e72001e177c3da2c92
-  data.tar.gz: 21e59364dcba511bd658c7503b4dce12fb7c26e37b7f4bec3b05c91d0d1dd4c4
+  metadata.gz: e486fff1d58be9ad944402aa2952bfceca493c6e78f1ba8c1e29cf6142543b01
+  data.tar.gz: a4be9557b902ff9dfe779baea964477aaf127519f8e389b82aa3cd83af3041da
 SHA512:
-  metadata.gz: ef710bfa64cef76922f89e93ca4292c106bda7e61cb8a49133452227f65163d2c5be70fade9ecc8d973ce35281a812d837edffe27be24689b34646c48109b07a
-  data.tar.gz: 812f288ec96fb46afa30a61fc34caa85b4efbe8857b8fb6dbeaeab9b2c181124db8b8deea40ebbccedcfc8b78d4039dbcad609782d0955a36423e543ba293865
+  metadata.gz: 3f4d5a82e3ee782716992b1183cac66e6a29cee8037a8491a56bb8dd832ee9f22946eee7900d9e1d8d20d9bc5dcce3336652f25f606f027e87d79be6a9a00c6d
+  data.tar.gz: f2de6f02475fe119947bd6ba2f66e9585664b522833180e5327fcda8aa3b92c8fcb95d3bfb6baf45724851c1dd6c2a8144fe473f70715c6399b8025d73b195b2

data/CHANGELOG.md

@@ -8,6 +8,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.5] - 2021-03-19
+
+### Fixed
+
+- Fix breaking changes introduced by [#86's](https://github.com/omniauth/omniauth-identity/pull/86) introduction of `:on_validation`
+
+### Added
+
+- Define `#save`, `#persisted?` and `::create` on `Omniauth::Identity::Model`
+- Add `@since` YARD tags to interface methods
+- Refactor `Omniauth::Strategies::Identity.registration_phase` to support `Omniauth::Identity::Model`-inheriting classes that do not define `#save`.
+  - This support will be dropped in v4.0.
+
 ## [3.0.4] - 2021-02-14
 
 ### Added

data/README.md

@@ -10,7 +10,7 @@
 [![Downloads Rank](https://img.shields.io/gem/rd/omniauth-identity.svg)](https://rubygems.org/gems/omniauth-identity)
 
 The OmniAuth Identity gem provides a way for applications to utilize a
-traditional login/password based authentication system without the need
+traditional username/password based authentication system without the need
 to give up the simple authentication flow provided by OmniAuth. Identity
 is designed on purpose to be as featureless as possible: it provides the
 basic construct for user management and then gets out of the way.
@@ -245,12 +245,32 @@ Note: Be careful when customizing `locate_conditions`.  The best way to modify t
 to copy the default value, and then add to the hash.  Removing the default condition will almost
 always break things!
 
+## Customizing Other Things
+
+From the code - here are the options we have for you, a couple of which are documented above, and the rest are documented... in the specs we hope!?
+```
+option :fields, %i[name email]
+
+      # Primary Feature Switches:
+option :enable_registration, true   # See #other_phase and #request_phase
+option :enable_login, true          # See #other_phase
+
+      # Customization Options:
+option :on_login, nil               # See #request_phase
+option :on_validation, nil          # See #registration_phase
+option :on_registration, nil        # See #registration_phase
+option :on_failed_registration, nil # See #registration_phase
+option :locate_conditions, ->(req) { { model.auth_key => req['auth_key'] } }
+```
+
+Please contribute some documentation if you have the gumption!  The maintainer's time is limited, and sometimes the authors of PRs with new options don't update the _this_ readme. 😭
+
 ## License
 
 MIT License. See LICENSE for details.
 
 ## Copyright
 
-Copyright (c) 2021 OmniAuth-Identity Maintainers
-Copyright (c) 2020 Peter Boling, Andrew Roberts, and Jellybooks Ltd.
-Copyright (c) 2010-2015 Michael Bleigh, and Intridea, Inc.
+* Copyright (c) 2021 OmniAuth-Identity Maintainers
+* Copyright (c) 2020 Peter Boling, Andrew Roberts, and Jellybooks Ltd.
+* Copyright (c) 2010-2015 Michael Bleigh, and Intridea, Inc.

data/lib/omniauth-identity/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAuth
   module Identity
-    VERSION = '3.0.4'
+    VERSION = '3.0.5'
   end
 end

data/lib/omniauth/identity/model.rb

@@ -4,23 +4,31 @@ module OmniAuth
   module Identity
     # This module provides an includable interface for implementing the
     # necessary API for OmniAuth Identity to properly locate identities
-    # and provide all necessary information. All methods marked as
-    # abstract must be implemented in the including class for things to
-    # work properly.
+    # and provide all necessary information.
+    #
+    # All methods marked as abstract must be implemented in the
+    # including class for things to work properly.
+    #
+    ### Singleton API
+    #
+    # * locate(key)
+    # * create(*args) - Deprecated in v3.0.5; Will be removed in v4.0
+    #
+    ### Instance API
+    #
+    # * save
+    # * persisted?
+    # * authenticate(password)
+    #
     module Model
+      SCHEMA_ATTRIBUTES = %w[name email nickname first_name last_name location description image phone].freeze
+
       def self.included(base)
         base.extend ClassMethods
       end
 
       module ClassMethods
-        # Locate an identity given its unique login key.
-        #
-        # @abstract
-        # @param [String] key The unique login key.
-        # @return [Model] An instance of the identity model class.
-        def locate(key)
-          raise NotImplementedError
-        end
+        extend Gem::Deprecate
 
         # Authenticate a user with the given key and password.
         #
@@ -43,6 +51,53 @@ module OmniAuth
 
           @auth_key || 'email'
         end
+
+        # Persists a new Identity object to the ORM.
+        # Defaults to calling super.  Override as needed per ORM.
+        #
+        # @deprecated v4.0 will begin using {#new} with {#save} instead.
+        # @abstract
+        # @param [Hash] args Attributes of the new instance.
+        # @return [Model] An instance of the identity model class.
+        # @since 3.0.5
+        def create(*args)
+          raise NotImplementedError unless defined?(super)
+
+          super
+        end
+
+        # Locate an identity given its unique login key.
+        #
+        # @abstract
+        # @param [String] key The unique login key.
+        # @return [Model] An instance of the identity model class.
+        def locate(key)
+          raise NotImplementedError
+        end
+      end
+
+      # Persists a new Identity object to the ORM.
+      # Default raises an error.  Override as needed per ORM.
+      #
+      # @abstract
+      # @return [Model] An instance of the identity model class.
+      # @since 3.0.5
+      def save
+        raise NotImplementedError unless defined?(super)
+
+        super
+      end
+
+      # Checks if the Identity object is persisted in the ORM.
+      # Defaults to calling super.  Override as needed per ORM.
+      #
+      # @abstract
+      # @return [true or false] true if object exists, false if not.
+      # @since 3.0.5
+      def persisted?
+        raise NotImplementedError unless defined?(super)
+
+        super
       end
 
       # Returns self if the provided password is correct, false
@@ -55,22 +110,6 @@ module OmniAuth
         raise NotImplementedError
       end
 
-      SCHEMA_ATTRIBUTES = %w[name email nickname first_name last_name location description image phone].freeze
-      # A hash of as much of the standard OmniAuth schema as is stored
-      # in this particular model. By default, this will call instance
-      # methods for each of the attributes it needs in turn, ignoring
-      # any for which `#respond_to?` is `false`.
-      #
-      # If `first_name`, `nickname`, and/or `last_name` is provided but
-      # `name` is not, it will be automatically calculated.
-      #
-      # @return [Hash] A string-keyed hash of user information.
-      def info
-        SCHEMA_ATTRIBUTES.each_with_object({}) do |attribute, hash|
-          hash[attribute] = send(attribute) if respond_to?(attribute)
-        end
-      end
-
       # An identifying string that must be globally unique to the
       # application. Defaults to stringifying the `id` method.
       #
@@ -113,6 +152,21 @@ module OmniAuth
           raise NotImplementedError
         end
       end
+
+      # A hash of as much of the standard OmniAuth schema as is stored
+      # in this particular model. By default, this will call instance
+      # methods for each of the attributes it needs in turn, ignoring
+      # any for which `#respond_to?` is `false`.
+      #
+      # If `first_name`, `nickname`, and/or `last_name` is provided but
+      # `name` is not, it will be automatically calculated.
+      #
+      # @return [Hash] A string-keyed hash of user information.
+      def info
+        SCHEMA_ATTRIBUTES.each_with_object({}) do |attribute, hash|
+          hash[attribute] = send(attribute) if respond_to?(attribute)
+        end
+      end
     end
   end
 end

data/lib/omniauth/identity/models/couch_potato.rb

@@ -6,6 +6,7 @@ module OmniAuth
   module Identity
     module Models
       # can not be named CouchPotato since there is a class with that name
+      # NOTE: CouchPotato is based on ActiveModel.
       module CouchPotatoModule
         def self.included(base)
           base.class_eval do

data/lib/omniauth/identity/models/mongoid.rb

@@ -5,6 +5,7 @@ require 'mongoid'
 module OmniAuth
   module Identity
     module Models
+      # NOTE: Mongoid is based on ActiveModel.
       module Mongoid
         def self.included(base)
           base.class_eval do

data/lib/omniauth/identity/models/no_brainer.rb

@@ -6,6 +6,7 @@ module OmniAuth
   module Identity
     module Models
       # http://nobrainer.io/ an ORM for RethinkDB
+      # NOTE: NoBrainer is based on ActiveModel.
       module NoBrainer
         def self.included(base)
           base.class_eval do

data/lib/omniauth/identity/models/sequel.rb

@@ -6,6 +6,9 @@ module OmniAuth
   module Identity
     module Models
       # http://sequel.jeremyevans.net/ an SQL ORM
+      # NOTE: Sequel is *not* based on ActiveModel, but supports the API we need, except for `persisted`:
+      # * create
+      # * save, but save is deprecated in favor of `save_changes`
       module Sequel
         def self.included(base)
           base.class_eval do
@@ -29,6 +32,14 @@ module OmniAuth
             def self.locate(search_hash)
               where(search_hash).first
             end
+
+            def persisted?
+              exists?
+            end
+
+            def save
+              save_changes
+            end
           end
         end
       end

data/lib/omniauth/strategies/identity.rb

@@ -6,8 +6,8 @@ module OmniAuth
     # user authentication using the same process flow that you
     # use for external OmniAuth providers.
     class Identity
+      DEFAULT_REGISTRATION_FIELDS = %i[password password_confirmation].freeze
       include OmniAuth::Strategy
-
       option :fields, %i[name email]
 
       # Primary Feature Switches:
@@ -65,29 +65,23 @@ module OmniAuth
       end
 
       def registration_phase
-        attributes = (options[:fields] + %i[password password_confirmation]).each_with_object({}) do |k, h|
+        attributes = (options[:fields] + DEFAULT_REGISTRATION_FIELDS).each_with_object({}) do |k, h|
           h[k] = request[k.to_s]
         end
         if model.respond_to?(:column_names) && model.column_names.include?('provider')
           attributes.reverse_merge!(provider: 'identity')
         end
-        @identity = model.new(attributes)
-
-        # on_validation may run a Captcha or other validation mechanism
-        # Must return true when validation passes, false otherwise
-        if options[:on_validation] && !options[:on_validation].call(env: env)
-          if options[:on_failed_registration]
-            env['omniauth.identity'] = @identity
-            options[:on_failed_registration].call(env)
+        if saving_instead_of_creating?
+          @identity = model.new(attributes)
+          env['omniauth.identity'] = @identity
+          if !validating? || valid?
+            @identity.save
+            registration_result
           else
-            validation_message = 'Validation failed'
-            registration_form(validation_message)
+            registration_failure('Validation failed')
           end
-        elsif @identity.save && @identity.persisted?
-          env['PATH_INFO'] = callback_path
-          callback_phase
         else
-          show_custom_options_or_default
+          deprecated_registration(attributes)
         end
       end
 
@@ -142,15 +136,53 @@ module OmniAuth
         end
       end
 
-      def show_custom_options_or_default
+      def saving_instead_of_creating?
+        model.respond_to?(:save) && model.respond_to?(:persisted?)
+      end
+
+      # Validates the model before it is persisted
+      #
+      # @return [truthy or falsey] :on_validation option is truthy or falsey
+      def validating?
+        options[:on_validation]
+      end
+
+      # Validates the model before it is persisted
+      #
+      # @return [true or false] result of :on_validation call
+      def valid?
+        # on_validation may run a Captcha or other validation mechanism
+        # Must return true when validation passes, false otherwise
+        !!options[:on_validation].call(env: env)
+      end
+
+      def registration_failure(message)
         if options[:on_failed_registration]
-          env['omniauth.identity'] = @identity
           options[:on_failed_registration].call(env)
         else
-          validation_message = 'One or more fields were invalid'
-          registration_form(validation_message)
+          registration_form(message)
+        end
+      end
+
+      def registration_result
+        if @identity.persisted?
+          env['PATH_INFO'] = callback_path
+          callback_phase
+        else
+          registration_failure('One or more fields were invalid')
         end
       end
+
+      def deprecated_registration(attributes)
+        warn <<~CREATEDEP
+          [DEPRECATION] Please define '#{model.class}#save'.
+                        Behavior based on '#{model.class}.create' will be removed in omniauth-identity v4.0.
+                        See lib/omniauth/identity/model.rb
+        CREATEDEP
+        @identity = model.create(attributes)
+        env['omniauth.identity'] = @identity
+        registration_result
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-identity
 version: !ruby/object:Gem::Version
-  version: 3.0.4
+  version: 3.0.5
 platform: ruby
 authors:
 - Peter Boling
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-02-14 00:00:00.000000000 Z
+date: 2021-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt
@@ -158,7 +158,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.4'
-description: Internal authentication handlers for OmniAuth.
+description: Traditional username/password based authentication system for OmniAuth
 email:
 executables: []
 extensions: []
@@ -211,7 +211,7 @@ requirements: []
 rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
-summary: Internal authentication handlers for OmniAuth.
+summary: Traditional username/password based authentication system for OmniAuth
 test_files:
 - spec/omniauth/identity/model_spec.rb
 - spec/omniauth/identity/models/active_record_spec.rb