Backend/events: Add logic for computing recurring event occurrence dates

[tristanlabelle]

Implements the logic to determine which event occurrences to schedule ahead of time for recurring events (#9544). Pure logic, no database. The next issue #9546 will store the rrule in the model and invoke this logic in a scheduled job to maintain the next few created events.

Closes #9545.

Testing

Backend checklist

• Added tests for any new code or added a regression test if fixing a bug
• Run the backend locally and it works
• Added migrations if there are any database changes, rebased onto develop if necessary for linear migration history

For maintainers

• Maintainers can push commits to my branch
• Maintainers can merge this PR for me

[CouchersBot]

Mobile

Install the Dev Tool (iOS via TestFlight, iOS Simulator, or Android .apk) here.

Scan the QR with your phone camera, or tap Open in Dev Tool on the device, to open this branch in the installed Dev Tool dev client.

iOS	Android
Open in Dev Tool	Open in Dev Tool

Deep links

iOS

couchers-devtool://expo-development-client/?url=https%3A%2F%2F881d003a--ota.preview.couchershq.org%2Fios%2Fmanifest

Android

couchers-devtool://expo-development-client/?url=https%3A%2F%2F881d003a--ota.preview.couchershq.org%2Fandroid%2Fmanifest

Web (Vercel)

View the Vercel web preview for this branch.

Backend

Schema	Schema diff	Sample emails	SQL query log no change in DB access patterns

Other

Protos

[aapeliv]

dateutil.rrule already has a system for producing these, why not use that?

[tristanlabelle]

dateutil.rrule already has a system for producing these, why not use that?

@aapeliv No reason -- I didn't realize I could use that and switched over now.

[aapeliv]

i think this is looking good.

my one main question is: why use rrule only for date and not full datetime?

the other tiny question is: would we want the schedule occurrences interface to instead produce a certain number of events instead of fill out a certain window? i'm not sure. i feel like a policy of "schedule the next 2 occurrences" is more like what we would want.

[tristanlabelle]

@aapeliv

why use rrule only for date and not full datetime?

Hmm my thinking is that we not only need to evaluate the rrule but also to support editing the recurrence in a user-friendly way, which gets more complicated the more we store into a single complex rrule table row in the data model (we then have to parse it out and make sense of it given what our UI can express). Since rrule is mostly about date recurrence complexity, not so much time, I figured it's better to keep out of it. It depends whether our data model is:

1. day-of-week, frequency, start-time, end-time, days-count (nothing prebaked as rrule, easily editable)
2. rrule (everything prebaked, harder to edit)

would we want the schedule occurrences interface to instead produce a certain number of events instead of fill out a certain window? i'm not sure. i feel like a policy of "schedule the next 2 occurrences" is more like what we would want.

It supports both. The idea was that if you have an event recurring very often, like a few times a week, you probably want to generate at least two weeks' worth of it as it's useful to know what's happening next week. If the event is every other week though, then we care more about generating the two instances. We have both knobs but don't have to use both of them.

[tristanlabelle]

Merging per Slack convo. We can still tweak whether to include the time and what to store in the model in the next PR which will add the model representation for recurring events.

[github-actions]

📝 Release Notes

This PR does not need to be included in release notes.

Reason: This PR adds backend-only recurrence computation logic as groundwork for a future recurring events feature, but it does not yet expose any user-facing functionality or deliver a clearly noticeable reliability/performance improvement on its own.

🤖 Bot Debug Information

Model: couchers.openai.gpt-5.4
Decision: exclude
Reasoning: This PR adds backend-only recurrence computation logic as groundwork for a future recurring events feature, but it does not yet expose any user-facing functionality or deliver a clearly noticeable reliability/performance improvement on its own.