tilia-dav 3.1.0.pre.alpha2

data/lib/tilia/dav/server_plugin.rb

@@ -0,0 +1,81 @@
+module Tilia
+  module Dav
+    # The baseclass for all server plugins.
+    #
+    # Plugins can modify or extend the servers behaviour.
+    class ServerPlugin
+      # This initializes the plugin.
+      #
+      # This function is called by Sabre\DAV\Server, after
+      # addPlugin is called.
+      #
+      # This method should set up the required event subscriptions.
+      #
+      # @param Server server
+      # @return void
+      def setup(server)
+      end
+
+      # This method should return a list of server-features.
+      #
+      # This is for example 'versioning' and is added to the DAV: header
+      # in an OPTIONS response.
+      #
+      # @return array
+      def features
+        []
+      end
+
+      # Use this method to tell the server this plugin defines additional
+      # HTTP methods.
+      #
+      # This method is passed a uri. It should only return HTTP methods that are
+      # available for the specified uri.
+      #
+      # @param string path
+      # @return array
+      def http_methods(_path)
+        []
+      end
+
+      # Returns a plugin name.
+      #
+      # Using this name other plugins will be able to access other plugins
+      # using \Sabre\DAV\Server::getPlugin
+      #
+      # @return string
+      def plugin_name
+        self.class.to_s
+      end
+
+      # Returns a list of reports this plugin supports.
+      #
+      # This will be used in the {DAV:}supported-report-set property.
+      # Note that you still need to subscribe to the 'report' event to actually
+      # implement them
+      #
+      # @param string uri
+      # @return array
+      def supported_report_set(_uri)
+        []
+      end
+
+      # Returns a bunch of meta-data about the plugin.
+      #
+      # Providing this information is optional, and is mainly displayed by the
+      # Browser plugin.
+      #
+      # The description key in the returned array may contain html and will not
+      # be sanitized.
+      #
+      # @return array
+      def plugin_info
+        {
+          'name' => plugin_name,
+          'description' => nil,
+          'link' => nil
+        }
+      end
+    end
+  end
+end

data/lib/tilia/dav/simple_collection.rb

@@ -0,0 +1,71 @@
+module Tilia
+  module Dav
+    # SimpleCollection
+    #
+    # The SimpleCollection is used to quickly setup static directory structures.
+    # Just create the object with a proper name, and add children to use it.
+    class SimpleCollection < Collection
+      # List of childnodes
+      #
+      # @var INode[]
+      attr_accessor :children
+
+      # Name of this resource
+      #
+      # @var string
+      attr_accessor :name
+
+      # Creates this node
+      #
+      # The name of the node must be passed, child nodes can also be passed.
+      # This nodes must be instances of INode
+      #
+      # @param string name
+      # @param INode[] children
+      def initialize(name, children = [])
+        @name = name
+        @children = {}
+        children.each do |child|
+          fail(Exception, 'Only instances of Sabre\DAV\INode are allowed to be passed in the children argument') unless child.is_a? INode
+          add_child(child)
+        end
+      end
+
+      # Adds a new childnode to this collection
+      #
+      # @param INode child
+      # @return void
+      def add_child(child)
+        @children[child.name] = child
+      end
+
+      # Returns the name of the collection
+      #
+      # @return string
+      attr_reader :name
+
+      # Returns a child object, by its name.
+      #
+      # This method makes use of the getChildren method to grab all the child nodes, and compares the name.
+      # Generally its wise to override this, as this can usually be optimized
+      #
+      # This method must throw Sabre\DAV\Exception\NotFound if the node does not
+      # exist.
+      #
+      # @param string name
+      # @throws Exception\NotFound
+      # @return INode
+      def child(name)
+        return @children[name] if @children.key?(name)
+        fail Exception::NotFound, "File not found: #{name} in '#{name}'"
+      end
+
+      # Returns a list of children for this collection
+      #
+      # @return INode[]
+      def children
+        @children.values
+      end
+    end
+  end
+end

data/lib/tilia/dav/simple_file.rb

