parse-stack 1.5.2 → 1.5.3

data/lib/parse/model/acl.rb

@@ -1,42 +1,113 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# An ACL represents the Parse Permissions object used for each record. In Parse,
-# it is composed a hash-like object that represent Parse::User objectIds and/or Parse::Role
-# names. For each entity (ex. User/Role/Public), you can define read/write priviledges on a particular record.
-# The way they are implemented here is through an internal hash, with each value being of type Parse::ACL::Permission object.
-# A Permission object contains two accessors - read and write - and knows how to generate its JSON
-# structure. In Parse, if you want to give priviledges for an action (ex. read/write), then you set it to true.
-# If you want to deny a priviledge, then you set it to false. One important thing is that when
-# being converted to the Parse format, removing a priviledge means omiting it from the final
-# JSON structure.
-# The class below also implements a type of delegate pattern in order to inform the main Parse::Object
-# of dirty tracking.
 
 module Parse
 
+  # This class allows you to define custom data types for your model fields. You
+  # can define a subclass that implements the {DataType.typecast} method to
+  # convert to and from a value for serialization. The {Parse::ACL} class is
+  # implemented in this fashion.
   class DataType
     include ::ActiveModel::Model
     include ::ActiveModel::Serializers::JSON
+
+    # @return [Hash] the set of attributes for this data type.
     def attributes
       {}
     end
 
+    # Transform an incoming value to another. The default implementation does
+    # returns the original value. This method should return an instance of a
+    # DataType subclass.
+    # @param value [Object] the input value to be typecasted.
+    # @param opts [Hash] a set of options to be used when typecasting.
+    # @return [Object]
     def self.typecast(value, **opts)
       value
     end
 
+    # Serialize this DataType into an JSON object hash format to be saved to Parse.
+    # The default implementation returns an empty hash.
+    # @return [Hash]
     def as_json(*args)
       {}.as_json
     end
 
   end
 
+  # An ACL represents the dirty-trackable Parse Permissions object used for
+  # each record. In Parse, it is composed a hash-like object that represent
+  # {Parse::User} objectIds and/or a set of {Parse::Role} names. For each entity
+  # (ex. User/Role/Public), you can define read/write priviledges on a particular
+  # record through a {Parse::ACL::Permission} instance.
+  #
+  # If you want to give priviledges for an action (ex. read/write),
+  # you set that particular permission it to true. If you want to deny a
+  # permission, then you set it to false. Any denied permissions will not be
+  # part of the final hash structure that is sent to parse, as omission of a permission
+  # means denial.
+  #
+  # An ACL is represented by a JSON object with the keys being Parse::User object
+  # ids or the special key of *, which indicates the public access permissions.
+  # The value of each key in the hash is a {Parse::ACL::Permission} object which
+  # defines the boolean permission state for read and write.
+  # The example below illustrates a Parse ACL JSON object where there is a public
+  # read permission, but public write is prevented. In addition, the user with
+  # id "3KmCvT7Zsb", is allowed to both read and write this record.
+  #  {
+  #    "*": { "read": true },
+  #    "3KmCvT7Zsb": {  "read": true, "write": true }
+  #  }
+  #
+  # All Parse::Object subclasses have an acl property by default. With this
+  # property, you can apply and delete permissions for this particular Parse
+  # object record.
+  #  user = Parse::User.first
+  #  artist = Artist.first
+  #
+  #  artist.acl # "*": { "read": true, "write": true }
+  #
+  #  # apply public read, but no public write
+  #  artist.acl.everyone true, false
+  #
+  #
+  #  # allow user to have read and write access
+  #  artist.acl.apply user.id, true, true
+  #
+  #  # remove all permissions for this user id
+  #  artist.acl.delete user.id
+  #
+  #  # allow the 'Admins' role read and write
+  #  artist.acl.apply_role "Admins", true, true
+  #
+  #  artist.save
+  # For more information about Parse record ACLs, see the documentation on
+  # {https://parseplatform.github.io/docs/rest/guide/#security Security}.
   class ACL < DataType
 
