feat: Implement conditional fetching for calendar entries and add related tests

Author: Marcus Markiewicz

src/ComingUpNextTray/HoverWindow.cs

@@ -115,7 +115,7 @@ public void UpdateMeeting(CalendarEntry? meeting, DateTime now, string? overlayT
             this.Size = new Size(Math.Min(width, 420), height);
         }
 
-    /// <summary>
+        /// <summary>
         /// Sets the background and foreground to match the specified colors.
         /// </summary>
         /// <param name="background">Background color.</param>

src/ComingUpNextTray/Services/CalendarService.cs

@@ -12,9 +12,29 @@ internal sealed class CalendarService : IDisposable
         private static readonly char[] LineSplitSeparators = new[] { '\r', '\n' };
 
         // HttpClient is intended to be reused; dispose only when this service is disposed (CA1001).
-        private readonly HttpClient httpClient = new ();
+        private readonly HttpClient httpClient;
+
+        // Lightweight change validators; we intentionally do NOT cache ICS content or parsed entries.
+        private string? lastEtag;
+        private DateTimeOffset? lastModified;
         private bool disposed;
 
+        /// <summary>Initializes a new instance of the <see cref="CalendarService"/> class.</summary>
+        internal CalendarService()
+        {
+            this.httpClient = new HttpClient();
+        }
+
+        /// <summary>Initializes a new instance of the <see cref="CalendarService"/> class using a custom <see cref="HttpMessageHandler"/>. Internal for test injection; production code uses the default constructor.</summary>
+        /// <param name="handler">Custom HTTP message handler.</param>
+        internal CalendarService(HttpMessageHandler handler)
+        {
+            this.httpClient = new HttpClient(handler, disposeHandler: true);
+        }
+
+        /// <summary>Gets a value indicating whether previously observed change validators (ETag or Last-Modified) are available.</summary>
+        public bool HasChangeValidators => this.lastEtag != null || this.lastModified != null;
+
         /// <summary>
         /// Fetches and parses calendar entries from the specified ICS URL.
         /// </summary>
@@ -66,6 +86,55 @@ public async Task<IReadOnlyList<CalendarEntry>> FetchAsync(Uri calendarIcsUri, C
             }
         }
 
+        /// <summary>
+        /// Performs a conditional GET using previously observed ETag / Last-Modified validators (if any) and
+        /// returns parsed entries only when the server indicates the resource changed. On 304 Not Modified an empty list is returned
+        /// allowing callers to decide whether to reuse prior results. This service purposely does not retain prior entries or ICS text.
+        /// </summary>
+        /// <param name="calendarIcsUri">ICS feed URI.</param>
+        /// <param name="ct">Cancellation token.</param>
+        /// <returns>List of parsed entries when changed; empty list on 304 or errors.</returns>
+        public async Task<IReadOnlyList<CalendarEntry>> FetchIfChangedAsync(Uri calendarIcsUri, CancellationToken ct = default)
+        {
+            try
+            {
+                using HttpRequestMessage req = new (HttpMethod.Get, calendarIcsUri);
+                if (!string.IsNullOrEmpty(this.lastEtag))
+                {
+                    req.Headers.TryAddWithoutValidation("If-None-Match", this.lastEtag);
+                }
+
+                if (this.lastModified.HasValue)
+                {
+                    req.Headers.IfModifiedSince = this.lastModified;
+                }
+
+                using HttpResponseMessage resp = await this.httpClient.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, ct).ConfigureAwait(false);
+                if (resp.StatusCode == System.Net.HttpStatusCode.NotModified)
+                {
+                    return Array.Empty<CalendarEntry>();
+                }
+
+                if (!resp.IsSuccessStatusCode)
+                {
+                    return Array.Empty<CalendarEntry>();
+                }
+
+                this.lastEtag = resp.Headers.ETag?.ToString();
+                this.lastModified = resp.Content.Headers.LastModified;
+                string text = await resp.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
+                return ParseIcs(text);
+            }
+            catch (HttpRequestException)
+            {
+                return Array.Empty<CalendarEntry>();
+            }
+            catch (TaskCanceledException)
+            {
+                return Array.Empty<CalendarEntry>();
+            }
+        }
+
         /// <summary>
         /// Similar to <see cref="FetchAsync(Uri, CancellationToken)"/> but propagates failures as exceptions
         /// so callers can inspect error messages. Use this when the caller wants to display errors to the user.
