protocol-caldav 1.0.0

data/lib/protocol/caldav/path.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    class Path
+      attr_reader :to_s, :storage_class
+
+      def initialize(raw, storage_class: nil)
+        p = raw.to_s.gsub(%r{/+}, '/')
+        p = "/#{p}" unless p.start_with?('/')
+        @to_s = p
+        @storage_class = storage_class
+      end
+
+      def parent
+        parts = @to_s.chomp('/').split('/')
+        if parts.length <= 1
+          self.class.new('/', storage_class: @storage_class)
+        else
+          self.class.new("#{parts[0..-2].join('/')}/", storage_class: @storage_class)
+        end
+      end
+
+      def depth
+        @to_s.chomp('/').split('/').reject(&:empty?).length
+      end
+
+      def child_of?(other)
+        parent_str = other.to_s
+        parent_str = "#{parent_str}/" unless parent_str.end_with?('/')
+        if @to_s.start_with?(parent_str)
+          remainder = @to_s[parent_str.length..]
+          remainder.chomp('/').count('/').zero? && !remainder.chomp('/').empty?
+        else
+          false
+        end
+      end
+
+      def parent_exists?
+        raise ArgumentError, "storage_class required for parent_exists?" unless @storage_class
+
+        if parent.depth <= 2
+          true
+        else
+          @storage_class.collection_exists?(parent.to_s)
+        end
+      end
+
+      def ensure_trailing_slash
+        if @to_s.end_with?('/')
+          self
+        else
+          self.class.new("#{@to_s}/", storage_class: @storage_class)
+        end
+      end
+
+      def start_with?(prefix)
+        @to_s.start_with?(prefix)
+      end
+
+      def ==(other)
+        to_s == other.to_s
+      end
+
+      def to_propfind_xml
+        <<~XML
+          <d:response>
+            <d:href>#{Xml.escape(@to_s)}</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>
+        XML
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Path" do
+    it "normalizes // to /" do
+      Protocol::Caldav::Path.new("//foo//bar").to_s.should.equal "/foo/bar"
+    end
+
+    it "normalizes leading ///foo to /foo" do
+      Protocol::Caldav::Path.new("///foo").to_s.should.equal "/foo"
+    end
+
+    it "adds leading / if missing" do
+      Protocol::Caldav::Path.new("foo/bar").to_s.should.equal "/foo/bar"
+    end
+
+    describe "#parent" do
+      it "parent of /a/b/c/ is /a/b/" do
+        Protocol::Caldav::Path.new("/a/b/c/").parent.to_s.should.equal "/a/b/"
+      end
+
+      it "parent of /a/ is /" do
+        Protocol::Caldav::Path.new("/a/").parent.to_s.should.equal "/"
+      end
+
+      it "parent of / is / (idempotent)" do
+        Protocol::Caldav::Path.new("/").parent.to_s.should.equal "/"
+      end
+    end
+
+    describe "#depth" do
+      it "depth of / is 0" do
+        Protocol::Caldav::Path.new("/").depth.should.equal 0
+      end
+
+      it "depth of /a/ is 1" do
+        Protocol::Caldav::Path.new("/a/").depth.should.equal 1
+      end
+
+      it "depth of /a/b is 2 (trailing-slash-insensitive)" do
+        Protocol::Caldav::Path.new("/a/b").depth.should.equal 2
+      end
+    end
+
+    describe "#child_of?" do
+      it "returns true for direct child" do
+        child = Protocol::Caldav::Path.new("/a/b/")
+        parent = Protocol::Caldav::Path.new("/a/")
+        child.child_of?(parent).should.equal true
+      end
+
+      it "returns false for grandchild" do
+        grandchild = Protocol::Caldav::Path.new("/a/b/c/")
+        grandparent = Protocol::Caldav::Path.new("/a/")
+        grandchild.child_of?(grandparent).should.equal false
+      end
+
+      it "returns false for sibling" do
+        a = Protocol::Caldav::Path.new("/a/b/")
+        b = Protocol::Caldav::Path.new("/a/c/")
+        a.child_of?(b).should.equal false
+      end
+
+      it "returns false for self" do
+        a = Protocol::Caldav::Path.new("/a/")
+        a.child_of?(a).should.equal false
+      end
+    end
+
+    describe "#ensure_trailing_slash" do
+      it "is idempotent on a slashed path" do
+        Protocol::Caldav::Path.new("/a/").ensure_trailing_slash.to_s.should.equal "/a/"
+      end
+
+      it "adds slash to unslashed" do
+        Protocol::Caldav::Path.new("/a").ensure_trailing_slash.to_s.should.equal "/a/"
+      end
+    end
+
+    describe "#start_with?" do
+      it "delegates to string semantics" do
+        Protocol::Caldav::Path.new("/calendars/admin/").start_with?("/calendars/").should.equal true
+        Protocol::Caldav::Path.new("/addressbooks/admin/").start_with?("/calendars/").should.equal false
+      end
+    end
+
+    describe "#==" do
+      it "paths with same string are equal" do
+        a = Protocol::Caldav::Path.new("/a/")
+        b = Protocol::Caldav::Path.new("/a/")
+        (a == b).should.equal true
+      end
+
+      it "paths from different storage_class but same string compare equal" do
+        a = Protocol::Caldav::Path.new("/a/", storage_class: Object.new)
+        b = Protocol::Caldav::Path.new("/a/", storage_class: Object.new)
+        (a == b).should.equal true
+      end
+    end
+  end
+end

