protocol-caldav 1.0.0

data/lib/protocol/caldav/ical/freebusy.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    module Ical
+      module FreeBusy
+        module_function
+
+        # Generate a VCALENDAR containing VFREEBUSY from a list of calendar items.
+        #
+        # @param items [Array] items with .body method returning iCal strings
+        # @param range_start [Time] query range start
+        # @param range_end [Time] query range end
+        # @return [String] serialized VCALENDAR with VFREEBUSY
+        def generate(items, range_start:, range_end:)
+          busy_periods = []
+          free_periods = []
+
+          items.each do |item|
+            component = Parser.parse(item.body)
+            next unless component
+
+            component.find_components('VEVENT').each do |vevent|
+              next if vevent.find_property('RECURRENCE-ID') # skip overrides in this pass
+
+              status = vevent.find_property('STATUS')&.value&.strip&.upcase
+              transp = vevent.find_property('TRANSP')&.value&.strip&.upcase
+
+              is_free = status == 'CANCELLED' || transp == 'TRANSPARENT'
+
+              rrule = vevent.find_property('RRULE')
+              if rrule
+                collect_recurring_periods(vevent, rrule, range_start, range_end, is_free, busy_periods, free_periods)
+              else
+                collect_single_period(vevent, range_start, range_end, is_free, busy_periods, free_periods)
+              end
+            end
+          end
+
+          serialize_freebusy(busy_periods, free_periods, range_start, range_end)
+        end
+
+        def collect_single_period(vevent, range_start, range_end, is_free, busy_periods, free_periods)
+          dtstart = Filter::Match.send(:parse_ical_datetime, vevent, 'DTSTART')
+          dtend = Filter::Match.send(:parse_ical_datetime, vevent, 'DTEND')
+          return unless dtstart
+
+          dtend ||= dtstart + 3600 # default 1 hour
+          return unless dtstart < range_end && dtend > range_start
+
+          period = "#{format_utc(dtstart)}/#{format_utc(dtend)}"
+          if is_free
+            free_periods << period
+          else
+            busy_periods << period
+          end
+        end
+
+        def collect_recurring_periods(vevent, rrule, range_start, range_end, is_free, busy_periods, free_periods)
+          dtstart = Filter::Match.send(:parse_ical_datetime, vevent, 'DTSTART')
+          return unless dtstart
+
+          dtend = Filter::Match.send(:parse_ical_datetime, vevent, 'DTEND')
+          duration = dtend ? (dtend - dtstart).to_i : 3600
+
+          exdates = vevent.find_all_properties('EXDATE').filter_map do |ex|
+            Filter::Match.send(:parse_datetime_string, ex.value.strip)
+          end
+
+          occurrences = Rrule.expand(
+            dtstart: dtstart,
+            rrule_value: rrule.value.strip,
+            range_start: range_start - duration,
+            range_end: range_end,
+            exdates: exdates,
+            max_count: 10000
+          )
+
+          occurrences.each do |occ_start|
+            occ_end = occ_start + duration
+            next unless occ_start < range_end && occ_end > range_start
+
+            period = "#{format_utc(occ_start)}/#{format_utc(occ_end)}"
+            if is_free
+              free_periods << period
+            else
+              busy_periods << period
+            end
+          end
+        end
+
+        def serialize_freebusy(busy_periods, free_periods, range_start, range_end)
+          lines = []
+          lines << "BEGIN:VCALENDAR"
+          lines << "VERSION:2.0"
+          lines << "PRODID:-//Protocol::Caldav//NONSGML//EN"
+          lines << "BEGIN:VFREEBUSY"
+          lines << "DTSTART:#{format_utc(range_start)}"
+          lines << "DTEND:#{format_utc(range_end)}"
+
+          busy_periods.each do |period|
+            lines << "FREEBUSY;FBTYPE=BUSY:#{period}"
+          end
+
+          free_periods.each do |period|
+            lines << "FREEBUSY;FBTYPE=FREE:#{period}"
+          end
+
+          lines << "END:VFREEBUSY"
+          lines << "END:VCALENDAR"
+          lines.map { |l| "#{l}\r\n" }.join
+        end
+
+        def format_utc(time)
+          time.utc.strftime('%Y%m%dT%H%M%SZ')
+        end
+
+        private_class_method :collect_single_period, :collect_recurring_periods,
+                             :serialize_freebusy, :format_utc
+      end
+    end
+  end
+end
+
+test do
+  describe "Protocol::Caldav::Ical::FreeBusy" do
+    FakeItem = Struct.new(:body)
+
+    it "returns VCALENDAR with VFREEBUSY" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260115T090000Z\r\nDTEND:20260115T100000Z\r\nSUMMARY:Meeting\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      items = [FakeItem.new(ical)]
+      result = Protocol::Caldav::Ical::FreeBusy.generate(
+        items,
+        range_start: Time.utc(2026, 1, 1),
+        range_end: Time.utc(2026, 2, 1)
+      )
+      result.should.include "BEGIN:VCALENDAR"
+      result.should.include "BEGIN:VFREEBUSY"
+      result.should.include "FREEBUSY;FBTYPE=BUSY:20260115T090000Z/20260115T100000Z"
+      result.should.include "END:VFREEBUSY"
+      result.should.include "END:VCALENDAR"
+    end
+
+    it "empty items list returns empty freebusy" do
+      result = Protocol::Caldav::Ical::FreeBusy.generate(
+        [],
+        range_start: Time.utc(2026, 1, 1),
+        range_end: Time.utc(2026, 2, 1)
+      )
+      result.should.include "BEGIN:VCALENDAR"
+      result.should.include "BEGIN:VFREEBUSY"
+      result.should.include "END:VFREEBUSY"
+      result.should.not.include "FREEBUSY;FBTYPE=BUSY"
+    end
+  end
+end

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    module Ical
+      module Parser
+        module_function
+
+        def parse(text)
+          return nil if text.nil? || text.strip.empty?
+
+          # Strip BOM
+          text = text.sub(/\A\xEF\xBB\xBF/, '')
+
+          lines = ContentLine.unfold(text).split("\n").map(&:strip).reject(&:empty?)
+          stack = []
+          current = nil
+
+          lines.each do |line|
+            parsed = ContentLine.parse_line(line)
+            next unless parsed
+
+            name, params, value = parsed
+
+            if name.casecmp?('BEGIN')
+              comp = Component.new(name: value.strip.upcase)
+              if current
+                stack.push(current)
+              end
+              current = comp
+            elsif name.casecmp?('END')
+              end_name = value.strip.upcase
+              raise ParseError, "Mismatched END:#{end_name} (expected END:#{current&.name})" if current.nil? || !current.name.casecmp?(end_name)
+
+              if stack.empty?
+                return current
+              else
+                parent = stack.pop
+                parent.components << current
+                current = parent
+              end
+            else
+              current&.properties&.push(Property.new(name: name, params: params, value: value))
+            end
+          end
+
+          raise ParseError, "Unclosed component: #{current&.name}" if current && stack.any?
+          current
+        end
+      end
+    end
+
+    class ParseError < StandardError; end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Ical::Parser" do
+    def parse(text)
+      Protocol::Caldav::Ical::Parser.parse(text)
+    end
+
+    describe "line unfolding" do
+      it "unfolds CRLF SPACE continuations" do
+        ical = "BEGIN:VCALENDAR\r\nSUMMARY:Annual\r\n planning\r\nEND:VCALENDAR"
+        c = parse(ical)
+        c.find_property("SUMMARY").value.should.equal "Annualplanning"
+      end
+
+      it "unfolds CRLF TAB continuations" do
+        ical = "BEGIN:VCALENDAR\r\nSUMMARY:Annual\r\n\tplanning\r\nEND:VCALENDAR"
+        c = parse(ical)
+        c.find_property("SUMMARY").value.should.equal "Annualplanning"
+      end
+
+      it "handles three consecutive folded lines" do
+        ical = "BEGIN:VCALENDAR\r\nX-LONG:a\r\n b\r\n c\r\nEND:VCALENDAR"
+        c = parse(ical)
+        c.find_property("X-LONG").value.should.equal "abc"
+      end
+    end
+
+    describe "component nesting" do
+      it "parses a flat VCALENDAR with no children" do
+        c = parse("BEGIN:VCALENDAR\r\nVERSION:2.0\r\nEND:VCALENDAR")
+        c.name.should.equal "VCALENDAR"
+        c.components.should.equal []
+      end
+
+      it "parses one VEVENT inside VCALENDAR" do
+        ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nSUMMARY:Test\r\nEND:VEVENT\r\nEND:VCALENDAR"
+        c = parse(ical)
+        c.components.length.should.equal 1
+        c.components[0].name.should.equal "VEVENT"
+        c.components[0].find_property("SUMMARY").value.should.equal "Test"
+      end
+
+      it "parses multiple sibling VEVENTs" do
+        ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nSUMMARY:A\r\nEND:VEVENT\r\nBEGIN:VEVENT\r\nSUMMARY:B\r\nEND:VEVENT\r\nEND:VCALENDAR"
+        c = parse(ical)
+        c.components.length.should.equal 2
+      end
+
+      it "parses VALARM nested inside VEVENT" do
+        ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nBEGIN:VALARM\r\nACTION:DISPLAY\r\nEND:VALARM\r\nEND:VEVENT\r\nEND:VCALENDAR"
+        c = parse(ical)
+        vevent = c.components[0]
+        vevent.components.length.should.equal 1
+        vevent.components[0].name.should.equal "VALARM"
+      end
+
+      it "raises on mismatched END" do
+        ical = "BEGIN:VEVENT\r\nEND:VTODO"
+        lambda { parse(ical) }.should.raise Protocol::Caldav::ParseError
+      end
+
+      it "handles BEGIN/END names case-insensitively" do
+        c = parse("begin:vcalendar\r\nend:vcalendar")
+        c.name.should.equal "VCALENDAR"
+      end
+
+      it "preserves component order" do
+        ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nEND:VEVENT\r\nBEGIN:VTODO\r\nEND:VTODO\r\nEND:VCALENDAR"
+        c = parse(ical)
+        c.components[0].name.should.equal "VEVENT"
+        c.components[1].name.should.equal "VTODO"
+      end
+    end
+
+    describe "property parsing" do
+      it "parses a property with no parameters" do
+        c = parse("BEGIN:VCALENDAR\r\nSUMMARY:Hello\r\nEND:VCALENDAR")
+        c.find_property("SUMMARY").value.should.equal "Hello"
+        c.find_property("SUMMARY").params.should.equal({})
+      end
+
+      it "parses a property with one parameter" do
+        c = parse("BEGIN:VCALENDAR\r\nDTSTART;TZID=America/New_York:20260101T090000\r\nEND:VCALENDAR")
+        p = c.find_property("DTSTART")
+        p.params["TZID"].should.equal "America/New_York"
+        p.value.should.equal "20260101T090000"
+      end
+
+      it "handles a property value containing colons" do
+        c = parse("BEGIN:VCALENDAR\r\nURL:https://example.com:8080/path\r\nEND:VCALENDAR")
+        c.find_property("URL").value.should.equal "https://example.com:8080/path"
+      end
+
+      it "handles an empty property value" do
+        c = parse("BEGIN:VCALENDAR\r\nDESCRIPTION:\r\nEND:VCALENDAR")
+        c.find_property("DESCRIPTION").value.should.equal ""
+      end
+
+      it "handles X-prefix custom properties" do
+        c = parse("BEGIN:VCALENDAR\r\nX-WR-CALNAME:My Calendar\r\nEND:VCALENDAR")
+        c.find_property("X-WR-CALNAME").value.should.equal "My Calendar"
+      end
+    end
+
+    describe "edge cases" do
+      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 trailing whitespace and blank lines" do
+        c = parse("BEGIN:VCALENDAR\r\n\r\nVERSION:2.0\r\n\r\nEND:VCALENDAR\r\n  \r\n")
+        c.name.should.equal "VCALENDAR"
+      end
+
+      it "tolerates BOM at start of file" do
+        c = parse("\xEF\xBB\xBFBEGIN:VCALENDAR\r\nEND:VCALENDAR")
+        c.name.should.equal "VCALENDAR"
+      end
+
+      it "tolerates LF-only line endings" do
+        c = parse("BEGIN:VCALENDAR\nVERSION:2.0\nEND:VCALENDAR")
+        c.name.should.equal "VCALENDAR"
+      end
+    end
+  end
+end

data/lib/protocol/caldav/ical/property.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+module Protocol
+  module Caldav
+    module Ical
+      Property = Struct.new(:name, :params, :value, keyword_init: true) do
+        def param(key)
+          params[key.upcase]
+        end
+      end
+    end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Ical::Property" do
+    it "exposes name, params, value" do
+      p = Protocol::Caldav::Ical::Property.new(name: "SUMMARY", params: {}, value: "Hello")
+      p.name.should.equal "SUMMARY"
+      p.params.should.equal({})
+      p.value.should.equal "Hello"
+    end
+
+    it "param lookup is case-insensitive on parameter names" do
+      p = Protocol::Caldav::Ical::Property.new(name: "DTSTART", params: {"TZID" => "UTC"}, value: "x")
+      p.param("tzid").should.equal "UTC"
+      p.param("TZID").should.equal "UTC"
+    end
+
+    it "value is the raw string, no type coercion" do
+      p = Protocol::Caldav::Ical::Property.new(name: "DTSTART", params: {}, value: "20260101T090000Z")
+      p.value.should.equal "20260101T090000Z"
+    end
+  end
+end