calendav 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3afd38354db59046e38adcad9be4376d7354b4acf4f97205bcbdc313d0bf1706
-  data.tar.gz: 3642fbb9d38108adcdf5af63c41e4f01c846b86a1a36225e8fd9bd92b58ae088
+  metadata.gz: e72b5067dad00dc1074cbd5cf7d0b3c28845b624d47ff5e992e3b78a9a65fa0d
+  data.tar.gz: 11c9e3e362f36c91323141650a0d3415914f87aed208ea4716d8b0253ffd2c6e
 SHA512:
-  metadata.gz: c54490f1ae94b3fb42c273777ccc29c342273bf8585b8270842e3402d383301867ec750eb2a0aaa3e51f770ef7f53a1094c4427e2e65de75fa3ba489eaa91667
-  data.tar.gz: 5e1855a5fde3e0adf27afbe387224617ffea0163eb82c6325320e2905a4bf176ff803cd8d6500da097a4001f35657e2be1144f8abbf9cfdca413d05267920f60
+  metadata.gz: 89da478d32baf4bbcfbd3c13ca2f89d5071f2dd4953889830d6f996d54bc4b5fb14feeac89af0c03891f047bf0e5b67fe7d88267df9ab0998a825387dbabf159
+  data.tar.gz: 05737755ec19e2c6b1e1f06b3f9273428e92d69381c19aee5cca14738bb9d63f243181a3c02b8d3d69ceb7e1b8c851847932aec8a81ae770a2d7c28d19357f12

data/CHANGELOG.md

@@ -1,6 +1,20 @@
-## [Unreleased]
+## Unreleased
 
-## [0.0.1] - 2021-06-13
+...
+
+## 0.1.0 - 2021-06-14
+
+* Support creating and deleting calendars.
+* Updating of events (with optional etag check).
+* List all events on a calendar (no timespan required).
+* Updating of calendars.
+* Allow for etag check to be used on event deletions.
+* Finding of single events and calendars by URLs.
+* Check if calendar creation is possible.
+* WebDAV-Sync support.
+* A vastly more useful README.
+
+## 0.0.1 - 2021-06-13
 
 An initial release with very limited (and likely buggy) support:
 

data/README.md

@@ -2,75 +2,203 @@
 
 A library for interacting with CalDAV servers via Ruby.
 
-At the time of writing, this gem is definitely not ready for production, nor is it anywhere close to supporting a decent set of features. Currently it covers the following:
+## Features
 
-* Determining the principal URL.
-* Determining the calendar home path.
-* Listing available calendars.
-* Creating events on a calendar.
-* Listing events on a calendar within a given timespan.
-* Deleting events on a calendar.
+### Credentials and Accounts
 
-Other features on the roadmap, in a rough order of priority:
+Calendav has support for a few calendar providers built-in by default: Apple, FastMail, and Google.
 
-* Consistent access to calendar/event URLs.
-* Updating events.
-* List all events on a calendar.
-* Create new calendars.
-* Update calendars.
-* Delete calendars.
-* Enable etag validation for updates/deletions (If-Match header).
-* Solid exception handling.
-* Use WebDAV-Sync to get changes since last sync.
-* Enable locking/unlocking when making changes.
-* Allow requesting only certain properties for calendars/events.
+```ruby
+credentials = Calendav.credentials(
+  :apple, username: "example@icloud.com", password: "app-specific-password"
+)
+```
 