+    # @!attribute permissions
+    # Contains a hash structure of permissions, with keys mapping to either Public '*',
+    # a role name or an objectId for a user and values of type {ACL::Permission}.
+    # @return [Hash] a hash of permissions.
+
+    # @!attribute delegate
+    # The instance object to be notified of changes. The delegate must support
+    # receiving a `acl_will_change!` method.
+    # @return [Parse::Object]
     attr_accessor :permissions, :delegate
+
+    def permissions
+      @permissions ||= {}
+    end
+
     PUBLIC = "*"
 
+    # Create a new ACL with default Public read/write permissions and any
+    # overrides from the input hash format.
+    # @param acls [Hash] a Parse-compatible hash acl format.
+    # @param owner [Parse::Object] a delegate to receive notifications of acl changes.
+    #  This delegate must support receiving `acl_will_change!` method.
     def initialize(acls = {}, owner: nil)
       everyone(true, true) # sets Public read/write
       @delegate = owner
@@ -46,32 +117,43 @@ module Parse
 
     end
 
+    # Create a new ACL::Permission instance with the supplied read and write values.
+    # @param read [Boolean] the read permission value
+    # @param write [Boolean] the write permission value.
+    # @return [ACL::Permission]
+    # @see ACL::Permission
     def self.permission(read, write = nil)
         ACL::Permission.new(read, write)
     end
 
-    def permissions
-      @permissions ||= {}
-    end
-
+    # @return [Boolean] whether two ACLs have the same set of priviledges.
     def ==(other_acl)
       return false unless other_acl.is_a?(self.class)
       return false if permissions.keys != other_acl.permissions.keys
       permissions.keys.all? { |per| permissions[per] == other_acl.permissions[per] }
     end
 
+    # Set the public read and write permissions.
+    # @param read [Boolean] the read permission state.
+    # @param write [Boolean] the write permission state.
+    # @return [Hash] the current public permissions.
     def everyone(read, write)
       apply(PUBLIC, read, write)
       permissions[PUBLIC]
     end
     alias_method :world, :everyone
 
-    # dirty tracking. We will tell the delegate through the acl_will_change! method
+    # Calls `acl_will_change!` on the delegate when the permissions have changed.
+    # All {Parse::Object} subclasses implement this method.
     def will_change!
       @delegate.acl_will_change! if @delegate.respond_to?(:acl_will_change!)
     end
 
-    # removes a permission
+    # Removes a permission for an objectId or user.
+    # @overload delete(object)
+    #  @param object [Parse::User] the user to revoke permissions.
+    # @overload delete(id)
+    #  @param id [String] the objectId to revoke permissions.
     def delete(id)
       id = id.id if id.is_a?(Parse::Pointer)
       if id.present? && permissions.has_key?(id)
@@ -80,8 +162,26 @@ module Parse
       end
     end
 
-    # apply a new permission with a given objectId (or tag)
+    # Apply a new permission with a given objectId (or tag)
+    # @overload apply(user, read = nil, write = nil)
+    #  Set the read and write permissions for this user on this ACL.
+    #  @param user [Parse::User] the user object.
+    #  @param read [Boolean] the read permission.
+    #  @param write [Boolean] the write permission.
+    # @overload apply(role, read = nil, write = nil)
+    #  Set the read and write permissions for this role object on this ACL.
+    #  @param role [Parse::Role] the role object.
+    #  @param read [Boolean] the read permission.
+    #  @param write [Boolean] the write permission.
+    # @overload apply(id, read = nil, write = nil)
+    #  Set the read and write permissions for this objectId on this ACL.
+    #  @param id [String] the objectId for a {Parse::User}.
+    #  @param read [Boolean] the read permission.
+    #  @param write [Boolean] the write permission.
+    # @return [Hash] the current set of permissions.
+    # @see #apply_role
     def apply(id, read = nil, write = nil)
+      return apply_role(id,read,write) if id.is_a?(Parse::Role)
       id = id.id if id.is_a?(Parse::Pointer)
       return unless id.present?
       # create a new Permissions
@@ -99,12 +199,24 @@ module Parse
       permissions
     end; alias_method :add, :apply
 
