tilia-dav 3.1.0.pre.alpha2

data/lib/tilia/dav_acl/principal.rb

@@ -0,0 +1,213 @@
+module Tilia
+  module DavAcl
+    # Principal class
+    #
+    # This class is a representation of a simple principal
+    #
+    # Many WebDAV specs require a user to show up in the directory
+    # structure.
+    #
+    # This principal also has basic ACL settings, only allowing the principal
+    # access it's own principal.
+    class Principal < Dav::Node
+      include IPrincipal
+      include Dav::IProperties
+      include IAcl
+
+      # @!attribute [rw] principal_properties
+      #   @!visibility private
+      #   Struct with principal information.
+      #
+      #   @return [Hash]
+
+      # @!attribute [rw] principal_backend
+      #   @!visibility private
+      #   Principal backend
+      #
+      #   @return [PrincipalBackend::BackendInterface]
+
+      # Creates the principal object
+      #
+      # @param IPrincipalBackend principal_backend
+      # @param array principal_properties
+      def initialize(principal_backend, principal_properties = {})
+        fail Dav::Exception, 'The principal properties must at least contain the \'uri\' key' unless principal_properties.key?('uri')
+
+        @principal_backend = principal_backend
+        @principal_properties = principal_properties
+      end
+
+      # Returns the full principal url
+      #
+      # @return string
+      def principal_url
+        @principal_properties['uri']
+      end
+
+      # Returns a list of alternative urls for a principal
+      #
+      # This can for example be an email address, or ldap url.
+      #
+      # @return array
+      def alternate_uri_set
+        uris = []
+        if @principal_properties.key?('{DAV:}alternate-URI-set')
+          uris = @principal_properties['{DAV:}alternate-URI-set']
+        end
+
+        if @principal_properties.key?('{http://sabredav.org/ns}email-address')
+          uris << "mailto:#{@principal_properties['{http://sabredav.org/ns}email-address']}"
+        end
+
+        uris.uniq
+      end
+
+      # Returns the list of group members
+      #
+      # If this principal is a group, this function should return
+      # all member principal uri's for the group.
+      #
+      # @return array
+      def group_member_set
+        @principal_backend.group_member_set(@principal_properties['uri'])
+      end
+
+      # Returns the list of groups this principal is member of
+      #
+      # If this principal is a member of a (list of) groups, this function
+      # should return a list of principal uri's for it's members.
+      #
+      # @return array
+      def group_membership
+        @principal_backend.group_membership(@principal_properties['uri'])
+      end
+
+      # Sets a list of group members
+      #
+      # If this principal is a group, this method sets all the group members.
+      # The list of members is always overwritten, never appended to.
+      #
+      # This method should throw an exception if the members could not be set.
+      #
+      # @param array group_members
+      # @return void
+      def group_member_set=(group_members)
+        @principal_backend.update_group_member_set(@principal_properties['uri'], group_members)
+      end
+
+      # Returns this principals name.
+      #
+      # @return string
+      def name
+        uri = @principal_properties['uri']
+        name = Http::UrlUtil.split_path(uri)[1]
+        name
+      end
+
+      # Returns the name of the user
+      #
+      # @return string
+      def displayname
+        if @principal_properties.key?('{DAV:}displayname')
+          return @principal_properties['{DAV:}displayname']
+        else
+          return name
+        end
+      end
+
+      # Returns a list of properties
+      #
+      # @param array requested_properties
+      # @return array
+      def properties(requested_properties)
+        new_properties = {}
+        requested_properties.each do |prop_name|
+          if @principal_properties.key?(prop_name)
+            new_properties[prop_name] = @principal_properties[prop_name]
+          end
+        end
+
+        new_properties
+      end
+
+      # Updates properties on this node.
+      #
+      # This method received a PropPatch object, which contains all the
+      # information about the update.
+      #
+      # To update specific properties, call the 'handle' method on this object.
+      # Read the PropPatch documentation for more information.
+      #
+      # @param DAV\PropPatch prop_patch
+      # @return void
+      def prop_patch(prop_patch)
+        @principal_backend.update_principal(
+          @principal_properties['uri'],
+          prop_patch
+        )
+      end
+
+      # Returns the owner principal
+      #
+      # This must be a url to a principal, or null if there's no owner
+      #
+      # @return string|null
+      def owner
+        @principal_properties['uri']
+      end
+
+      # Returns a group principal
+      #
+      # This must be a url to a principal, or null if there's no owner
+      #
+      # @return string|null
+      def group
+        nil
+      end
+
+      # Returns a list of ACE's for this node.
+      #
+      # Each ACE has the following properties:
+      #   * 'privilege', a string such as {DAV:}read or {DAV:}write. These are
+      #     currently the only supported privileges
+      #   * 'principal', a url to the principal who owns the node
+      #   * 'protected' (optional), indicating that this ACE is not allowed to
+      #      be updated.
+      #
+      # @return array
+      def acl
+        [
+          {
+            'privilege' => '{DAV:}read',
+            'principal' => '{DAV:}authenticated',
+            'protected' => true
+          }
+        ]
+      end
+
+      # Updates the ACL
+      #
+      # This method will receive a list of new ACE's.
+      #
+      # @param array acl
+      # @return void
+      def acl=(_acl)
+        fail Dav::Exception::MethodNotAllowed, 'Updating ACLs is not allowed here'
+      end
+
+      # Returns the list of supported privileges for this node.
+      #
+      # The returned data structure is a list of nested privileges.
+      # See Tilia::DavAcl::Plugin::getDefaultSupportedPrivilegeSet for a simple
+      # standard structure.
+      #
+      # If null is returned from this method, the default privilege set is used,
+      # which is fine for most common usecases.
+      #
+      # @return array|null
+      def supported_privilege_set
+        nil
+      end
+    end
+  end
+end

