protocol-caldav 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b119c6f8e0f3fa86e9ca3606eea776a73cd872049fac80674a4f8ffba0bfaf4
+  data.tar.gz: 7f4d5929f5c6227694375e5ec77130b18e7b7b72e72bc01f67c633a63f73aa3d
+SHA512:
+  metadata.gz: 4c842735fafa37d1d224ac8d8a48ee18237897baada5e8dc755a327bc0c9e67d29a4060ca9ca0f1d1cd435ec7d701462cdbe84c145579e720d1dad85b32031ce
+  data.tar.gz: b6187b613165259a2c277483f4ed46b404d103618545ff6b1c7caa77481428b96402c970711e70c9ea6db1e5bc8cbd5b70e942859a2d533dd2cb6ac9d7b8a9aa

data/lib/protocol/caldav/collection.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    class Collection
+      attr_reader :path, :type, :displayname, :description, :color, :props
+
+      def initialize(path:, type: :collection, displayname: nil, description: nil, color: nil, props: {})
+        @path = path
+        @type = type
+        @displayname = displayname
+        @description = description
+        @color = color
+        @props = props || {}
+      end
+
+      def update_attrs(updates)
+        @displayname = updates[:displayname] if updates.key?(:displayname)
+        @description = updates[:description] if updates.key?(:description)
+        @color = updates[:color] if updates.key?(:color)
+        @props = (@props || {}).merge(updates[:props]) if updates.key?(:props)
+        self
+      end
+
+      def to_propfind_xml
+        prop_lines = []
+
+        if @type == :calendar
+          prop_lines << '<d:resourcetype><d:collection/><c:calendar/></d:resourcetype>'
+        elsif @type == :addressbook
+          prop_lines << '<d:resourcetype><d:collection/><cr:addressbook/></d:resourcetype>'
+        else
+          prop_lines << '<d:resourcetype><d:collection/></d:resourcetype>'
+        end
+
+        prop_lines << "<d:displayname>#{Xml.escape(@displayname)}</d:displayname>" if @displayname
+        prop_lines << "<c:calendar-description>#{Xml.escape(@description)}</c:calendar-description>" if @description
+        prop_lines << "<x:calendar-color>#{Xml.escape(@color)}</x:calendar-color>" if @color
+
+        item_etags = @path.storage_class.list_items(@path.to_s).map { |_, data| data[:etag] }
+        ctag = CTag.compute(
+          path: @path.to_s,
+          displayname: @displayname,
+          description: @description,
+          color: @color,
+          item_etags: item_etags
+        )
+        prop_lines << "<cs:getctag>#{ctag}</cs:getctag>"
+        prop_lines << "<d:sync-token>http://caldav.local/sync/#{ctag}</d:sync-token>"
+
+        if @type == :calendar
+          prop_lines << '<c:supported-calendar-component-set><c:comp name="VEVENT"/><c:comp name="VTODO"/><c:comp name="VJOURNAL"/></c:supported-calendar-component-set>'
+        end
+
+        @props.each do |key, value|
+          prop_lines << "<#{key}>#{Xml.escape(value)}</#{key}>"
+        end
+
+        <<~XML
+          <d:response>
+            <d:href>#{Xml.escape(@path.to_s)}</d:href>
+            <d:propstat>
+              <d:prop>
+                #{prop_lines.join("\n          ")}
+              </d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+          </d:response>
+        XML
+      end
+
+      def to_propname_xml
+        names = ['<d:resourcetype/>']
+        names << '<d:displayname/>' if @displayname
+        names << '<c:calendar-description/>' if @description
+        names << '<x:calendar-color/>' if @color
+        names << '<cs:getctag/>'
+        names << '<d:sync-token/>'
+        names << '<c:supported-calendar-component-set/>' if @type == :calendar
+
+        <<~XML
+          <d:response>
+            <d:href>#{Xml.escape(@path.to_s)}</d:href>
+            <d:propstat>
+              <d:prop>
+                #{names.join("\n          ")}
+              </d:prop>
+              <d:status>HTTP/1.1 200 OK</d:status>
+            </d:propstat>
+          </d:response>
+        XML
+      end
+    end
+  end
+end
+
+test do
+  def normalize(xml)
+    xml.gsub(/>\s+</, '><').strip
+  end
+
+  # Minimal mock storage for Collection tests
+  class MockStorageForCollection < Protocol::Caldav::Storage
+    def list_items(_path)
+      []
+    end
+  end
+
+  describe "Protocol::Caldav::Collection" do
+    def make_collection(type: :calendar, displayname: "Work", **opts)
+      storage = MockStorageForCollection.new
+      path = Protocol::Caldav::Path.new("/calendars/admin/work/", storage_class: storage)
+      Protocol::Caldav::Collection.new(path: path, type: type, displayname: displayname, **opts)
+    end
+
+    it "renders calendar resourcetype" do
+      xml = make_collection(type: :calendar).to_propfind_xml
+      xml.should.include "<c:calendar/>"
+    end
+
+    it "renders addressbook resourcetype" do
+      xml = make_collection(type: :addressbook).to_propfind_xml
+      xml.should.include "<cr:addressbook/>"
+    end
+
+    it "includes displayname when set" do
+      xml = make_collection(displayname: "Work").to_propfind_xml
+      xml.should.include "<d:displayname>Work</d:displayname>"
+    end
+
+    it "omits displayname when nil" do
+      xml = make_collection(displayname: nil).to_propfind_xml
+      xml.should.not.include "displayname"
+    end
+
+    it "includes ctag" do
+      xml = make_collection.to_propfind_xml
+      xml.should.include "<cs:getctag>"
+    end
+
+    it "includes supported-calendar-component-set for calendars" do
+      xml = make_collection(type: :calendar).to_propfind_xml
+      xml.should.include "supported-calendar-component-set"
+    end
+
+    it "omits supported-calendar-component-set for addressbooks" do
+      xml = make_collection(type: :addressbook).to_propfind_xml
+      xml.should.not.include "supported-calendar-component-set"
+    end
+
+    it "escapes special characters in displayname" do
+      xml = make_collection(displayname: "Work & <Personal>").to_propfind_xml
+      xml.should.include "Work &amp; &lt;Personal&gt;"
+    end
+
+    it "update_attrs modifies named fields" do
+      col = make_collection(displayname: "Old")
+      col.update_attrs(displayname: "New")
+      col.displayname.should.equal "New"
+    end
+
+    it "update_attrs leaves unmentioned fields alone" do
+      col = make_collection(displayname: "Work", description: "Desc")
+      col.update_attrs(displayname: "New")
+      col.description.should.equal "Desc"
+    end
+  end
+end