@@ -105,6 +174,65 @@ public async Task<IReadOnlyList<CalendarEntry>> FetchWithErrorsAsync(Uri calenda
             return ParseIcs(text);
         }
 
+        /// <summary>
+        /// Same as <see cref="FetchWithErrorsAsync"/> but uses conditional validators to potentially avoid downloading the body.
+        /// Throws only when the server returns an error status for a changed resource; 304 yields an empty list.
+        /// </summary>
+        /// <param name="calendarIcsUri">ICS feed URI.</param>
+        /// <param name="ct">Cancellation token.</param>
+        /// <returns>Parsed entries when changed; empty list when not modified.</returns>
+        /// <exception cref="HttpRequestException">If HTTP status is non-success (excluding 304).</exception>
+        public async Task<IReadOnlyList<CalendarEntry>> FetchIfChangedWithErrorsAsync(Uri calendarIcsUri, CancellationToken ct = default)
+        {
+            using HttpRequestMessage req = new (HttpMethod.Get, calendarIcsUri);
+            if (!string.IsNullOrEmpty(this.lastEtag))
+            {
+                req.Headers.TryAddWithoutValidation("If-None-Match", this.lastEtag);
+            }
+
+            if (this.lastModified.HasValue)
+            {
+                req.Headers.IfModifiedSince = this.lastModified;
+            }
+
+            using HttpResponseMessage resp = await this.httpClient.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, ct).ConfigureAwait(false);
+            if (resp.StatusCode == System.Net.HttpStatusCode.NotModified)
+            {
+                return Array.Empty<CalendarEntry>();
+            }
+
+            if (!resp.IsSuccessStatusCode)
+            {
+                int code = (int)resp.StatusCode;
+                string reason = resp.ReasonPhrase ?? resp.StatusCode.ToString();
+                string loc = resp.Headers.Location?.ToString() ?? string.Empty;
+                string hint = string.Empty;
+                if (code >= 300 && code < 400)
+                {
+                    hint = " Redirected location may require authentication.";
+                }
+                else if (code == 401 || code == 403)
+                {
+                    hint = " Calendar feed appears to require authentication (401/403).";
+                }
+
+                string msg = !string.IsNullOrEmpty(loc)
+                    ? $"HTTP {code} {reason} -> {loc}.{hint}"
+                    : $"HTTP {code} {reason}.{hint}";
+
+                throw new HttpRequestException(msg);
+            }
+
+            this.lastEtag = resp.Headers.ETag?.ToString();
+            this.lastModified = resp.Content.Headers.LastModified;
+            string text = await resp.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
+            return ParseIcs(text);
+        }
+
+        /// <summary>
+        /// Indicates whether conditional request validators were previously observed (ETag or Last-Modified).
+        /// </summary>
+
         /// <summary>
         /// Disposes the underlying <see cref="HttpClient"/> instance used by this service.
         /// </summary>

src/ComingUpNextTray/TrayApplication.cs

@@ -129,19 +129,30 @@ internal async Task<bool> RefreshAsync(CancellationToken ct = default)
             try
             {
                 // Try the error-propagating fetch so we can show users what went wrong.
-                IReadOnlyList<CalendarEntry> entries;
+                IReadOnlyList<CalendarEntry> newEntries = Array.Empty<CalendarEntry>();
+                bool changed = false;
                 if (Uri.TryCreate(this._calendarUrl, UriKind.Absolute, out Uri? uri))
                 {
-                    entries = await this._calendarService.FetchWithErrorsAsync(uri, ct).ConfigureAwait(false);
-                }
-                else
-                {
-                    entries = Array.Empty<CalendarEntry>();
+                    // Prefer conditional fetch when we already have validators; fall back to full fetch otherwise.
+                    if (this._calendarService.HasChangeValidators)
+                    {
+                        newEntries = await this._calendarService.FetchIfChangedWithErrorsAsync(uri, ct).ConfigureAwait(false);
+                        changed = newEntries.Count > 0; // empty list means not modified (or error not thrown).
+                        if (!changed && this._lastEntries != null)
+                        {
+                            newEntries = this._lastEntries; // reuse prior parsed entries.
+                        }
+                    }
+                    else
+                    {
+                        newEntries = await this._calendarService.FetchWithErrorsAsync(uri, ct).ConfigureAwait(false);
+                        changed = true;
+                    }
                 }
 
                 this._lastFetchError = null;
-                this._lastEntries = entries;
-                this._nextMeeting = NextMeetingSelector.GetNextMeeting(entries, DateTime.Now, this._ignoreFreeOrFollowing);
+                this._lastEntries = newEntries;
+                this._nextMeeting = NextMeetingSelector.GetNextMeeting(newEntries, DateTime.Now, this._ignoreFreeOrFollowing);
                 this._lastRefreshUtc = DateTime.UtcNow;
                 return true;
             }

