fix: stop orphaning google calendar events on schedule re-upload (#501)

Author: jaspermayone

app/jobs/cleanup_untracked_google_events_job.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Deletes events that exist in a user's Google Calendar but have no tracking
+# row in google_calendar_events. These orphans were left behind when tracking
+# rows were cascade-destroyed (e.g. meeting times destroyed on schedule
+# re-upload) without deleting the real events, so every subsequent sync
+# created a duplicate next to them.
+#
+# The app owns these calendars end-to-end, so any untracked event is one we
+# created and lost the pointer to. Modified instances of a tracked recurring
+# series are preserved (user-edited occurrences carry their own event id).
+#
+# Run with dry_run: true first to log what would be deleted without deleting.
+class CleanupUntrackedGoogleEventsJob < ApplicationJob
+  include GoogleApiRateLimiter
+
+  queue_as :low
+
+  def perform(google_calendar_id = nil, dry_run: false)
+    calendars = if google_calendar_id
+                  GoogleCalendar.where(id: google_calendar_id)
+    else
+                  GoogleCalendar.all
+    end
+
+    totals = { scanned: 0, deleted: 0, errors: 0 }
+
+    calendars.find_each do |calendar|
+      stats = reconcile_calendar(calendar, dry_run: dry_run)
+      totals.each_key { |key| totals[key] += stats[key] }
+    rescue => e
+      totals[:errors] += 1
+      Rails.logger.error "[CleanupUntrackedGoogleEventsJob] Failed for calendar #{calendar.id}: #{e.message}"
+    end
+
+    Rails.logger.info "[CleanupUntrackedGoogleEventsJob] Completed (dry_run: #{dry_run}): #{totals.to_json}"
+    totals
+  end
+
+  private
+
+  def reconcile_calendar(calendar, dry_run:)
+    stats = { scanned: 0, deleted: 0, errors: 0 }
+    tracked_ids = calendar.google_calendar_events.pluck(:google_event_id).to_set
+
+    untracked = []
+    page_token = nil
+
+    loop do
+      response = with_rate_limit_handling do
+        calendar_service.list_events(
+          calendar.google_calendar_id,
+          max_results: 2500,
+          page_token: page_token,
+          show_deleted: false
+        )
+      end
+
+      Array(response.items).each do |event|
+        stats[:scanned] += 1
+        next if event.status == "cancelled"
+        next if tracked_ids.include?(event.id)
+        # A user-edited occurrence of a tracked recurring series gets its own
+        # event id; deleting it would wipe the user's edit.
+        next if event.recurring_event_id.present? && tracked_ids.include?(event.recurring_event_id)
+
+        untracked << event
+      end
+
+      page_token = response.next_page_token
+      break if page_token.blank?
+    end
+
+    if dry_run
+      untracked.each do |event|
+        Rails.logger.info "[CleanupUntrackedGoogleEventsJob] [dry run] Would delete #{event.id} " \
+                          "(#{event.summary.inspect}) from calendar #{calendar.id}"
+      end
+      stats[:deleted] = untracked.size
+      return stats
+    end
+
+    with_batch_throttling(untracked) do |event|
+      delete_untracked_event(calendar, event)
+      stats[:deleted] += 1
+    rescue Google::Apis::Error => e
+      stats[:errors] += 1
+      Rails.logger.error "[CleanupUntrackedGoogleEventsJob] Failed to delete #{event.id} " \
+                         "from calendar #{calendar.id}: #{e.message}"
+    end
+
+    Rails.logger.info "[CleanupUntrackedGoogleEventsJob] Calendar #{calendar.id}: " \
+                      "#{stats[:deleted]} untracked events deleted (#{stats[:scanned]} scanned)"
+    stats
+  end
+
+  def delete_untracked_event(calendar, event)
+    calendar_service.delete_event(calendar.google_calendar_id, event.id)
+    Rails.logger.info "[CleanupUntrackedGoogleEventsJob] Deleted #{event.id} " \
+                      "(#{event.summary.inspect}) from calendar #{calendar.id}"
+  rescue Google::Apis::ClientError => e
+    raise unless e.status_code == 404
+  end
+
+  # The service account created and owns every app-managed calendar, so it can
+  # list and delete regardless of the state of the user's OAuth tokens.
+  def calendar_service
+    @calendar_service ||= begin
+      service = Google::Apis::CalendarV3::CalendarService.new
+      service.authorization = service_account_credentials
+      service
+    end
+  end
+
+  def service_account_credentials
+    service_account_config = Rails.application.credentials.dig(:google, :service_account)
+
+    credentials_json = if service_account_config.is_a?(String)
+                         service_account_config
+    else
+                         service_account_config.to_json
+    end
+
+    Google::Auth::ServiceAccountCredentials.make_creds(
+      json_key_io: StringIO.new(credentials_json),
+      scope:       Google::Apis::CalendarV3::AUTH_CALENDAR
+    )
+  end
+end

app/models/course/meeting_time.rb

@@ -38,7 +38,10 @@ class Course::MeetingTime < ApplicationRecord
   has_many :meeting_time_rooms, class_name: "Course::MeetingTimeRoom",
                                 foreign_key: :meeting_time_id, dependent: :destroy, inverse_of: :meeting_time
   has_many :rooms, through: :meeting_time_rooms
-  has_many :google_calendar_events, dependent: :destroy
+  # Nullify, never destroy: the tracking row is the only pointer to the real
+  # event in Google Calendar. CleanupOrphanedCalendarEventsJob deletes orphans
+  # from Google before removing the row.
+  has_many :google_calendar_events, dependent: :nullify
   has_one :event_preference, as: :preferenceable, dependent: :destroy
 
   def room

app/models/final_exam.rb

@@ -35,7 +35,9 @@ class FinalExam < ApplicationRecord
 
   belongs_to :term
   belongs_to :course, optional: true
-  has_many :google_calendar_events, dependent: :destroy
+  # Nullify, never destroy: see Course::MeetingTime — destroying tracking rows
+  # strands the real events in Google Calendar.
+  has_many :google_calendar_events, dependent: :nullify
 
   validates :crn, presence: true
   validates :exam_date, :start_time, :end_time, presence: true

app/services/course_processor_service.rb

@@ -191,12 +191,16 @@ def call
           Rails.logger.info("Linked FinalExam for CRN #{course.crn} to course #{course.id}")
         end
 
-        course.meeting_times.destroy_all
-
-        MeetingTimesIngestService.call(
+        # Upsert in place so meeting time IDs stay stable — destroying them
+        # cascades to google_calendar_events tracking rows, which strands the
+        # real events in Google Calendar and duplicates them on the next sync.
+        # Only rows absent from the upload are removed; their calendar events
+        # are nullified and cleaned up by CleanupOrphanedCalendarEventsJob.
+        touched_meeting_time_ids = MeetingTimesIngestService.call(
           course: course,
           raw_meeting_times: meeting_times
         )
+        course.meeting_times.where.not(id: touched_meeting_time_ids).destroy_all
 
         process_faculty(course, faculty_data)
 

app/services/meeting_times_ingest_service.rb

@@ -12,11 +12,15 @@ def initialize(course:, raw_meeting_times:, **options)
     super()
   end
 
+  # Upserts meeting times in place and returns the IDs of every row that was
+  # created or updated, so callers can prune stale rows without touching the rest.
   def call
     preload_buildings_and_rooms
+    @touched_meeting_time_ids = []
     raw_meeting_times.each do |mt|
       ingest_one(mt)
     end
+    @touched_meeting_time_ids
   end
 
   private
@@ -170,6 +174,7 @@ def ingest_one(mt)
       end
 
       @meeting_time_cache[cache_key] = meeting_time if @meeting_time_cache
+      @touched_meeting_time_ids << meeting_time.id
     end
   end
 

spec/jobs/cleanup_untracked_google_events_job_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe CleanupUntrackedGoogleEventsJob do
+  let(:user) { User.create!(email: "student@wit.edu", password: "password123") }
+  let(:credential) do
+    user.oauth_credentials.create!(
+      provider: "google", uid: "google-uid", email: user.email, access_token: "token"
+    )
+  end
+  let(:calendar) { credential.create_google_calendar!(google_calendar_id: "cal_123") }
+
+  let(:term) { Term.create!(uid: 202710, season: :fall, year: 2026) }
+  let(:course) do
+    Course.create!(
+      crn: 12345, term: term, title: "Data Structures", subject: "COMP",
+      course_number: 2000, section_number: "01", schedule_type: "LEC",
+      start_date: Date.new(2026, 9, 8), end_date: Date.new(2026, 12, 15)
+    )
+  end
+  let(:meeting_time) do
+    Course::MeetingTime.create!(
+      course: course,
+      start_date: Time.zone.local(2026, 9, 8),
+      end_date: Time.zone.local(2026, 12, 15, 23, 59, 59),
+      begin_time: 1300, end_time: 1445,
+      day_of_week: :monday,
+      meeting_schedule_type: :lecture, meeting_type: :class_meeting
+    )
+  end
+
+  let!(:tracked_event) do
+    calendar.google_calendar_events.create!(google_event_id: "tracked_1", meeting_time: meeting_time)
+  end
+
+  let(:fake_service) { instance_double(Google::Apis::CalendarV3::CalendarService) }
+  let(:job) { described_class.new }
+
+  def gcal_event(id:, status: "confirmed", summary: "Data Structures", recurring_event_id: nil)
+    instance_double(
+      Google::Apis::CalendarV3::Event,
+      id: id, status: status, summary: summary, recurring_event_id: recurring_event_id
+    )
+  end
+
+  let(:listed_events) do
+    [
+      gcal_event(id: "tracked_1"),
+      gcal_event(id: "orphan_1"),
+      gcal_event(id: "cancelled_1", status: "cancelled"),
+      gcal_event(id: "tracked_1_20260914", recurring_event_id: "tracked_1")
+    ]
+  end
+
+  before do
+    allow(job).to receive(:calendar_service).and_return(fake_service)
+    allow(fake_service).to receive(:list_events).and_return(
+      instance_double(Google::Apis::CalendarV3::Events, items: listed_events, next_page_token: nil)
+    )
+    job.rate_limit_config = GoogleApiRateLimiter::RateLimitConfig.new.tap { |c| c.batch_throttle_delay = 0 }
+  end
+
+  it "deletes only untracked events, keeping tracked events and edited instances of tracked series" do
+    expect(fake_service).to receive(:delete_event).with("cal_123", "orphan_1")
+
+    result = job.perform(calendar.id)
+
+    expect(result[:deleted]).to eq(1)
+    expect(result[:errors]).to eq(0)
+    expect(GoogleCalendarEvent.exists?(tracked_event.id)).to be(true)
+  end
+
+  it "does not delete anything in dry run mode" do
+    expect(fake_service).not_to receive(:delete_event)
+
+    result = job.perform(calendar.id, dry_run: true)
+
+    expect(result[:deleted]).to eq(1)
+  end
+
+  it "treats an already-deleted event as success" do
+    error = Google::Apis::ClientError.new("notFound", status_code: 404)
+    allow(fake_service).to receive(:delete_event).and_raise(error)
+
+    result = job.perform(calendar.id)
+
+    expect(result[:errors]).to eq(0)
+  end
+end

spec/models/google_calendar_event_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe GoogleCalendarEvent, type: :model do
+  let(:user) { User.create!(email: "student@wit.edu", password: "password123") }
+  let(:credential) do
+    user.oauth_credentials.create!(
+      provider: "google", uid: "google-uid", email: user.email, access_token: "token"
+    )
+  end
+  let(:calendar) { credential.create_google_calendar!(google_calendar_id: "cal_123") }
+
+  let(:term) { Term.create!(uid: 202710, season: :fall, year: 2026) }
+  let(:course) do
+    Course.create!(
+      crn: 12345, term: term, title: "Data Structures", subject: "COMP",
+      course_number: 2000, section_number: "01", schedule_type: "LEC",
+      start_date: Date.new(2026, 9, 8), end_date: Date.new(2026, 12, 15)
+    )
+  end
+
+  describe "orphaning behavior" do
+    it "is nullified, not destroyed, when its meeting time is destroyed" do
+      meeting_time = Course::MeetingTime.create!(
+        course: course,
+        start_date: Time.zone.local(2026, 9, 8),
+        end_date: Time.zone.local(2026, 12, 15, 23, 59, 59),
+        begin_time: 1300, end_time: 1445,
+        day_of_week: :monday,
+        meeting_schedule_type: :lecture, meeting_type: :class_meeting
+      )
+      event = calendar.google_calendar_events.create!(
+        google_event_id: "evt_1", meeting_time: meeting_time
+      )
+
+      expect { meeting_time.destroy! }.not_to change(GoogleCalendarEvent, :count)
+      expect(event.reload.meeting_time_id).to be_nil
+      expect(GoogleCalendarEvent.orphaned).to include(event)
+    end
+
+    it "is nullified, not destroyed, when its final exam is destroyed" do
+      final_exam = FinalExam.create!(
+        term: term, course: course, crn: 12345,
+        exam_date: Date.new(2026, 12, 17),
+        start_time: Time.zone.local(2026, 12, 17, 10, 0),
+        end_time: Time.zone.local(2026, 12, 17, 12, 0)
+      )
+      event = calendar.google_calendar_events.create!(
+        google_event_id: "evt_2", final_exam: final_exam
+      )
+
+      expect { final_exam.destroy! }.not_to change(GoogleCalendarEvent, :count)
+      expect(event.reload.final_exam_id).to be_nil
+      expect(GoogleCalendarEvent.orphaned).to include(event)
+    end
+  end
+end