[management] Add gRPC update debouncing mechanism

[pappz]

Implements backpressure handling for peer network map updates to efficiently handle rapid changes. The first update is sent immediately; subsequent rapid updates are coalesced, ensuring that only the latest update is sent after a 1-second quiet period.

Intermediate changes do not need to be applied, so the focus is on processing only the final update in the queue.
This also fixes lost network updates on the producer side. The network map producer should not depend on network-related layers. Todo: set the channal size to 1 and set it to blocker.

Describe your changes

Issue ticket number and link

Stack

Checklist

• Is it a bug fix
• Is a typo/documentation fix
• Is a feature enhancement
• It is a refactor
• Created tests that fail without the change (if possible)

By submitting this pull request, you confirm that you have read and agree to the terms of the Contributor License Agreement.

Documentation

Select exactly one:

• I added/updated documentation for this change
• Documentation is not needed for this change (explain why)

Docs PR URL (required if "docs added" is checked)

Paste the PR link from https://github.com/netbirdio/docs here:

https://github.com/netbirdio/docs/pull/__

Summary by CodeRabbit

• Infrastructure

  • Introduced a per-peer update debouncing mechanism to reduce redundant transmissions, improve backpressure and coalesce rapid updates for streaming syncs.

• Tests

  • Added comprehensive test coverage verifying immediate send behavior, coalescing of rapid updates, timer-driven flushes, cleanup, and various edge cases.

[coderabbitai]

📝 Walkthrough

Walkthrough

A per-peer UpdateDebouncer was added and integrated into the gRPC server update loop. Updates are either sent immediately (first after a quiet period) or coalesced and flushed after a debounce interval; debouncer lifecycle and timer-driven flushes are managed per connection.

Changes

Cohort / File(s)	Summary
Update Debouncer Core management/internals/shared/grpc/update_debouncer.go	New exported UpdateDebouncer type and methods (NewUpdateDebouncer, ProcessUpdate, TimerChannel, GetPendingUpdate, Stop) implementing per-peer backpressure: immediate-first-send, coalescing of rapid updates, timer lifecycle and pending-update retrieval.
Debouncer Tests management/internals/shared/grpc/update_debouncer_test.go	New comprehensive test suite (~350 lines) validating immediate send, coalescing, timer firing, GetPendingUpdate semantics, Stop cleanup, high-frequency sequences, and edge cases.
Server Integration management/internals/shared/grpc/server.go	handleUpdates now instantiates and uses UpdateDebouncer per peer: routes incoming updates through ProcessUpdate, handles immediate sends vs. deferred timer-driven flush via TimerChannel+GetPendingUpdate, and ensures debouncer stop/cleanup on exit.
Test orchestration update management/server/management_test.go	Test TestSync10PeersGetUpdates updated to track per-peer observed counts with mutex-protected state, wait for debounced observations, add debounce-aware sleeps/timeouts, and adjust completion signaling to match debounced update delivery.

Sequence Diagrams

sequenceDiagram
    participant Peer
    participant Server
    participant Debouncer
    participant Timer

    Peer->>Server: Send Update (1st)
    Server->>Debouncer: ProcessUpdate(msg)
    Debouncer->>Debouncer: start timer
    Debouncer-->>Server: return true (send immediately)
    Server->>Peer: Send Update immediately

    Peer->>Server: Send Update (2nd, rapid)
    Server->>Debouncer: ProcessUpdate(msg)
    Debouncer->>Debouncer: set pending, reset timer
    Debouncer-->>Server: return false (defer)

    Peer->>Server: Send Update (3rd, rapid)
    Server->>Debouncer: ProcessUpdate(msg)
    Debouncer->>Debouncer: replace pending, reset timer
    Debouncer-->>Server: return false (defer)

    Timer->>Debouncer: Timer fires (quiet period)
    Debouncer-->>Server: TimerChannel signal
    Server->>Debouncer: GetPendingUpdate()
    Debouncer-->>Server: return pending update (last one)
    Server->>Peer: Send pending update

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• [management] move network map logic into new design #4774: Modifies gRPC server update flow and update handling; directly related to per-peer update message handling and debouncer integration.

Poem

🐰 A hop, a timer, patience kept so fine,
First update leaps, the rest in line,
I nibble noise and hold the rest,
When quiet comes I send the best,
Coalesced and calm — updates align.

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The pull request description addresses the primary changes but lacks structured compliance with the template, missing detailed issue/stack information and incomplete checklist reasoning.	Add issue ticket number and link, provide stack branch information, explain why tests were not created if applicable, and clarify the networking layer dependency concern mentioned in the TODO.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: introducing a gRPC update debouncing mechanism for managing backpressure in peer network map updates.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/grpc-debounce

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud