feat(progress): Add debouncing to prevent spam from rapid updates

[jellingson]

Add debouncing to progress plugin to prevent notification spam

Problem

The progress plugin currently posts to Discord immediately when changes are detected. This causes spam when Brandon's website updates multiple times in quick succession (e.g., update → revert → update), flooding the Discord channel with
notifications.

Solution

Added a configurable debounceDelay option that waits for a specified period after the last detected change before posting. This ensures only the final state is posted after rapid changes settle.

Changes

• New config option: debounceDelay (e.g., "2m", "30s") - optional, defaults to immediate posting
• Enhanced offset format: Stores timing and pending change information for debouncing
• Backward compatibility: Automatically handles legacy offset format
• Updated documentation: README reflects new configuration options

Usage

yaml
connectors:
brandon-progress:
plugin: progress
config:
url: https://brandonsanderson.com
message: The progress bars on Brandon's website were updated!
debounceDelay: "2m" # Wait 2 minutes after last change

Testing

Tested with rapid successive runs (modifying the saved offset in between) - no immediate posts during changes, only posts after delay expires.

[marvin-roesch]

Thanks for this submission! There's only a few things I have to note, one of which will require some work on my part first (unless you also want to tackle the offset parsing).

[jellingson]

Summary of changes:

• Changed to time.Duration with automatic YAML parsing
• Added legacy offset migration via custom JSON unmarshaling
• Added comprehensive test suite covering all scenarios
• Fixed to keep original progress when debouncing

[marvin-roesch]

Thanks for these changes, especially the unit tests! I think the logic is all good now, but I still find a little hard to follow. See my suggestion to maybe improve that.

[marvin-roesch]

Thanks for adding tests, I was a bit too lazy to introduce them so far, but it definitely makes sense at this level of complexity.

However, I think it would be good to actually check the content of the posted messages here to verify that the progress reports are correctly done. Could separate the actual reporting into its own struct with a method that accepts a ProgressDiff so that that can be mocked for easier testing, too.

[jellingson]

Added discord message validation. I'm sure there is a better way to do it, but this is what I could come up with.

[jellingson]

Made a bunch of changes to make the logic clearer. Mainly

• Changed the ProgressOffset struct to keep track of the PostedState, ObservedState and DebounceStart
  • Removed PendingDiff because it required both recalculating the difference between Progress and the website + checking if that diff was the same as the PendingDiff
  • Removed PendingChange because it is unnecessary (as you pointed out)
• Added functions to ProgressOffset to make it clear what we are checking and to remove most of the nested if statements (there is one error case when posting I couldn't figure out how to remove)
• Refactored tests to make the scenarios easier to read and understand
• Added discord message validation

[jellingson]

Fixed a stupid mistake I made in the previous revision and added comments in the test scenarios to better explain what it is testing.