data/lib/protocol/caldav/constants.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+module Protocol
+  module Caldav
+    module Constants
+      DAV_HEADERS = {
+        'dav' => '1, 2, 3, calendar-access, addressbook, extended-mkcol',
+        'allow' => 'OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, PROPPATCH, MKCALENDAR, MKCOL, MOVE, REPORT',
+        'content-type' => 'text/xml; charset=utf-8'
+      }.freeze
+
+      DAV_NS        = 'DAV:'
+      CALDAV_NS     = 'urn:ietf:params:xml:ns:caldav'
+      CARDDAV_NS    = 'urn:ietf:params:xml:ns:carddav'
+      CALSERVER_NS  = 'http://calendarserver.org/ns/'
+      APPLE_NS      = 'http://apple.com/ns/ical/'
+
+      CALENDAR_MEDIA_TYPE = 'text/calendar'
+      VCARD_MEDIA_TYPE    = 'text/vcard'
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Constants" do
+    it "DAV_HEADERS is frozen" do
+      Protocol::Caldav::Constants::DAV_HEADERS.should.be.frozen
+    end
+
+    it "DAV_HEADERS includes calendar-access" do
+      Protocol::Caldav::Constants::DAV_HEADERS['dav'].should.include 'calendar-access'
+    end
+
+    it "DAV_HEADERS includes addressbook" do
+      Protocol::Caldav::Constants::DAV_HEADERS['dav'].should.include 'addressbook'
+    end
+
+    it "defines all required namespace URIs" do
+      Protocol::Caldav::Constants::DAV_NS.should.equal 'DAV:'
+      Protocol::Caldav::Constants::CALDAV_NS.should.equal 'urn:ietf:params:xml:ns:caldav'
+      Protocol::Caldav::Constants::CARDDAV_NS.should.equal 'urn:ietf:params:xml:ns:carddav'
+      Protocol::Caldav::Constants::CALSERVER_NS.should.equal 'http://calendarserver.org/ns/'
+    end
+
+    it "defines media types" do
+      Protocol::Caldav::Constants::CALENDAR_MEDIA_TYPE.should.equal 'text/calendar'
+      Protocol::Caldav::Constants::VCARD_MEDIA_TYPE.should.equal 'text/vcard'
+    end
+  end
+end