data/lib/tilia/dav_acl/principal_backend.rb

@@ -0,0 +1,11 @@
+module Tilia
+  module DavAcl
+    module PrincipalBackend
+      require 'tilia/dav_acl/principal_backend/backend_interface'
+      require 'tilia/dav_acl/principal_backend/create_principal_support'
+
+      require 'tilia/dav_acl/principal_backend/abstract_backend'
+      require 'tilia/dav_acl/principal_backend/sequel'
+    end
+  end
+end

data/lib/tilia/dav_acl/principal_backend/abstract_backend.rb

@@ -0,0 +1,42 @@
+module Tilia
+  module DavAcl
+    module PrincipalBackend
+      # Abstract Principal Backend
+      #
+      # Currently this class has no function. It's here for consistency and so we
+      # have a non-bc-breaking way to add a default generic implementation to
+      # functions we may add in the future.
+      class AbstractBackend
+        include BackendInterface
+
+        # Finds a principal by its URI.
+        #
+        # This method may receive any type of uri, but mailto: addresses will be
+        # the most common.
+        #
+        # Implementation of this API is optional. It is currently used by the
+        # CalDAV system to find principals based on their email addresses. If this
+        # API is not implemented, some features may not work correctly.
+        #
+        # This method must return a relative principal path, or null, if the
+        # principal was not found or you refuse to find it.
+        #
+        # @param string uri
+        # @param string principal_prefix
+        # @return string
+        def find_by_uri(uri, principal_prefix)
+          # Note that the default implementation here is a bit slow and could
+          # likely be optimized.
+          return nil unless uri[0, 7] == 'mailto:'
+
+          result = search_principals(
+            principal_prefix,
+            '{http://sabredav.org/ns}email-address' => uri[7..-1]
+          )
+
+          result[0]
+        end
+      end
+    end
+  end
+end

data/lib/tilia/dav_acl/principal_backend/backend_interface.rb

