tilia-dav 3.1.0.pre.alpha2

data/lib/tilia/dav/prop_patch.rb

@@ -0,0 +1,278 @@
+module Tilia
+  module Dav
+    # This class represents a set of properties that are going to be updated.
+    #
+    # Usually this is simply a PROPPATCH request, but it can also be used for
+    # internal updates.
+    #
+    # Property updates must always be atomic. This means that a property update
+    # must either completely succeed, or completely fail.
+    class PropPatch
+      # Properties that are being updated.
+      #
+      # This is a key-value list. If the value is null, the property is supposed
+      # to be deleted.
+      #
+      # @var array
+      attr_accessor :mutations
+
+      # A list of properties and the result of the update. The result is in the
+      # form of a HTTP status code.
+      #
+      # @var array
+      attr_accessor :result
+
+      # This is the list of callbacks when we're performing the actual update.
+      #
+      # @var array
+      attr_accessor :property_update_callbacks
+
+      # This property will be set to true if the operation failed.
+      #
+      # @var bool
+      attr_accessor :failed
+
+      # Constructor
+      #
+      # @param array mutations A list of updates
+      def initialize(mutations)
+        self.mutations = mutations
+        self.result = {}
+        self.failed = false
+        self.property_update_callbacks = []
+      end
+
+      # Call this function if you wish to handle updating certain properties.
+      # For instance, your class may be responsible for handling updates for the
+      # {DAV:}displayname property.
+      #
+      # In that case, call this method with the first argument
+      # "{DAV:}displayname" and a second argument that's a method that does the
+      # actual updating.
+      #
+      # It's possible to specify more than one property as an array.
+      #
+      # The callback must return a boolean or an it. If the result is true, the
+      # operation was considered successful. If it's false, it's consided
+      # failed.
+      #
+      # If the result is an integer, we'll use that integer as the http status
+      # code associated with the operation.
+      #
+      # @param string|string[] properties
+      # @param callable callback
+      # @return void
+      def handle(properties, callback)
+        used_properties = []
+        [properties].flatten.each do |property_name|
+          next unless mutations.key?(property_name) && !result.key?(property_name)
+          used_properties << property_name
+          # HTTP Accepted
+          result[property_name] = 202
+        end
+
+        # Only registering if there's any unhandled properties.
+        return nil unless used_properties.any?
+
+        property_update_callbacks << [
+          # If the original argument to this method was a string, we need
+          # to also make sure that it stays that way, so the commit function
+          # knows how to format the arguments to the callback.
+          properties.is_a?(String) ? properties : used_properties,
+          callback]
+      end
+
+      # Call this function if you wish to handle _all_ properties that haven't
+      # been handled by anything else yet. Note that you effectively claim with
+      # this that you promise to process _all_ properties that are coming in.
+      #
+      # @param callable callback
+      # @return void
+      def handle_remaining(callback)
+        properties = remaining_mutations
+        unless properties.any?
+          # Nothing to do, don't register callback
+          return
+        end
+
+        properties.each do |property_name|
+          # HTTP Accepted
+          result[property_name] = 202
+
+          property_update_callbacks << [
+            properties,
+            callback]
+        end
+      end
+
+      # Sets the result code for one or more properties.
+      #
+      # @param string|string[] properties
+      # @param int result_code
+      # @return void
+      def update_result_code(properties, result_code)
+        [properties].flatten.each do |property_name|
+          result[property_name] = result_code
+        end
+
+        self.failed = true if result_code >= 400
+      end
+
+      # Sets the result code for all properties that did not have a result yet.
+      #
+      # @param int result_code
+      # @return void
+      def remaining_result_code=(result_code)
+        update_result_code(
+          remaining_mutations,
+          result_code
+        )
+      end
+
+      # Returns the list of properties that don't have a result code yet.
+      #
+      # This method returns a list of property names, but not its values.
+      #
+      # @return string[]
+      def remaining_mutations
+        remaining = []
+        mutations.keys.each do |property_name|
+          remaining << property_name unless result.key? property_name
+        end
+        remaining
+      end
+
+      # Returns the list of properties that don't have a result code yet.
+      #
+      # This method returns list of properties and their values.
+      #
+      # @return array
+      def remaining_values
+        remaining = {}
+        mutations.each do |property_name, prop_value|
+          remaining[property_name] = prop_value unless result.key? property_name
+        end
+        remaining
+      end
+
+      # Performs the actual update, and calls all callbacks.
+      #
+      # This method returns true or false depending on if the operation was
+      # successful.
+      #
+      # @return bool
+      def commit
+        # First we validate if every property has a handler
+        mutations.keys.each do |property_name|
+          unless result.key? property_name
+            self.failed = true
+            result[property_name] = 403
+          end
+        end
+
+        property_update_callbacks.each do |callbackInfo|
+          break if failed
+          if callbackInfo[0].is_a? String
+            do_callback_single_prop(callbackInfo[0], callbackInfo[1])
+          else
+            do_callback_multi_prop(callbackInfo[0], callbackInfo[1])
+          end
+        end
+
+        # If anywhere in this operation updating a property failed, we must
+        # update all other properties accordingly.
+        if failed
+          result.each do |property_name, status|
+            if status == 202
+              # Failed dependency
+              result[property_name] = 424
+            end
+          end
+        end
+
+        !failed
+      end
+
+      # Returns the result of the operation.
+      #
+      # @return array
+      attr_reader :result
+
+      # Returns the full list of mutations
+      #
+      # @return array
+      attr_reader :mutations
+
+      private
+
+      # Executes a property callback with the single-property syntax.
+      #
+      # @param string property_name
+      # @param callable callback
+      # @return void
+      def do_callback_single_prop(property_name, callback)
+        result = callback.call(mutations[property_name])
+        if result.is_a?(TrueClass) || result.is_a?(FalseClass)
+          if result
+            if mutations[property_name].nil?
+              # Delete
+              result = 204
+            else
+              # Update
+              result = 200
+            end
+          else
+            # Fail
+            result = 403
+          end
+        end
+
+        unless result.is_a? Fixnum
+          fail 'A callback sent to handle() did not return an int or a bool'
+        end
+        self.result[property_name] = result
+        self.failed = true if result >= 400
+      end
+
+      # Executes a property callback with the multi-property syntax.
+      #
+      # @param array property_list
+      # @param callable callback
+      # @return void
+      def do_callback_multi_prop(property_list, callback)
+        argument = {}
+        property_list.each do |property_name|
+          argument[property_name] = mutations[property_name]
+        end
+
+        result = callback.call(argument)
+
+        if result.is_a? Hash
+          property_list.each do |property_name|
+            unless result.key? property_name
+              result_code = 500
+            else
+              result_code = result[property_name]
+            end
+            self.failed = true if result_code >= 400
+
+            self.result[property_name] = result_code
+          end
+        elsif result == true
+          # Success
+          argument.each do |property_name, property_value|
+            self.result[property_name] = property_value.nil? ? 204 : 200
+          end
+        elsif result == false
+          # Fail :(
+          self.failed = true
+          property_list.each do |property_name|
+            self.result[property_name] = 403
+          end
+        else
+          fail 'A callback sent to handle() did not return an array or a bool'
+        end
+      end
+    end
+  end
+end

