Define API for classes utilizing OmniAuth::Identity::Model

Author: pboling

.rubocop.yml

@@ -7,6 +7,7 @@ require:
   - 'rubocop-performance'
   - 'rubocop-rake'
   - 'rubocop-rspec'
+  - 'rubocop-sequel'
 
 AllCops:
   NewCops: enable
@@ -25,3 +26,9 @@ Metrics/BlockLength:
     - shared_examples_for
     - namespace
     - draw
+
+Sequel/SaveChanges:
+  Enabled: false
+
+Lint/UselessMethodDefinition:
+  Enabled: false

.rubocop_todo.yml

@@ -40,7 +40,7 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
 # IgnoredMethods: refine
 Metrics/BlockLength:
-  Max: 27
+  Max: 28
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne.

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Fix breaking changes introduced by [#86's](https://github.com/omniauth/omniauth-identity/pull/86) introduction of `:on_validation`
+
 ## [3.0.4] - 2021-02-14
 
 ### Added

Gemfile

@@ -39,6 +39,7 @@ group :development, :test do
     gem 'rubocop-performance', platform: :mri
     gem 'rubocop-rake', platform: :mri
     gem 'rubocop-rspec', platform: :mri
+    gem 'rubocop-sequel', platform: :mri
 
     gem 'simplecov', '~> 0.21', platform: :mri
   end

README.md

@@ -249,21 +249,21 @@ always break 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]
+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
+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'] } }
+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. 😭 
+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
 

lib/omniauth/identity/model.rb

@@ -8,20 +8,13 @@ module Identity
     # abstract must be implemented in the including class for things to
     # work properly.
     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
-
         # Authenticate a user with the given key and password.
         #
         # @param [String] key The unique login key provided for a given identity.
@@ -43,6 +36,67 @@ def auth_key(method = false)
 
           @auth_key || 'email'
         end
+
+        ### Singleton API for classes utilizing the OmniAuth::Identity::Model
+        #
+        # * create(*args)
+        # * locate(key)
+
+        # Persists a new Identity object to the ORM.
+        # Defaults to calling super.  Override as needed per ORM.
+        #
+        # @abstract
+        # @param [Hash] args Attributes of the new instance.
+        # @return [Model] An instance of the identity model class.
+        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 Singleton API for classes utilizing the OmniAuth::Identity::Model
+      end
+
+      ### Instance API for classes utilizing the OmniAuth::Identity::Model
+      #
+      # * save
+      # * persisted?
+      # * authenticate(password)
+      # * uid
+      # * auth_key - Normally defined by the macro `auth_key`
+      # * auth_key=(value) - Normally defined by the macro `auth_key`
+      #
+
+      # Persists a new Identity object to the ORM.
+      # Default raises an error.  Override as needed per ORM.
+      #
+      # @since 3.0.5
+      # @abstract
+      # @return [Model] An instance of the identity model class.
+      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.
+      def persisted?
+        raise NotImplementedError unless defined?(super)
+
+        super
       end
 
       # Returns self if the provided password is correct, false
@@ -55,22 +109,6 @@ def authenticate(password)
         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 +151,23 @@ def auth_key=(value)
           raise NotImplementedError
         end
       end
+      #
+      ### END Instance API for classes utilizing the OmniAuth::Identity::Model
+
+      # 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

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

lib/omniauth/identity/models/mongoid.rb

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

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

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 @@ def self.auth_key=(key)
             def self.locate(search_hash)
               where(search_hash).first
             end
+
+            def persisted?
+              exists?
+            end
+
+            def save
+              save_changes
+            end
           end
         end
       end