webdav 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 282fc0b7d1998d1002ce33a6a590d1b42b352d7918ed41c001a75fac0f473bfa
-  data.tar.gz: 3c61685c5a13c143db955a376985b175fa7799efe13e986e8a7044bed8c27f2a
+  metadata.gz: 112d0cec672b4fba93b1b1b356ba14d148982ae94b9063c7df8ff0116ab2f775
+  data.tar.gz: 0e94db83b43f2dd4efed30a214931086d29278fb5eab5dc3cc0b4cecf1fdb051
 SHA512:
-  metadata.gz: ec83adb732f914c8786003133ecdc4e9ebbc71a42e3d2e0b59d1b76c1b21e9ab48ffc5af3cea08a193676e71591e5c850da2af57977d3a12c354a7c32cc0b04d
-  data.tar.gz: 761abe1872f20ca61c80ba3468709da9dea781116866c7ece0954cd67ddfdb65011981c859ffd15ec7bb79c7a9849be2db36c19e6b8a6ea56c55d7f4cef33993
+  metadata.gz: 1684e452204e2e57250698d6acd09d7603bd51fcaeea1ddb679edf7bb2d80ae7310ad122ffb3917b5d9fa1bfe0e6e4952e4c79c5db74068a554a73c4d793a165
+  data.tar.gz: 686bf1a9d4729235642d694379663ee5e9711291d5d524013a22ce05c10aac66b4235477cb8085e5208316830793f4cc58ef2ae6c26308ec7bb13ceacad70fc9

data/CHANGELOG

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## 20260522
+
+0.2.0: Rewrite MultiStatus#parse; align dependencies with http.rb 1.0.0; document WebDAV concepts.
+
+1. ~ WebDAV::MultiStatus#parse: Walk propstat blocks individually; preserve per-propstat status; detect response-level status (for COPY/MOVE/DELETE); preserve namespace URIs on properties. Now private; resources remains the public accessor.
+2. ~ WebDAV::MultiStatus resource shape: Properties move from flat hash keyed by local name to nested hash keyed by namespace URI then local name. Resources now have :propstats (array of {properties:, status:}) and :status (response-level, may be nil) instead of a single :properties and :status pair.
+3. ~ test/WebDAV/MultiStatus_test.rb: Update existing tests for new shape; + tests for per-propstat status, response-level status, namespace preservation, and same-local-name collision across namespaces.
+4. ~ README.md: Document new MultiStatus#resources shape, with paired wire-XML and parsed-Ruby examples for both PROPFIND and collection-cascade Multi-Status; + WebDAV::Response wire example; + Concepts section (properties vs content, collections and the trailing slash, why 207 Multi-Status exists, namespaces).
+5. ~ webdav.gemspec: required_ruby_version />= 2.7/>= 3.2/; http.rb dependency /[]/['~> 1.0']/; minitest pin /'~> 5.27'/'~> 6.0'/; + minitest-mock (minitest 6 split it out).
+6. ~ WebDAV::VERSION: /0.1.2/0.2.0/
+7. ~ CHANGELOG: + 0.2.0 entry
+
 ## 20260520
 
 0.1.2: Fix Response#success? to return true only for 2xx responses.

data/README.md