-    # You can apply a Role as a permission ex. "Admin". This will add the
-    # ACL of 'role:Admin' as the key in the permissions hash.
+    # Apply a {Parse::Role} to this ACL.
+    # @overload apply_role(role, read = nil, write = nil)
+    #  @param role [Parse::Role] the role object.
+    #  @param read [Boolean] the read permission.
+    #  @param write [Boolean] the write permission.
+    # @overload apply_role(role_name, read = nil, write = nil)
+    #  @param role_name [String] the name of the role.
+    #  @param read [Boolean] the read permission.
+    #  @param write [Boolean] the write permission.
     def apply_role(name, read = nil, write = nil)
+      name = name.name if name.is_a?(Parse::Role)
       apply("role:#{name}", read, write)
     end; alias_method :add_role, :apply_role
-    # Used for object conversion when formatting the input/output value in Parse::Object properties
+
+    # Used for object conversion when formatting the input/output value in
+    # Parse::Object properties
+    # @return [ACL]
+    # @see Parse::DataType
     def self.typecast(value, delegate = nil)
       ACL.new(value, owner: delegate)
     end
@@ -113,10 +225,13 @@ module Parse
     # in the Permissions hash, since omission means denial of priviledge. If the
     # permission value has neither read or write, then the entire record has been denied
     # all priviledges
+
+    # @return [Hash]
     def attributes
       permissions.select {|k,v| v.present? }.as_json
     end
 
+    # @!visibility private
     def attributes=(h)
       return unless h.is_a?(Hash)
       will_change!
@@ -126,48 +241,75 @@ module Parse
       end
     end
 
+    # @!visibility private
     def inspect
       "ACL(#{as_json.inspect})"
     end
 
+    # @return [Hash]
     def as_json(*args)
       permissions.select {|k,v| v.present? }.as_json
     end
 
+    # @return [Boolean] true if there are any permissions.
     def present?
       permissions.values.any? { |v| v.present? }
     end
 
-    # Permission class
+    # The Permission class tracks the read and write permissions for a specific
+    # ACL entry. The value of an Parse-ACL hash only contains two keys: "read" and "write".
+    #
+    #  # Example of the ACL format
+    #   { "*":          { "read": true },
+    #     "3KmCvT7Zsb": { "read": true, "write": true }
+    #   }
+    # This would be managed as:
+    #   { "*":          ACL::Permission.new(true),
+    #     "3KmCvT7Zsb": ACL::Permission.new(true, true)
+    #   }
+    #
     class Permission
       include ::ActiveModel::Model
       include ::ActiveModel::Serializers::JSON
-      # we don't support changing priviledges directly since it would become
-      # crazy to track for dirty tracking
-      attr_reader :read, :write
-
-      # initialize with read and write priviledge
-      def initialize(r = nil, w = nil)
-        if r.is_a?(Hash)
-          r.symbolize_keys!
-          # @read = true if r[:read].nil? || r[:read].present?
-          # @write = true if r[:write].nil? || r[:write].present?
-          @read = r[:read].present?
-          @write = r[:write].present?
+
+      # The *read* permission state.
+      # @return [Boolean] whether this permission is allowed.
+      attr_reader :read
+
+      # The *write* permission state.
+      # @return [Boolean] whether this permission is allowed.
+      attr_reader :write
+
+      # Create a new permission with the given read and write priviledges.
+      # @overload new(read = nil, write = nil)
+      #  @param read [Boolean] whether reading is allowed.
+      #  @param write [Boolean] whether writing is allowed.
+      #  @example
+      #   ACL::Permission.new(true, false)
+      # @overload new(hash)
+      #  @param hash [Hash] a key value pair for read/write permissions.
+      #  @example
+      #   ACL::Permission.new({read: true, write: false})
+      #
+      def initialize(r_perm = nil, w_perm = nil)
+        if r_perm.is_a?(Hash)
+          r_perm.symbolize_keys!
+          @read = r_perm[:read].present?
+          @write = r_perm[:write].present?
         else
-          # @read = true if r.nil? || r.present?
-          # @write = true if w.nil? || w.present?
-          @read = r.present?
-          @write = w.present?
+          @read = r_perm.present?
+          @write = w_perm.present?
         end
       end
 