src/ComingUpNextTray/TrayContext.cs

@@ -18,6 +18,7 @@ internal sealed class TrayContext : ApplicationContext
         private readonly ContextMenuStrip menu;
         private readonly ToolStripMenuItem nextMeetingDisplayItem; // shows formatted first meeting
         private readonly ToolStripMenuItem secondMeetingDisplayItem; // shows formatted second meeting
+        private readonly ToolStripMenuItem lastUpdatedDisplayItem; // shows last successful refresh timestamp
         private readonly System.Windows.Forms.Timer refreshTimer;
         private readonly System.Windows.Forms.Timer overlayTimer; // updates icon/tooltip more frequently
         private ToolStripMenuItem? toggleHoverWindowItem;
@@ -45,6 +46,7 @@ public TrayContext()
             // Dynamic meeting display items (inserted at top later):
             this.nextMeetingDisplayItem = new ToolStripMenuItem(string.Empty) { Enabled = false }; // will show formatted first meeting
             this.secondMeetingDisplayItem = new ToolStripMenuItem(string.Empty) { Enabled = false }; // will show formatted second meeting
+            this.lastUpdatedDisplayItem = new ToolStripMenuItem(string.Empty) { Enabled = false }; // will show last updated timestamp
 
             // Core items
             ToolStripMenuItem openMeetingItem = new ToolStripMenuItem(UiText.OpenMeeting, null, this.OnOpenMeetingClick) { Enabled = false };
@@ -85,6 +87,7 @@ public TrayContext()
             // Insert meeting display placeholders at top.
             this.menu.Items.Add(this.nextMeetingDisplayItem);
             this.menu.Items.Add(this.secondMeetingDisplayItem);
+            this.menu.Items.Add(this.lastUpdatedDisplayItem);
             this.menu.Items.Add(new ToolStripSeparator());
             this.menu.Items.Add(openMeetingItem);
             this.menu.Items.Add(copyMeetingLinkItem);
@@ -246,6 +249,7 @@ protected override void Dispose(bool disposing)
                 this.notifyIcon.Dispose();
                 this.nextMeetingDisplayItem.Dispose();
                 this.secondMeetingDisplayItem.Dispose();
+                this.lastUpdatedDisplayItem.Dispose();
                 this.toggleHoverWindowItem?.Dispose();
                 this.toggleIgnoreFreeFollowingItem?.Dispose();
                 this.menu.Dispose();
@@ -400,6 +404,20 @@ private void UpdateMenuState()
 
             this.secondMeetingDisplayItem.Text = second is null ? string.Empty : NextMeetingSelector.FormatTooltip(second, DateTime.Now);
             this.secondMeetingDisplayItem.Visible = second is not null;