data/lib/protocol/caldav/content_line.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+module Protocol
+  module Caldav
+    module ContentLine
+      module_function
+
+      # Unfold lines per RFC 5545 §3.1: CRLF followed by a single space or tab
+      # is removed (the space/tab is part of the folding, not the value).
+      # Also normalizes line endings to LF.
+      def unfold(text)
+        text.gsub("\r\n", "\n").gsub("\r", "\n").gsub(/\n[ \t]/, '')
+      end
+
+      # Parse a single content line into [name, params, value].
+      # Format: NAME;PARAM1=VAL1;PARAM2="VAL2":value
+      # The value is everything after the first unquoted colon.
+      def parse_line(line)
+        # Find the first colon not inside a quoted parameter value
+        in_quotes = false
+        colon_idx = nil
+        line.each_char.with_index do |ch, i|
+          if ch == '"'
+            in_quotes = !in_quotes
+          elsif ch == ':' && !in_quotes
+            colon_idx = i
+            break
+          end
+        end
+
+        return nil unless colon_idx
+
+        left = line[0...colon_idx]
+        value = line[(colon_idx + 1)..]
+
+        parts = split_params(left)
+        name = parts.shift
+        params = {}
+        parts.each do |param_str|
+          key, val = param_str.split('=', 2)
+          next unless key
+          val = val[1..-2] if val&.start_with?('"') && val&.end_with?('"')
+          params[key.upcase] = val || ''
+        end
+
+        [name, params, value]
+      end
+
+      # Split the left side of a content line by semicolons,
+      # respecting quoted values.
+      def split_params(str)
+        parts = []
+        current = +''
+        in_quotes = false
+
+        str.each_char do |ch|
+          if ch == '"'
+            in_quotes = !in_quotes
+            current << ch
+          elsif ch == ';' && !in_quotes
+            parts << current
+            current = +''
+          else
+            current << ch
+          end
+        end
+        parts << current unless current.empty?
+        parts
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::ContentLine" do
+    describe ".unfold" do
+      it "unfolds CRLF SPACE continuations" do
+        Protocol::Caldav::ContentLine.unfold("SUMMARY:Annual\r\n planning").should.equal "SUMMARY:Annualplanning"
+      end
+
+      it "unfolds CRLF TAB continuations" do
+        Protocol::Caldav::ContentLine.unfold("SUMMARY:Annual\r\n\tplanning").should.equal "SUMMARY:Annualplanning"
+      end
+
+      it "does not unfold CRLF followed by non-whitespace" do
+        result = Protocol::Caldav::ContentLine.unfold("SUMMARY:A\r\nDTSTART:B")
+        result.should.equal "SUMMARY:A\nDTSTART:B"
+      end
+
+      it "removes the space/tab character (not kept in value)" do
+        Protocol::Caldav::ContentLine.unfold("X:hello\r\n world").should.equal "X:helloworld"
+      end
+
+      it "handles three consecutive folded lines" do
+        Protocol::Caldav::ContentLine.unfold("X:a\r\n b\r\n c").should.equal "X:abc"
+      end
+
+      it "handles LF-only line endings" do
+        Protocol::Caldav::ContentLine.unfold("X:a\n b").should.equal "X:ab"
+      end
+    end
+
+    describe ".parse_line" do
+      it "parses a property with no parameters" do
+        name, params, value = Protocol::Caldav::ContentLine.parse_line("SUMMARY:Hello")
+        name.should.equal "SUMMARY"
+        params.should.equal({})
+        value.should.equal "Hello"
+      end
+
+      it "parses a property with one parameter" do
+        name, params, value = Protocol::Caldav::ContentLine.parse_line("DTSTART;TZID=America/New_York:20260101T090000")
+        name.should.equal "DTSTART"
+        params["TZID"].should.equal "America/New_York"
+        value.should.equal "20260101T090000"
+      end
+
+      it "parses a parameter with a quoted value" do
+        name, params, value = Protocol::Caldav::ContentLine.parse_line('ATTENDEE;CN="Smith, John":mailto:j@e.com')
+        params["CN"].should.equal "Smith, John"
+        value.should.equal "mailto:j@e.com"
+      end
+
+      it "handles a colon inside a quoted parameter value" do
+        name, params, value = Protocol::Caldav::ContentLine.parse_line('X;FOO="a:b":realvalue')
+        params["FOO"].should.equal "a:b"
+        value.should.equal "realvalue"
+      end
+
+      it "handles a property value containing colons" do
+        _, _, value = Protocol::Caldav::ContentLine.parse_line("URL:https://example.com:8080/path")
+        value.should.equal "https://example.com:8080/path"
+      end
+
+      it "handles an empty property value" do
+        _, _, value = Protocol::Caldav::ContentLine.parse_line("DESCRIPTION:")
+        value.should.equal ""
+      end
+
+      it "returns nil for a line with no colon" do
+        Protocol::Caldav::ContentLine.parse_line("NOCOLON").should.be.nil
+      end
+
+      it "uppercases parameter names" do
+        _, params, _ = Protocol::Caldav::ContentLine.parse_line("X;tzid=utc:val")
+        params.key?("TZID").should.equal true
+      end
+    end
+  end
+end