data/lib/tilia/dav/property_storage.rb

@@ -0,0 +1,8 @@
+module Tilia
+  module Dav
+    module PropertyStorage
+      require 'tilia/dav/property_storage/backend'
+      require 'tilia/dav/property_storage/plugin'
+    end
+  end
+end

data/lib/tilia/dav/property_storage/backend.rb

@@ -0,0 +1,10 @@
+module Tilia
+  module Dav
+    module PropertyStorage
+      module Backend
+        require 'tilia/dav/property_storage/backend/backend_interface'
+        require 'tilia/dav/property_storage/backend/sequel'
+      end
+    end
+  end
+end

data/lib/tilia/dav/property_storage/backend/backend_interface.rb

@@ -0,0 +1,69 @@
+module Tilia
+  module Dav
+    module PropertyStorage
+      module Backend
+        # Propertystorage backend interface.
+        #
+        # Propertystorage backends must implement this interface to be used by the
+        # propertystorage plugin.
+        module BackendInterface
+          # Fetches properties for a path.
+          #
+          # This method received a PropFind object, which contains all the
+          # information about the properties that need to be fetched.
+          #
+          # Ususually you would just want to call 'get404Properties' on this object,
+          # as this will give you the _exact_ list of properties that need to be
+          # fetched, and haven't yet.
+          #
+          # However, you can also support the 'allprops' property here. In that
+          # case, you should check for prop_find.all_props?.
+          #
+          # @param string path
+          # @param PropFind prop_find
+          # @return void
+          def prop_find(_path, _prop_find)
+          end
+
+          # Updates properties for a path
+          #
+          # This method received a PropPatch object, which contains all the
+          # information about the update.
+          #
+          # Usually you would want to call 'handleRemaining' on this object, to get
+          # a list of all properties that need to be stored.
+          #
+          # @param string path
+          # @param PropPatch prop_patch
+          # @return void
+          def prop_patch(_path, _prop_patch)
+          end
+
+          # This method is called after a node is deleted.
+          #
+          # This allows a backend to clean up all associated properties.
+          #
+          # The delete method will get called once for the deletion of an entire
+          # tree.
+          #
+          # @param string path
+          # @return void
+          def delete(_path)
+          end
+
+          # This method is called after a successful MOVE
+          #
+          # This should be used to migrate all properties from one path to another.
+          # Note that entire collections may be moved, so ensure that all properties
+          # for children are also moved along.
+          #
+          # @param string source
+          # @param string destination
+          # @return void
+          def move(_source, _destination)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tilia/dav/property_storage/backend/sequel.rb

