Live Queue Tracker UI
Relevant source files
The following files were used as context for generating this wiki page:
The Live Queue Tracker UI is a real-time monitoring system within the Refined GitHub Projects extension that provides visibility into background API operations. Because GitHub Projects V2 mutations must be executed sequentially with delays to avoid rate-limit bans, this UI ensures users can track the progress of bulk edits, deletions, and duplications as they occur in the background service worker.
Sources: README.md:104-106, README.md:189-195
Architecture and Data Flow
The system follows a decoupled architecture where the logic resides in the Background Service Worker and the visualization is handled by a React component injected into the GitHub DOM.
Communication Flow
The background script manages the task queue and broadcasts updates using a messaging protocol. The Content Script listens for these updates and synchronizes a local state store, which drives the QueueTracker component.
The background worker retrieves the user's PAT, builds a sequential task queue, and fires GraphQL mutations with 1-second delays. Progress is broadcast back as queueStateUpdate messages.
Sources: README.md:197-206, src/entries/background/handlers/bulk-handlers.ts:468-482
Component Breakdown
QueueTracker Component
The main container for the tracking UI. It subscribes to the queueStore and renders a collection of ProcessCard components. It is positioned at the bottom-right of the viewport with a fixed z-index for visibility.
Sources: src/components/queue-tracker.tsx:243-268, src/components/queue-tracker.tsx:11-12
ProcessCard Component
This sub-component represents a single background operation (e.g., a Bulk Edit or Bulk Delete). It handles the following logic:
- Progress Calculation: Computes percentage based on
completedvstotaltasks. - Rate Limit Handling: Displays a countdown timer when the background process is paused due to 403 or 429 errors.
- Failure Management: Provides a toggleable list of failed items with specific error messages and a "Retry Failed" action.
- Visual States: Uses different colors for the progress bar (Accent for active, Success for completed, Attention for paused/failed).
Sources: src/components/queue-tracker.tsx:14-118, src/components/queue-tracker.tsx:210-220
State and Data Structures
The UI relies on a specific ProcessEntry structure received from the background handlers.
| Field | Type | Description |
|---|---|---|
processId | string | Unique identifier for the operation session. |
label | string | Human-readable name (e.g., "Bulk update · 5 items"). |
status | string | Current phase (e.g., "Resolving items...", "Done!"). |
completed | number | Number of successful mutations. |
total | number | Total number of tasks in the batch. |
paused | boolean | Flag indicating if the queue is waiting on a rate limit. |
retryAfter | number | Seconds remaining until the process resumes. |
failedItems | Array | List of items that encountered GraphQL or REST errors. |
Sources: src/components/queue-tracker.tsx:14-140, src/entries/background/handlers/bulk-handlers.ts:50-65
Error Handling and Rate Limits
A critical function of the Queue Tracker is managing GitHub's secondary rate limits. Per project guidelines, Promise.all() is strictly forbidden for mutations.
Sequential Processing and Backoff
If a 403 (Abuse) or 429 (Too Many Requests) error is encountered, the background helper triggers a "paused" state. The UI reflects this by showing a warning flash and a countdown.
Failure Logs
When operations fail, the UI allows users to:
- Retry Failed: Sends a new message to the background script containing only the subset of failed IDs.
- Copy Error Log: Copies a formatted list of errors to the clipboard for debugging.
Sources: src/components/queue-tracker.tsx:147-195
The Live Queue Tracker UI acts as the bridge between the asynchronous, rate-limited background processing layer and the user interface, providing essential feedback for long-running bulk operations.