tilia-dav 3.1.0.pre.alpha2

data/lib/tilia/cal_dav/schedule/scheduling_object.rb

@@ -0,0 +1,126 @@
+module Tilia
+  module CalDav
+    module Schedule
+      # The SchedulingObject represents a scheduling object in the Inbox collection
+      class SchedulingObject < CalendarObject
+        include ISchedulingObject
+
+        # @!attribute [r] caldav_backend
+        #   @!visibility private
+        #   The CalDAV backend
+        #
+        #   @var Backend\SchedulingSupport
+
+        # @!attribute [r] object_data
+        #   @!visibility private
+        #   Array with information about this SchedulingObject
+        #
+        #   @var array
+
+        # Constructor
+        #
+        # The following properties may be passed within object_data:
+        #
+        #   * uri - A unique uri. Only the 'basename' must be passed.
+        #   * principaluri - the principal that owns the object.
+        #   * calendardata (optional) - The iCalendar data
+        #   * etag - (optional) The etag for this object, MUST be encloded with
+        #            double-quotes.
+        #   * size - (optional) The size of the data in bytes.
+        #   * lastmodified - (optional) format as a unix timestamp.
+        #   * acl - (optional) Use this to override the default ACL for the node.
+        #
+        # @param Backend\BackendInterface caldav_backend
+        # @param array object_data
+        def initialize(caldav_backend, object_data)
+          @caldav_backend = caldav_backend
+
+          fail ArgumentError, 'The objectData argument must contain an \'uri\' property' unless object_data.key?('uri')
+
+          @object_data = object_data
+        end
+
+        # Returns the ICalendar-formatted object
+        #
+        # @return string
+        def get
+          # Pre-populating the 'calendardata' is optional, if we don't have it
+          # already we fetch it from the backend.
+          unless @object_data.key?('calendardata')
+            @object_data = @caldav_backend.scheduling_object(@object_data['principaluri'], @object_data['uri'])
+          end
+          @object_data['calendardata']
+        end
+
+        # Updates the ICalendar-formatted object
+        #
+        # @param string|resource calendar_data
+        # @return string
+        def put(_calendar_data)
+          fail Dav::Exception::MethodNotAllowed, 'Updating scheduling objects is not supported'
+        end
+
+        # Deletes the scheduling message
+        #
+        # @return void
+        def delete
+          @caldav_backend.delete_scheduling_object(@object_data['principaluri'], @object_data['uri'])
+        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
+          @object_data['principaluri']
+        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
+          # An alternative acl may be specified in the object data.
+          #
+          return @object_data['acl'] if @object_data.key?('acl')
+
+          # The default ACL
+          [
+            {
+              'privilege' => '{DAV:}read',
+              'principal' => @object_data['principaluri'],
+              'protected' => true
+            },
+            {
+              'privilege' => '{DAV:}write',
+              'principal' => @object_data['principaluri'],
+              'protected' => true
+            },
+            {
+              'privilege' => '{DAV:}read',
+              'principal' => @object_data['principaluri'] + '/calendar-proxy-write',
+              'protected' => true
+            },
+            {
+              'privilege' => '{DAV:}write',
+              'principal' => @object_data['principaluri'] + '/calendar-proxy-write',
+              'protected' => true
+            },
+            {
+              'privilege' => '{DAV:}read',
+              'principal' => @object_data['principaluri'] + '/calendar-proxy-read',
+              'protected' => true
+            }
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/tilia/cal_dav/shareable_calendar.rb

@@ -0,0 +1,54 @@
+module Tilia
+  module CalDav
+    # This object represents a CalDAV calendar that can be shared with other
+    # users.
+    class ShareableCalendar < Calendar
+      include IShareableCalendar
+
+      # Updates the list of shares.
+      #
+      # The first array is a list of people that are to be added to the
+      # calendar.
+      #
+      # Every element in the add array has the following properties:
+      #   * href - A url. Usually a mailto: address
+      #   * commonName - Usually a first and last name, or false
+      #   * summary - A description of the share, can also be false
+      #   * readOnly - A boolean value
+      #
+      # Every element in the remove array is just the address string.
+      #
+      # @param array add
+      # @param array remove
+      # @return void
+      def update_shares(add, remove)
+        @caldav_backend.update_shares(@calendar_info['id'], add, remove)
+      end
+
+      # Returns the list of people whom this calendar is shared with.
+      #
+      # Every element in this array should have the following properties:
+      #   * href - Often a mailto: address
+      #   * commonName - Optional, for example a first + last name
+      #   * status - See the Sabre\CalDAV\SharingPlugin::STATUS_ constants.
+      #   * readOnly - boolean
+      #   * summary - Optional, a description for the share
+      #
+      # @return array
+      def shares
+        @caldav_backend.shares(@calendar_info['id'])
+      end
+
+      # Marks this calendar as published.
+      #
+      # Publishing a calendar should automatically create a read-only, public,
+      # subscribable calendar.
+      #
+      # @param bool value
+      # @return void
+      def publish_status=(value)
+        @caldav_backend.update_publish_status(@calendar_info['id'], value)
+      end
+    end
+  end
+end

data/lib/tilia/cal_dav/shared_calendar.rb

@@ -0,0 +1,120 @@
+module Tilia
+  module CalDav
+    # This object represents a CalDAV calendar that is shared by a different user.
+    class SharedCalendar < Calendar
+      include ISharedCalendar
+
+      # Constructor
+      #
+      # @param Backend\BackendInterface caldav_backend
+      # @param array calendar_info
+      def initialize(caldav_backend, calendar_info)
+        required = [
+          '{http://calendarserver.org/ns/}shared-url',
+          '{http://sabredav.org/ns}owner-principal',
+          '{http://sabredav.org/ns}read-only'
+        ]
+
+        required.each do |r|
+          unless calendar_info.key?(r)
+            fail ArgumentError, "The #{r} property must be specified for SharedCalendar(s)"
+          end
+        end
+
+        super
+      end
+
+      # This method should return the url of the owners' copy of the shared
+      # calendar.
+      #
+      # @return string
+      def shared_url
+        @calendar_info['{http://calendarserver.org/ns/}shared-url']
+      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
+        @calendar_info['{http://sabredav.org/ns}owner-principal']
+      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
+        # The top-level ACL only contains access information for the true
+        # owner of the calendar, so we need to add the information for the
+        # sharee.
+        acl = super
+        acl << {
+          'privilege' => '{DAV:}read',
+          'principal' => @calendar_info['principaluri'],
+          'protected' => true
+        }
+        if @calendar_info['{http://sabredav.org/ns}read-only']
+          acl << {
+            'privilege' => '{DAV:}write-properties',
+            'principal' => @calendar_info['principaluri'],
+            'protected' => true
+          }
+        else
+          acl << {
+            'privilege' => '{DAV:}write',
+            'principal' => @calendar_info['principaluri'],
+            'protected' => true
+          }
+        end
+
+        acl
+      end
+
+      # This method returns the ACL's for calendar objects in this calendar.
+      # The result of this method automatically gets passed to the
+      # calendar-object nodes in the calendar.
+      #
+      # @return array
+      def child_acl
+        acl = super
+        acl << {
+          'privilege' => '{DAV:}read',
+          'principal' => @calendar_info['principaluri'],
+          'protected' => true
+        }
+
+        unless @calendar_info['{http://sabredav.org/ns}read-only']
+          acl << {
+            'privilege' => '{DAV:}write',
+            'principal' => @calendar_info['principaluri'],
+            'protected' => true
+          }
+        end
+
+        acl
+      end
+
+      # Returns the list of people whom this calendar is shared with.
+      #
+      # Every element in this array should have the following properties:
+      #   * href - Often a mailto: address
+      #   * commonName - Optional, for example a first + last name
+      #   * status - See the Sabre\CalDAV\SharingPlugin::STATUS_ constants.
+      #   * readOnly - boolean
+      #   * summary - Optional, a description for the share
+      #
+      # @return array
+      def shares
+        @caldav_backend.shares(@calendar_info['id'])
+      end
+    end
+  end
+end

data/lib/tilia/cal_dav/sharing_plugin.rb

@@ -0,0 +1,359 @@
+module Tilia
+  module CalDav
+    # This plugin implements support for caldav sharing.
+    #
+    # This spec is defined at:
+    # http://svn.calendarserver.org/repository/calendarserver/CalendarServer/trunk/doc/Extensions/caldav-sharing.txt
+    #
+    # See:
+    # Sabre\CalDAV\Backend\SharingSupport for all the documentation.
+    #
+    # Note: This feature is experimental, and may change in between different
+    # SabreDAV versions.
+    class SharingPlugin < Dav::ServerPlugin
+      # These are the various status constants used by sharing-messages.
+      STATUS_ACCEPTED = 1
+      STATUS_DECLINED = 2
+      STATUS_DELETED = 3
+      STATUS_NORESPONSE = 4
+      STATUS_INVALID = 5
+
+      # @!attribute [r] server
+      #   @!visibility private
+      #   Reference to SabreDAV server object.
+      #
+      #   @var Sabre\DAV\Server
+
+      # 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
+        ['calendarserver-sharing']
+      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
+        'caldav-sharing'
+      end
+
+      # 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 DAV\Server server
+      # @return void
+      def setup(server)
+        @server = server
+        server.resource_type_mapping[ISharedCalendar] = "{#{Plugin::NS_CALENDARSERVER}}shared"
+
+        @server.protected_properties += [
+          "{#{Plugin::NS_CALENDARSERVER}}invite",
+          "{#{Plugin::NS_CALENDARSERVER}}allowed-sharing-modes",
+          "{#{Plugin::NS_CALENDARSERVER}}shared-url"
+        ]
+
+        @server.xml.element_map["{#{Plugin::NS_CALENDARSERVER}}share"] = Xml::Request::Share
+        @server.xml.element_map["{#{Plugin::NS_CALENDARSERVER}}invite-reply"] = Xml::Request::InviteReply
+
+        @server.on('propFind',     method(:prop_find_early))
+        @server.on('propFind',     method(:prop_find_late), 150)
+        @server.on('propPatch',    method(:prop_patch), 40)
+        @server.on('method:POST',  method(:http_post))
+      end
+
+      # This event is triggered when properties are requested for a certain
+      # node.
+      #
+      # This allows us to inject any properties early.
+      #
+      # @param DAV\PropFind prop_find
+      # @param DAV\INode node
+      # @return void
+      def prop_find_early(prop_find, node)
+        if node.is_a?(IShareableCalendar)
+          prop_find.handle(
+            "{#{Plugin::NS_CALENDARSERVER}}invite",
+            -> { Xml::Property::Invite.new(node.shares) }
+          )
+        end
+
+        if node.is_a?(ISharedCalendar)
+          prop_find.handle(
+            "{#{Plugin::NS_CALENDARSERVER}}shared-url",
+            -> { return Dav::Xml::Property::Href.new(node.shared_url) }
+          )
+
+          prop_find.handle(
+            "{#{Plugin::NS_CALENDARSERVER}}invite",
+            lambda do
+              # Fetching owner information
+              props = @server.properties_for_path(
+                node.owner,
+                [
+                  '{http://sabredav.org/ns}email-address',
+                  '{DAV:}displayname'
+                ],
+                0
+              )
+
+              owner_info = {
+                'href' => node.owner
+              }
+
+              if props[0].key?(200)
+                # We're mapping the internal webdav properties to the
+                # elements caldav-sharing expects.
+                if props[0][200].key?('{http://sabredav.org/ns}email-address')
+                  owner_info['href'] = 'mailto:' + props[0][200]['{http://sabredav.org/ns}email-address']
+                end
+
+                if props[0][200].key?('{DAV:}displayname')
+                  owner_info['commonName'] = props[0][200]['{DAV:}displayname']
+                end
+              end
+
+              Xml::Property::Invite.new(
+                node.shares,
+                owner_info
+              )
+            end
+          )
+        end
+      end
+
+      # This method is triggered *after* all properties have been retrieved.
+      # This allows us to inject the correct resourcetype for calendars that
+      # have been shared.
+      #
+      # @param DAV\PropFind prop_find
+      # @param DAV\INode node
+      # @return void
+      def prop_find_late(prop_find, node)
+        if node.is_a?(IShareableCalendar)
+          rt = prop_find.get('{DAV:}resourcetype')
+          if rt
+            if node.shares.size > 0
+              rt.add("{#{Plugin::NS_CALENDARSERVER}}shared-owner")
+            end
+          end
+
+          prop_find.handle(
+            "{#{Plugin::NS_CALENDARSERVER}}allowed-sharing-modes",
+            lambda do
+              Xml::Property::AllowedSharingModes.new(true, false)
+            end
+          )
+        end
+      end
+
+      # This method is trigged when a user attempts to update a node's
+      # properties.
+      #
+      # A previous draft of the sharing spec stated that it was possible to use
+      # PROPPATCH to remove 'shared-owner' from the resourcetype, thus unsharing
+      # the calendar.
+      #
+      # Even though this is no longer in the current spec, we keep this around
+      # because OS X 10.7 may still make use of this feature.
+      #
+      # @param string path
+      # @param DAV\PropPatch prop_patch
+      # @return void
+      def prop_patch(path, prop_patch)
+        node = @server.tree.node_for_path(path)
+        return nil unless node.is_a?(IShareableCalendar)
+
+        prop_patch.handle(
+          '{DAV:}resourcetype',
+          lambda do |value|
+            return false if value.is("{#{Plugin::NS_CALENDARSERVER}}shared-owner")
+
+            shares = node.shares
+            remove = []
+            shares.each do |share|
+              remove << share['href']
+            end
+            node.update_shares([], remove)
+
+            true
+          end
+        )
+      end
+
+      # We intercept this to handle POST requests on calendars.
+      #
+      # @param RequestInterface request
+      # @param ResponseInterface response
+      # @return null|bool
+      def http_post(request, response)
+        path = request.path
+
+        # Only handling xml
+        content_type = request.header('Content-Type')
+        return nil unless content_type.index('application/xml') || content_type.index('text/xml')
+
+        # Making sure the node exists
+        begin
+          node = @server.tree.node_for_path(path)
+        rescue Dav::Exception::NotFound
+          return nil
+        end
+
+        request_body = request.body_as_string
+
+        # If this request handler could not deal with this POST request, it
+        # will return 'null' and other plugins get a chance to handle the
+        # request.
+        #
+        # However, we already requested the full body. This is a problem,
+        # because a body can only be read once. This is why we preemptively
+        # re-populated the request body with the existing data.
+        request.body = request_body
+
+        document_type_box = Box.new('')
+        message = @server.xml.parse(request_body, request.url, document_type_box)
+        document_type = document_type_box.value
+
+        case document_type
+        # Dealing with the 'share' document, which modified invitees on a
+        # calendar.
+        when "{#{Plugin::NS_CALENDARSERVER}}share"
+          # We can only deal with IShareableCalendar objects
+          return true unless node.is_a?(IShareableCalendar)
+
+          @server.transaction_type = 'post-calendar-share'
+
+          # Getting ACL info
+          acl = @server.plugin('acl')
+
+          # If there's no ACL support, we allow everything
+          acl.check_privileges(path, '{DAV:}write') if acl
+
+          node.update_shares(message.set, message.remove)
+
+          response.status = 200
+          # Adding this because sending a response body may cause issues,
+          # and I wanted some type of indicator the response was handled.
+          response.update_header('X-Sabre-Status', 'everything-went-well')
+
+          # Breaking the event chain
+          return false
+        # The invite-reply document is sent when the user replies to an
+        # invitation of a calendar share.
+        when "{#{Plugin::NS_CALENDARSERVER}}invite-reply"
+
+          # This only works on the calendar-home-root node.
+          return true unless node.is_a?(CalendarHome)
+
+          @server.transaction_type = 'post-invite-reply'
+
+          # Getting ACL info
+          acl = @server.plugin('acl')
+
+          # If there's no ACL support, we allow everything
+          acl.check_privileges(path, '{DAV:}write') if acl
+
+          url = node.share_reply(
+            message.href,
+            message.status,
+            message.calendar_uri,
+            message.in_reply_to,
+            message.summary
+          )
+
+          response.status = 200
+          # Adding this because sending a response body may cause issues,
+          # and I wanted some type of indicator the response was handled.
+          response.update_header('X-Sabre-Status', 'everything-went-well')
+
+          if url
+            writer = @server.xml.writer
+            writer.open_memory
+            writer.start_document
+            writer.start_element("{#{Plugin::NS_CALENDARSERVER}}shared-as")
+            writer.write(Dav::Xml::Property::Href.new(url))
+            writer.end_element
+            response.update_header('Content-Type', 'application/xml')
+            response.body = writer.output_memory
+          end
+
+          # Breaking the event chain
+          return false
+        when "{#{Plugin::NS_CALENDARSERVER}}publish-calendar"
+          # We can only deal with IShareableCalendar objects
+          return true unless node.is_a?(IShareableCalendar)
+
+          @server.transaction_type = 'post-publish-calendar'
+
+          # Getting ACL info
+          acl = @server.plugin('acl')
+
+          # If there's no ACL support, we allow everything
+          acl.check_privileges(path, '{DAV:}write') if acl
+
+          node.publish_status = true
+
+          # iCloud sends back the 202, so we will too.
+          response.status = 202
+
+          # Adding this because sending a response body may cause issues,
+          # and I wanted some type of indicator the response was handled.
+          response.update_header('X-Sabre-Status', 'everything-went-well')
+
+          # Breaking the event chain
+          return false
+        when "{#{Plugin::NS_CALENDARSERVER}}unpublish-calendar"
+          # We can only deal with IShareableCalendar objects
+          return true unless node.is_a?(IShareableCalendar)
+
+          @server.transaction_type = 'post-unpublish-calendar'
+
+          # Getting ACL info
+          acl = @server.plugin('acl')
+
+          # If there's no ACL support, we allow everything
+          acl.check_privileges(path, '{DAV:}write') if acl
+
+          node.publish_status = false
+
+          response.status = 200
+
+          # Adding this because sending a response body may cause issues,
+          # and I wanted some type of indicator the response was handled.
+          response.update_header('X-Sabre-Status', 'everything-went-well')
+
+          # Breaking the event chain
+          return false
+        end
+      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 caldav-sharing.',
+          'link'        => 'http://sabre.io/dav/caldav-sharing/'
+        }
+      end
+    end
+  end
+end