+      # @return [Boolean] whether two permission instances have the same permissions.
       def ==(per)
         return false unless per.is_a?(self.class)
         @read == per.read && @write == per.write
       end
 
-      # omission or false on a priviledge means don't include it
+      # @return [Hash] A Parse-compatible ACL-hash. Omission or false on a
+      #  priviledge means don't include it
       def as_json(*args)
         h = {}
         h[:read] = true if @read
@@ -175,6 +317,7 @@ module Parse
         h.empty? ? nil : h.as_json
       end
 
+      # @return [Hash]
       def attributes
         h = {}
         h.merge!(read: :boolean) if @read
@@ -182,10 +325,12 @@ module Parse
         h
       end
 
+      # @!visibility private
       def inspect
         as_json.inspect
       end
 
+      # @return [Boolean] whether there is at least one permission set to true.
       def present?
         @read.present? || @write.present?
       end

data/lib/parse/model/associations/belongs_to.rb

@@ -8,6 +8,7 @@ require_relative 'relation_collection_proxy'
 
 
 module Parse
+  # Defines all the types of Parse object associations.
   module Associations
     # This association creates a one-to-one association with another Parse model.
     # BelongsTo relation is the simplies association in which the local

data/lib/parse/model/classes/role.rb

@@ -4,15 +4,21 @@ require_relative '../object'
 require_relative 'user'
 module Parse
   # This class represents the data and columns contained in the standard Parse `_Role` collection.
+  # Roles allow the an application to group a set of {Parse::User} records with the same set of
+  # permissions, so that specific records in the database can have {Parse::ACL}s related to a role
+  # than trying to add all the users in a group.
   class Role < Parse::Object
-    
+
     parse_class Parse::Model::CLASS_ROLE
     # @return [String] the name of this role.
     property :name
+    # This attribute is mapped as a `has_many` Parse relation association with the {Parse::Role} class,
+    # as roles can be associated with multiple child roles to support role inheritance.
     # The roles Parse relation provides a mechanism to create a hierarchical inheritable types of permissions
     # by assigning child roles.
     # @return [RelationCollectionProxy<Role>] a collection of Roles.
     has_many :roles, through: :relation
+    # This attribute is mapped as a `has_many` Parse relation association with the {Parse::User} class.
     # @return [RelationCollectionProxy<User>] a Parse relation of users belonging to this role.
     has_many :users, through: :relation
 

data/lib/parse/model/classes/session.rb

@@ -21,10 +21,14 @@ module Parse
     property :installation_id
     # @return [Boolean] whether this session token is restricted.
     property :restricted, :boolean
-    # @return [String] the session token for this installation and user pair.
+    # @!attribute [r] session_token
+    #  @return [String] the session token for this installation and user pair.
     property :session_token
-    # @return [User] the user corresponding to this session.
-    # @see User
+    # @!attribute [r] user
+    #  This property is mapped as a `belongs_to` association with the {Parse::User}
+    #  class. Every session instance is tied to a specific logged in user.
+    #  @return [User] the user corresponding to this session.
+    #  @see User
     belongs_to :user
 
     # Return the Session record for this session token.

data/lib/parse/model/classes/user.rb

@@ -21,6 +21,105 @@ module Parse
   # The main class representing the _User table in Parse. A user can either be signed up or anonymous.
   # All users need to have a username and a password, with email being optional but globally unique if set.
   # You may add additional properties by redeclaring the class to match your specific schema.