@@ -0,0 +1,127 @@
+module Tilia
+  module DavAcl
+    module PrincipalBackend
+      # Implement this interface to create your own principal backends.
+      #
+      # Creating backends for principals is entirely optional. You can also
+      # implement Tilia::DavAcl::IPrincipal directly. This interface is used solely by
+      # Tilia::DavAcl::AbstractPrincipalCollection.
+      module BackendInterface
+        # Returns a list of principals based on a prefix.
+        #
+        # This prefix will often contain something like 'principals'. You are only
+        # expected to return principals that are in this base path.
+        #
+        # You are expected to return at least a 'uri' for every user, you can
+        # return any additional properties if you wish so. Common properties are:
+        #   {DAV:}displayname
+        #   {http://sabredav.org/ns}email-address - This is a custom SabreDAV
+        #     field that's actually injected in a number of other properties. If
+        #     you have an email address, use this property.
+        #
+        # @param string prefix_path
+        # @return array
+        def principals_by_prefix(prefix_path)
+        end
+
+        # Returns a specific principal, specified by it's path.
+        # The returned structure should be the exact same as from
+        # getPrincipalsByPrefix.
+        #
+        # @param string path
+        # @return array
+        def principal_by_path(path)
+        end
+
+        # Updates one ore more webdav properties on a principal.
+        #
+        # The list of mutations is stored in a Sabre\DAV\PropPatch object.
+        # To do the actual updates, you must tell this object which properties
+        # you're going to process with the handle method.
+        #
+        # Calling the handle method is like telling the PropPatch object "I
+        # promise I can handle updating this property".
+        #
+        # Read the PropPatch documenation for more info and examples.
+        #
+        # @param string path
+        # @param \Sabre\DAV\PropPatch prop_patch
+        # @return void
+        def update_principal(path, prop_patch)
+        end
+
+        # This method is used to search for principals matching a set of
+        # properties.
+        #
+        # This search is specifically used by RFC3744's principal-property-search
+        # REPORT.
+        #
+        # The actual search should be a unicode-non-case-sensitive search. The
+        # keys in searchProperties are the WebDAV property names, while the values
+        # are the property values to search on.
+        #
+        # By default, if multiple properties are submitted to this method, the
+        # various properties should be combined with 'AND'. If test is set to
+        # 'anyof', it should be combined using 'OR'.
+        #
+        # This method should simply return an array with full principal uri's.
+        #
+        # If somebody attempted to search on a property the backend does not
+        # support, you should simply return 0 results.
+        #
+        # You can also just return 0 results if you choose to not support
+        # searching at all, but keep in mind that this may stop certain features
+        # from working.
+        #
+        # @param string prefix_path
+        # @param array search_properties
+        # @param string test
+        # @return array
+        def search_principals(prefix_path, search_properties, test = 'allof')
+        end
+
+        # Finds a principal by its URI.
+        #
+        # This method may receive any type of uri, but mailto: addresses will be
+        # the most common.
+        #
+        # Implementation of this API is optional. It is currently used by the
+        # CalDAV system to find principals based on their email addresses. If this
+        # API is not implemented, some features may not work correctly.
+        #
+        # This method must return a relative principal path, or null, if the
+        # principal was not found or you refuse to find it.
+        #
+        # @param string uri
+        # @param string principal_prefix
+        # @return string
+        def find_by_uri(uri, principal_prefix)
+        end
+
+        # Returns the list of members for a group-principal
+        #
+        # @param string principal
+        # @return array
+        def group_member_set(principal)
+        end
+
+        # Returns the list of groups a principal is a member of
+        #
+        # @param string principal
+        # @return array
+        def group_membership(principal)
+        end
+
+        # Updates the list of group members for a group principal.
+        #
+        # The principals should be passed as a list of uri's.
+        #
+        # @param string principal
+        # @param array members
+        # @return void
+        def update_group_member_set(principal, members)
+        end
+      end
+    end
+  end
+end

data/lib/tilia/dav_acl/principal_backend/create_principal_support.rb

@@ -0,0 +1,27 @@
+module Tilia
+  module DavAcl
+    module PrincipalBackend
+      # Implement this interface to add support for creating new principals to your
+      # principal backend.
+      #
+      # @copyright Copyright (C) 2007-2015 fruux GmbH (https://fruux.com/).
+      # @author Evert Pot (http://evertpot.com/)
+      # @license http://sabre.io/license/ Modified BSD License
+      module CreatePrincipalSupport
+        include BackendInterface
+
+        # Creates a new principal.
+        #
+        # This method receives a full path for the new principal. The mkCol object
+        # contains any additional webdav properties specified during the creation
+        # of the principal.
+        #
+        # @param string path
+        # @param MkCol mk_col
+        # @return void
+        def create_principal(path, mk_col)
+        end
+      end
+    end
+  end
+end

data/lib/tilia/dav_acl/principal_backend/sequel.rb