@@ -0,0 +1,82 @@
+require 'digest'
+module Tilia
+  module Dav
+    # SimpleFile
+    #
+    # The 'SimpleFile' class is used to easily add read-only immutable files to
+    # the directory structure. One usecase would be to add a 'readme.txt' to a
+    # root of a webserver with some standard content.
+    class SimpleFile < File
+      # File contents
+      #
+      # @var string
+      attr_accessor :contents
+
+      # Name of this resource
+      #
+      # @var string
+      attr_accessor :name
+
+      # A mimetype, such as 'text/plain' or 'text/html'
+      #
+      # @var string
+      attr_accessor :mime_type
+
+      # Creates this node
+      #
+      # The name of the node must be passed, as well as the contents of the
+      # file.
+      #
+      # @param string name
+      # @param string contents
+      # @param string|nil mime_type
+      def initialize(name, contents, mime_type = nil)
+        @name = name
+        @contents = contents
+        @mime_type = mime_type
+      end
+
+      # Returns the node name for this file.
+      #
+      # This name is used to construct the url.
+      #
+      # @return string
+      attr_reader :name
+
+      # Returns the data
+      #
+      # This method may either return a string or a readable stream resource
+      #
+      # @return mixed
+      def get
+        @contents
+      end
+
+      # Returns the size of the file, in bytes.
+      #
+      # @return int
+      def size
+        @contents.bytes.size
+      end
+
+      # Returns the ETag for a file
+      #
+      # An ETag is a unique identifier representing the current version of the file. If the file changes, the ETag MUST change.
+      # The ETag is an arbitrary string, but MUST be surrounded by double-quotes.
+      #
+      # Return null if the ETag can not effectively be determined
+      # @return string
+      def etag
+        '"' + Digest::SHA1.hexdigest(@contents) + '"'
+      end
+
+      # Returns the mime-type for a file
+      #
+      # If null is returned, we'll assume application/octet-stream
+      # @return string
+      def content_type
+        @mime_type
+      end
+    end
+  end
+end

data/lib/tilia/dav/string_util.rb

@@ -0,0 +1,68 @@
+module Tilia
+  module Dav
+    # String utility
+    #
+    # This class is mainly used to implement the 'text-match' filter, used by both
+    # the CalDAV calendar-query REPORT, and CardDAV addressbook-query REPORT.
+    # Because they both need it, it was decided to put it in Sabre\DAV instead.
+    class StringUtil
+      # Checks if a needle occurs in a haystack ;)
+      #
+      # @param string haystack
+      # @param string needle
+      # @param string collation
+      # @param string match_type
+      # @return bool
+      def self.text_match(haystack, needle, collation, match_type = 'contains')
+        case collation
+        when 'i;ascii-casemap'
+          # NOTE: following is not true for RUBY
+          # default strtolower takes locale into consideration
+          # we don't want this.
+          haystack = haystack.upcase
+          needle = needle.upcase
+        when 'i;octet'
+          # Do nothing
+        when 'i;unicode-casemap'
+          haystack = haystack.mb_chars.upcase.to_s
+          needle = needle.mb_chars.upcase.to_s
+        else
+          fail Exception::BadRequest, "Collation type: #{collation} is not supported"
+        end
+
+        case match_type
+        when 'contains'
+          !!haystack.index(needle)
+        when 'equals'
+          haystack == needle
+        when 'starts-with'
+          haystack.index(needle) == 0
+        when 'ends-with'
+          haystack.rindex(needle) == haystack.length - needle.length
+        else
+          fail Exception::BadRequest, "Match-type: #{match_type} is not supported"
+        end
+      end
+
+      # This method takes an input string, checks if it's not valid UTF-8 and
+      # attempts to convert it to UTF-8 if it's not.
+      #
+      # Note that currently this can only convert ISO-8559-1 to UTF-8 (latin-1),
+      # anything else will likely fail.
+      #
+      # @param string input
+      # @return string
+      def self.ensure_utf8(input)
+        cd = CharDet.detect(input)
+
+        # Best solution I could find ...
+        if cd['confidence'] > 0.4 && cd['encoding'] =~ /(?:windows|iso)/i
+          input = input.encode('UTF-8', cd['encoding'])
+        end
+
+        # Removing any control characters
+        input.gsub(/(?:[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F])/, '')
+      end
+    end
+  end
+end

data/lib/tilia/dav/sync.rb

@@ -0,0 +1,8 @@
+module Tilia
+  module Dav
+    module Sync
+      require 'tilia/dav/sync/i_sync_collection'
+      require 'tilia/dav/sync/plugin'
+    end
+  end
+end

data/lib/tilia/dav/sync/i_sync_collection.rb