data/lib/protocol/caldav/storage.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+module Protocol
+  module Caldav
+    class Storage
+      # --- Collections ---
+
+      def create_collection(path, props = {})
+        raise NotImplementedError
+      end
+
+      def get_collection(path)
+        raise NotImplementedError
+      end
+
+      def delete_collection(path)
+        raise NotImplementedError
+      end
+
+      def list_collections(parent_path)
+        raise NotImplementedError
+      end
+
+      def update_collection(path, props)
+        raise NotImplementedError
+      end
+
+      def collection_exists?(path)
+        raise NotImplementedError
+      end
+
+      # --- Items ---
+
+      def get_item(path)
+        raise NotImplementedError
+      end
+
+      def put_item(path, body, content_type)
+        raise NotImplementedError
+      end
+
+      def delete_item(path)
+        raise NotImplementedError
+      end
+
+      def list_items(collection_path)
+        raise NotImplementedError
+      end
+
+      def move_item(from_path, to_path)
+        raise NotImplementedError
+      end
+
+      def get_multi(paths)
+        raise NotImplementedError
+      end
+
+      # --- General ---
+
+      def exists?(path)
+        raise NotImplementedError
+      end
+
+      def etag(path)
+        raise NotImplementedError
+      end
+
+      # --- Sync ---
+
+      # Snapshot the current item state for a collection and return a sync token.
+      # Subsequent calls to sync_changes with this token return the diff.
+      def snapshot_sync(collection_path)
+        raise NotImplementedError
+      end
+
+      # Return [new_token, changes] where changes is an array of [path, status]
+      # status is :modified (200) or :deleted (404).
+      # Returns nil if the token is invalid/unknown.
+      def sync_changes(collection_path, token)
+        raise NotImplementedError
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Storage" do
+    it "every method raises NotImplementedError" do
+      s = Protocol::Caldav::Storage.new
+      methods = %i[create_collection get_collection delete_collection list_collections
+                   update_collection collection_exists? get_item put_item delete_item
+                   list_items move_item get_multi exists? etag snapshot_sync sync_changes]
+      three_arg = %i[put_item]
+      two_arg = %i[update_collection move_item sync_changes]
+      methods.each do |m|
+        if three_arg.include?(m)
+          lambda { s.send(m, "/x", "body", "ct") }.should.raise NotImplementedError
+        elsif two_arg.include?(m)
+          lambda { s.send(m, "/x", {}) }.should.raise NotImplementedError
+        else
+          lambda { s.send(m, "/x") }.should.raise NotImplementedError
+        end
+      end
+    end
+
+    it "can be subclassed with partial implementation" do
+      klass = Class.new(Protocol::Caldav::Storage) do
+        def exists?(path)
+          true
+        end
+      end
+      klass.new.exists?("/x").should.equal true
+      lambda { klass.new.get_item("/x") }.should.raise NotImplementedError
+    end
+  end
+end

