fix: accept recurrence-set with master in any position

RFC 5545 does not mandate that the master VEVENT (carrying RRULE) appears
first in a VCALENDAR.  Some CalDAV servers (notably calendar.mail.ru) emit
override VEVENTs (with RECURRENCE-ID) before the master, which caused
_validate_and_normalize_component to raise ValueError and silently drop all
expanded recurring instances downstream.

Fix: locate the master by content (RRULE present, no RECURRENCE-ID) regardless
of position; reorder so it sits at index 0 for downstream expansion code.

Additions on top of the original PR (#10):
- Align property key casing to lowercase throughout (mixed uppercase/lowercase)
- Collapse redundant duplicate ValueError check in the else-branch
- Add test for two-masters rejection path

Closes #10

prompt: Fix up #10 according to the code review and merge (rebase-merge) the PR

Co-Authored-By: Tema <temsocial@users.noreply.github.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Recurrence sets with master in non-first position were rejected**: RFC 5545 does not mandate that the master VEVENT (carrying `RRULE`) appears first in a VCALENDAR.  Some CalDAV servers (notably `calendar.mail.ru`) emit override VEVENTs (with `RECURRENCE-ID`) before the master.  The previous validation assumed `components[0]` was always the master and raised `ValueError` for any other ordering, which caused `caldav._filter_search_results` to silently drop all expanded recurring instances.  The master is now located by content (has `RRULE`, no `RECURRENCE-ID`) regardless of position, and the list is reordered so it sits at index 0 for downstream expansion.  Also reduced duplicated error-check code in the same function.
+
 - **`check_component()` mutated `self` on every call**: The method resolved `None` fields (`include_completed`, `todo`, `event`, `journal`) and normalised `start`/`end`/`alarm_start`/`alarm_end` date objects to datetimes by writing back to `self`.  This made a `Searcher` instance stateful: calling `check_component()` twice could produce different results, and reusing a `Searcher` across multiple search operations (e.g. in the python-caldav library) could silently change behaviour after the first call.  All these values are now computed as local variables inside `check_component()` and threaded to the internal filter methods via new keyword parameters (`_start`, `_end`, `_alarm_start`, `_alarm_end`, `_include_completed`), keeping `self` immutable throughout.  (Triggered by https://github.com/python-caldav/caldav/issues/650)
 
 ## [1.0.5] - 2026-02-19

src/icalendar_searcher/searcher.py

@@ -452,14 +452,20 @@ def _normalise_dt_local(value: datetime | None) -> datetime | None:
             ## OPTIMIZATION TODO: If the object was recurring, we should
             ## probably trust recur.between to do the right thing?
             if not _ignore_rrule_and_time and (_start or _end):
-                recurrence_set = (x for x in recurrence_set if self._check_range(x, _start=_start, _end=_end))
+                recurrence_set = (
+                    x for x in recurrence_set if self._check_range(x, _start=_start, _end=_end)
+                )
 
             ## This if is just to save some few CPU cycles - skip filtering if it's not needed
             if not all(_compflags[x] for x in comptypesl):
                 recurrence_set = (x for x in recurrence_set if x.name in comptypesu)
 
             ## Filter based on include_completed setting
-            recurrence_set = (x for x in recurrence_set if self._check_completed_filter(x, _include_completed=_include_completed))
+            recurrence_set = (
+                x
+                for x in recurrence_set
+                if self._check_completed_filter(x, _include_completed=_include_completed)
+            )
 
             ## Apply property filters
             if self._property_filters or self._property_operator:
@@ -471,7 +477,11 @@ def _normalise_dt_local(value: datetime | None) -> datetime | None:
 
             ## Apply alarm filters
             if not _ignore_rrule_and_time and (_alarm_start or _alarm_end):
-                recurrence_set = (x for x in recurrence_set if self._check_alarm_range(x, _alarm_start=_alarm_start, _alarm_end=_alarm_end))
+                recurrence_set = (
+                    x
+                    for x in recurrence_set
+                    if self._check_alarm_range(x, _alarm_start=_alarm_start, _alarm_end=_alarm_end)
+                )
 
         if self.expand:
             ## TODO: fix wrapping, if needed
@@ -838,11 +848,16 @@ def _validate_and_normalize_component(
 
         2.1) All components in the recurrence set should have the same UID
 
-        2.2) First element ("master") of the recurrence set may have the RRULE
-        property set
+        2.2) Exactly one element ("master") of the recurrence set may
+        have the RRULE property set.  RFC 5545 does not mandate any
+        particular ordering inside a VCALENDAR, so the master may
+        appear in any position; this method will move it to the head
+        of the returned list so downstream expansion code can rely on
+        ``components[0]`` being the master.
 
