Implement cross-process coordination to reduce HTTP polling and stay within Azure rate limits

[Copilot]

This PR implements a cross-process coordination system to address the rate limiting issue where multiple processes polling the Azure Scheduled Events endpoint can exceed the 5 requests/second per VM limit.

Problem

Currently, every process that uses this library queries the HTTP endpoint individually:

• Rate limit: 5 requests/second per VM
• Multiple processes = potential rate limit violations
• Inefficient resource usage with duplicate HTTP calls

Solution

Implemented a file-based caching system with Named Mutex coordination:

Architecture

• Global Lock: Uses Named Mutex (Azure.ScheduledEvents.GlobalLock) for cross-process coordination
• Coordinator Process: First process to acquire lock becomes HTTP poller (every 10 seconds)
• Client Processes: Read from shared cache file with 30-second expiry
• Automatic Failover: Periodic lock checking (every 30 seconds) ensures takeover if coordinator dies

Key Components

• ScheduledEventsCoordinator: Manages lock acquisition, HTTP polling, and file caching
• File Cache: JSON data stored in %TEMP%\azure-scheduled-events-cache.json
• Fallback Logic: Direct HTTP calls when coordination fails
• Modified ScheduledEventsClient: Now uses coordinator instead of direct HTTP

Benefits

✅ Reduces HTTP requests from N processes to 1 per VM
✅ Stays within rate limits (5 requests/second per VM)
✅ Zero breaking changes - existing API unchanged
✅ Fault tolerant - automatic failover when coordinator process dies
✅ Production ready - comprehensive error handling and logging

Usage

No code changes required - the existing API works identically:

var services = new ServiceCollection()
    .AddScheduledEventsClient()  // Now includes coordination
    .BuildServiceProvider();

var client = services.GetRequiredService<ScheduledEventsClient>();
var events = await client.GetScheduledEvents(); // Uses coordination automatically

Testing

Added comprehensive test suite:

• Coordinator instantiation and cleanup
• Multiple coordinator instance coordination
• Cache file operations and expiry
• HTTP timeout handling
• Failover scenarios
• Backward compatibility validation

All tests pass successfully, demonstrating robust coordination behavior.

Fixes #8.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.