@@ -0,0 +1,192 @@
+require 'yaml'
+
+module Tilia
+  module Dav
+    module PropertyStorage
+      module Backend
+        # PropertyStorage PDO backend.
+        #
+        # This backend class uses a PDO-enabled database to store webdav properties.
+        # Both sqlite and mysql have been tested.
+        #
+        # The database structure can be found in the examples/sql/ directory.
+        class Sequel
+          include BackendInterface
+
+          # Value is stored as string.
+          VT_STRING = 1
+
+          # Value is stored as XML fragment.
+          VT_XML = 2
+
+          # Value is stored as a property object.
+          VT_OBJECT = 3
+
+          protected
+
+          # PDO
+          #
+          # @var sequel
+          attr_accessor :sequel
+
+          public
+
+          # PDO table name we'll be using
+          #
+          # @var string
+          attr_accessor :table_name
+
+          # Creates the PDO property storage engine
+          #
+          # @param Sequel sequel
+          def initialize(sequel)
+            @sequel = sequel
+            @table_name = 'propertystorage'
+          end
+
+          # Fetches properties for a path.
+          #
+          # This method received a PropFind object, which contains all the
+          # information about the properties that need to be fetched.
+          #
+          # Ususually you would just want to call 'get404Properties' on this object,
+          # as this will give you the _exact_ list of properties that need to be
+          # fetched, and haven't yet.
+          #
+          # However, you can also support the 'allprops' property here. In that
+          # case, you should check for prop_find.all_props?.
+          #
+          # @param string path
+          # @param PropFind prop_find
+          # @return void
+          def prop_find(path, prop_find)
+            if !prop_find.all_props? && prop_find.load_404_properties.size == 0
+              return
+            end
+
+            @sequel.fetch("SELECT name, value, valuetype FROM #{@table_name} WHERE path = ?", path) do |row|
+              case row[:valuetype]
+              when nil, VT_STRING
+                prop_find.set(row[:name], row[:value])
+              when VT_XML
+                prop_find.set(row[:name], Xml::Property::Complex.new(row[:value]))
+              when VT_OBJECT
+                prop_find.set(row[:name], YAML.load(row[:value]))
+              end
+            end
+          end
+
+          # Updates properties for a path
+          #
+          # This method received a PropPatch object, which contains all the
+          # information about the update.
+          #
+          # Usually you would want to call 'handleRemaining' on this object, to get
+          # a list of all properties that need to be stored.
+          #
+          # @param string path
+          # @param PropPatch prop_patch
+          # @return void
+          def prop_patch(path, prop_patch)
+            prop_patch.handle_remaining(
+              lambda do |properties|
+                update_stmt = "REPLACE INTO #{@table_name} (path, name, valuetype, value) VALUES (?, ?, ?, ?)"
+                delete_stmt = "DELETE FROM #{@table_name} WHERE path = ? AND name = ?"
+
+                properties.each do |name, value|
+                  if !value.nil?
+                    if value.scalar?
+                      value_type = VT_STRING
+                    elsif value.is_a?(Xml::Property::Complex)
+                      value_type = VT_XML
+                      value = value.xml
+                    else
+                      value_type = VT_OBJECT
+                      value = YAML.dump(value)
+                    end
+
+                    update_ds = @sequel[
+                      update_stmt,
+                      path,
+                      name,
+                      value_type,
+                      value
+                    ]
+                    update_ds.update
+                  else
+                    delete_ds = @sequel[
+                      delete_stmt,
+                      path,
+                      name
+                    ]
+                    delete_ds.delete
+                  end
+                end
+
+                true
+              end
+            )
+          end
+
+          # This method is called after a node is deleted.
+          #
+          # This allows a backend to clean up all associated properties.
+          #
+          # The delete method will get called once for the deletion of an entire
+          # tree.
+          #
+          # @param string path
+          # @return void
+          def delete(path)
+            child_path = path.gsub(
+              /[=%_]/,
+              '=' => '==',
+              '%' => '=%',
+              '_' => '=_'
+            )
+            child_path << '/%'
+            delete_ds = @sequel[
+              "DELETE FROM #{@table_name} WHERE path = ? OR path LIKE ? ESCAPE '='",
+              path,
+              child_path
+            ]
+            delete_ds.delete
+          end
+
+          # This method is called after a successful MOVE
+          #
+          # This should be used to migrate all properties from one path to another.
+          # Note that entire collections may be moved, so ensure that all properties
+          # for children are also moved along.
+          #
+          # @param string source
+          # @param string destination
+          # @return void
+          def move(source, destination)
+            # I don't know a way to write this all in a single sql query that's
+            # also compatible across db engines, so we're letting PHP do all the
+            # updates. Much slower, but it should still be pretty fast in most
+            # cases.
+            update = "UPDATE #{table_name} SET path = ? WHERE id = ?"
+            @sequel.fetch("SELECT id, path FROM #{@table_name} WHERE path = ? OR path LIKE ?", source, "#{source}/%") do |row|
+              # Sanity check. SQL may select too many records, such as records
+              # with different cases.
+              next if row[:path] != source && row[:path].index("#{source}/") != 0
+
+              trailing_part = row[:path][source.size + 1..-1]
+              new_path = destination
+              new_path << "/#{trailing_part}" unless trailing_part.blank?
+
+              update_ds = @sequel[
+                update,
+                new_path,
+                row[:id]
+              ]
+              update_ds.update
+            end
+          end
+        end
+      end
+    end
+  end
+end