-        2.3) Any following elements of a recurrence set ("exception
-        recurrences") should have the RECURRENCE-ID property set.
+        2.3) Any non-master elements of a recurrence set ("exception
+        recurrences") should have the RECURRENCE-ID property set and
+        must not have RRULE.
 
         2.4) (there are more properties that may only be set in the
         master or only in the recurrences, but currently we don't do
@@ -860,25 +875,33 @@ def _validate_and_normalize_component(
         ## We shouldn't get here.  There should always be a valid component.
         if not len(components):
             raise ValueError("Empty component?")
-        first = components[0]
 
-        ## A recurrence set should always be one "master" with
-        ## rrule-id set, followed by zero or more objects without
-        ## rrule-id but with recurrence-id set
+        ## A recurrence set should be exactly one "master" (with RRULE) plus zero
+        ## or more "exception recurrences" (with RECURRENCE-ID and without RRULE),
+        ## OR zero masters plus one-or-more standalone occurrences (all with
+        ## RECURRENCE-ID).  RFC 5545 does not mandate an ordering inside the
+        ## VCALENDAR, so we accept the master in any position and reorder it to
+        ## the head.  Some servers (notably calendar.mail.ru) emit overrides
+        ## before the master.
         if len(components) > 1:
-            if (
-                ("RRULE" not in components[0] and "RECURRENCE-ID" not in components[0])
-                or not all("recurrence-id" in x for x in components[1:])
-                or any("RRULE" in x for x in components[1:])
-            ):
+            masters = [c for c in components if "rrule" in c and "recurrence-id" not in c]
+            non_masters = [c for c in components if c not in masters]
+            if len(masters) > 1 or any("rrule" in c for c in non_masters):
+                raise ValueError(
+                    "Expected a valid recurrence set, either with one master component followed with special recurrences or with only occurrences"
+                )
+            if not all("recurrence-id" in c for c in non_masters):
                 raise ValueError(
                     "Expected a valid recurrence set, either with one master component followed with special recurrences or with only occurrences"
                 )
+            if masters:
+                components = masters + non_masters
 
         ## components should typically be a list with only one component.
         ## if there are more components, it should be a recurrence set
         ## one of the things identifying a recurrence set is that the
         ## uid is the same for all components in the set
+        first = components[0]
         if any(x for x in components if x["uid"] != first["uid"]):
             raise ValueError(
                 "Input parameter component is supposed to contain a single component or a recurrence set - but multiple UIDs found"

tests/test_validate_and_normalize_component.py

@@ -402,3 +402,106 @@ def test_validate_all_same_component_type_same_uid_without_recurrence() -> None:
     # This should raise ValueError because first component lacks RRULE
     with pytest.raises(ValueError, match="valid recurrence set"):
         searcher._validate_and_normalize_component(cal)
+
+
+def test_validate_recurrence_set_master_after_exception() -> None:
+    """Master may appear after the exception in the VCALENDAR.
+
+    RFC 5545 does not mandate any particular ordering of VEVENT components
+    inside a VCALENDAR.  Some CalDAV servers (notably ``calendar.mail.ru``)
+    return overrides before the master in the .ics they hand out, which used
+    to make ``_validate_and_normalize_component`` raise.  The normalized list
+    must put the master first so that the downstream expansion code can rely
+    on ``components[0]`` being the master.
+    """
+    cal = Calendar()
+
+    # Exception event first (mail.ru-style ordering)
+    exception = Event()
+    exception.add("uid", "recurring-meeting")
+    exception.add("summary", "Special Meeting")
+    exception.add("dtstart", datetime(2025, 1, 13, 14, 0))
+    exception.add("dtend", datetime(2025, 1, 13, 15, 0))
+    exception.add("recurrence-id", datetime(2025, 1, 13, 10, 0))
+    cal.add_component(exception)
+
+    # Master event with RRULE last
+    master = Event()
+    master.add("uid", "recurring-meeting")
+    master.add("summary", "Weekly Meeting")
+    master.add("dtstart", datetime(2025, 1, 6, 10, 0))
+    master.add("dtend", datetime(2025, 1, 6, 11, 0))
+    master.add("rrule", vRecur(FREQ="WEEKLY", COUNT=4))
+    cal.add_component(master)
+
+    searcher = Searcher()
+    result = searcher._validate_and_normalize_component(cal)
+
+    assert len(result) == 2, "Should contain master and exception"
+    assert "rrule" in result[0], "Master must be reordered to position 0"
+    assert "recurrence-id" not in result[0], "Master must not carry RECURRENCE-ID"
+    assert "recurrence-id" in result[1], "Exception must follow the master"
+    assert "rrule" not in result[1], "Exception must not carry RRULE"
+
+
+def test_validate_recurrence_set_master_in_middle() -> None:
+    """Master may appear between exceptions in arbitrary order."""
+    cal = Calendar()
+
+    exception1 = Event()
+    exception1.add("uid", "meeting")
+    exception1.add("summary", "First override")
+    exception1.add("dtstart", datetime(2025, 1, 13, 14, 0))
+    exception1.add("dtend", datetime(2025, 1, 13, 15, 0))
+    exception1.add("recurrence-id", datetime(2025, 1, 13, 10, 0))
+    cal.add_component(exception1)
+
+    master = Event()
+    master.add("uid", "meeting")
+    master.add("summary", "Weekly Meeting")
+    master.add("dtstart", datetime(2025, 1, 6, 10, 0))
+    master.add("dtend", datetime(2025, 1, 6, 11, 0))
+    master.add("rrule", vRecur(FREQ="WEEKLY", COUNT=10))
+    cal.add_component(master)
+
+    exception2 = Event()
+    exception2.add("uid", "meeting")
+    exception2.add("summary", "Second override")
+    exception2.add("dtstart", datetime(2025, 1, 20, 14, 0))
+    exception2.add("dtend", datetime(2025, 1, 20, 15, 0))
+    exception2.add("recurrence-id", datetime(2025, 1, 20, 10, 0))
+    cal.add_component(exception2)
+
+    searcher = Searcher()
+    result = searcher._validate_and_normalize_component(cal)
+
+    assert len(result) == 3, "Should contain master and both exceptions"
+    assert "rrule" in result[0], "Master must be reordered to position 0"
+    assert all("recurrence-id" in c for c in result[1:]), (
+        "All non-master components must carry RECURRENCE-ID"
+    )
+
+
+def test_validate_recurrence_set_two_masters_rejected() -> None:
+    """Two VEVENTs both carrying RRULE must be rejected as invalid."""
+    cal = Calendar()
+
+    master1 = Event()
+    master1.add("uid", "meeting")
+    master1.add("summary", "Weekly Meeting A")
+    master1.add("dtstart", datetime(2025, 1, 6, 10, 0))
+    master1.add("dtend", datetime(2025, 1, 6, 11, 0))
+    master1.add("rrule", vRecur(FREQ="WEEKLY", COUNT=4))
+    cal.add_component(master1)
+
+    master2 = Event()
+    master2.add("uid", "meeting")
+    master2.add("summary", "Weekly Meeting B")
+    master2.add("dtstart", datetime(2025, 1, 7, 10, 0))
+    master2.add("dtend", datetime(2025, 1, 7, 11, 0))
+    master2.add("rrule", vRecur(FREQ="DAILY", COUNT=4))
+    cal.add_component(master2)
+
+    searcher = Searcher()
+    with pytest.raises(ValueError, match="valid recurrence set"):
+        searcher._validate_and_normalize_component(cal)