@@ -0,0 +1,313 @@
+module Tilia
+  module DavAcl
+    module PrincipalBackend
+      # PDO principal backend
+      #
+      # This backend assumes all principals are in a single collection. The default collection
+      # is 'principals/', but this can be overriden.
+      class Sequel < AbstractBackend
+        include CreatePrincipalSupport
+
+        # PDO table name for 'principals'
+        #
+        # @var string
+        attr_accessor :table_name
+
+        # PDO table name for 'group members'
+        #
+        # @var string
+        attr_accessor :group_members_table_name
+
+        protected
+
+        # pdo
+        #
+        # @var PDO
+        attr_accessor :sequel
+
+        # A list of additional fields to support
+        #
+        # @var array
+        attr_accessor :field_map
+
+        public
+
+        # Sets up the backend.
+        #
+        # @param PDO pdo
+        def initialize(sequel)
+          @table_name = 'principals'
+          @group_members_table_name = 'groupmembers'
+          @field_map = {
+            # This property can be used to display the users' real name.
+            '{DAV:}displayname' => {
+              'dbField' => 'displayname'
+            },
+
+            # This is the users' primary email-address.
+            '{http://sabredav.org/ns}email-address' => {
+              'dbField' => 'email'
+            }
+          }
+          @sequel = sequel
+        end
+
+        # Returns a list of principals based on a prefix.
+        #
+        # This prefix will often contain something like 'principals'. You are only
+        # expected to return principals that are in this base path.
+        #
+        # You are expected to return at least a 'uri' for every user, you can
+        # return any additional properties if you wish so. Common properties are:
+        #   {DAV:}displayname
+        #   {http://sabredav.org/ns}email-address - This is a custom SabreDAV
+        #     field that's actualy injected in a number of other properties. If
+        #     you have an email address, use this property.
+        #
+        # @param string prefix_path
+        # @return array
+        def principals_by_prefix(prefix_path)
+          fields = ['uri']
+
+          @field_map.each do |_key, value|
+            fields << value['dbField']
+          end
+
+          principals = []
+          @sequel.fetch("SELECT #{fields.join(',')} FROM #{@table_name}") do |row|
+            # Checking if the principal is in the prefix
+            row_prefix = Http::UrlUtil.split_path(row[:uri])[0]
+
+            next unless row_prefix == prefix_path
+
+            principal = {
+              'uri' => row[:uri]
+            }
+
+            @field_map.each do |key, value|
+              unless row[value['dbField'].to_sym].blank?
+                principal[key] = row[value['dbField'].to_sym]
+              end
+            end
+            principals << principal
+          end
+
+          principals
+        end
+
+        # Returns a specific principal, specified by it's path.
+        # The returned structure should be the exact same as from
+        # getPrincipalsByPrefix.
+        #
+        # @param string path
+        # @return array
+        def principal_by_path(path)
+          fields = [
+            'id',
+            'uri'
+          ]
+
+          @field_map.each do |_key, value|
+            fields << value['dbField']
+          end
+
+          ds = @sequel["SELECT #{fields.join(',')}  FROM #{@table_name} WHERE uri = ?", path]
+          row = ds.all.first
+
+          return unless row
+
+          principal = {
+            'id'  => row[:id],
+            'uri' => row[:uri]
+          }
+
+          @field_map.each do |key, value|
+            if row[value['dbField'].to_sym]
+              principal[key] = row[value['dbField'].to_sym]
+            end
+          end
+
+          principal
+        end
+
+        # Updates one ore more webdav properties on a principal.
+        #
+        # The list of mutations is stored in a Sabre\DAV\PropPatch object.
+        # To do the actual updates, you must tell this object which properties
+        # you're going to process with the handle method.
+        #
+        # Calling the handle method is like telling the PropPatch object "I
+        # promise I can handle updating this property".
+        #
+        # Read the PropPatch documenation for more info and examples.
+        #
+        # @param string path
+        # @param DAV\PropPatch prop_patch
+        def update_principal(path, prop_patch)
+          prop_patch.handle(
+            @field_map.keys,
+            lambda do |properties|
+              query = "UPDATE #{@table_name} SET "
+
+              first = true
+              values = {}
+              properties.each do |key, value|
+                db_field = @field_map[key]['dbField']
+
+                query << ', ' unless first
+                first = false
+                query << "#{db_field} = :#{db_field}"
+                values[db_field.to_sym] = value
+              end
+
+              query << ' WHERE uri = :uri'
+              values[:uri] = path
+
+              ds = @sequel[query, values]
+              ds.update
+
+              true
+            end
+          )
+        end
+
+        # This method is used to search for principals matching a set of
+        # properties.
+        #
+        # This search is specifically used by RFC3744's principal-property-search
+        # REPORT.
+        #
+        # The actual search should be a unicode-non-case-sensitive search. The
+        # keys in searchProperties are the WebDAV property names, while the values
+        # are the property values to search on.
+        #
+        # By default, if multiple properties are submitted to this method, the
+        # various properties should be combined with 'AND'. If test is set to
+        # 'anyof', it should be combined using 'OR'.
+        #
+        # This method should simply return an array with full principal uri's.
+        #
+        # If somebody attempted to search on a property the backend does not
+        # support, you should simply return 0 results.
+        #
+        # You can also just return 0 results if you choose to not support
+        # searching at all, but keep in mind that this may stop certain features
+        # from working.
+        #
+        # @param string prefix_path
+        # @param array search_properties
+        # @param string test
+        # @return array
+        def search_principals(prefix_path, search_properties, _test = 'allof')
+          query = "SELECT uri FROM #{@table_name} WHERE 1=1 "
+          values = []
+
+          search_properties.each do |property, value|
+            case property
+            when '{DAV:}displayname'
+              query << ' AND displayname LIKE ?'
+              values << "%#{value}%"
+            when '{http://sabredav.org/ns}email-address'
+              query << ' AND email LIKE ?'
+              values << "%#{value}%"
+            else
+              # Unsupported property
+              return []
+            end
+          end
+
+          principals = []
+          @sequel.fetch(query, *values) do |row|
+            # Checking if the principal is in the prefix
+            row_prefix = Http::UrlUtil.split_path(row[:uri])[0]
+            next unless row_prefix == prefix_path
+
+            principals << row[:uri]
+          end
+
+          principals
+        end
+
+        # Returns the list of members for a group-principal
+        #
+        # @param string principal
+        # @return array
+        def group_member_set(principal)
+          principal = principal_by_path(principal)
+          fail Dav::Exception, 'Principal not found' if principal.empty?
+
+          result = []
+          @sequel.fetch("SELECT principals.uri as uri FROM #{@group_members_table_name} AS groupmembers LEFT JOIN #{@table_name} AS principals ON groupmembers.member_id = principals.id WHERE groupmembers.principal_id = ?", principal['id']) do |row|
+            result << row[:uri]
+          end
+
+          result
+        end
+
+        # Returns the list of groups a principal is a member of
+        #
+        # @param string principal
+        # @return array
+        def group_membership(principal)
+          principal = principal_by_path(principal)
+          fail Dav::Exception, 'Principal not found' if principal.empty?
+
+          result = []
+          @sequel.fetch("SELECT principals.uri as uri FROM #{@group_members_table_name} AS groupmembers LEFT JOIN #{@table_name} AS principals ON groupmembers.principal_id = principals.id WHERE groupmembers.member_id = ?", principal['id']) do |row|
+            result << row[:uri]
+          end
+
+          result
+        end
+
+        # Updates the list of group members for a group principal.
+        #
+        # The principals should be passed as a list of uri's.
+        #
+        # @param string principal
+        # @param array members
+        # @return void
+        def update_group_member_set(principal, members)
+          # Grabbing the list of principal id's.
+          member_ids = []
+          principal_id = nil
+
+          @sequel.fetch("SELECT id, uri FROM #{@table_name} WHERE uri IN (?#{', ?' * members.size})", principal, *members) do |row|
+            if row[:uri] == principal
+              principal_id = row[:id]
+            else
+              member_ids << row[:id]
+            end
+          end
+
+          fail Dav::Exception, 'Principal not found' unless principal_id
+
+          # Wiping out old members
+          ds = @sequel["DELETE FROM #{@group_members_table_name} WHERE principal_id = ?", principal_id]
+          ds.delete
+
+          member_ids.each do |member_id|
+            ds = @sequel["INSERT INTO #{@group_members_table_name} (principal_id, member_id) VALUES (?, ?)", principal_id, member_id]
+            ds.insert
+          end
+        end
+
+        # Creates a new principal.
+        #
+        # This method receives a full path for the new principal. The mkCol object
+        # contains any additional webdav properties specified during the creation
+        # of the principal.
+        #
+        # @param string path
+        # @param MkCol mk_col
+        # @return void
+        def create_principal(path, mk_col)
+          ds = @sequel["INSERT INTO #{@table_name} (uri) VALUES (?)", path]
+          ds.insert
+
+          update_principal(path, mk_col)
+        end
+      end
+    end
+  end
+end