data/lib/protocol/caldav/ctag.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require 'digest'
+
+module Protocol
+  module Caldav
+    module CTag
+      module_function
+
+      def compute(path:, displayname:, description: nil, color: nil, item_etags: [])
+        sorted = item_etags.sort.join(":")
+        Digest::SHA256.hexdigest("#{path}:#{displayname}:#{description}:#{color}:#{sorted}")[0..15]
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::CTag" do
+    it "is stable for the same collection state" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work")
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work")
+      a.should.equal b
+    end
+
+    it "changes when displayname changes" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work")
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Personal")
+      a.should.not.equal b
+    end
+
+    it "changes when description changes" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", description: "desc1")
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", description: "desc2")
+      a.should.not.equal b
+    end
+
+    it "changes when color changes" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", color: "#ff0000")
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", color: "#00ff00")
+      a.should.not.equal b
+    end
+
+    it "changes when an item is added" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["etag1"])
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["etag1", "etag2"])
+      a.should.not.equal b
+    end
+
+    it "changes when an item etag changes" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["etag1"])
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["etag2"])
+      a.should.not.equal b
+    end
+
+    it "changes when an item is removed" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["etag1", "etag2"])
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["etag1"])
+      a.should.not.equal b
+    end
+
+    it "does not depend on item_etags order" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["b", "a"])
+      b = Protocol::Caldav::CTag.compute(path: "/cal/", displayname: "Work", item_etags: ["a", "b"])
+      a.should.equal b
+    end
+
+    it "same state on different paths produces different ctags" do
+      a = Protocol::Caldav::CTag.compute(path: "/cal/a/", displayname: "Work")
+      b = Protocol::Caldav::CTag.compute(path: "/cal/b/", displayname: "Work")
+      a.should.not.equal b
+    end
+  end
+end

data/lib/protocol/caldav/etag.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require 'digest'
+
+module Protocol
+  module Caldav
+    module ETag
+      module_function
+
+      def compute(body)
+        %("#{Digest::SHA256.hexdigest(body)[0..15]}")
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::ETag" do
+    it "is stable: same body produces same etag" do
+      a = Protocol::Caldav::ETag.compute("hello")
+      b = Protocol::Caldav::ETag.compute("hello")
+      a.should.equal b
+    end
+
+    it "different bodies produce different etags" do
+      a = Protocol::Caldav::ETag.compute("hello")
+      b = Protocol::Caldav::ETag.compute("world")
+      a.should.not.equal b
+    end
+
+    it "is double-quoted per RFC 7232" do
+      etag = Protocol::Caldav::ETag.compute("test")
+      etag.should.match(/\A"[0-9a-f]+"/)
+    end
+
+    it "truncates to consistent length" do
+      etag = Protocol::Caldav::ETag.compute("test")
+      inner = etag[1..-2] # strip quotes
+      inner.length.should.equal 16
+    end
+
+    it "is binary-safe: body with null bytes produces an etag" do
+      etag = Protocol::Caldav::ETag.compute("hello\x00world")
+      etag.should.match(/\A"[0-9a-f]+"/)
+    end
+  end
+end