+  #
+  # *Signup*
+  #
+  # You can signup new users in two ways. You can either use a class method
+  # {Parse::User.signup} to create a new user with the minimum fields of username,
+  # password and email, or create a {Parse::User} object can call the {#signup!}
+  # method. If signup fails, it will raise the corresponding exception.
+  #
+  #  user = Parse::User.signup(username, password, email)
+  #
+  #  #or
+  #  user = Parse::User.new username: "user", password: "s3cret"
+  #  user.signup!
+  #
+  # *Login/Logout*
+  #
+  # With the {Parse::User} class, you can also perform login and logout
+  # functionality. The class special accessors for {#session_token} and {#session}
+  # to manage its authentication state. This will allow you to authenticate
+  # users as well as perform Parse queries as a specific user using their session
+  # token. To login a user, use the {Parse::User.login} method by supplying the
+  # corresponding username and password, or if you already have a user record,
+  # use {#login!} with the proper password.
+  #
+  #  user = Parse::User.login(username,password)
+  #  user.session_token # session token from a Parse::Session
+  #  user.session # Parse::Session tied to the token
+  #
+  #  # You can login user records
+  #  user = Parse::User.first
+  #  user.session_token # nil
+  #
+  #  passwd = 'p_n7!-e8' # corresponding password
+  #  user.login!(passwd) # true
+  #
+  #  user.session_token # 'r:pnktnjyb996sj4p156gjtp4im'
+  #
+  #  # logout to delete the session
+  #  user.logout
+  #
+  # If you happen to already have a valid session token, you can use it to
+  # retrieve the corresponding Parse::User.
+  #
+  #  # finds user with session token
+  #  user = Parse::User.session(session_token)
+  #
+  #  user.logout # deletes the corresponding session
+  #
+  # *OAuth-Login*
+  #
+  # You can signup users using third-party services like Facebook and Twitter as
+  # described in {https://parseplatform.github.io/docs/rest/guide/#signing-up-and-logging-in
+  # Signing Up and Logging In}. To do this with Parse-Stack, you can call the
+  # {Parse::User.autologin_service} method by passing the service name and the
+  # corresponding authentication hash data. For a listing of supported third-party
+  # authentication services, see {https://github.com/ParsePlatform/parse-server/wiki/OAuth OAuth}.
+  #
+  #  fb_auth = {}
+  #  fb_auth[:id] = "123456789"
+  #  fb_auth[:access_token] = "SaMpLeAAiZBLR995wxBvSGNoTrEaL"
+  #  fb_auth[:expiration_date] = "2025-02-21T23:49:36.353Z"
+  #
+  #  # signup or login a user with this auth data.
+  #  user = Parse::User.autologin_service(:facebook, fb_auth)
+  #
+  # You may also combine both approaches of signing up a new user with a
+  # third-party service and set additional custom fields. For this, use the
+  # method {Parse::User.create}.
+  #
+  #  # or to signup a user with additional data, but linked to Facebook
+  #  data = {
+  #    username: "johnsmith",
+  #    name: "John",
+  #    email: "user@example.com",
+  #    authData: { facebook: fb_auth }
+  #  }
+  #  user = Parse::User.create data
+  #
+  # *Linking/Unlinking*
+  #
+  # You can link or unlink user accounts with third-party services like
+  # Facebook and Twitter as described in:
+  # {https://parseplatform.github.io/docs/rest/guide/#linking Linking and Unlinking Users}.
+  # To do this, you must first get the corresponding authentication data for the
+  # specific service, and then apply it to the user using the linking and
+  # unlinking methods. Each method returns true or false if the action was
+  # successful. For a listing of supported third-party authentication services,
+  # see {https://github.com/ParsePlatform/parse-server/wiki/OAuth OAuth}.
+  #
+  #  user = Parse::User.first
+  #
+  #  fb_auth = { ... } # Facebook auth data
+  #
+  #  # Link this user's Facebook account with Parse
+  #  user.link_auth_data! :facebook, fb_auth
+  #
+  #  # Unlinks this user's Facebook account from Parse
+  #  user.unlink_auth_data! :facebook
+  #
   class User < Parse::Object
 
     parse_class Parse::Model::CLASS_USER
@@ -101,6 +200,7 @@ module Parse
 
     # Request a password reset for this user
     # @return [Boolean] true if it was successful requested. false otherwise.
+    # @see Parse::User.request_password_reset
     def request_password_reset
       return false if email.nil?
       Parse::User.request_password_reset(email)
@@ -251,6 +351,13 @@ module Parse
     end
 
     # Request a password reset for a registered email.
+    # @example
+    #  user = Parse::User.first
+    #
+    #  # pass a user object
+    #  Parse::User.request_password_reset user
+    #  # or email
+    #  Parse::User.request_password_reset("user@example.com")
     # @param email [String] The user's email address.
     # @return [Boolean] True/false if successful.
     def self.request_password_reset(email)