caldav.rb 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25dd8ca7b31b78c727d868379e569f2a9a1715ca4f00d7378aa0fdba1bf534aa
+  data.tar.gz: fbd981192af07191ba341e9087966b509c04976fbb985d8152b0e1a67340198b
+SHA512:
+  metadata.gz: 69bb382d65bf98f71c1ccc3fad7b110a034edad6906efab5530b46ff3a4bcd0e78d0852864fadfa5c116c96b89803ed46e79755ba548fb817243b74287cc3e70
+  data.tar.gz: e6c8231c951220f020b36d1b6330713fb31ecf5908b26c0e0e1190754f9bbd4159a70d518d39d83526e6e8f1ea33e529debaac8438c1dda6bff12456686202c1

data/CHANGELOG

@@ -0,0 +1,13 @@
+# CHANGELOG
+
+## 20260620
+
+0.0.0: Initial release.
+
+1. + CalDAV connection class (< WebDAV) providing the four CalDAV-specific protocol verbs: mkcalendar, calendar_query, calendar_multiget, freebusy_query.
+2. + Net::HTTP::Mkcalendar request class. Not provided by Ruby's standard library. Mirrors webdav's Net::HTTP::Report. The REPORT method (used by calendar_query, calendar_multiget, freebusy_query) is already provided by webdav 0.2.0 and is reused.
+3. + CalDAV::MultiStatus (< WebDAV::MultiStatus): type-preserving subclass. Overrides the private WebDAV::MultiStatus#parse_response to wrap each resource in a CalDAV::Resource. Interim coupling to a private webdav method; dissolves when webdav objectifies resources at the factoring stage.
+4. + CalDAV::Resource: wraps a webdav resource hash and adds CalDAV-namespace navigation accessors: calendar_data, calendar_description, supported_calendar_component_set, calendar_timezone, is_calendar?. Strictly navigation, not parsing — accessors return raw iCalendar strings/values; iCalendar parsing into domain objects is Layer 2.
+5. + Discovery helpers: CalDAV#current_user_principal, #calendar_home_set, #calendars. Return paths/strings. The object-oriented discovery API is Layer 2 (future release).
+6. + Layer 1 (Protocol) of the planned three-layer ecosystem. Layer 2 (Objects: Event/Calendar/Principal value objects with iCalendar parsing) and Layer 3 (Queryable: Namo-backed Calendar) are future releases — reserved require paths are caldav.rb/objects and caldav.rb/queryable respectively.
+7. + Read-only compatibility. Writes (requiring If-Match conditional headers, which webdav's #put does not yet expose), OAuth, sync-collection, and server-quirk handling are deferred.

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thoran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# caldav.rb
+
+A CalDAV client library for Ruby, built on [webdav](https://github.com/thoran/webdav) and implementing RFC 4791. This release ships **Layer 1 (Protocol)** of a planned three-layer ecosystem.
+
+
+## Installation
+
+```
+gem install caldav.rb
+```
+
+Or in your Gemfile:
+
+```ruby
+gem 'caldav.rb'
+```
+
+
+## Concepts
+
+caldav.rb is designed in three layers, each a strict superset of the one below. This release ships Layer 1 only; the higher layers are future releases with reserved require paths.
+
+- **Layer 1 — Protocol** (this release). The CalDAV verbs, multistatus responses, and namespace-aware navigation accessors. The equivalent of a raw protocol library: it returns CalDAV-typed responses but does not parse iCalendar payloads or construct domain objects. Most users will want Layer 2 once it ships; until then, the protocol layer is usable directly by reading `resource.calendar_data` and parsing it with the `icalendar` gem.
+- **Layer 2 — Objects** (future, `require 'caldav.rb/objects'`). `CalDAV::Event`, `CalDAV::Calendar`, and `CalDAV::Principal` value objects with iCalendar parsing and convenience predicates.
+- **Layer 3 — Queryable** (future, `require 'caldav.rb/queryable'`). A [Namo](https://github.com/thoran/namo)-backed `CalDAV::Query::Calendar` exposing events as queryable rows with derived columns.
+
+
+## Usage
+
+```ruby
+require 'caldav'
+
+caldav = CalDAV.new('https://caldav.example.com/dav/', username: 'user', password: 'pass')
+```
+
+### Discovery
+
+```ruby
+principal = caldav.current_user_principal
+home = caldav.calendar_home_set(principal)
+caldav.calendars(home).each{|href| puts href}
+```
+
+Each discovery helper defaults its argument to the result of the previous step, so `caldav.calendars` alone walks principal → home-set → calendars.
+
+Discovery begins by PROPFINDing the **path of the base URL**. Many servers do not expose the current-user-principal at `/`, so point the base URL at the server's CalDAV context — e.g. `https://caldav.example.com/dav/` rather than `https://caldav.example.com/`. (RFC 6764 `.well-known/caldav` redirects are not auto-followed for PROPFIND in this release.) You can also override the starting point per call: `caldav.current_user_principal('/dav/')`.
+
+### Querying a calendar
+
+```ruby
+result = caldav.calendar_query('/calendars/user/work/', body: query_xml)
+result.resources.each do |resource|
+  puts resource.href
+  puts resource.calendar_data  # the raw iCalendar string
+end
+```
+
+### Fetching specific events
+
+```ruby
+result = caldav.calendar_multiget('/calendars/user/work/', body: multiget_xml)
+```
+
+### Free/busy
+
+```ruby
+response = caldav.freebusy_query('/calendars/user/work/', body: freebusy_xml)
+puts response.body  # VFREEBUSY iCalendar data — not a multistatus
+```
+
+### Creating a calendar
+
+```ruby
+caldav.mkcalendar('/calendars/user/new/', body: mkcalendar_xml)
+```
+
+
+## Methods
+
+### Protocol verbs (RFC 4791)
+
+- `mkcalendar(path, body:)` — §5.3.1. Create a calendar collection. Returns a `WebDAV::Response`.
+- `calendar_query(path, body:, depth:)` — §7.8. REPORT with a `<c:calendar-query>` body. Returns a `CalDAV::MultiStatus`.
+- `calendar_multiget(path, body:, depth:)` — §7.9. REPORT with a `<c:calendar-multiget>` body. Returns a `CalDAV::MultiStatus`.
+- `freebusy_query(path, body:, depth:)` — §7.10. REPORT with a `<c:free-busy-query>` body. Returns a raw `WebDAV::Response` carrying VFREEBUSY iCalendar data — **not** a multistatus. This asymmetry is inherent to the CalDAV spec.
+
+### Discovery
+
+- `current_user_principal(path = base URL path)` — returns the principal URL string. PROPFINDs the base URL's path by default; pass a path to start discovery elsewhere.
+- `calendar_home_set(principal = current_user_principal)` — returns the calendar-home-set URL string.
+- `calendars(home = calendar_home_set)` — returns an array of calendar collection URL strings.
+
+
+## Responses
+
+The REPORT verbs return `CalDAV::MultiStatus`, a type-preserving subclass of `WebDAV::MultiStatus` whose `resources` are `CalDAV::Resource` objects. Each `CalDAV::Resource` adds CalDAV-namespace navigation accessors over the underlying webdav resource:
+
+- `href` — the resource URL
+- `calendar_data` — the iCalendar string from `<c:calendar-data>`
+- `calendar_description` — `<c:calendar-description>`
+- `supported_calendar_component_set` — `<c:supported-calendar-component-set>`
+- `calendar_timezone` — the VTIMEZONE string from `<c:calendar-timezone>`
+- `is_calendar?` — true when `<d:resourcetype>` includes `<c:calendar/>`
+
+These are strictly navigation: they return raw strings and values, never parsed iCalendar objects. Parsing is Layer 2's job.
+
+
+## Limitations
+
+This is a Layer 1 protocol release. Known boundaries:
+
+- **Read-only.** Conditional writes need `If-Match`, which webdav's `put` does not yet expose; writes arrive with Layer 2.
+- **No iCalendar parsing.** Use the `icalendar` gem on `resource.calendar_data` if you need parsed events now.
+- **Basic auth only.** No OAuth.
+- **Tested against one real CalDAV server.** Other servers should work but are unverified.
+- **No sync-collection.** Incremental sync is deferred.
+
+
+## Dependencies
+
+- [webdav](https://github.com/thoran/webdav)
+
+
+## Testing
+
+```
+rake
+```
+
+Unit tests stub at the request boundary and need no network. A separate set of
+integration tests (`test/integration_test.rb`) run against a real CalDAV server
+via [VCR](https://github.com/vcr/vcr): they record real interactions into
+host- and credential-scrubbed cassettes under `test/cassettes/` on first run, then
+replay offline. Without a cassette and without credentials they skip, so the
+default suite stays green.
+
+To record against a live account, supply the server and credentials through the
+environment and run `rake`:
+
+```
+CALDAV_URL='https://your-caldav-host/' \
+CALDAV_USERNAME='you@example.com' \
+CALDAV_PASSWORD='app-password' \
+rake
+```
+
+See [test/cassettes/README.md](test/cassettes/README.md) for details.
+
+
+## Contributing
+
+1. Fork it [https://github.com/thoran/caldav.rb/fork](https://github.com/thoran/caldav.rb/fork)
+2. Create your feature branch (git checkout -b my-new-feature)
+3. Commit your changes (git commit -am 'Add some feature')
+4. Push to the branch (git push origin my-new-feature)
+5. Create a new pull request
+
+
+## Licence
+
+MIT

data/Rakefile

@@ -0,0 +1,9 @@
+# Rakefile
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/caldav.rb.gemspec

@@ -0,0 +1,50 @@
+require_relative './lib/CalDAV/VERSION'
+
+class Gem::Specification
+  def dependencies=(gems)
+    gems.each{|gem| add_dependency(*gem)}
+  end
+
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'caldav.rb'
+  spec.version = CalDAV::VERSION
+
+  spec.summary = "A Ruby CalDAV client library."
+  spec.description = "A Ruby CalDAV client library, built on webdav (RFC 4791)."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'https://github.com/thoran/caldav'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 3.2'
+  spec.require_paths = ['lib']
+
+  spec.files = [
+    'caldav.rb.gemspec',
+    'CHANGELOG',
+    'Gemfile',
+    'LICENSE',
+    'Rakefile',
+    'README.md',
+    Dir['lib/**/*.rb'],
+    Dir['test/**/*.rb']
+  ].flatten
+
+  spec.dependencies = [
+    ['webdav', '~> 0.2']
+  ]
+
+  spec.development_dependencies = [
+    ['minitest', '~> 6.0'],
+    ['minitest-mock'],
+    ['rake'],
+    ['vcr', '~> 6.0'],
+    ['webmock', '~> 3.0']
+  ]
+end

data/lib/CalDAV/MultiStatus.rb

@@ -0,0 +1,33 @@
+# CalDAV/MultiStatus.rb
+# CalDAV::MultiStatus
+
+require 'webdav'
+
+require_relative './Resource'
+
+class CalDAV < WebDAV
+  class MultiStatus < WebDAV::MultiStatus
+
+    private
+
+    def parse_response(response_element)
+      CalDAV::Resource.new(super)
+    end
+
+    # Interim: webdav 0.2.0's parse_properties does `text || to_s`, so a nested
+    # property (resourcetype, current-user-principal, calendar-home-set) whose
+    # server pretty-prints the XML yields the inter-tag whitespace instead of the
+    # markup, dropping the nested elements. Treat blank text as absent so such
+    # properties fall through to their serialised form, as they do for compact
+    # servers. Dissolves when webdav is reworked.
+    def parse_properties(prop_element)
+      return {} unless prop_element
+      prop_element.elements.to_a.each_with_object({}) do |property_element, result|
+        result[property_element.namespace] ||= {}
+        text = property_element.text
+        value = text && !text.strip.empty? ? text : property_element.to_s
+        result[property_element.namespace][property_element.name] = value
+      end
+    end
+  end
+end

data/lib/CalDAV/Resource.rb

@@ -0,0 +1,68 @@
+# CalDAV/Resource.rb
+# CalDAV::Resource
+
+require 'webdav'
+
+class CalDAV < WebDAV
+  class Resource
+    attr_reader :hash
+
+    def href
+      hash[:href]
+    end
+
+    def status
+      hash[:status]
+    end
+
+    def propstats
+      hash[:propstats]
+    end
+
+    # Navigation accessors. Strictly navigation, not parsing: they return the
+    # underlying iCalendar string or value.
+
+    def calendar_data
+      property(NAMESPACE, 'calendar-data')
+    end
+
+    def calendar_description
+      property(NAMESPACE, 'calendar-description')
+    end
+
+    def supported_calendar_component_set
+      property(NAMESPACE, 'supported-calendar-component-set')
+    end
+
+    def calendar_timezone
+      property(NAMESPACE, 'calendar-timezone')
+    end
+
+    # Matches a <calendar> element (under any namespace prefix) in the serialised
+    # resourcetype, rather than a bare 'calendar' substring: the substring also
+    # matches calendar-proxy-read/write collections, which are not calendars.
+    def is_calendar?
+      resource_type.match?(%r{<(?:\w+:)?calendar(?:\s[^>]*)?/?>})
+    end
+
+    private
+
+    def initialize(hash)
+      @hash = hash
+    end
+
+    def properties
+      @properties ||= propstats.each_with_object({}) do |propstat, result|
+        result.merge!(propstat[:properties])
+      end
+    end
+
+    def property(namespace, name)
+      properties.dig(namespace, name)
+    end
+
+    def resource_type
+      property(DAV_NAMESPACE, 'resourcetype').to_s
+    end
+  end
+end

data/lib/CalDAV/VERSION.rb

@@ -0,0 +1,8 @@
+# CalDAV/VERSION.rb
+# CalDAV::VERSION
+
+class WebDAV; end
+
+class CalDAV < WebDAV
+  VERSION = '0.0.0'
+end

data/lib/CalDAV.rb

@@ -0,0 +1,135 @@
+# CalDAV.rb
+# CalDAV
+
+require 'webdav'
+
+require_relative './CalDAV/Resource'
+require_relative './CalDAV/MultiStatus'
+require_relative './Net/HTTP/Mkcalendar'
+
+class CalDAV < WebDAV
+  NAMESPACE = 'urn:ietf:params:xml:ns:caldav'
+  DAV_NAMESPACE = 'DAV:'
+
+  # Protocol verbs (RFC 4791)
+
+  # RFC 4791 §5.3.1. Creates a calendar collection.
+  def mkcalendar(path, body: nil)
+    response = request(:mkcalendar, path, body: body)
+    handle_response(response)
+  end
+
+  # RFC 4791 §7.8. REPORT with a <c:calendar-query> body.
+  def calendar_query(path, body:, depth: '1')
+    report_as_caldav(path, body: body, depth: depth)
+  end
+
+  # RFC 4791 §7.9. REPORT with a <c:calendar-multiget> body.
+  def calendar_multiget(path, body:, depth: '0')
+    report_as_caldav(path, body: body, depth: depth)
+  end
+
+  # RFC 4791 §7.10. REPORT with a <c:free-busy-query> body. Asymmetric: returns
+  # the raw response carrying iCalendar VFREEBUSY data, not a multistatus.
+  def freebusy_query(path, body:, depth: '0')
+    response = request(:report, path, body: body, headers: {'Depth' => depth})
+    handle_response(response)
+  end
+
+  # Discovery helpers. Return paths/strings. And object-oriented discovery API
+  # (Principal/Calendar objects) is is planned.
+
+  def current_user_principal(path = discovery_path)
+    resource = propfind_as_caldav(path, body: current_user_principal_body, depth: '0').resources.first
+    resource&.then{|r| href_property(r, DAV_NAMESPACE, 'current-user-principal')}
+  end
+
+  def calendar_home_set(principal = current_user_principal)
+    resource = propfind_as_caldav(principal, body: calendar_home_set_body, depth: '0').resources.first
+    resource&.then{|r| href_property(r, NAMESPACE, 'calendar-home-set')}
+  end
+
+  def calendars(home = calendar_home_set)
+    resources = propfind_as_caldav(home, body: calendars_body, depth: '1').resources
+    resources.select{|resource| resource.is_calendar?}.collect{|resource| resource.href}
+  end
+
+  private
+
+  # Send a REPORT and return the CalDAV-typed multistatus rather than the plain
+  # WebDAV one. Constructed from the raw response so the CalDAV resource wrappers
+  # are produced by CalDAV::MultiStatus's overridden parse_response.
+  def report_as_caldav(path, body:, depth:)
+    response = request(:report, path, body: body, headers: {'Depth' => depth})
+    raise WebDAV::Error.new(response) if response.code.to_i >= 400
+    CalDAV::MultiStatus.new(response)
+  end
+
+  # As report_as_caldav, but for PROPFIND. Needed because the inherited #propfind
+  # returns a plain WebDAV::MultiStatus whose resources are bare hashes, not
+  # CalDAV::Resource wrappers. Discovery relies on the wrappers (#is_calendar?,
+  # #href), so it routes through here.
+  def propfind_as_caldav(path, body:, depth:)
+    response = request(:propfind, path, body: body, headers: {'Depth' => depth})
+    raise WebDAV::Error.new(response) if response.code.to_i >= 400
+    CalDAV::MultiStatus.new(response)
+  end
+
+  # The discovery properties (current-user-principal, calendar-home-set) wrap
+  # their value in a nested <d:href>. webdav 0.2.0 renders a nested-element
+  # property as serialised markup, so the bare URL is lifted back out here.
+  # Caveat: when a server pretty-prints, webdav's `text || to_s` returns the
+  # leading whitespace text node and the href is lost upstream; recovering that
+  # waits for the webdav-objectifies-resources rework.
+  def href_property(resource, namespace, name)
+    resource.propstats.each do |propstat|
+      href = extract_href(propstat[:properties].dig(namespace, name))
+      return href if href
+    end
+    nil
+  end
+
+  def extract_href(value)
+    return nil unless value
+    match = value.match(%r{<(?:\w+:)?href[^>]*>(.*?)</(?:\w+:)?href>}m)
+    href = (match ? match[1] : value).strip
+    href.empty? ? nil : href
+  end
+
+  # Discovery starts from the path of the configured base URL, so a server that
+  # does not expose the current-user-principal at '/' is reached by giving its
+  # CalDAV context path in the base URL (e.g. https://host/dav/). Falls back to
+  # '/' when the base URL has no path.
+  def discovery_path
+    @uri.path.empty? ? '/' : @uri.path
+  end
+
+  def current_user_principal_body
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <d:propfind xmlns:d="DAV:">
+        <d:prop><d:current-user-principal/></d:prop>
+      </d:propfind>
+    XML
+  end
+
+  def calendar_home_set_body
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <d:propfind xmlns:d="DAV:" xmlns:c="#{NAMESPACE}">
+        <d:prop><c:calendar-home-set/></d:prop>
+      </d:propfind>
+    XML
+  end
+
+  def calendars_body
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <d:propfind xmlns:d="DAV:">
+        <d:prop>
+          <d:resourcetype/>
+        </d:prop>
+      </d:propfind>
+    XML
+  end
+end

data/lib/Net/HTTP/Mkcalendar.rb

@@ -0,0 +1,16 @@
+# Net/HTTP/Mkcalendar.rb
+# Net::HTTP::Mkcalendar
+
+require 'net/http'
+
+module Net
+  class HTTP
+    class Mkcalendar < Net::HTTPRequest
+
+      METHOD = 'MKCALENDAR'
+      REQUEST_HAS_BODY = true
+      RESPONSE_HAS_BODY = true
+
+    end
+  end
+end

data/test/CalDAV/Resource_test.rb

@@ -0,0 +1,96 @@
+# test/CalDAV/Resource_test.rb
+
+require_relative '../helper'
+
+describe CalDAV::Resource do
+  let(:calendar_xml) do
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <d:multistatus xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
+        <d:response>
+          <d:href>/calendars/user/work/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype><d:collection/><c:calendar/></d:resourcetype>
+              <c:calendar-description>Work calendar</c:calendar-description>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+        <d:response>
+          <d:href>/calendars/user/work/event.ics</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:getetag>"abc123"</d:getetag>
+              <c:calendar-data>BEGIN:VCALENDAR</c:calendar-data>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+        <d:response>
+          <d:href>/calendars/user/calendar-proxy-read/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype><d:collection/><cs:calendar-proxy-read xmlns:cs="http://calendarserver.org/ns/"/></d:resourcetype>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+      </d:multistatus>
+    XML
+  end
+
+  let(:multistatus){CalDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: calendar_xml))}
+  let(:calendar_resource){multistatus.resources[0]}
+  let(:event_resource){multistatus.resources[1]}
+  let(:proxy_resource){multistatus.resources[2]}
+
+  it "wraps resources as CalDAV::Resource" do
+    _(calendar_resource).must_be_kind_of CalDAV::Resource
+  end
+
+  it "exposes href" do
+    _(calendar_resource.href).must_equal '/calendars/user/work/'
+  end
+
+  it "reads calendar-description" do
+    _(calendar_resource.calendar_description).must_equal 'Work calendar'
+  end
+
+  it "reads calendar-data" do
+    _(event_resource.calendar_data).must_equal 'BEGIN:VCALENDAR'
+  end
+
+  it "identifies a calendar collection" do
+    _(calendar_resource.is_calendar?).must_equal true
+  end
+
+  it "identifies a non-calendar resource" do
+    _(event_resource.is_calendar?).must_equal false
+  end
+
+  it "does not mistake a calendar-proxy collection for a calendar" do
+    _(proxy_resource.is_calendar?).must_equal false
+  end
+
+  it "identifies a calendar from a pretty-printed (indented) resourcetype" do
+    pretty = CalDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: <<~XML))
+      <?xml version="1.0" encoding="utf-8"?>
+      <d:multistatus xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
+        <d:response>
+          <d:href>/dav/calendars/user/x/work/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype>
+                <d:collection/>
+                <c:calendar/>
+              </d:resourcetype>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+      </d:multistatus>
+    XML
+    _(pretty.resources.first.is_calendar?).must_equal true
+  end
+end

data/test/CalDAV_test.rb

@@ -0,0 +1,182 @@
+# test/caldav_test.rb
+
+require_relative './helper'
+
+describe CalDAV do
+  let(:base_uri){'https://caldav.example.com/'}
+  let(:caldav){CalDAV.new(base_uri, username: 'user', password: 'pass')}
+
+  let(:multistatus_response) do
+    MockResponse.new(
+      code: '207',
+      message: 'Multi-Status',
+      body: <<~XML,
+        <?xml version="1.0" encoding="UTF-8"?>
+        <d:multistatus xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
+          <d:response>
+            <d:href>/calendars/user/work/event.ics</d:href>
+            <d:propstat>
+              <d:prop>
+                <d:getetag>"abc123"</d:getetag>
+                <c:calendar-data>BEGIN:VCALENDAR</c:calendar-data>
+              </d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+          </d:response>
+        </d:multistatus>
+      XML
+    )
+  end
+
+  let(:created_response){MockResponse.new(code: '201', message: 'Created', body: '')}
+
+  describe "#mkcalendar" do
+    it "returns a Response" do
+      caldav.stub(:request, created_response) do
+        result = caldav.mkcalendar('/calendars/user/new/')
+        _(result).must_be_kind_of WebDAV::Response
+        _(result.code).must_equal 201
+      end
+    end
+  end
+
+  describe "#calendar_query" do
+    it "returns a CalDAV::MultiStatus" do
+      caldav.stub(:request, multistatus_response) do
+        result = caldav.calendar_query('/calendars/user/work/', body: '<c:calendar-query/>')
+        _(result).must_be_kind_of CalDAV::MultiStatus
+        _(result.resources.first).must_be_kind_of CalDAV::Resource
+      end
+    end
+  end
+
+  describe "#calendar_multiget" do
+    it "returns a CalDAV::MultiStatus" do
+      caldav.stub(:request, multistatus_response) do
+        result = caldav.calendar_multiget('/calendars/user/work/', body: '<c:calendar-multiget/>')
+        _(result).must_be_kind_of CalDAV::MultiStatus
+      end
+    end
+  end
+
+  describe "#freebusy_query" do
+    it "returns a raw Response carrying VFREEBUSY" do
+      freebusy = MockResponse.new(code: '200', message: 'OK', body: 'BEGIN:VCALENDAR')
+      caldav.stub(:request, freebusy) do
+        result = caldav.freebusy_query('/calendars/user/work/', body: '<c:free-busy-query/>')
+        _(result).must_be_kind_of WebDAV::Response
+        _(result.body).must_equal 'BEGIN:VCALENDAR'
+      end
+    end
+  end
+
+  describe "#current_user_principal" do
+    let(:response) do
+      MockResponse.new(code: '207', message: 'Multi-Status', body: <<~XML)
+        <?xml version="1.0" encoding="UTF-8"?>
+        <d:multistatus xmlns:d="DAV:">
+          <d:response>
+            <d:href>/</d:href>
+            <d:propstat>
+              <d:prop><d:current-user-principal><d:href>/dav/principals/user/abc/</d:href></d:current-user-principal></d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+          </d:response>
+        </d:multistatus>
+      XML
+    end
+
+    it "returns the principal href as a bare URL string" do
+      caldav.stub(:request, response) do
+        _(caldav.current_user_principal).must_equal '/dav/principals/user/abc/'
+      end
+    end
+
+    it "PROPFINDs the base URL's path by default, not '/'" do
+      dav = CalDAV.new('https://caldav.example.com/dav/', username: 'u', password: 'p')
+      captured = nil
+      responder = ->(verb, path, **kw){captured = path; response}
+      dav.stub(:request, responder) do
+        dav.current_user_principal
+      end
+      _(captured).must_equal '/dav/'
+    end
+
+    it "extracts the principal from a pretty-printed (indented) response" do
+      pretty = MockResponse.new(code: '207', message: 'Multi-Status', body: <<~XML)
+        <?xml version="1.0" encoding="utf-8"?>
+        <d:multistatus xmlns:d="DAV:">
+          <d:response>
+            <d:href>/dav/</d:href>
+            <d:propstat>
+              <d:prop>
+                <d:current-user-principal>
+                  <d:href>/dav/principals/user/abc/</d:href>
+                </d:current-user-principal>
+              </d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+          </d:response>
+        </d:multistatus>
+      XML
+      caldav.stub(:request, pretty) do
+        _(caldav.current_user_principal).must_equal '/dav/principals/user/abc/'
+      end
+    end
+  end
+
+  describe "#calendar_home_set" do
+    let(:response) do
+      MockResponse.new(code: '207', message: 'Multi-Status', body: <<~XML)
+        <?xml version="1.0" encoding="UTF-8"?>
+        <d:multistatus xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
+          <d:response>
+            <d:href>/dav/principals/user/abc/</d:href>
+            <d:propstat>
+              <d:prop><c:calendar-home-set><d:href>/dav/calendars/user/abc/</d:href></c:calendar-home-set></d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+          </d:response>
+        </d:multistatus>
+      XML
+    end
+
+    it "returns the home-set href as a bare URL string" do
+      caldav.stub(:request, response) do
+        _(caldav.calendar_home_set('/dav/principals/user/abc/')).must_equal '/dav/calendars/user/abc/'
+      end
+    end
+  end
+
+  describe "#calendars" do
+    let(:response) do
+      MockResponse.new(code: '207', message: 'Multi-Status', body: <<~XML)
+        <?xml version="1.0" encoding="UTF-8"?>
+        <d:multistatus xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav" xmlns:cs="http://calendarserver.org/ns/">
+          <d:response>
+            <d:href>/dav/calendars/user/abc/</d:href>
+            <d:propstat><d:prop><d:resourcetype><d:collection/></d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>
+          </d:response>
+          <d:response>
+            <d:href>/dav/calendars/user/abc/work/</d:href>
+            <d:propstat><d:prop><d:resourcetype><d:collection/><c:calendar/></d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>
+          </d:response>
+          <d:response>
+            <d:href>/dav/calendars/user/abc/inbox/</d:href>
+            <d:propstat><d:prop><d:resourcetype><d:collection/><c:schedule-inbox/></d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>
+          </d:response>
+          <d:response>
+            <d:href>/dav/calendars/user/abc/proxy/</d:href>
+            <d:propstat><d:prop><d:resourcetype><d:collection/><cs:calendar-proxy-read/></d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>
+          </d:response>
+        </d:multistatus>
+      XML
+    end
+
+    it "returns only the calendar collection hrefs as bare URL strings" do
+      caldav.stub(:request, response) do
+        _(caldav.calendars('/dav/calendars/user/abc/')).must_equal ['/dav/calendars/user/abc/work/']
+      end
+    end
+  end
+end

data/test/Net/HTTP/Mkcalendar_test.rb

@@ -0,0 +1,21 @@
+# test/Net/HTTP/Mkcalendar_test.rb
+
+require_relative '../../helper'
+
+describe Net::HTTP::Mkcalendar do
+  it "is a subclass of Net::HTTPRequest" do
+    _(Net::HTTP::Mkcalendar < Net::HTTPRequest).must_equal(true)
+  end
+
+  it "has the correct METHOD" do
+    _(Net::HTTP::Mkcalendar::METHOD).must_equal('MKCALENDAR')
+  end
+
+  it "accepts a body" do
+    _(Net::HTTP::Mkcalendar::REQUEST_HAS_BODY).must_equal(true)
+  end
+
+  it "expects a response body" do
+    _(Net::HTTP::Mkcalendar::RESPONSE_HAS_BODY).must_equal(true)
+  end
+end

data/test/helper.rb

@@ -0,0 +1,13 @@
+# test/helper.rb
+
+require 'minitest/autorun'
+require 'minitest/mock'
+require 'minitest/spec'
+
+require_relative '../lib/caldav'
+
+MockResponse = Struct.new(:code, :message, :body, :headers_hash, keyword_init: true) do
+  def [](key)
+    headers_hash&.dig(key)
+  end
+end

data/test/integration_test.rb

@@ -0,0 +1,52 @@
+# test/integration_test.rb
+
+require_relative './helper'
+require_relative './vcr_helper'
+
+describe 'CalDAV integration' do
+  let(:caldav){caldav_client}
+
+  let(:events_query_body) do
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <c:calendar-query xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
+        <d:prop>
+          <d:getetag/>
+          <c:calendar-data/>
+        </d:prop>
+        <c:filter>
+          <c:comp-filter name="VCALENDAR">
+            <c:comp-filter name="VEVENT"/>
+          </c:comp-filter>
+        </c:filter>
+      </c:calendar-query>
+    XML
+  end
+
+  it "discovers principal, home-set and calendars as bare URL strings" do
+    with_caldav_cassette('discovery') do
+      principal = caldav.current_user_principal
+      _(principal).must_be_kind_of String
+      _(principal).wont_include '<'
+      home = caldav.calendar_home_set(principal)
+      _(home).must_be_kind_of String
+      _(home).wont_include '<'
+      calendars = caldav.calendars(home)
+      _(calendars).must_be_kind_of Array
+      calendars.each do |href|
+        _(href).must_be_kind_of String
+        _(href).wont_include '<'
+      end
+    end
+  end
+
+  it "queries the first calendar and returns CalDAV resources" do
+    with_caldav_cassette('calendar_query') do
+      calendar = caldav.calendars.first
+      skip 'no calendars on this account' unless calendar
+      result = caldav.calendar_query(calendar, body: events_query_body)
+      _(result).must_be_kind_of CalDAV::MultiStatus
+      result.resources.each{|resource| _(resource).must_be_kind_of CalDAV::Resource}
+    end
+  end
+end

data/test/vcr_helper.rb

@@ -0,0 +1,55 @@
+# test/vcr_helper.rb
+
+require 'uri'
+require 'vcr'
+
+EXAMPLE_CALDAV_URL = 'https://caldav.example.com/dav/'
+CALDAV_URL = ENV.fetch('CALDAV_URL', EXAMPLE_CALDAV_URL)
+
+# Replaces the account-identifier segment in CalDAV collection paths (e.g.
+# /principals/user/<id>/ or /calendars/user/<id>/) with a fixed placeholder, so a
+# committed cassette does not expose an account-specific id. The collection name
+# after the id (a calendar name, say) is preserved. Covers the common
+# collection/realm/id layout; the credential filters still scrub email-style ids.
+ACCOUNT_PATH = %r{(/(?:principals|calendars)/[^/]+/)[^/]+/}
+
+def anonymise_account_path(string)
+  string&.gsub(ACCOUNT_PATH, '\1anon/')
+end
+
+VCR.configure do |config|
+  config.cassette_library_dir = File.expand_path('cassettes', __dir__)
+  config.hook_into :webmock
+  config.filter_sensitive_data(URI(EXAMPLE_CALDAV_URL).host){URI(ENV['CALDAV_URL']).host if ENV['CALDAV_URL']}
+  # Basic auth is base64(user:pass), so the credential filters below would not catch it — filter the Authorization header itself too.
+  config.filter_sensitive_data('<BASIC_AUTH>'){|interaction| interaction.request.headers['Authorization']&.first}
+  config.filter_sensitive_data('<CALDAV_USERNAME>'){ENV['CALDAV_USERNAME']}
+  config.filter_sensitive_data('<CALDAV_PASSWORD>'){ENV['CALDAV_PASSWORD']}
+  # Anonymise account ids in request URIs and response bodies before writing. The
+  # rewrite is self-consistent (the same paths drive the next request), so the
+  # anonymised cassette still replays.
+  config.before_record do |interaction|
+    interaction.request.uri = anonymise_account_path(interaction.request.uri)
+    interaction.response.body = anonymise_account_path(interaction.response.body)
+  end
+end
+
+def caldav_client
+  CalDAV.new(
+    CALDAV_URL,
+    username: ENV.fetch('CALDAV_USERNAME', 'recorded'),
+    password: ENV.fetch('CALDAV_PASSWORD', 'recorded')
+  )
+end
+
+# Records against the real server when credentials are present; replays from the
+# committed cassette otherwise. Skips when a real request would be needed but no
+# credentials are set, so the suite stays green without an account. To re-record,
+# delete the cassette and re-run with credentials.
+def with_caldav_cassette(name)
+  cassette = File.join(VCR.configuration.cassette_library_dir, "#{name}.yml")
+  unless File.exist?(cassette) || ENV['CALDAV_USERNAME']
+    raise Minitest::Skip, "no cassette '#{name}.yml' and CALDAV_USERNAME unset; export CALDAV_URL/CALDAV_USERNAME/CALDAV_PASSWORD to record"
+  end
+  VCR.use_cassette(name){yield}
+end

data/test/vcr_helper_test.rb

@@ -0,0 +1,31 @@
+# test/vcr_helper_test.rb
+
+require_relative './helper'
+require_relative './vcr_helper'
+
+describe 'anonymise_account_path' do
+  it "replaces the id under a principals collection" do
+    _(anonymise_account_path('/dav/principals/user/john@example.net/')).must_equal '/dav/principals/user/anon/'
+  end
+
+  it "replaces the id under a calendars collection, keeping the calendar name" do
+    _(anonymise_account_path('/dav/calendars/user/abc123/work/')).must_equal '/dav/calendars/user/anon/work/'
+  end
+
+  it "replaces an opaque (non-email) id" do
+    _(anonymise_account_path('/dav/principals/user/u9f8e7d6/')).must_equal '/dav/principals/user/anon/'
+  end
+
+  it "anonymises ids inside a serialised response body" do
+    body = '<d:href>/dav/calendars/user/abc123/</d:href>'
+    _(anonymise_account_path(body)).must_equal '<d:href>/dav/calendars/user/anon/</d:href>'
+  end
+
+  it "leaves unrelated paths untouched" do
+    _(anonymise_account_path('/dav/')).must_equal '/dav/'
+  end
+
+  it "handles nil" do
+    _(anonymise_account_path(nil)).must_be_nil
+  end
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: caldav.rb
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- thoran
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: webdav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-mock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby CalDAV client library, built on webdav (RFC 4791).
+email: code@thoran.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- caldav.rb.gemspec
+- lib/CalDAV.rb
+- lib/CalDAV/MultiStatus.rb
+- lib/CalDAV/Resource.rb
+- lib/CalDAV/VERSION.rb
+- lib/Net/HTTP/Mkcalendar.rb
+- test/CalDAV/Resource_test.rb
+- test/CalDAV_test.rb
+- test/Net/HTTP/Mkcalendar_test.rb
+- test/helper.rb
+- test/integration_test.rb
+- test/vcr_helper.rb
+- test/vcr_helper_test.rb
+homepage: https://github.com/thoran/caldav
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: A Ruby CalDAV client library.
+test_files: []