carddav.rb 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9430d7a069267b260526ee0cfc83d48015b5ed3246d9cbb665929915d1146e8a
+  data.tar.gz: 312d5939b30b496bcf96c747ed1e3aea39cafd53225dde43668c4bbe865e71b9
+SHA512:
+  metadata.gz: ab268a645a1fb8769ff36517f908469655d2407c553271892c220b90f303a61120824542a2505da6b6b51043b5c8e873a282da6541547bfee97baf0fdac41b33
+  data.tar.gz: 131b86e9cdfea2c4bf6892effb27d1f8d5386a50721a812d2c65891b35ddb10f8f9c710afc2c075836261b86f94ac874ff33cf9d614429968b1812786547423e

data/CHANGELOG

@@ -0,0 +1,17 @@
+# CHANGELOG
+
+## 20260623
+
+0.0.0: Initial release.
+
+1. + CardDAV protocol verbs: mkcol (extended MKCOL), addressbook_query, and addressbook_multiget.
+2. + CardDAV discovery helpers: #current_user_principal, #addressbook_home_set, #addressbooks.
+3. + CardDAV::MultiStatus: type-preserving subclass that wraps each response resource as a CardDAV::Resource.
+3. + CardDAV::Resource: wraps a webdav resource hash and adds CardDAV-namespace navigation accessors: address_data, addressbook_description, supported_address_data, max_resource_size, is_addressbook?.
+4. + CardDAV::VERSION
+5. + carddav.rb.gemspec
+6. + CHANGELOG
+7. + Gemfile
+8. + LICENSE
+9. + Rakefile
+10. + README.md

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,155 @@
+# carddav.rb
+
+A CardDAV client library for Ruby, built on [webdav](https://github.com/thoran/webdav) and implementing RFC 6352. This release ships **Layer 1 (Protocol)** of a planned three-layer ecosystem.
+
+
+## Installation
+
+```
+gem install carddav.rb
+```
+
+Or in your Gemfile:
+
+```ruby
+gem 'carddav.rb'
+```
+
+
+## Concepts
+
+carddav.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 CardDAV verbs, multistatus responses, and namespace-aware navigation accessors. The equivalent of a raw protocol library: it returns CardDAV-typed responses but does not parse vCard 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.address_data` and parsing it with a vCard gem such as `vpim`.
+- **Layer 2 — Objects** (future, `require 'carddav.rb/objects'`). `CardDAV::Card`, `CardDAV::Addressbook`, and `CardDAV::Principal` value objects with vCard parsing and convenience predicates. The principal object will expose `CARDDAV:principal-address` (RFC 6352 §7.1.2) — the vCard that identifies the principal — which Layer 1 cannot surface, since discovery returns bare strings rather than principal objects.
+- **Layer 3 — Queryable** (future, `require 'carddav.rb/queryable'`). A [Namo](https://github.com/thoran/namo)-backed `CardDAV::Query::Addressbook` exposing contacts as queryable rows with derived columns. Its fluent `addressbook-query` filter builder will negotiate `CARDDAV:supported-collation-set` (RFC 6352 §8.3.1) for text-match collations — also reserved until then.
+
+
+## Usage
+
+```ruby
+require 'carddav.rb'
+
+carddav = CardDAV.new('https://carddav.example.com/dav/', username: 'user', password: 'pass')
+```
+
+### Discovery
+
+```ruby
+principal = carddav.current_user_principal
+home = carddav.addressbook_home_set(principal)
+carddav.addressbooks(home).each{|href| puts href}
+```
+
+Each discovery helper defaults its argument to the result of the previous step, so `carddav.addressbooks` alone walks principal → home-set → addressbooks.
+
+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 CardDAV context — e.g. `https://carddav.example.com/dav/` rather than `https://carddav.example.com/`. (RFC 6764 `.well-known/carddav` redirects are not auto-followed for PROPFIND in this release.) You can also override the starting point per call: `carddav.current_user_principal('/dav/')`.
+
+### Querying an addressbook
+
+```ruby
+result = carddav.addressbook_query('/addressbooks/user/contacts/', body: query_xml)
+result.resources.each do |resource|
+  puts resource.href
+  puts resource.address_data  # the raw vCard string
+end
+```
+
+### Fetching specific cards
+
+```ruby
+result = carddav.addressbook_multiget('/addressbooks/user/contacts/', body: multiget_xml)
+```
+
+### Creating an addressbook
+
+```ruby
+carddav.mkcol('/addressbooks/user/new/', body: mkcol_xml)
+```
+
+CardDAV has no `MKCARDDAV` method; an addressbook is created with an **extended MKCOL** (RFC 6352 §6.3.1) — a standard MKCOL carrying a body that sets `resourcetype` to include `<c:addressbook/>`. `CardDAV#mkcol` overrides webdav's zero-body `#mkcol` to accept that optional body.
+
+
+## Methods
+
+### Protocol verbs (RFC 6352)
+
+- `mkcol(path, body:)` — §6.3.1. Create an addressbook collection via extended MKCOL. Returns a `WebDAV::Response`.
+- `addressbook_query(path, body:, depth:)` — §8.6. REPORT with a `<c:addressbook-query>` body. Returns a `CardDAV::MultiStatus`.
+- `addressbook_multiget(path, body:, depth:)` — §8.7. REPORT with a `<c:addressbook-multiget>` body. Returns a `CardDAV::MultiStatus`.
+
+### 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.
+- `addressbook_home_set(principal = current_user_principal)` — returns the addressbook-home-set URL string.
+- `addressbooks(home = addressbook_home_set)` — returns an array of addressbook collection URL strings.
+
+
+## Responses
+
+The REPORT verbs return `CardDAV::MultiStatus`, a type-preserving subclass of `WebDAV::MultiStatus` whose `resources` are `CardDAV::Resource` objects. Each `CardDAV::Resource` adds CardDAV-namespace navigation accessors over the underlying webdav resource:
+
+- `href` — the resource URL
+- `address_data` — the vCard string from `<c:address-data>`
+- `addressbook_description` — `<c:addressbook-description>`
+- `supported_address_data` — `<c:supported-address-data>`
+- `max_resource_size` — `<c:max-resource-size>`
+- `is_addressbook?` — true when `<d:resourcetype>` includes `<c:addressbook/>`
+
+These are strictly navigation: they return raw strings and values, never parsed vCard 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 vCard parsing.** Use a vCard gem (e.g. `vpim`) on `resource.address_data` if you need parsed contacts now.
+- **Basic auth only.** No OAuth.
+- **Not yet verified against a live server.** The integration suite is in place but ships without a committed cassette; supply credentials to record one and exercise it (see below).
+- **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 CardDAV 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`:
+
+```
+CARDDAV_URL='https://your-carddav-host/' \
+CARDDAV_USERNAME='you@example.com' \
+CARDDAV_PASSWORD='app-password' \
+rake
+```
+
+See [test/cassettes/README.md](test/cassettes/README.md) for details.
+
+
+## Contributing
+
+1. Fork it [https://github.com/thoran/carddav.rb/fork](https://github.com/thoran/carddav.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/carddav.rb.gemspec

@@ -0,0 +1,50 @@
+require_relative './lib/CardDAV/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 = 'carddav.rb'
+  spec.version = CardDAV::VERSION
+
+  spec.summary = "A Ruby CardDAV client library."
+  spec.description = "A Ruby CardDAV client library (RFC 6352)."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'https://github.com/thoran/carddav'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 3.2'
+  spec.require_paths = ['lib']
+
+  spec.files = [
+    'carddav.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/CardDAV/MultiStatus.rb

@@ -0,0 +1,33 @@
+# CardDAV/MultiStatus.rb
+# CardDAV::MultiStatus
+
+require 'webdav'
+
+require_relative './Resource'
+
+class CardDAV < WebDAV
+  class MultiStatus < WebDAV::MultiStatus
+
+    private
+
+    def parse_response(response_element)
+      CardDAV::Resource.new(super)
+    end
+
+    # Interim: webdav 0.2.0's parse_properties does `text || to_s`, so a nested
+    # property (resourcetype, current-user-principal, addressbook-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/CardDAV/Resource.rb

@@ -0,0 +1,69 @@
+# CardDAV/Resource.rb
+# CardDAV::Resource
+
+require 'webdav'
+
+class CardDAV < 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 vCard string or value.
+
+    def address_data
+      property(NAMESPACE, 'address-data')
+    end
+
+    def addressbook_description
+      property(NAMESPACE, 'addressbook-description')
+    end
+
+    def supported_address_data
+      property(NAMESPACE, 'supported-address-data')
+    end
+
+    def max_resource_size
+      property(NAMESPACE, 'max-resource-size')
+    end
+
+    # Matches an <addressbook> element (under any namespace prefix) in the
+    # serialised resourcetype, rather than a bare 'addressbook' substring (RFC 6352
+    # §5.2). There is no addressbook-proxy collision as there is for calendars, but
+    # the namespaced-element match is kept for symmetry and safety.
+    def is_addressbook?
+      resource_type.match?(%r{<(?:\w+:)?addressbook(?:\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/CardDAV/VERSION.rb

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

data/lib/carddav.rb

@@ -0,0 +1,138 @@
+# CardDAV.rb
+# CardDAV
+
+require 'webdav'
+
+require_relative './CardDAV/MultiStatus'
+require_relative './CardDAV/Resource'
+require_relative './CardDAV/VERSION'
+
+class CardDAV < WebDAV
+  NAMESPACE = 'urn:ietf:params:xml:ns:carddav'
+  DAV_NAMESPACE = 'DAV:'
+
+  # Protocol verbs (RFC 6352)
+
+  # RFC 6352 §6.3.1. Extended MKCOL — creates an addressbook collection. CardDAV
+  # has no MKCARDDAV: an addressbook is made with a standard MKCOL carrying a body
+  # that sets resourcetype to include <c:addressbook/>. Overrides the inherited
+  # zero-body WebDAV#mkcol to add the optional body (a deliberate widening, not a
+  # shadow). Returns a WebDAV::Response.
+  def mkcol(path, body: nil)
+    response = request(:mkcol, path, body: body)
+    handle_response(response)
+  end
+
+  # RFC 6352 §8.6. REPORT with a <c:addressbook-query> body. The filter grammar
+  # (prop-filter/text-match) is the caller's XML at Layer 1; a fluent filter
+  # builder — which would negotiate CARDDAV:supported-collation-set (§8.3.1) — is
+  # reserved for Layer 3.
+  def addressbook_query(path, body:, depth: '1')
+    report_as_carddav(path, body: body, depth: depth)
+  end
+
+  # RFC 6352 §8.7. REPORT with a <c:addressbook-multiget> body.
+  def addressbook_multiget(path, body:, depth: '0')
+    report_as_carddav(path, body: body, depth: depth)
+  end
+
+  # Discovery helpers. Return paths/strings. An object-oriented discovery API
+  # (Principal/Addressbook objects) is planned. The CARDDAV:principal-address
+  # property (§7.1.2), which identifies a principal's own vCard, is a principal
+  # property — reserved for Layer 2 (Objects) alongside CardDAV::Principal, since
+  # Layer 1 has no discovery path returning a principal Resource to read it from.
+
+  def current_user_principal(path = discovery_path)
+    resource = propfind_as_carddav(path, body: current_user_principal_body, depth: '0').resources.first
+    resource&.then{|r| href_property(r, DAV_NAMESPACE, 'current-user-principal')}
+  end
+
+  def addressbook_home_set(principal = current_user_principal)
+    resource = propfind_as_carddav(principal, body: addressbook_home_set_body, depth: '0').resources.first
+    resource&.then{|r| href_property(r, NAMESPACE, 'addressbook-home-set')}
+  end
+
+  def addressbooks(home = addressbook_home_set)
+    resources = propfind_as_carddav(home, body: addressbooks_body, depth: '1').resources
+    resources.select{|resource| resource.is_addressbook?}.collect{|resource| resource.href}
+  end
+
+  private
+
+  # Send a REPORT and return the CardDAV-typed multistatus rather than the plain
+  # WebDAV one. Constructed from the raw response so the CardDAV resource wrappers
+  # are produced by CardDAV::MultiStatus's overridden parse_response.
+  def report_as_carddav(path, body:, depth:)
+    response = request(:report, path, body: body, headers: {'Depth' => depth})
+    raise WebDAV::Error.new(response) if response.code.to_i >= 400
+    CardDAV::MultiStatus.new(response)
+  end
+
+  # As report_as_carddav, but for PROPFIND. Needed because the inherited #propfind
+  # returns a plain WebDAV::MultiStatus whose resources are bare hashes, not
+  # CardDAV::Resource wrappers. Discovery relies on the wrappers (#is_addressbook?,
+  # #href), so it routes through here.
+  def propfind_as_carddav(path, body:, depth:)
+    response = request(:propfind, path, body: body, headers: {'Depth' => depth})
+    raise WebDAV::Error.new(response) if response.code.to_i >= 400
+    CardDAV::MultiStatus.new(response)
+  end
+
+  # The discovery properties (current-user-principal, addressbook-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
+  # CardDAV 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 addressbook_home_set_body
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <d:propfind xmlns:d="DAV:" xmlns:c="#{NAMESPACE}">
+        <d:prop><c:addressbook-home-set/></d:prop>
+      </d:propfind>
+    XML
+  end
+
+  def addressbooks_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/test/CardDAV/MultiStatus_test.rb

@@ -0,0 +1,61 @@
+# test/CardDAV/MultiStatus_test.rb
+
+require_relative '../helper'
+
+describe CardDAV::MultiStatus do
+  let(:body) do
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <d:multistatus xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:carddav">
+        <d:response>
+          <d:href>/addressbooks/user/contacts/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype>
+                <d:collection/>
+                <c:addressbook/>
+              </d:resourcetype>
+              <c:addressbook-description>Work contacts</c:addressbook-description>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+        <d:response>
+          <d:href>/addressbooks/user/personal/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype>
+                <d:collection/>
+                <c:addressbook/>
+              </d:resourcetype>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+      </d:multistatus>
+    XML
+  end
+  let(:multistatus){CardDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: body))}
+  let(:contacts){multistatus.resources[0]}
+  let(:contacts_properties){contacts.propstats.first[:properties]}
+
+  it "parses one resource per response element" do
+    _(multistatus.resources.size).must_equal 2
+  end
+
+  it "wraps every response as a CardDAV::Resource" do
+    _(multistatus.resources.map(&:class).uniq).must_equal [CardDAV::Resource]
+  end
+
+  it "preserves response order" do
+    _(multistatus.resources.collect(&:href)).must_equal ['/addressbooks/user/contacts/', '/addressbooks/user/personal/']
+  end
+
+  it "keeps a pretty-printed nested property as serialised markup, not whitespace" do
+    _(contacts_properties[CardDAV::DAV_NAMESPACE]['resourcetype']).must_match(%r{<(?:\w+:)?addressbook})
+  end
+
+  it "keeps a flat property's text" do
+    _(contacts_properties[CardDAV::NAMESPACE]['addressbook-description']).must_equal 'Work contacts'
+  end
+end

data/test/CardDAV/Resource_test.rb

@@ -0,0 +1,108 @@
+# test/CardDAV/Resource_test.rb
+
+require_relative '../helper'
+
+describe CardDAV::Resource do
+  let(:addressbook_xml) do
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <d:multistatus xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:carddav">
+        <d:response>
+          <d:href>/addressbooks/user/contacts/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype><d:collection/><c:addressbook/></d:resourcetype>
+              <c:addressbook-description>Work contacts</c:addressbook-description>
+              <c:supported-address-data>
+                <c:address-data-type content-type="text/vcard" version="3.0"/>
+              </c:supported-address-data>
+              <c:max-resource-size>10485760</c:max-resource-size>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+        <d:response>
+          <d:href>/addressbooks/user/contacts/card.vcf</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:getetag>"abc123"</d:getetag>
+              <c:address-data>BEGIN:VCARD</c:address-data>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+        <d:response>
+          <d:href>/addressbooks/user/addressbook-proxy-read/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype><d:collection/><cs:addressbook-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){CardDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: addressbook_xml))}
+  let(:addressbook_resource){multistatus.resources[0]}
+  let(:card_resource){multistatus.resources[1]}
+  let(:proxy_resource){multistatus.resources[2]}
+
+  it "wraps resources as CardDAV::Resource" do
+    _(addressbook_resource).must_be_kind_of CardDAV::Resource
+  end
+
+  it "exposes href" do
+    _(addressbook_resource.href).must_equal '/addressbooks/user/contacts/'
+  end
+
+  it "reads addressbook-description" do
+    _(addressbook_resource.addressbook_description).must_equal 'Work contacts'
+  end
+
+  it "reads address-data" do
+    _(card_resource.address_data).must_equal 'BEGIN:VCARD'
+  end
+
+  it "reads supported-address-data as serialised markup" do
+    _(addressbook_resource.supported_address_data).must_match %r{<(?:\w+:)?address-data-type\b[^>]*content-type=['"]text/vcard['"][^>]*version=['"]3\.0['"]}
+  end
+
+  it "reads max-resource-size" do
+    _(addressbook_resource.max_resource_size).must_equal '10485760'
+  end
+
+  it "identifies an addressbook collection" do
+    _(addressbook_resource.is_addressbook?).must_equal true
+  end
+
+  it "identifies a non-addressbook resource" do
+    _(card_resource.is_addressbook?).must_equal false
+  end
+
+  it "does not mistake an addressbook-proxy collection for an addressbook" do
+    _(proxy_resource.is_addressbook?).must_equal false
+  end
+
+  it "identifies an addressbook from a pretty-printed (indented) resourcetype" do
+    pretty = CardDAV::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:carddav">
+        <d:response>
+          <d:href>/dav/addressbooks/user/x/contacts/</d:href>
+          <d:propstat>
+            <d:prop>
+              <d:resourcetype>
+                <d:collection/>
+                <c:addressbook/>
+              </d:resourcetype>
+            </d:prop>
+            <d:status>HTTP/1.1 200 OK</d:status>
+          </d:propstat>
+        </d:response>
+      </d:multistatus>
+    XML
+    _(pretty.resources.first.is_addressbook?).must_equal true
+  end
+end

data/test/carddav_test.rb

@@ -0,0 +1,167 @@
+# test/carddav_test.rb
+
+require_relative './helper'
+
+describe CardDAV do
+  let(:base_uri){'https://carddav.example.com/'}
+  let(:carddav){CardDAV.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:carddav">
+          <d:response>
+            <d:href>/addressbooks/user/contacts/card.vcf</d:href>
+            <d:propstat>
+              <d:prop>
+                <d:getetag>"abc123"</d:getetag>
+                <c:address-data>BEGIN:VCARD</c:address-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 "#mkcol" do
+    it "returns a Response" do
+      carddav.stub(:request, created_response) do
+        result = carddav.mkcol('/addressbooks/user/new/')
+        _(result).must_be_kind_of WebDAV::Response
+        _(result.code).must_equal 201
+      end
+    end
+  end
+
+  describe "#addressbook_query" do
+    it "returns a CardDAV::MultiStatus" do
+      carddav.stub(:request, multistatus_response) do
+        result = carddav.addressbook_query('/addressbooks/user/contacts/', body: '<c:addressbook-query/>')
+        _(result).must_be_kind_of CardDAV::MultiStatus
+        _(result.resources.first).must_be_kind_of CardDAV::Resource
+      end
+    end
+  end
+
+  describe "#addressbook_multiget" do
+    it "returns a CardDAV::MultiStatus" do
+      carddav.stub(:request, multistatus_response) do
+        result = carddav.addressbook_multiget('/addressbooks/user/contacts/', body: '<c:addressbook-multiget/>')
+        _(result).must_be_kind_of CardDAV::MultiStatus
+      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
+      carddav.stub(:request, response) do
+        _(carddav.current_user_principal).must_equal '/dav/principals/user/abc/'
+      end
+    end
+
+    it "PROPFINDs the base URL's path by default, not '/'" do
+      dav = CardDAV.new('https://carddav.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
+      carddav.stub(:request, pretty) do
+        _(carddav.current_user_principal).must_equal '/dav/principals/user/abc/'
+      end
+    end
+  end
+
+  describe "#addressbook_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:carddav">
+          <d:response>
+            <d:href>/dav/principals/user/abc/</d:href>
+            <d:propstat>
+              <d:prop><c:addressbook-home-set><d:href>/dav/addressbooks/user/abc/</d:href></c:addressbook-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
+      carddav.stub(:request, response) do
+        _(carddav.addressbook_home_set('/dav/principals/user/abc/')).must_equal '/dav/addressbooks/user/abc/'
+      end
+    end
+  end
+
+  describe "#addressbooks" 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:carddav" xmlns:cs="http://calendarserver.org/ns/">
+          <d:response>
+            <d:href>/dav/addressbooks/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/addressbooks/user/abc/contacts/</d:href>
+            <d:propstat><d:prop><d:resourcetype><d:collection/><c:addressbook/></d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>
+          </d:response>
+          <d:response>
+            <d:href>/dav/addressbooks/user/abc/proxy/</d:href>
+            <d:propstat><d:prop><d:resourcetype><d:collection/><cs:addressbook-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 addressbook collection hrefs as bare URL strings" do
+      carddav.stub(:request, response) do
+        _(carddav.addressbooks('/dav/addressbooks/user/abc/')).must_equal ['/dav/addressbooks/user/abc/contacts/']
+      end
+    end
+  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/carddav'
+
+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 'CardDAV integration' do
+  let(:carddav){carddav_client}
+
+  let(:contacts_query_body) do
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <c:addressbook-query xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:carddav">
+        <d:prop>
+          <d:getetag/>
+          <c:address-data/>
+        </d:prop>
+        <c:filter>
+          <c:prop-filter name="FN">
+            <c:text-match collation="i;unicode-casemap" match-type="contains">a</c:text-match>
+          </c:prop-filter>
+        </c:filter>
+      </c:addressbook-query>
+    XML
+  end
+
+  it "discovers principal, home-set and addressbooks as bare URL strings" do
+    with_carddav_cassette('discovery') do
+      principal = carddav.current_user_principal
+      _(principal).must_be_kind_of String
+      _(principal).wont_include '<'
+      home = carddav.addressbook_home_set(principal)
+      _(home).must_be_kind_of String
+      _(home).wont_include '<'
+      addressbooks = carddav.addressbooks(home)
+      _(addressbooks).must_be_kind_of Array
+      addressbooks.each do |href|
+        _(href).must_be_kind_of String
+        _(href).wont_include '<'
+      end
+    end
+  end
+
+  it "queries the first addressbook and returns CardDAV resources" do
+    with_carddav_cassette('addressbook_query') do
+      addressbook = carddav.addressbooks.first
+      skip 'no addressbooks on this account' unless addressbook
+      result = carddav.addressbook_query(addressbook, body: contacts_query_body)
+      _(result).must_be_kind_of CardDAV::MultiStatus
+      result.resources.each{|resource| _(resource).must_be_kind_of CardDAV::Resource}
+    end
+  end
+end

data/test/vcr_helper.rb

@@ -0,0 +1,55 @@
+# test/vcr_helper.rb
+
+require 'uri'
+require 'vcr'
+
+EXAMPLE_CARDDAV_URL = 'https://carddav.example.com/dav/'
+CARDDAV_URL = ENV.fetch('CARDDAV_URL', EXAMPLE_CARDDAV_URL)
+
+# Replaces the account-identifier segment in CardDAV collection paths (e.g.
+# /principals/user/<id>/ or /addressbooks/user/<id>/) with a fixed placeholder, so
+# a committed cassette does not expose an account-specific id. The collection name
+# after the id (an addressbook name, say) is preserved. Covers the common
+# collection/realm/id layout; the credential filters still scrub email-style ids.
+ACCOUNT_PATH = %r{(/(?:principals|addressbooks)/[^/]+/)[^/]+/}
+
+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_CARDDAV_URL).host){URI(ENV['CARDDAV_URL']).host if ENV['CARDDAV_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('<CARDDAV_USERNAME>'){ENV['CARDDAV_USERNAME']}
+  config.filter_sensitive_data('<CARDDAV_PASSWORD>'){ENV['CARDDAV_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 carddav_client
+  CardDAV.new(
+    CARDDAV_URL,
+    username: ENV.fetch('CARDDAV_USERNAME', 'recorded'),
+    password: ENV.fetch('CARDDAV_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_carddav_cassette(name)
+  cassette = File.join(VCR.configuration.cassette_library_dir, "#{name}.yml")
+  unless File.exist?(cassette) || ENV['CARDDAV_USERNAME']
+    raise Minitest::Skip, "no cassette '#{name}.yml' and CARDDAV_USERNAME unset; export CARDDAV_URL/CARDDAV_USERNAME/CARDDAV_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 an addressbooks collection, keeping the addressbook name" do
+    _(anonymise_account_path('/dav/addressbooks/user/abc123/contacts/')).must_equal '/dav/addressbooks/user/anon/contacts/'
+  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/addressbooks/user/abc123/</d:href>'
+    _(anonymise_account_path(body)).must_equal '<d:href>/dav/addressbooks/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,140 @@
+--- !ruby/object:Gem::Specification
+name: carddav.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 CardDAV client library (RFC 6352).
+email: code@thoran.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- carddav.rb.gemspec
+- lib/CardDAV/MultiStatus.rb
+- lib/CardDAV/Resource.rb
+- lib/CardDAV/VERSION.rb
+- lib/carddav.rb
+- test/CardDAV/MultiStatus_test.rb
+- test/CardDAV/Resource_test.rb
+- test/carddav_test.rb
+- test/helper.rb
+- test/integration_test.rb
+- test/vcr_helper.rb
+- test/vcr_helper_test.rb
+homepage: https://github.com/thoran/carddav
+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.10
+specification_version: 4
+summary: A Ruby CardDAV client library.
+test_files: []