@@ -0,0 +1,80 @@
+module Tilia
+  module Dav
+    module Sync
+      # If a class extends ISyncCollection, it supports WebDAV-sync.
+      #
+      # You are responsible for maintaining a changelist for this collection. This
+      # means that if any child nodes in this collection was created, modified or
+      # deleted in any way, you should maintain an updated changelist.
+      module ISyncCollection
+        include ICollection
+
+        # This method returns the current sync-token for this collection.
+        # This can be any string.
+        #
+        # If null is returned from this function, the plugin assumes there's no
+        # sync information available.
+        #
+        # @return string|null
+        def sync_token
+        end
+
+        # The getChanges method returns all the changes that have happened, since
+        # the specified syncToken and the current collection.
+        #
+        # This function should return an array, such as the following:
+        #
+        # [
+        #   'syncToken' => 'The current synctoken',
+        #   'added'   => [
+        #      'new.txt',
+        #   ],
+        #   'modified'   => [
+        #      'modified.txt',
+        #   ],
+        #   'deleted' => array(
+        #      'foo.php.bak',
+        #      'old.txt'
+        #   )
+        # ]
+        #
+        # The syncToken property should reflect the *current* syncToken of the
+        # collection, as reported sync_token. This is needed here too, to
+        # ensure the operation is atomic.
+        #
+        # If the syncToken is specified as null, this is an initial sync, and all
+        # members should be reported.
+        #
+        # The modified property is an array of nodenames that have changed since
+        # the last token.
+        #
+        # The deleted property is an array with nodenames, that have been deleted
+        # from collection.
+        #
+        # The second argument is basically the 'depth' of the report. If it's 1,
+        # you only have to report changes that happened only directly in immediate
+        # descendants. If it's 2, it should also include changes from the nodes
+        # below the child collections. (grandchildren)
+        #
+        # The third (optional) argument allows a client to specify how many
+        # results should be returned at most. If the limit is not specified, it
+        # should be treated as infinite.
+        #
+        # If the limit (infinite or not) is higher than you're willing to return,
+        # you should throw a Sabre\DAV\Exception\Too_much_matches exception.
+        #
+        # If the syncToken is expired (due to data cleanup) or unknown, you must
+        # return null.
+        #
+        # The limit is 'suggestive'. You are free to ignore it.
+        #
+        # @param string sync_token
+        # @param int sync_level
+        # @param int limit
+        # @return array
+        def changes(_sync_token, _sync_level, _limit = nil)
+        end
+      end
+    end
+  end
+end

data/lib/tilia/dav/sync/plugin.rb

