tilia-dav 3.1.0.pre.alpha2

data/lib/tilia/cal_dav/backend/sharing_support.rb

@@ -0,0 +1,239 @@
+module Tilia
+  module CalDav
+    module Backend
+      # Adds support for sharing features to a CalDAV server.
+      #
+      # Note: This feature is experimental, and may change in between different
+      # SabreDAV versions.
+      #
+      # Early warning: Currently SabreDAV provides no implementation for this. This
+      # is, because in it's current state there is no elegant way to do this.
+      # The problem lies in the fact that a real CalDAV server with sharing support
+      # would first need email support (with invite notifications), and really also
+      # a browser-frontend that allows people to accept or reject these shares.
+      #
+      # In addition, the CalDAV backends are currently kept as independent as
+      # possible, and should not be aware of principals, email addresses or
+      # accounts.
+      #
+      # Adding an implementation for Sharing to standard-sabredav would contradict
+      # these goals, so for this reason this is currently not implemented, although
+      # it may very well in the future; but probably not before SabreDAV 2.0.
+      #
+      # The interface works however, so if you implement all this, and do it
+      # correctly sharing _will_ work. It's not particularly easy, and I _urge you_
+      # to make yourself acquainted with the following document first:
+      #
+      # https://trac.calendarserver.org/browser/CalendarServer/trunk/doc/Extensions/caldav-sharing.txt
+      #
+      # An overview
+      # ========
+      #
+      # Implementing this interface will allow a user to share his or her calendars
+      # to other users. Effectively, when a calendar is shared the calendar will
+      # show up in both the Sharer's and Sharee's calendar-home root.
+      # This interface adds a few methods that ensure that this happens, and there
+      # are also a number of new requirements in the base-class you must now follow.
+      #
+      #
+      # How it works
+      # ========
+      #
+      # When a user shares a calendar, the update_shares method will be called with
+      # a list of sharees that are now added, and a list of sharees that have been
+      # removed.
+      # Removal is instant, but when a sharee is added the sharee first gets a
+      # chance to accept or reject the invitation for a share.
+      #
+      # After a share is accepted, the calendar will be returned from
+      # getUserCalendars for both the sharer, and the sharee.
+      #
+      # If the sharee deletes the calendar, only their share gets deleted. When the
+      # owner deletes a calendar, it will be removed for everybody.
+      #
+      #
+      # Notifications
+      # =========
+      #
+      # During all these sharing operations, a lot of notifications are sent back
+      # and forward.
+      #
+      # Whenever the list of sharees for a calendar has been changed (they have been
+      # added, removed or modified) all sharees should get a notification for this
+      # change.
+      # This notification is always represented by:
+      #
+      # Sabre\CalDAV\Notifications\Notification\Invite
+      #
+      # In the case of an invite, the sharee may reply with an 'accept' or
+      # 'decline'. These are always represented by:
+      #
+      # Sabre\CalDAV\Notifications\Notification\InviteReply
+      #
+      #
+      # Calendar access by sharees
+      # ==================
+      #
+      # As mentioned earlier, shared calendars must now also be returned for
+      # getCalendarsForUser for sharees. A few things change though.
+      #
+      # The following properties must be specified:
+      #
+      # 1. {http://calendarserver.org/ns/}shared-url
+      #
+      # This property MUST contain the url to the original calendar, that is.. the
+      # path to the calendar from the owner.
+      #
+      # 2. {http://sabredav.org/ns}owner-principal
+      #
+      # This is a url to to the principal who is sharing the calendar.
+      #
+      # 3. {http://sabredav.org/ns}read-only
+      #
+      # This should be either 0 or 1, depending on if the user has read-only or
+      # read-write access to the calendar.
+      #
+      # Only when this is done, the calendar will correctly be marked as a calendar
+      # that's shared to him, thus allowing clients to display the correct interface
+      # and ACL enforcement.
+      #
+      # If a sharee deletes their calendar, only their instance of the calendar
+      # should be deleted, the original should still exists.
+      # Pretty much any 'dead' WebDAV properties on these shared calendars should be
+      # specific to a user. This means that if the displayname is changed by a
+      # sharee, the original is not affected. This is also true for:
+      #   * The description
+      #   * The color
+      #   * The order
+      #   * And any other dead properties.
+      #
+      # Properties like a ctag should not be different for multiple instances of the
+      # calendar.
+      #
+      # Lastly, objects *within* calendars should also have user-specific data. The
+      # two things that are user-specific are:
+      #   * VALARM objects
+      #   * The TRANSP property
+      #
+      # This _also_ implies that if a VALARM is deleted by a sharee for some event,
+      # this has no effect on the original VALARM.
+      #
+      # Understandably, the this last requirement is one of the hardest.
+      # Realisticly, I can see people ignoring this part of the spec, but that could
+      # cause a different set of issues.
+      #
+      #
+      # Publishing
+      # =======
+      #
+      # When a user publishes a url, the server should generate a 'publish url'.
+      # This is a read-only url, anybody can use to consume the calendar feed.
+      #
+      # Calendars are in one of two states:
+      #   * published
+      #   * unpublished
+      #
+      # If a calendar is published, the following property should be returned
+      # for each calendar in getCalendarsForUser.
+      #
+      # {http://calendarserver.org/ns/}publish-url
+      #
+      # This element should contain a {DAV:}href element, which points to the
+      # public url that does not require authentication. Unlike every other href,
+      # this url must be absolute.
+      #
+      # Ideally, the following property is always returned
+      #
+      # {http://calendarserver.org/ns/}pre-publish-url
+      #
+      # This property should contain the url that the calendar _would_ have, if it
+      # were to be published. iCal uses this to display the url, before the user
+      # will actually publish it.
+      #
+      #
+      # Selectively disabling publish or share feature
+      # ===============================
+      #
+      # If Sabre\CalDAV\Property\AllowedSharingModes is returned from
+      # getCalendarsForUser, this allows the server to specify whether either sharing,
+      # or publishing is supported.
+      #
+      # This allows a client to determine in advance which features are available,
+      # and update the interface appropriately. If this property is not returned by
+      # the backend, the SharingPlugin automatically injects it and assumes both
+      # features are available.
+      #
+      # @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 SharingSupport
+        include NotificationSupport
+
+        # 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.
+        #
+        # Note that if the calendar is currently marked as 'not shared' by and
+        # this method is called, the calendar should be 'upgraded' to a shared
+        # calendar.
+        #
+        # @param mixed calendar_id
+        # @param array add
+        # @param array remove
+        # @return void
+        def update_shares(calendar_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
+        #
+        # This method may be called by either the original instance of the
+        # calendar, as well as the shared instances. In the case of the shared
+        # instances, it is perfectly acceptable to return an empty array in case
+        # there are privacy concerns.
+        #
+        # @param mixed calendar_id
+        # @return array
+        def shares(calendar_id)
+        end
+
+        # This method is called when a user replied to a request to share.
+        #
+        # If the user chose to accept the share, this method should return the
+        # newly created calendar url.
+        #
+        # @param string href The sharee who is replying (often a mailto: address)
+        # @param int status One of the SharingPlugin::STATUS_* constants
+        # @param string calendar_uri The url to the calendar thats being shared
+        # @param string in_reply_to The unique id this message is a response to
+        # @param string summary A description of the reply
+        # @return null|string
+        def share_reply(href, status, calendar_uri, in_reply_to, summary = nil)
+        end
+
+        # Publishes a calendar
+        #
+        # @param mixed calendar_id
+        # @param bool value
+        # @return void
+        def update_publish_status(calendar_id, value)
+        end
+      end
+    end
+  end
+end

data/lib/tilia/cal_dav/backend/subscription_support.rb

@@ -0,0 +1,79 @@
+module Tilia
+  module CalDav
+    module Backend
+      # Every CalDAV backend must at least implement this interface.
+      module SubscriptionSupport
+        include BackendInterface
+
+        # Returns a list of subscriptions for a principal.
+        #
+        # Every subscription is an array with the following keys:
+        #  * id, a unique id that will be used by other functions to modify the
+        #    subscription. This can be the same as the uri or a database key.
+        #  * uri. This is just the 'base uri' or 'filename' of the subscription.
+        #  * principaluri. The owner of the subscription. Almost always the same as
+        #    principalUri passed to this method.
+        #
+        # Furthermore, all the subscription info must be returned too:
+        #
+        # 1. {DAV:}displayname
+        # 2. {http://apple.com/ns/ical/}refreshrate
+        # 3. {http://calendarserver.org/ns/}subscribed-strip-todos (omit if todos
+        #    should not be stripped).
+        # 4. {http://calendarserver.org/ns/}subscribed-strip-alarms (omit if alarms
+        #    should not be stripped).
+        # 5. {http://calendarserver.org/ns/}subscribed-strip-attachments (omit if
+        #    attachments should not be stripped).
+        # 6. {http://calendarserver.org/ns/}source (Must be a
+        #     Sabre\DAV\Property\Href).
+        # 7. {http://apple.com/ns/ical/}calendar-color
+        # 8. {http://apple.com/ns/ical/}calendar-order
+        # 9. {urn:ietf:params:xml:ns:caldav}supported-calendar-component-set
+        #    (should just be an instance of
+        #    Sabre\CalDAV\Property\SupportedCalendarComponentSet, with a bunch of
+        #    default components).
+        #
+        # @param string principal_uri
+        # @return array
+        def subscriptions_for_user(principal_uri)
+        end
+
+        # Creates a new subscription for a principal.
+        #
+        # If the creation was a success, an id must be returned that can be used to reference
+        # this subscription in other methods, such as updateSubscription.
+        #
+        # @param string principal_uri
+        # @param string uri
+        # @param array properties
+        # @return mixed
+        def create_subscription(principal_uri, uri, properties)
+        end
+
+        # Updates a subscription
+        #
+        # 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 mixed subscription_id
+        # @param \Sabre\DAV\PropPatch prop_patch
+        # @return void
+        def update_subscription(subscription_id, prop_patch)
+        end
+
+        # Deletes a subscription.
+        #
+        # @param mixed subscription_id
+        # @return void
+        def delete_subscription(subscription_id)
+        end
+      end
+    end
+  end
+end

data/lib/tilia/cal_dav/backend/sync_support.rb

@@ -0,0 +1,75 @@
+module Tilia
+  module CalDav
+    module Backend
+      # WebDAV-sync support for CalDAV backends.
+      #
+      # In order for backends to advertise support for WebDAV-sync, this interface
+      # must be implemented.
+      #
+      # Implementing this can result in a significant reduction of bandwidth and CPU
+      # time.
+      #
+      # For this to work, you _must_ return a {http://sabredav.org/ns}sync-token
+      # property from getCalendarsFromUser.
+      module SyncSupport
+        include BackendInterface
+        # The getChanges method returns all the changes that have happened, since
+        # the specified syncToken in the specified calendar.
+        #
+        # This function should return an array, such as the following:
+        #
+        # [
+        #   'syncToken' => 'The current synctoken',
+        #   'added'   => [
+        #      'new.txt',
+        #   ],
+        #   'modified'   => [
+        #      'modified.txt',
+        #   ],
+        #   'deleted' => [
+        #      'foo.php.bak',
+        #      'old.txt'
+        #   ]
+        # )
+        #
+        # The returned syncToken property should reflect the *current* syncToken
+        # of the calendar, as reported in the {http://sabredav.org/ns}sync-token
+        # property This is * needed here too, to ensure the operation is atomic.
+        #
+        # If the sync_token argument 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 sync_level 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 limit 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\TooMuchMatches 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 calendar_id
+        # @param string sync_token
+        # @param int sync_level
+        # @param int limit
+        # @return array
+        def changes_for_calendar(calendar_id, sync_token, sync_level, limit = nil)
+        end
+      end
+    end
+  end
+end

data/lib/tilia/cal_dav/calendar.rb

@@ -0,0 +1,426 @@
+module Tilia
+  module CalDav
+    # This object represents a CalDAV calendar.
+    #
+    # A calendar can contain multiple TODO and or Events. These are represented
+    # as \Sabre\CalDAV\CalendarObject objects.
+    class Calendar
+      include ICalendar
+      include Dav::IProperties
+      include Dav::Sync::ISyncCollection
+      include Dav::IMultiGet
+
+      # @!attribute [r] calendar_info
+      #   @!visibility private
+      #   This is an array with calendar information
+      #
+      #   @var array
+
+      # @!attribute [r] caldav_backend
+      #   @!visibility private
+      #   CalDAV backend
+      #
+      #   @var Backend\BackendInterface
+
+      # Constructor
+      #
+      # @param Backend\BackendInterface caldav_backend
+      # @param array calendar_info
+      def initialize(caldav_backend, calendar_info)
+        @caldav_backend = caldav_backend
+        @calendar_info = calendar_info
+      end
+
+      # Returns the name of the calendar
+      #
+      # @return string
+      def name
+        @calendar_info['uri']
+      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 PropPatch prop_patch
+      # @return void
+      def prop_patch(prop_patch)
+        @caldav_backend.update_calendar(@calendar_info['id'], prop_patch)
+      end
+
+      # Returns the list of properties
+      #
+      # @param array requested_properties
+      # @return array
+      def properties(_requested_properties)
+        response = {}
+
+        @calendar_info.each do |prop_name, _prop_value|
+          response[prop_name] = @calendar_info[prop_name] if prop_name[0] == '{'
+        end
+
+        response
+      end
+
+      # Returns a calendar object
+      #
+      # The contained calendar objects are for example Events or Todo's.
+      #
+      # @param string name
+      # @return \Sabre\CalDAV\ICalendarObject
+      def child(name)
+        obj = @caldav_backend.calendar_object(@calendar_info['id'], name)
+
+        fail Dav::Exception::NotFound, 'Calendar object not found' unless obj
+
+        obj['acl'] = child_acl
+
+        CalendarObject.new(@caldav_backend, @calendar_info, obj)
+      end
+
+      # Returns the full list of calendar objects
+      #
+      # @return array
+      def children
+        objs = @caldav_backend.calendar_objects(@calendar_info['id'])
+
+        children = []
+        objs.each do |obj|
+          obj['acl'] = child_acl
+          children << CalendarObject.new(@caldav_backend, @calendar_info, obj)
+        end
+
+        children
+      end
+
+      # This method receives a list of paths in it's first argument.
+      # It must return an array with Node objects.
+      #
+      # If any children are not found, you do not have to return them.
+      #
+      # @param string[] paths
+      # @return array
+      def multiple_children(paths)
+        objs = @caldav_backend.multiple_calendar_objects(@calendar_info['id'], paths)
+
+        children = []
+        objs.each do |obj|
+          obj['acl'] = child_acl
+          children << CalendarObject.new(@caldav_backend, @calendar_info, obj)
+        end
+
+        children
+      end
+
+      # Checks if a child-node exists.
+      #
+      # @param string name
+      # @return bool
+      def child_exists(name)
+        obj = @caldav_backend.calendar_object(@calendar_info['id'], name)
+
+        if !obj
+          return false
+        else
+          return true
+        end
+      end
+
+      # Creates a new directory
+      #
+      # We actually block this, as subdirectories are not allowed in calendars.
+      #
+      # @param string name
+      # @return void
+      def create_directory(_name)
+        fail Dav::Exception::MethodNotAllowed, 'Creating collections in calendar objects is not allowed'
+      end
+
+      # Creates a new file
+      #
+      # The contents of the new file must be a valid ICalendar string.
+      #
+      # @param string name
+      # @param resource calendar_data
+      # @return string|null
+      def create_file(name, calendar_data = nil)
+        calendar_data = calendar_data.read unless calendar_data.is_a?(String)
+
+        @caldav_backend.create_calendar_object(@calendar_info['id'], name, calendar_data)
+      end
+
+      # Deletes the calendar.
+      #
+      # @return void
+      def delete
+        @caldav_backend.delete_calendar(@calendar_info['id'])
+      end
+
+      # Renames the calendar. Note that most calendars use the
+      # {DAV:}displayname to display a name to display a name.
+      #
+      # @param string new_name
+      # @return void
+      def name=(_new_name)
+        fail Dav::Exception::MethodNotAllowed, 'Renaming calendars is not yet supported'
+      end
+
+      # Returns the last modification date as a unix timestamp.
+      #
+      # @return void
+      def last_modified
+        nil
+      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['principaluri']
+      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
+        acl = [
+          {
+            'privilege' => '{DAV:}read',
+            'principal' => owner,
+            'protected' => true
+          },
+          {
+            'privilege' => '{DAV:}read',
+            'principal' => owner + '/calendar-proxy-write',
+            'protected' => true
+          },
+          {
+            'privilege' => '{DAV:}read',
+            'principal' => owner + '/calendar-proxy-read',
+            'protected' => true
+          },
+          {
+            'privilege' => "{#{Plugin::NS_CALDAV}}read-free-busy",
+            'principal' => '{DAV:}authenticated',
+            'protected' => true
+          }
+
+        ]
+        unless @calendar_info['{http://sabredav.org/ns}read-only']
+          acl << {
+            'privilege' => '{DAV:}write',
+            'principal' => owner,
+            'protected' => true
+          }
+          acl << {
+            'privilege' => '{DAV:}write',
+            'principal' => owner + '/calendar-proxy-write',
+            '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 = [
+          {
+            'privilege' => '{DAV:}read',
+            'principal' => owner,
+            'protected' => true
+          },
+          {
+            'privilege' => '{DAV:}read',
+            'principal' => owner + '/calendar-proxy-write',
+            'protected' => true
+          },
+          {
+            'privilege' => '{DAV:}read',
+            'principal' => owner + '/calendar-proxy-read',
+            'protected' => true
+          }
+
+        ]
+        unless @calendar_info['{http://sabredav.org/ns}read-only']
+          acl << {
+            'privilege' => '{DAV:}write',
+            'principal' => owner,
+            'protected' => true
+          }
+          acl << {
+            'privilege' => '{DAV:}write',
+            'principal' => owner + '/calendar-proxy-write',
+            'protected' => true
+          }
+        end
+
+        acl
+      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, 'Changing ACL is not yet supported'
+      end
+
+      # Returns the list of supported privileges for this node.
+      #
+      # The returned data structure is a list of nested privileges.
+      # See \Sabre\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
+        default = DavAcl::Plugin.default_supported_privilege_set
+
+        # We need to inject 'read-free-busy' in the tree, aggregated under
+        # {DAV:}read.
+        default['aggregates'].each do |agg|
+          next unless agg['privilege'] == '{DAV:}read'
+
+          agg['aggregates'] << {
+            'privilege' => "{#{Plugin::NS_CALDAV}}read-free-busy"
+          }
+        end
+
+        default
+      end
+
+      # Performs a calendar-query on the contents of this calendar.
+      #
+      # The calendar-query is defined in RFC4791 : CalDAV. Using the
+      # calendar-query it is possible for a client to request a specific set of
+      # object, based on contents of iCalendar properties, date-ranges and
+      # iCalendar component types (VTODO, VEVENT).
+      #
+      # This method should just return a list of (relative) urls that match this
+      # query.
+      #
+      # The list of filters are specified as an array. The exact array is
+      # documented by Sabre\CalDAV\CalendarQueryParser.
+      #
+      # @param array filters
+      # @return array
+      def calendar_query(filters)
+        @caldav_backend.calendar_query(@calendar_info['id'], filters)
+      end
+
+      # 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
+        if @caldav_backend.is_a?(Backend::SyncSupport) &&
+           @calendar_info.key?('{DAV:}sync-token')
+          return @calendar_info['{DAV:}sync-token']
+        end
+
+        if @caldav_backend.is_a?(Backend::SyncSupport) &&
+           @calendar_info.key?('{http://sabredav.org/ns}sync-token')
+          return @calendar_info['{http://sabredav.org/ns}sync-token']
+        end
+      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' => [
+      #      'foo.php.bak',
+      #      'old.txt'
+      #   ]
+      # ]
+      #
+      # The syncToken property should reflect the *current* syncToken of the
+      # collection, as reported get_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\TooMuchMatches 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)
+        return nil unless @caldav_backend.is_a?(Backend::SyncSupport)
+
+        @caldav_backend.changes_for_calendar(
+          @calendar_info['id'],
+          sync_token,
+          sync_level,
+          limit
+        )
+      end
+    end
+  end
+end