@@ -30,7 +30,14 @@ dav = WebDAV.new('https://dav.example.com/files/', username: 'user', password: '
 response = dav.propfind('/', depth: '1')
 response.resources.each do |resource|
   puts resource[:href]
-  puts resource[:properties]
+  resource[:propstats].each do |propstat|
+    puts propstat[:status]
+    propstat[:properties].each do |namespace, properties|
+      properties.each do |name, value|
+        puts "  #{namespace} #{name} = #{value}"
+      end
+    end
+  end
 end
 ```
 
@@ -92,6 +99,27 @@ end
 ```
 
 
+## Concepts
+
+WebDAV extends HTTP with a few ideas that don't have direct REST analogues. The ones below explain why the API is shaped the way it is.
+
+### Properties vs content
+
+A WebDAV resource has two faces. **Content** is what GET returns — the bytes of the file. **Properties** are metadata associated with the resource: display name, creation date, lock state, content type, and any custom properties the server defines. The same URL identifies both, but different verbs reach them — GET/PUT for content, PROPFIND/PROPPATCH for properties.
+
+### Collections and the trailing slash
+
+A **collection** is WebDAV's directory: a resource that contains other resources. MKCOL creates one. By convention, collection URLs end in `/` and ordinary resources don't; servers that care about the distinction will redirect or 404 if you get it wrong. The distinction matters because COPY, MOVE, and DELETE on a collection cascade to its children — which is also why those verbs can return 207 Multi-Status when children succeed and fail independently.
+
+### Why 207 Multi-Status exists
+
+HTTP assumes one request maps to one status. WebDAV breaks that assumption: PROPFIND on a folder asks about many resources at once; COPY of a tree may succeed on some children and fail on others. The 207 Multi-Status response code says "the request touched many things; here are per-thing outcomes." The XML body carries one `<d:response>` per affected resource. This gem returns those as `WebDAV::MultiStatus`; the `resources` accessor exposes the per-resource detail (see [Responses](#responses)).
+
+### Namespaces
+
+WebDAV properties are XML elements, and XML elements belong to namespaces. The core RFC 4918 properties live in the `DAV:` namespace. Extensions — CalDAV (`urn:ietf:params:xml:ns:caldav`), CardDAV, Exchange, ownCloud, custom server vocabularies — each define their own. Properties from different namespaces can share local names (`<d:displayname>` and `<x:displayname>` are different properties), so the parser preserves namespace URIs as the outer key in the properties hash.
+
+
 ## Methods
 
 WebDAV extends HTTP with additional methods for distributed authoring. This gem provides all the methods defined in RFC 4918 ("HTTP Extensions for Web Distributed Authoring and Versioning") and the REPORT method from RFC 3253 ("Versioning Extensions to WebDAV"), which is essential for CalDAV and CardDAV queries.
@@ -149,12 +177,108 @@ All methods return either a `WebDAV::Response` or a `WebDAV::MultiStatus`.
 - `content_type`
 - `success?`
 
+A `GET` response on the wire:
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/plain
+Content-Length: 13
+ETag: "5d41402a"
+
+Hello, world.
+```
+
+Parses to:
+
+```ruby
+response.code          # => 200
+response.message       # => "OK"
+response.body          # => "Hello, world."
+response.etag          # => "\"5d41402a\""
+response.content_type  # => "text/plain"
+response.success?      # => true
+```
+
 `WebDAV::MultiStatus` additionally provides:
 
 - `resources` — an array of hashes, each with:
-  - `href`
-  - `properties`
-  - `status`
+  - `href` — the resource URL
+  - `propstats` — an array of `{properties:, status:}` hashes (PROPFIND / PROPPATCH / REPORT). May be empty when the response carries a response-level status instead.
+  - `status` — the response-level status string (COPY / MOVE / DELETE). `nil` when the response has propstats instead.
+
+Within a propstat, `properties` is a nested hash keyed first by XML namespace URI, then by local name. For example, a CalDAV calendar property appears as `propstat[:properties]['urn:ietf:params:xml:ns:caldav']['calendar-data']` and a DAV property as `propstat[:properties]['DAV:']['getetag']`. Keeping the namespace explicit prevents collisions between properties from different namespaces that share a local name.
+
+A PROPFIND response — properties grouped by namespace, status per propstat, response-level status `nil`. The wire XML:
+
+```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>/calendar/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:propstat>
+      <d:prop>
+        <d:getctag/>
+      </d:prop>
+      <d:status>HTTP/1.1 404 Not Found</d:status>
+    </d:propstat>
+  </d:response>
+</d:multistatus>
+```
+
+Parses to:
+
+```ruby
+[
+  {
+    href: '/calendar/event.ics',
+    propstats: [
+      {
+        properties: {
+          'DAV:' => {'getetag' => '"abc123"'},
+          'urn:ietf:params:xml:ns:caldav' => {'calendar-data' => 'BEGIN:VCALENDAR...'}
+        },
+        status: 'HTTP/1.1 200 OK'
+      },
+      {
+        properties: {'DAV:' => {'getctag' => ''}},
+        status: 'HTTP/1.1 404 Not Found'
+      }
+    ],
+    status: nil
+  }
+]
+```
+
+A COPY / MOVE / DELETE on a collection where a child resource failed — the server returns 207 Multi-Status with one `<d:response>` per affected child, each carrying a response-level status rather than propstats. Single-resource lifecycle operations don't go through this path; they return a plain `WebDAV::Response` with the status code as the whole story. The wire XML:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<d:multistatus xmlns:d="DAV:">
+  <d:response>
+    <d:href>/dir/file.txt</d:href>
+    <d:status>HTTP/1.1 403 Forbidden</d:status>
+  </d:response>
+</d:multistatus>
+```
+
+Parses to:
+
+```ruby
+[
+  {
+    href: '/dir/file.txt',
+    propstats: [],
+    status: 'HTTP/1.1 403 Forbidden'
+  }
+]
+```
 
 
 ## Errors

data/lib/WebDAV/MultiStatus.rb

@@ -9,26 +9,48 @@ class WebDAV
   class MultiStatus < Response
     attr_reader :resources
 
-    def parse
-      doc = REXML::Document.new(body)
-      resources = []
-      doc.elements.each('//d:response') do |resp|
-        href = resp.elements['.//d:href']&.text
-        properties = {}
-        resp.elements.each('.//d:prop/*') do |prop|
-          properties[prop.name] = prop.text || prop.to_s
-        end
-        status = resp.elements['.//d:status']&.text
-        resources << {href: href, properties: properties, status: status}
-      end
-      resources
-    end
-
     private
 
     def initialize(response)
       super
       @resources = parse
     end
+
+    def parse
+      doc = REXML::Document.new(body)
+      doc.elements.collect('//d:response'){|response_element| parse_response(response_element)}
+    end
+
+    def parse_response(response_element)
+      {
+        href: response_element.elements['d:href']&.text,
+        propstats: parse_propstats(response_element),
+        status: parse_response_status(response_element)
+      }
+    end
+
+    def parse_propstats(response_element)
+      response_element.elements.collect('d:propstat'){|propstat_element| parse_propstat(propstat_element)}
+    end
+
+    def parse_propstat(propstat_element)
+      {
+        properties: parse_properties(propstat_element.elements['d:prop']),
+        status: propstat_element.elements['d:status']&.text
+      }
+    end
+
+    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] ||= {}
+        result[property_element.namespace][property_element.name] = property_element.text || property_element.to_s
+      end
+    end
+
+    def parse_response_status(response_element)
+      return nil if response_element.elements['d:propstat']
+      response_element.elements['d:status']&.text
+    end
   end
 end

data/lib/WebDAV/VERSION.rb

@@ -2,5 +2,5 @@
 # WebDAV::VERSION
 
 class WebDAV
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/test/WebDAV/MultiStatus_test.rb

@@ -67,13 +67,142 @@ describe WebDAV::MultiStatus do
       _(response.resources[1][:href]).must_equal '/dav/calendars/user/test/calendar2/'
     end
 
-    it "extracts properties from each resource" do
-      _(response.resources[0][:properties]['displayname']).must_equal 'Work'
-      _(response.resources[1][:properties]['displayname']).must_equal 'Personal'
+    it "extracts properties from each propstat, keyed by namespace then local name" do
+      _(response.resources[0][:propstats][0][:properties]['DAV:']['displayname']).must_equal 'Work'
+      _(response.resources[1][:propstats][0][:properties]['DAV:']['displayname']).must_equal 'Personal'
     end
 
-    it "extracts status from each resource" do
-      _(response.resources[0][:status]).must_equal 'HTTP/1.1 200 OK'
+    it "extracts per-propstat status" do
+      _(response.resources[0][:propstats][0][:status]).must_equal 'HTTP/1.1 200 OK'
+    end
+
+    it "leaves response-level status nil when propstats are present" do
+      _(response.resources[0][:status]).must_be_nil
+    end
+  end
+
+  describe "with multiple propstats per response" do
+    let(:mixed_status_xml) do
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <d:multistatus xmlns:d="DAV:">
+          <d:response>
+            <d:href>/calendar/</d:href>
+            <d:propstat>
+              <d:prop>
+                <d:displayname>Work</d:displayname>
+              </d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+            <d:propstat>
+              <d:prop>
+                <d:getctag/>
+              </d:prop>
+              <d:status>HTTP/1.1 404 Not Found</d:status>
+            </d:propstat>
+          </d:response>
+        </d:multistatus>
+      XML
+    end
+
+    let(:mixed_response){WebDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: mixed_status_xml))}
+
+    it "preserves each propstat as a separate entry" do
+      _(mixed_response.resources[0][:propstats].length).must_equal 2
+    end
+
+    it "keeps the 200 propstat's properties under its own status" do
+      successful_propstat = mixed_response.resources[0][:propstats][0]
+      _(successful_propstat[:status]).must_equal 'HTTP/1.1 200 OK'
+      _(successful_propstat[:properties]['DAV:']['displayname']).must_equal 'Work'
+    end
+
+    it "keeps the 404 propstat's properties under its own status" do
+      missing_propstat = mixed_response.resources[0][:propstats][1]
+      _(missing_propstat[:status]).must_equal 'HTTP/1.1 404 Not Found'
+      _(missing_propstat[:properties]['DAV:']).must_include 'getctag'
+    end
+  end
+
+  describe "with response-level status (COPY/MOVE/DELETE)" do
+    let(:response_level_xml) do
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <d:multistatus xmlns:d="DAV:">
+          <d:response>
+            <d:href>/dir/file.txt</d:href>
+            <d:status>HTTP/1.1 403 Forbidden</d:status>
+          </d:response>
+        </d:multistatus>
+      XML
+    end
+
+    let(:response_level_response){WebDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: response_level_xml))}
+
+    it "populates the response-level status" do
+      _(response_level_response.resources[0][:status]).must_equal 'HTTP/1.1 403 Forbidden'
+    end
+
+    it "leaves propstats empty" do
+      _(response_level_response.resources[0][:propstats]).must_equal []
+    end
+  end
+
+  describe "with multiple namespaces" do
+    let(:multi_namespace_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>/calendar/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(:multi_namespace_response){WebDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: multi_namespace_xml))}
+
+    it "groups DAV properties under the DAV: namespace" do
+      _(multi_namespace_response.resources[0][:propstats][0][:properties]['DAV:']['getetag']).must_equal '"abc123"'
+    end
+
+    it "groups CalDAV properties under the CalDAV namespace" do
+      _(multi_namespace_response.resources[0][:propstats][0][:properties]['urn:ietf:params:xml:ns:caldav']['calendar-data']).must_equal 'BEGIN:VCALENDAR'
+    end
+  end
+
+  describe "with the same local name in different namespaces" do
+    let(:collision_xml) do
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <d:multistatus xmlns:d="DAV:" xmlns:x="http://example.com/custom">
+          <d:response>
+            <d:href>/file.txt</d:href>
+            <d:propstat>
+              <d:prop>
+                <d:displayname>From DAV</d:displayname>
+                <x:displayname>From custom</x:displayname>
+              </d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+          </d:response>
+        </d:multistatus>
+      XML
+    end
+
+    let(:collision_response){WebDAV::MultiStatus.new(MockResponse.new(code: '207', message: 'Multi-Status', body: collision_xml))}
+
+    it "keeps both without collision" do
+      properties = collision_response.resources[0][:propstats][0][:properties]
+      _(properties['DAV:']['displayname']).must_equal 'From DAV'
+      _(properties['http://example.com/custom']['displayname']).must_equal 'From custom'
     end
   end
 

data/webdav.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.homepage = 'https://github.com/thoran/webdav'
   spec.license = 'MIT'
 
-  spec.required_ruby_version = '>= 2.7'
+  spec.required_ruby_version = '>= 3.2'
   spec.require_paths = ['lib']
 
   spec.files = [
@@ -37,12 +37,13 @@ Gem::Specification.new do |spec|
   ].flatten
 
   spec.dependencies = [
-    ['http.rb'],
+    ['http.rb', '~> 1.0'],
     ['rexml']
   ]
 
   spec.development_dependencies = [
-    ['minitest', '~> 5.27'],
+    ['minitest', '~> 6.0'],
+    ['minitest-mock'],
     ['rake']
   ]
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: webdav
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - thoran
@@ -13,16 +13,16 @@ dependencies:
   name: http.rb
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rexml
   requirement: !ruby/object:Gem::Requirement
@@ -43,14 +43,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.27'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.27'
+        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
@@ -104,7 +118,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="