carddav.rb 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9430d7a069267b260526ee0cfc83d48015b5ed3246d9cbb665929915d1146e8a
-  data.tar.gz: 312d5939b30b496bcf96c747ed1e3aea39cafd53225dde43668c4bbe865e71b9
+  metadata.gz: 6f9a882a50cfe2e0a7b002c79b037846dbd1c6c4a597c4b96c5391d523597bc4
+  data.tar.gz: 86b1b9f289f156b3cf72f3016abf8557cf668f3791be5dee1c390b21db0bd412
 SHA512:
-  metadata.gz: ab268a645a1fb8769ff36517f908469655d2407c553271892c220b90f303a61120824542a2505da6b6b51043b5c8e873a282da6541547bfee97baf0fdac41b33
-  data.tar.gz: 131b86e9cdfea2c4bf6892effb27d1f8d5386a50721a812d2c65891b35ddb10f8f9c710afc2c075836261b86f94ac874ff33cf9d614429968b1812786547423e
+  metadata.gz: 013f037d7b799411fc78fbac0111ba6accf852bea198d77d88be73ff8c4884300bf17b298f32c6a49403e6294124365c972806410b28bbff8af345bad7c299e8
+  data.tar.gz: 22657fdcc2eec3bce60c230f749ff167995001449f6667a2ce8628f26c7d84afa7f066d5f85cc5651cec504a354b7f6e4d0e733541e58c9703d09f7a3e7c0cf4

data/CHANGELOG

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## 20260708
+
+0.1.0: Querying without a body.
+
+1. ~ CardDAV#addressbook_query: body: now optional; a filterless prop-request body is constructed from properties: (default: getetag, address-data) when absent.
+2. ~ CardDAV#addressbook_multiget: body: now optional; constructed from hrefs: and properties: when absent.
+3. + CardDAV::DEFAULT_REPORT_PROPERTIES
+4. + CardDAV::DAV_PROPERTY_NAMES
+5. + CardDAV#addressbook_query_body
+6. + CardDAV#addressbook_multiget_body
+7. + CardDAV#property_element
+8. + CardDAV#property_elements
+9. + CardDAV#href_elements
+
 ## 20260623
 
 0.0.0: Initial release.

data/README.md

@@ -48,7 +48,12 @@ Discovery begins by PROPFINDing the **path of the base URL**. Many servers do no
 ### Querying an addressbook
 
 ```ruby
+# Every card in the addressbook — no caller XML needed.
+result = carddav.addressbook_query('/addressbooks/user/contacts/')
+
+# Or supply a hand-rolled filter XML body verbatim.
 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
@@ -58,7 +63,7 @@ end
 ### Fetching specific cards
 
 ```ruby
-result = carddav.addressbook_multiget('/addressbooks/user/contacts/', body: multiget_xml)
+result = carddav.addressbook_multiget('/addressbooks/user/contacts/', hrefs: ['/addressbooks/user/contacts/a.vcf'])
 ```
 
 ### Creating an addressbook
@@ -75,8 +80,8 @@ CardDAV has no `MKCARDDAV` method; an addressbook is created with an **extended
 ### 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`.
+- `addressbook_query(path, body: nil, properties:, depth:)` — §8.6. REPORT with a `<c:addressbook-query>` body. Returns a `CardDAV::MultiStatus`. `body:` is optional: when omitted, a filterless prop-request body is built from `properties:` (default `%w{getetag address-data}`), so the common "return every card" query needs no caller XML. Pass `body:` to supply a hand-rolled filter verbatim.
+- `addressbook_multiget(path, hrefs:, body: nil, properties:, depth:)` — §8.7. REPORT with a `<c:addressbook-multiget>` body. Returns a `CardDAV::MultiStatus`. `body:` is optional: when omitted, a body is built from `hrefs:` (the cards to fetch) and `properties:`. Raises `ArgumentError` if neither `body:` nor `hrefs:` is given.
 
 ### Discovery
 