data/lib/protocol/caldav/vcard/card.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    module Vcard
+      Card = Struct.new(:properties, keyword_init: true) do
+        def initialize(properties: [])
+          super(properties: properties)
+        end
+
+        def find_property(prop_name)
+          properties.find { |p| p.name.casecmp?(prop_name) }
+        end
+
+        def find_all_properties(prop_name)
+          properties.select { |p| p.name.casecmp?(prop_name) }
+        end
+      end
+    end
+  end
+end
+
+test do
+  describe "Protocol::Caldav::Vcard::Card" do
+    def prop(name, value)
+      Protocol::Caldav::Ical::Property.new(name: name, params: {}, value: value)
+    end
+
+    it "find_property returns the first matching property" do
+      card = Protocol::Caldav::Vcard::Card.new(properties: [prop("FN", "John"), prop("FN", "Jane")])
+      card.find_property("FN").value.should.equal "John"
+    end
+
+    it "find_property is case-insensitive" do
+      card = Protocol::Caldav::Vcard::Card.new(properties: [prop("FN", "John")])
+      card.find_property("fn").value.should.equal "John"
+    end
+
+    it "find_property returns nil when absent" do
+      card = Protocol::Caldav::Vcard::Card.new(properties: [])
+      card.find_property("FN").should.be.nil
+    end
+
+    it "has no sub-component finder (vCards don't nest)" do
+      card = Protocol::Caldav::Vcard::Card.new
+      card.should.not.respond_to(:find_components)
+    end
+
+    it "find_all_properties returns all matching" do
+      card = Protocol::Caldav::Vcard::Card.new(properties: [prop("TEL", "123"), prop("EMAIL", "x"), prop("TEL", "456")])
+      card.find_all_properties("TEL").length.should.equal 2
+    end
+  end
+end

data/lib/protocol/caldav/vcard/parser.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    module Vcard
+      module Parser
+        module_function
+
+        def parse(text)
+          return nil if text.nil? || text.strip.empty?
+
+          text = text.sub(/\A\xEF\xBB\xBF/, '')
+
+          lines = ContentLine.unfold(text).split("\n").map(&:strip).reject(&:empty?)
+          props = []
+          inside = false
+
+          lines.each do |line|
+            parsed = ContentLine.parse_line(line)
+            next unless parsed
+
+            name, params, value = parsed
+
+            if name.casecmp?('BEGIN') && value.strip.casecmp?('VCARD')
+              inside = true
+            elsif name.casecmp?('END') && value.strip.casecmp?('VCARD')
+              break
+            elsif inside
+              props << Ical::Property.new(name: name, params: params, value: value)
+            end
+          end
+
+          props.empty? ? nil : Card.new(properties: props)
+        end
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Vcard::Parser" do
+    def parse(text)
+      Protocol::Caldav::Vcard::Parser.parse(text)
+    end
+
+    it "parses a flat BEGIN:VCARD / END:VCARD" do
+      card = parse("BEGIN:VCARD\r\nVERSION:3.0\r\nFN:John\r\nEND:VCARD")
+      card.should.not.be.nil
+      card.find_property("FN").value.should.equal "John"
+    end
+
+    it "handles VERSION:3.0 and VERSION:4.0 without distinction" do
+      card3 = parse("BEGIN:VCARD\r\nVERSION:3.0\r\nFN:A\r\nEND:VCARD")
+      card4 = parse("BEGIN:VCARD\r\nVERSION:4.0\r\nFN:A\r\nEND:VCARD")
+      card3.find_property("VERSION").value.should.equal "3.0"
+      card4.find_property("VERSION").value.should.equal "4.0"
+    end
+
+    it "handles structured values in N property as raw string" do
+      card = parse("BEGIN:VCARD\r\nN:Doe;John;;;Jr.\r\nEND:VCARD")
+      card.find_property("N").value.should.equal "Doe;John;;;Jr."
+    end
+
+    it "returns nil for empty input" do
+      parse("").should.be.nil
+    end
+
+    it "returns nil for nil input" do
+      parse(nil).should.be.nil
+    end
+
+    it "tolerates LF-only line endings" do
+      card = parse("BEGIN:VCARD\nFN:Test\nEND:VCARD")
+      card.find_property("FN").value.should.equal "Test"
+    end
+
+    it "tolerates BOM" do
+      card = parse("\xEF\xBB\xBFBEGIN:VCARD\r\nFN:Test\r\nEND:VCARD")
+      card.should.not.be.nil
+    end
+  end
+end

data/lib/protocol/caldav/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Protocol
+  module Caldav
+    VERSION = "1.0.0"
+  end
+end