-Also, the plan is to have a test suite that covers multiple CalDAV server implementations.
+Both Apple and FastMail expect app-specific passwords (rather than the account's main password). Google expects an OAuth 2 access token for the password instead.
 
-## Usage
+You can also create credentials for other providers:
 
 ```ruby
-credentials = Calendav.credentials(
-  :google, username: "example@gmail.com", password: "oauth-access-token"
-)
-# Also supported are FastMail and Apple, where the passwords should be
-# app-specific, with authentication via Basic Auth. Google uses a Bearer Token
-# for authentication (supplied as the password).
-#
-# Otherwise, to compose a more custom set of credentials:
 credentials = Calendav::Credentials::Standard.new(
   host: "https://www.example.com/caldav",
   username: "example",
   password: "secret",
   authentication: :basic_auth # or :bearer_token
 )
+```
 
-client = Calendav.client credentials
+You can use credentials to create a new client instance. If required, you can confirm they're valid by checking if a principal URL for the account can be returned.
+
+```ruby
+client = Calendav.client(credentials)
 puts client.principal_url
+```
 
-puts client.calendars.home_url
+### Calendars
+
+You can retrieve a list of all available calendars:
+
+```ruby
 calendars = client.calendars.list
-calendars.each { |calendar| puts calendar.path, calendar.display_name }
+calendars.each do |calendar|
+  puts calendar.url
+  puts calendar.display_name
+end
+```
+
+All calendars returned will have a URL - and this is the primary and unique reference to the calendar, and will not change. They should also have a display name, description, etag, ctag, time zone and color - but not all providers support all of these properties.
+
+If you already have the Calendar's URL, then you can request its information directly as well:
+
+```ruby
+calendar = client.calendars.find(calendar_url)
+```
+
+Some providers (though not Google) allow you to create calendars via the CalDAV protocol. You must supply the identifier of this calendar, which is the final part of its URL - and so must be unique for the account. Using a UUID could be a good option.
+
+```ruby
+require "securerandom"
+
+identifier = SecureRandom.uuid
+
+calendar_url = client.calendars.create(identifier, display_name: "My Calendar")
+```
 
+You can also edit calendar details, and delete them (if the provide allows such actions). The allowed attributes are `display_name`, `description`, `time_zone` and `color`.
+
+```ruby
+client.calendars.update(calendar_url, display_name: "Altered Calendar")
+client.calendars.delete(calendar_url)
+```
+
+It is possible to check whether a calendar provider supports calendar creation/deletion:
+
+```ruby
+client.calendars.create? # => true/false
+```
+
+Also, if it's useful, you can access the account's calendar home path (the root directory for that account's calendars):
+
+```ruby
+client.calendars.home_url
+```
+
+### Events
+
+Once you have a calendar's URL, you can retrieve events from it. Unless you are making a copy of the calendar for synchronisation purposes, it's recommended you limit the request to a specific timeframe (though the `from` and `to` arguments are optional).
+
+```ruby
 events = client.events.list(
-  calendar.path, from: Time.new(2021, 1, 1), to: Time.new(2022, 1, 1)
+  calendar_url, from: Time.new(2021, 1, 1), to: Time.new(2022, 1, 1)
 )
+events.each do |event|
+  puts event.url
+  puts event.summary
+  puts event.calendar_data
+end
+```
+
+The returned events have a unique URL (just like calendars), an `etag` (which changes when the event changes), and `calendar_data`, which is stored in the [iCalendar](https://datatracker.ietf.org/doc/html/rfc5545) format. The event objects returned currently parse the summary out of the calendar data, but nothing else - further attributes may be made visible, but for full control it's recommended you use the [icalendar](https://github.com/icalendar/icalendar) gem.
+
+If you have an event's URL, you can fetch the details of just that event directly:
+
+```ruby
+event = client.events.find(event_url)
+```
+
+Creating events, just like creating calendars, requires a unique identifier. There are no hard requirements for the format from the perspective of CalDAV generally, but some providers require the identifier to have the extension `.ics`.
+
+You will also need to generate the iCalendar data - again, the [icalendar](https://github.com/icalendar/icalendar) gem is very helpful for this.
+
+```ruby
+require "securerandom"
+require "icalendar"
 
-# use the icalendar gem to generate ICS strings
 ics = Icalendar::Calendar.new
 ics.event do |event|
 # ...
 end
 ics.publish
 
-# You need to provide the expected filename for the event:
 identifier = "#{SecureRandom.uuid}.ics"
-# … but the server may change it on you, so the new, full URL is returned:
-event_url = client.events.create(calendar.path, identifier, ics.to_ical)
+event_url = client.events.create(calendar.url, identifier, ics.to_ical)
+```
+
+*Please note*: some providers (definitely Google, possibly others) will not keep your supplied event identifier, but generate a new one. So, if you need an ongoing reference to the event, save the returned URL (rather than combining the calendar URL and your identifier).
+
+Updating events is done in a similar manner - with the event's URL and the updated iCalendar content:
+
+```ruby
+client.events.update(event_url, ics.to_ical)
+```
+
+To ensure you're only changing a known version of an event, it's recommended you use that version's etag as a precondition check (the update call will return false if the event on the server has a different etag value):
+
+```ruby
+event = client.events.find(event_url)
+
+# figure out the changes you want to make, generate the new ical data, and then:
+
+client.events.update(event_url, modified_ical, etag: event.etag)
+```
 
+Deletion of events is done via the event's URL as well - some providers (including Apple) support the etag precondition check for this, but others (including Google) do not. In the latter situation, the deletion will happen regardless of the server event's etag value.
+
+```ruby
 client.events.delete(event_url)
+
+client.events.delete(event_url, etag: event.etag)
+```
+
+### Synchronising
+
+If you are maintaining your own copy/history of events from a CalDAV server, then it's highly recommended you take advantage of the WebDAV-Sync protocol (should the calendar provider support it). Using Calendav, the suggested approach is:
+
+* Get a token for a specific calendar
+* Request all events for that calendar
+* Then, to get just the changed/deleted events, use the token to request the delta.
+* That request will return a new token, which you use in the _next_ delta request, and so forth.
+
+These `sync_token` values are not returned by default, but can be requested on a per-calendar basis:
+
+```ruby
+token = subject.calendars.find(calendar_url, sync: true).sync_token
+```
+
+To retrieve all events for that calendar (when starting the initial synchronisation process):
+
+```ruby
+events = subject.events.list(calendar_url)
 ```
 
+And then to retrieve the delta changes and a new `sync_token`:
+
+```ruby
+collection = subject.calendars.sync(calendar_url, token)
+collection.changes.each { |change| puts change.url }
+collection.deletions.each { |deletion_url| puts deletion_url }
+token = collection.sync_token
+```
+
+The `deletions` array is the event URLs for any events that have been removed since your previous sync - no other details are available.
+
+The `changes` array are Event objects - but some may not have their `calendar_data` populated, as not all calendar providers supply this as part of requesting the synchronisation delta. Apple does not return this information, but Google does. So, you may need to request the full event object if required:
+
+```ruby
+events = collection.changes.collect do |event|
+  event.unloaded? ? client.events.find(event.url) : event
+end
+```
+
+### Still to be implemented
+
+While a lot of the core CalDAV functionality is covered and this gem is useful as it stands, the following features are on the roadmap:
+
+* Further iCalendar parsing for Event objects.
+* Automated tests against FastMail and possibly other providers (Apple and Google are already covered).
+* Locking/unlocking of events as per the WebCAL RFC.
+* Support for VTODO, VJOURNAL, VFREEBUSY and any other components beyond VEVENT.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -87,16 +215,32 @@ Or install it yourself as:
 
     $ gem install calendav
 
+## API Design
+
+I've thus far preferred separation between data objects (`Calendav::Event` and `Calendav::Calendar`), and the interaction layer (via `Calendav::Client`) - as opposed to, say, a more ActiveRecord-like manner of interactions from within data objects.
+
+I've chosen the separated approach because it allows actions to occur on specific calendars or events without having a full data tree - this keeps requests to calendar providers to a minimum. You don't want to be loading everything from their servers every time you're reading/modifying one event!
+
+One thing that will likely evolve is how identifiers are handled for new calendars and events - while allowing custom ones to be provided will remain, I'll be looking at autogeneration with UUIDs to ensure a simpler approach is possible.
+
+Similarly, providing translation around event/calendar/time-zone details (via [icalendar](https://github.com/icalendar/icalendar)) is also a consideration.
+
+## Thanks
+
+The work done in previous Ruby CalDAV clients [RubyCaldav](https://github.com/digITpro/caldav_client) and [caldav](https://github.com/collectiveidea/caldav) has been very helpful, even though the codebases haven't seen updates in many years. I also found Sabre's documentation on [building a CalDAV client](https://sabre.io/dav/building-a-caldav-client/) to be extremely useful. Thank you to those teams for their hard work!
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+## Tests
+
+The test suite currently only runs against Google and Apple accounts I've created especially for this purpose - and the credentials are not public. I realise this makes contributions more difficult, and I'm open to finding better ways to handle this. I did look into running a CalDAV server within the test suite, but couldn't find anything small and easy enough for that purpose. But also: testing against common CalDAV servers does help to ensure this gem is truly useful (and has knowledge of their idiosyncrasies).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/pat/calendav. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/pat/calendav/blob/main/CODE_OF_CONDUCT.md).
 
-The test suite currently only runs against a Google account I've created especially for this purpose - and the credentials are not public. I realise this makes contributions more difficult, and I'm open to finding better ways to handle this. I did look into running a CalDAV server within the test suite, but couldn't find anything small and easy enough for that purpose. But also: testing against common CalDAV servers does help to ensure this gem is truly useful (and has knowledge of their idiosyncrasies).
-
 ## License
 
 The gem is available as open source under the terms of the [Hippocratic License](https://firstdonoharm.dev).

data/lib/calendav/calendar.rb

@@ -1,55 +1,31 @@
 # frozen_string_literal: true
 
-require_relative "./xml_processor"
+require_relative "./contextual_url"
+require_relative "./parsers/calendar_xml"
 
 module Calendav
   class Calendar
-    attr_reader :path
+    attr_reader :url, :display_name, :description, :ctag, :etag, :time_zone,
+                :color, :components, :reports, :sync_token
 
-    def self.from_xml(node)
+    def self.from_xml(host, node)
       new(
-        node.xpath("./dav:href").text,
-        node.xpath(".//dav:prop/*").to_xml,
-        node.namespaces
+        ContextualURL.call(host, node.xpath("./dav:href").text),
+        Parsers::CalendarXML.call(node)
       )
     end
 
-    def initialize(path, attribute_nodes, namespaces = {})
-      @path = path
-      @attribute_nodes = attribute_nodes
-      @namespaces = namespaces
-    end
-
-    def display_name
-      attribute_value fragment.xpath("//dav:displayname")
-    end
-
-    def ctag
-      attribute_value fragment.xpath("//cs:getctag")
-    end
-
-    def etag
-      attribute_value fragment.xpath("//dav:getetag")
-    end
-
-    private
-
-    attr_reader :attribute_nodes, :namespaces
-
-    def fragment
-      @fragment ||= XMLProcessor.call(
-        "<nodes>#{attribute_nodes}</nodes>", namespaces
-      )
-    end
-
-    def attribute_value(node)
-      return nil if node.children.empty?
-
-      if node.children.any?(&:element?)
-        node.children.select(&:element?).collect(&:to_xml).join
-      else
-        node.children.text
-      end
+    def initialize(url, attributes = {})
+      @url = url
+      @display_name = attributes[:display_name]
+      @description = attributes[:description]
+      @ctag = attributes[:ctag]
+      @etag = attributes[:etag]
+      @time_zone = attributes[:time_zone]
+      @color = attributes[:color]
+      @components = attributes[:components]
+      @reports = attributes[:reports]
+      @sync_token = attributes[:sync_token]
     end
   end
 end

data/lib/calendav/client.rb

@@ -23,13 +23,11 @@ module Calendav
     def principal_url
       @principal_url ||= begin
         request = Requests::CurrentUserPrincipal.call
+        response = endpoint.propfind(request.to_xml).first
 
         ContextualURL.call(
-          credentials,
-          endpoint
-            .propfind(request.to_xml)
-            .xpath(".//dav:current-user-principal/dav:href")
-            .text
+          credentials.host,
+          response.xpath(".//dav:current-user-principal/dav:href").text
         )
       end
     end

data/lib/calendav/clients/calendars_client.rb

@@ -3,13 +3,20 @@
 require "securerandom"
 
 require_relative "../calendar"
+require_relative "../parsers/sync_xml"
 require_relative "../requests/calendar_home_set"
 require_relative "../requests/list_calendars"
 require_relative "../requests/make_calendar"
+require_relative "../requests/sync_collection"
+require_relative "../requests/update_calendar"
 
 module Calendav
   module Clients
     class CalendarsClient
+      DEFAULT_ATTRIBUTES = %i[
+        display_name resource_type etag ctag color components reports
+      ].freeze
+
       def initialize(client, endpoint, credentials)
         @client = client
         @endpoint = endpoint
@@ -19,47 +26,82 @@ module Calendav
       def home_url
         @home_url ||= begin
           request = Requests::CalendarHomeSet.call
+          response = endpoint.propfind(request.to_xml, url: principal_url).first
 
           ContextualURL.call(
-            credentials,
-            endpoint
-              .propfind(request.to_xml, url: client.principal_url)
-              .xpath(".//caldav:calendar-home-set/dav:href")
-              .text
+            credentials.host,
+            response.xpath(".//caldav:calendar-home-set/dav:href").text
           )
         end
       end
 
-      def create(attributes)
-        request = Requests::MakeCalendar.call(attributes)
-
-        id = SecureRandom.uuid
-        id = "/#{id}" unless home_url.end_with?("/")
-        url = home_url + id
+      def create?
+        options.include?("MKCOL") || options.include?("MKCALENDAR")
+      end
 
-        endpoint.mkcalendar(request.to_xml, url: url)
+      def create(identifier, attributes)
+        request = Requests::MakeCalendar.call(attributes)
+        url = merged_url(identifier)
+        result = endpoint.mkcalendar(request.to_xml, url: url)
 
-        url
+        result.headers["Location"] || url
       end
 
       def delete(url)
         endpoint.delete(url: url)
       end
 
-      def list
-        request = Requests::ListCalendars.call
+      def find(url, attributes: DEFAULT_ATTRIBUTES, sync: false)
+        attributes = (attributes.dup << :sync_token) if sync
+
+        list(url, depth: 0, attributes: attributes).first
+      end
+
+      def list(url = home_url, depth: 1, attributes: DEFAULT_ATTRIBUTES)
+        request = Requests::ListCalendars.call(attributes)
         calendar_xpath = ".//dav:resourcetype/caldav:calendar"
 
         endpoint
-          .propfind(request.to_xml, url: home_url, depth: 1)
-          .xpath(".//dav:response")
+          .propfind(request.to_xml, url: url, depth: depth)
           .select { |node| node.xpath(calendar_xpath).any? }
-          .collect { |node| Calendar.from_xml(node) }
+          .collect { |node| Calendar.from_xml(home_url, node) }
+      end
+
+      def options
+        endpoint
+          .options(url: home_url)
+          .headers["Allow"]
+          .split(", ")
+      end
+
+      def sync(url, token)
+        request = Requests::SyncCollection.call(token)
+
+        Parsers::SyncXML.call(
+          url, endpoint.report(request.to_xml, url: url, depth: nil)
+        )
+      end
+
+      def update(url, attributes)
+        request = Requests::UpdateCalendar.call(attributes)
+        endpoint
+          .proppatch(request.to_xml, url: url)
+          .first
+          .xpath(".//dav:status")
+          .text["200 OK"] == "200 OK"
       end
 
       private
 
       attr_reader :client, :endpoint, :credentials
+
+      def merged_url(identifier)
+        "#{home_url.delete_suffix('/')}/#{identifier.delete_suffix('/')}/"
+      end
+
+      def principal_url
+        client.principal_url
+      end
     end
   end
 end