@@ -106,7 +111,6 @@ 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.
 
 
@@ -123,10 +127,10 @@ 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.
+via [VCR](https://github.com/vcr/vcr): they replay host- and credential-scrubbed
+cassettes committed under `test/cassettes/` (`discovery.yml`, `addressbook_query.yml`),
+so discovery and query have round-tripped against a live server and the default
+suite stays green offline. Supply credentials to re-record against your own account.
 
 To record against a live account, supply the server and credentials through the
 environment and run `rake`:

data/lib/CardDAV/VERSION.rb

@@ -4,5 +4,5 @@
 class WebDAV; end
 
 class CardDAV < WebDAV
-  VERSION = '0.0.0'
+  VERSION = '0.1.0'
 end

data/lib/carddav.rb

@@ -8,8 +8,10 @@ require_relative './CardDAV/Resource'
 require_relative './CardDAV/VERSION'
 
 class CardDAV < WebDAV
-  NAMESPACE = 'urn:ietf:params:xml:ns:carddav'
   DAV_NAMESPACE = 'DAV:'
+  DAV_PROPERTY_NAMES = %w{displayname getcontenttype getetag getlastmodified resourcetype}
+  DEFAULT_REPORT_PROPERTIES = %w{getetag address-data}
+  NAMESPACE = 'urn:ietf:params:xml:ns:carddav'
 
   # Protocol verbs (RFC 6352)
 
@@ -23,17 +25,20 @@ class CardDAV < WebDAV
     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
+  # RFC 6352 §8.6. REPORT with a <c:addressbook-query> body. When no body is
+  # given, a filterless prop-request body is constructed from properties:, so the
+  # common "return every card" query needs no caller XML. The filter grammar
+  # (prop-filter/text-match) remains 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)
+  def addressbook_query(path, body: nil, properties: DEFAULT_REPORT_PROPERTIES, depth: '1')
+    report_as_carddav(path, body: body || addressbook_query_body(properties), 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)
+  # RFC 6352 §8.7. REPORT with a <c:addressbook-multiget> body. When no body is
+  # given, one is constructed from hrefs: and properties:.
+  def addressbook_multiget(path, hrefs: nil, body: nil, properties: DEFAULT_REPORT_PROPERTIES, depth: '0')
+    report_as_carddav(path, body: body || addressbook_multiget_body(hrefs, properties), depth: depth)
   end
 
   # Discovery helpers. Return paths/strings. An object-oriented discovery API
@@ -135,4 +140,42 @@ class CardDAV < WebDAV
       </d:propfind>
     XML
   end
+
+  # Resolves a bare property name to its namespace prefix: the known DAV live
+  # properties get d:, everything else is assumed CardDAV and gets c:. A name
+  # that already carries a prefix (contains a colon, e.g. 'd:sync-token') is
+  # emitted verbatim — the escape hatch for DAV properties outside the known set,
+  # and the growth path towards namespace-qualified property names.
+  def property_element(name)
+    return "<#{name}/>" if name.include?(':')
+    "<#{DAV_PROPERTY_NAMES.include?(name) ? 'd' : 'c'}:#{name}/>"
+  end
+
+  def property_elements(properties)
+    properties.collect{|name| property_element(name)}.join
+  end
+
+  def href_elements(hrefs)
+    hrefs.collect{|href| "<d:href>#{href}</d:href>"}.join
+  end
+
+  def addressbook_query_body(properties)
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <c:addressbook-query xmlns:d="DAV:" xmlns:c="#{NAMESPACE}">
+        <d:prop>#{property_elements(properties)}</d:prop>
+      </c:addressbook-query>
+    XML
+  end
+
+  def addressbook_multiget_body(hrefs, properties)
+    raise ArgumentError, 'addressbook_multiget requires hrefs: when no body: is given' unless hrefs
+    <<~XML
+      <?xml version="1.0" encoding="UTF-8"?>
+      <c:addressbook-multiget xmlns:d="DAV:" xmlns:c="#{NAMESPACE}">
+        <d:prop>#{property_elements(properties)}</d:prop>
+        #{href_elements(hrefs)}
+      </c:addressbook-multiget>
+    XML
+  end
 end

data/test/carddav_test.rb

@@ -164,4 +164,53 @@ describe CardDAV do
       end
     end
   end
+
+  describe "#addressbook_query without a body" do
+    it "constructs a filterless prop-request body from the default properties" do
+      captured = nil
+      responder = ->(verb, path, **kw){captured = kw[:body]; multistatus_response}
+      carddav.stub(:request, responder) do
+        carddav.addressbook_query('/addressbooks/user/contacts/')
+      end
+      _(captured).must_include '<c:addressbook-query'
+      _(captured).must_include '<d:getetag/>'
+      _(captured).must_include '<c:address-data/>'
+      _(captured).wont_include '<c:filter>'
+    end
+
+    it "uses a supplied body verbatim" do
+      captured = nil
+      responder = ->(verb, path, **kw){captured = kw[:body]; multistatus_response}
+      carddav.stub(:request, responder) do
+        carddav.addressbook_query('/addressbooks/user/contacts/', body: '<custom/>')
+      end
+      _(captured).must_equal '<custom/>'
+    end
+
+    it "emits a prefixed property name verbatim rather than re-namespacing it" do
+      captured = nil
+      responder = ->(verb, path, **kw){captured = kw[:body]; multistatus_response}
+      carddav.stub(:request, responder) do
+        carddav.addressbook_query('/addressbooks/user/contacts/', properties: %w{d:sync-token address-data})
+      end
+      _(captured).must_include '<d:sync-token/>'
+      _(captured).wont_include '<c:d:sync-token/>'
+    end
+  end
+
+  describe "#addressbook_multiget without a body" do
+    it "constructs a multiget body from hrefs" do
+      captured = nil
+      responder = ->(verb, path, **kw){captured = kw[:body]; multistatus_response}
+      carddav.stub(:request, responder) do
+        carddav.addressbook_multiget('/addressbooks/user/contacts/', hrefs: ['/addressbooks/user/contacts/a.vcf'])
+      end
+      _(captured).must_include '<c:addressbook-multiget'
+      _(captured).must_include '<d:href>/addressbooks/user/contacts/a.vcf</d:href>'
+    end
+
+    it "requires hrefs when no body is given" do
+      _{carddav.addressbook_multiget('/addressbooks/user/contacts/')}.must_raise ArgumentError
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carddav.rb
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - thoran
@@ -134,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.15
 specification_version: 4
 summary: A Ruby CardDAV client library.
 test_files: []