data/lib/protocol/caldav/xml.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+module Protocol
+  module Caldav
+    module Xml
+      module_function
+
+      def escape(str)
+        return '' unless str
+
+        str.to_s
+           .gsub('&', '&')
+           .gsub('<', '&lt;')
+           .gsub('>', '&gt;')
+           .gsub('"', '&quot;')
+      end
+
+      def extract_value(xml, tag)
+        return nil if xml.nil? || xml.empty?
+
+        match = xml.match(/<[^>]*#{Regexp.escape(tag)}[^>]*>([^<]*)</)
+        return nil unless match
+
+        value = match[1].strip
+        value.empty? ? nil : value
+      end
+
+      def extract_attr(xml, tag, attr)
+        return nil if xml.nil? || xml.empty?
+
+        match = xml.match(/<[^>]*#{Regexp.escape(tag)}[^>]*#{Regexp.escape(attr)}="([^"]*)"/)
+        match ? match[1] : nil
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Xml" do
+    describe ".escape" do
+      it "escapes ampersand" do
+        Protocol::Caldav::Xml.escape("a&b").should.equal "a&amp;b"
+      end
+
+      it "escapes less-than" do
+        Protocol::Caldav::Xml.escape("a<b").should.equal "a&lt;b"
+      end
+
+      it "escapes greater-than" do
+        Protocol::Caldav::Xml.escape("a>b").should.equal "a&gt;b"
+      end
+
+      it "escapes double-quote" do
+        Protocol::Caldav::Xml.escape('a"b').should.equal "a&quot;b"
+      end
+
+      it "escapes all five entities together" do
+        Protocol::Caldav::Xml.escape('&<>"').should.equal '&amp;&lt;&gt;&quot;'
+      end
+
+      it "returns empty string for nil" do
+        Protocol::Caldav::Xml.escape(nil).should.equal ''
+      end
+
+      it "returns empty string for empty string" do
+        Protocol::Caldav::Xml.escape('').should.equal ''
+      end
+
+      it "passes through plain text unchanged" do
+        Protocol::Caldav::Xml.escape("hello world").should.equal "hello world"
+      end
+    end
+
+    describe ".extract_value" do
+      it "extracts text content from a tag" do
+        Protocol::Caldav::Xml.extract_value('<d:displayname>Work</d:displayname>', 'displayname').should.equal 'Work'
+      end
+
+      it "returns nil for empty content" do
+        Protocol::Caldav::Xml.extract_value('<d:displayname></d:displayname>', 'displayname').should.be.nil
+      end
+
+      it "returns nil when tag not found" do
+        Protocol::Caldav::Xml.extract_value('<d:other>x</d:other>', 'displayname').should.be.nil
+      end
+
+      it "returns nil for nil input" do
+        Protocol::Caldav::Xml.extract_value(nil, 'displayname').should.be.nil
+      end
+
+      it "returns nil for empty input" do
+        Protocol::Caldav::Xml.extract_value('', 'displayname').should.be.nil
+      end
+
+      it "strips whitespace from value" do
+        Protocol::Caldav::Xml.extract_value('<d:displayname>  Work  </d:displayname>', 'displayname').should.equal 'Work'
+      end
+    end
+
+    describe ".extract_attr" do
+      it "extracts attribute value from a tag" do
+        Protocol::Caldav::Xml.extract_attr('<c:comp-filter name="VCALENDAR">', 'comp-filter', 'name').should.equal 'VCALENDAR'
+      end
+
+      it "returns nil when tag not found" do
+        Protocol::Caldav::Xml.extract_attr('<c:other name="x">', 'comp-filter', 'name').should.be.nil
+      end
+
+      it "returns nil for nil input" do
+        Protocol::Caldav::Xml.extract_attr(nil, 'comp-filter', 'name').should.be.nil
+      end
+
+      it "returns nil for empty input" do
+        Protocol::Caldav::Xml.extract_attr('', 'comp-filter', 'name').should.be.nil
+      end
+    end
+  end
+end

data/lib/protocol/caldav.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'caldav/version'
+require_relative 'caldav/constants'
+require_relative 'caldav/etag'
+require_relative 'caldav/ctag'
+require_relative 'caldav/xml'
+require_relative 'caldav/multistatus'
+require_relative 'caldav/path'
+require_relative 'caldav/storage'
+require_relative 'caldav/collection'
+require_relative 'caldav/item'
+require_relative 'caldav/content_line'
+require_relative 'caldav/ical/property'
+require_relative 'caldav/ical/component'
+require_relative 'caldav/ical/parser'
+require_relative 'caldav/ical/rrule'
+require_relative 'caldav/ical/expand'
+require_relative 'caldav/ical/freebusy'
+require_relative 'caldav/vcard/card'
+require_relative 'caldav/vcard/parser'
+require_relative 'caldav/filter/calendar'
+require_relative 'caldav/filter/addressbook'
+require_relative 'caldav/filter/parser'
+require_relative 'caldav/filter/match'
+
+module Protocol
+  module Caldav
+  end
+end