@@ -0,0 +1,225 @@
+module Tilia
+  module Dav
+    module Sync
+      # This plugin all WebDAV-sync capabilities to the Server.
+      #
+      # WebDAV-sync is defined by rfc6578
+      #
+      # The sync capabilities only work with collections that implement
+      # Sabre\DAV\Sync\ISyncCollection.
+      class Plugin < ServerPlugin
+        # Reference to server object
+        #
+        # @var DAV\Server
+        # RUBY: attr_accessor :server
+
+        SYNCTOKEN_PREFIX = 'http://sabre.io/ns/sync/'
+
+        # Returns a plugin name.
+        #
+        # Using this name other plugins will be able to access other plugins
+        # using \Sabre\DAV\Server::getPlugin
+        #
+        # @return string
+        def plugin_name
+          'sync'
+        end
+
+        # Initializes the plugin.
+        #
+        # This is when the plugin registers it's hooks.
+        #
+        # @param DAV\Server server
+        # @return void
+        def setup(server)
+          @server = server
+          server.xml.element_map['{DAV:}sync-collection'] = Xml::Request::SyncCollectionReport
+
+          server.on(
+            'report',
+            lambda do |report_name, dom, uri|
+              if report_name == '{DAV:}sync-collection'
+                @server.transaction_type = 'report-sync-collection'
+                sync_collection(uri, dom)
+                return false
+              end
+            end
+          )
+
+          server.on('propFind',       method(:prop_find))
+          server.on('validateTokens', method(:validate_tokens))
+        end
+
+        # Returns a list of reports this plugin supports.
+        #
+        # This will be used in the {DAV:}supported-report-set property.
+        # Note that you still need to subscribe to the 'report' event to actually
+        # implement them
+        #
+        # @param string uri
+        # @return array
+        def supported_report_set(uri)
+          node = @server.tree.node_for_path(uri)
+          if node.is_a?(ISyncCollection) && node.sync_token
+            return ['{DAV:}sync-collection']
+          end
+
+          []
+        end
+
+        # This method handles the {DAV:}sync-collection HTTP REPORT.
+        #
+        # @param string uri
+        # @param SyncCollectionReport report
+        # @return void
+        def sync_collection(uri, report)
+          # Getting the data
+          node = @server.tree.node_for_path(uri)
+          unless node.is_a?(ISyncCollection)
+            fail Exception::ReportNotSupported, 'The {DAV:}sync-collection REPORT is not supported on this url.'
+          end
+
+          token = node.sync_token
+          unless token
+            fail Exception::ReportNotSupported, 'No sync information is available at this node'
+          end
+
+          sync_token = report.sync_token
+          if sync_token
+            # Sync-token must start with our prefix
+            unless sync_token[0, SYNCTOKEN_PREFIX.length] == SYNCTOKEN_PREFIX
+              fail Exception::InvalidSyncToken, 'Invalid or unknown sync token'
+            end
+
+            sync_token = sync_token[SYNCTOKEN_PREFIX.length..-1]
+          end
+
+          change_info = node.changes(sync_token, report.sync_level, report.limit)
+
+          unless change_info
+            fail Exception::InvalidSyncToken, 'Invalid or unknown sync token'
+          end
+
+          # Encoding the response
+          send_sync_collection_response(
+            change_info['syncToken'],
+            uri,
+            change_info['added'],
+            change_info['modified'],
+            change_info['deleted'],
+            report.properties
+          )
+        end
+
+        protected
+
+        # Sends the response to a sync-collection request.
+        #
+        # @param string sync_token
+        # @param string collection_url
+        # @param array added
+        # @param array modified
+        # @param array deleted
+        # @param array properties
+        # @return void
+        def send_sync_collection_response(sync_token, collection_url, added, modified, deleted, properties)
+          full_paths = []
+
+          # Pre-fetching children, if this is possible.
+          (added + modified).each do |item|
+            full_path = collection_url + '/' + item
+            full_paths << full_path
+          end
+
+          responses = []
+          @server.properties_for_multiple_paths(full_paths, properties).each do |full_path, props|
+            # The 'Property_Response' class is responsible for generating a
+            # single {DAV:}response xml element.
+            responses << Xml::Element::Response.new(full_path, props)
+          end
+
+          # Deleted items also show up as 'responses'. They have no properties,
+          # and a single {DAV:}status element set as 'HTTP/1.1 404 Not Found'.
+          deleted.each do |item|
+            full_path = collection_url + '/' + item
+            responses << Xml::Element::Response.new(full_path, {}, 404)
+          end
+
+          multi_status = Xml::Response::MultiStatus.new(responses, SYNCTOKEN_PREFIX + sync_token.to_s)
+
+          @server.http_response.status = 207
+          @server.http_response.update_header('Content-Type', 'application/xml; charset=utf-8')
+          @server.http_response.body = @server.xml.write('{DAV:}multistatus', multi_status, @server.base_uri)
+        end
+
+        public
+
+        # This method is triggered whenever properties are requested for a node.
+        # We intercept this to see if we must return a {DAV:}sync-token.
+        #
+        # @param DAV\PropFind prop_find
+        # @param DAV\INode node
+        # @return void
+        def prop_find(prop_find, node)
+          prop_find.handle(
+            '{DAV:}sync-token',
+            lambda do
+              if !node.is_a?(ISyncCollection)
+                return nil
+              else
+                token = node.sync_token
+                return nil unless token
+              end
+              return SYNCTOKEN_PREFIX + token.to_s
+            end
+          )
+        end
+
+        # The validateTokens event is triggered before every request.
+        #
+        # It's a moment where this plugin can check all the supplied lock tokens
+        # in the If: header, and check if they are valid.
+        #
+        # @param RequestInterface request
+        # @param array conditions
+        # @return void
+        def validate_tokens(_request, conditions_box)
+          conditions = conditions_box.value
+          conditions.each_with_index do |condition, kk|
+            condition['tokens'].each_with_index do |token, ii|
+              # Sync-tokens must always start with our designated prefix.
+              if token['token'][0, SYNCTOKEN_PREFIX.length] != SYNCTOKEN_PREFIX
+                next
+              end
+
+              # Checking if the token is a match.
+              node = @server.tree.node_for_path(condition['uri'])
+
+              if node.is_a?(ISyncCollection) && node.sync_token.to_s == token['token'][SYNCTOKEN_PREFIX.length..-1]
+                conditions[kk]['tokens'][ii]['validToken'] = true
+              end
+            end
+          end
+          conditions_box.value = conditions
+        end
+
+        # Returns a bunch of meta-data about the plugin.
+        #
+        # Providing this information is optional, and is mainly displayed by the
+        # Browser plugin.
+        #
+        # The description key in the returned array may contain html and will not
+        # be sanitized.
+        #
+        # @return array
+        def plugin_info
+          {
+            'name'        => plugin_name,
+            'description' => 'Adds support for WebDAV Collection Sync (rfc6578)',
+            'link'        => 'http://sabre.io/dav/sync/'
+          }
+        end
+      end
+    end
+  end
+end