+
+            // Update last updated timestamp line
+            DateTime lastUtc = this.app.GetLastRefreshUtcForUi();
+            if (lastUtc != default)
+            {
+                DateTime local = lastUtc.ToLocalTime();
+                this.lastUpdatedDisplayItem.Text = $"Updated {local:MM/dd ddd h:mm tt}";
+                this.lastUpdatedDisplayItem.Visible = true;
+            }
+            else
+            {
+                this.lastUpdatedDisplayItem.Visible = false;
+            }
+
             string calendarUrl = this.app.GetCalendarUrlForUi();
             if (this.toggleHoverWindowItem is not null)
             {

tests/ComingUpNextTray.Tests/ConditionalFetchTests.cs

@@ -0,0 +1,97 @@
+using System;
+using System.Net;
+using System.Net.Http;
+using System.Threading;
+using System.Threading.Tasks;
+using ComingUpNextTray.Services;
+using Xunit;
+
+namespace ComingUpNextTray.Tests
+{
+    public sealed class ConditionalFetchTests
+    {
+        private sealed class StubHandler : HttpMessageHandler
+        {
+            private readonly Func<HttpRequestMessage, HttpResponseMessage> responder;
+            public StubHandler(Func<HttpRequestMessage, HttpResponseMessage> responder)
+            {
+                this.responder = responder;
+            }
+            protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+            {
+                return Task.FromResult(this.responder(request));
+            }
+        }
+
+        [Fact]
+        public async Task FirstFetch_NoValidators_ReturnsEntries()
+        {
+            const string ics = "BEGIN:VEVENT\nDTSTART:20250101T130000Z\nEND:VEVENT";
+            using StubHandler handler = new StubHandler(_ => new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(ics),
+                Headers = { ETag = new System.Net.Http.Headers.EntityTagHeaderValue("\"v1\"") }
+            });
+            using CalendarService service = new CalendarService(handler);
+            IReadOnlyList<ComingUpNextTray.Models.CalendarEntry> entries = await service.FetchIfChangedAsync(new Uri("https://example.com/calendar.ics"));
+            Assert.NotEmpty(entries);
+            Assert.True(service.HasChangeValidators);
+        }
+
+        [Fact]
+        public async Task SecondFetch_NotModified_ReturnsEmpty()
+        {
+            int call = 0;
+            using StubHandler handler = new StubHandler(_ =>
+            {
+                call++;
+                if (call == 1)
+                {
+                    return new HttpResponseMessage(HttpStatusCode.OK)
+                    {
+                        Content = new StringContent("BEGIN:VEVENT\nDTSTART:20250101T130000Z\nEND:VEVENT"),
+                        Headers = { ETag = new System.Net.Http.Headers.EntityTagHeaderValue("\"v2\"") }
+                    };
+                }
+                return new HttpResponseMessage(HttpStatusCode.NotModified)
+                {
+                    Headers = { ETag = new System.Net.Http.Headers.EntityTagHeaderValue("\"v2\"") }
+                };
+            });
+            using CalendarService service = new CalendarService(handler);
+            IReadOnlyList<ComingUpNextTray.Models.CalendarEntry> first = await service.FetchIfChangedAsync(new Uri("https://example.com/calendar.ics"));
+            Assert.NotEmpty(first);
+            IReadOnlyList<ComingUpNextTray.Models.CalendarEntry> second = await service.FetchIfChangedAsync(new Uri("https://example.com/calendar.ics"));
+            Assert.Empty(second); // indicates unchanged
+        }
+
+        [Fact]
+        public async Task Modified_ReturnsNewEntries()
+        {
+            int call = 0;
+            using StubHandler handler = new StubHandler(_ =>
+            {
+                call++;
+                if (call == 1)
+                {
+                    return new HttpResponseMessage(HttpStatusCode.OK)
+                    {
+                        Content = new StringContent("BEGIN:VEVENT\nDTSTART:20250101T130000Z\nEND:VEVENT"),
+                        Headers = { ETag = new System.Net.Http.Headers.EntityTagHeaderValue("\"v3\"") }
+                    };
+                }
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent("BEGIN:VEVENT\nDTSTART:20250102T130000Z\nEND:VEVENT"),
+                    Headers = { ETag = new System.Net.Http.Headers.EntityTagHeaderValue("\"v4\"") }
+                };
+            });
+            using CalendarService service = new CalendarService(handler);
+            IReadOnlyList<ComingUpNextTray.Models.CalendarEntry> first = await service.FetchIfChangedAsync(new Uri("https://example.com/calendar.ics"));
+            IReadOnlyList<ComingUpNextTray.Models.CalendarEntry> second = await service.FetchIfChangedAsync(new Uri("https://example.com/calendar.ics"));
+            Assert.Single(first);
+            Assert.Single(second);
+            Assert.NotEqual(first[0].StartTime, second[0].StartTime);
+        }
+    }
+}