data/lib/protocol/caldav/filter/addressbook.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+module Protocol
+  module Caldav
+    module Filter
+      module Addressbook
+        Filter = Struct.new(:test, :prop_filters, keyword_init: true) do
+          def initialize(test: 'anyof', prop_filters: [])
+            super
+          end
+        end
+
+        PropFilter = Struct.new(:name, :is_not_defined, :text_match, :param_filters, keyword_init: true) do
+          def initialize(name:, is_not_defined: false, text_match: nil, param_filters: [])
+            super
+          end
+        end
+
+        ParamFilter = Struct.new(:name, :is_not_defined, :text_match, keyword_init: true) do
+          def initialize(name:, is_not_defined: false, text_match: nil)
+            super
+          end
+        end
+
+        TextMatch = Struct.new(:value, :collation, :match_type, :negate_condition, keyword_init: true) do
+          def initialize(value:, collation: 'i;ascii-casemap', match_type: 'contains', negate_condition: false)
+            super
+          end
+        end
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Filter::Addressbook" do
+    it "Filter defaults test to anyof" do
+      f = Protocol::Caldav::Filter::Addressbook::Filter.new
+      f.test.should.equal "anyof"
+      f.prop_filters.should.equal []
+    end
+
+    it "Filter accepts allof" do
+      f = Protocol::Caldav::Filter::Addressbook::Filter.new(test: "allof")
+      f.test.should.equal "allof"
+    end
+
+    it "PropFilter defaults" do
+      pf = Protocol::Caldav::Filter::Addressbook::PropFilter.new(name: "FN")
+      pf.name.should.equal "FN"
+      pf.is_not_defined.should.equal false
+      pf.text_match.should.be.nil
+    end
+
+    it "no comp-filter or time-range in addressbook" do
+      pf = Protocol::Caldav::Filter::Addressbook::PropFilter.new(name: "FN")
+      pf.should.not.respond_to(:time_range)
+      pf.should.not.respond_to(:comp_filters)
+    end
+  end
+end

data/lib/protocol/caldav/filter/calendar.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+module Protocol
+  module Caldav
+    module Filter
+      module Calendar
+        CompFilter = Struct.new(:name, :is_not_defined, :time_range, :prop_filters, :comp_filters, keyword_init: true) do
+          def initialize(name:, is_not_defined: false, time_range: nil, prop_filters: [], comp_filters: [])
+            super
+          end
+        end
+
+        PropFilter = Struct.new(:name, :is_not_defined, :time_range, :text_match, :param_filters, keyword_init: true) do
+          def initialize(name:, is_not_defined: false, time_range: nil, text_match: nil, param_filters: [])
+            super
+          end
+        end
+
+        ParamFilter = Struct.new(:name, :is_not_defined, :text_match, keyword_init: true) do
+          def initialize(name:, is_not_defined: false, text_match: nil)
+            super
+          end
+        end
+
+        TextMatch = Struct.new(:value, :collation, :match_type, :negate_condition, keyword_init: true) do
+          def initialize(value:, collation: 'i;ascii-casemap', match_type: 'contains', negate_condition: false)
+            super
+          end
+        end
+
+        TimeRange = Struct.new(:start_time, :end_time, keyword_init: true)
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Filter::Calendar" do
+    it "CompFilter accepts documented fields" do
+      cf = Protocol::Caldav::Filter::Calendar::CompFilter.new(name: "VCALENDAR")
+      cf.name.should.equal "VCALENDAR"
+      cf.is_not_defined.should.equal false
+      cf.time_range.should.be.nil
+      cf.prop_filters.should.equal []
+      cf.comp_filters.should.equal []
+    end
+
+    it "PropFilter defaults" do
+      pf = Protocol::Caldav::Filter::Calendar::PropFilter.new(name: "SUMMARY")
+      pf.name.should.equal "SUMMARY"
+      pf.is_not_defined.should.equal false
+      pf.text_match.should.be.nil
+      pf.param_filters.should.equal []
+    end
+
+    it "TextMatch defaults" do
+      tm = Protocol::Caldav::Filter::Calendar::TextMatch.new(value: "test")
+      tm.collation.should.equal "i;ascii-casemap"
+      tm.match_type.should.equal "contains"
+      tm.negate_condition.should.equal false
+    end
+
+    it "TimeRange holds start and end" do
+      tr = Protocol::Caldav::Filter::Calendar::TimeRange.new(start_time: "20260101T000000Z", end_time: "20260201T000000Z")
+      tr.start_time.should.equal "20260101T000000Z"
+      tr.end_time.should.equal "20260201T000000Z"
+    end
+
+    it "CompFilter with is_not_defined and other fields is valid" do
+      cf = Protocol::Caldav::Filter::Calendar::CompFilter.new(
+        name: "VTODO",
+        is_not_defined: true,
+        prop_filters: [Protocol::Caldav::Filter::Calendar::PropFilter.new(name: "X")]
+      )
+      cf.is_not_defined.should.equal true
+      cf.prop_filters.length.should.equal 1
+    end
+  end
+end