[fix][broker] Fix backlog clearing for unloaded namespace bundles

[zhanghaou]

Fixes #20706

Motivation

Clearing backlog for a namespace/bundle should work even when the bundle is not loaded on any broker.

Modifications

1. Convert namespace backlog clear paths to async internal methods and update v1/v2 admin resources to use async-response flow consistent with existing patterns (e.g. getMaxProducersPerTopic).
2. Ensure bundle backlog clearing can operate when bundles are unloaded by enumerating persistent topics from metadata and loading topics as needed.
3. Add tests to verify backlog clearing on unloaded bundles (all subscriptions and per-subscription cases).

Verifying this change

• Make sure that the change passes the CI checks.

(Please pick either of the following options)

This change is a trivial rework / code cleanup without any test coverage.

(or)

This change is already covered by existing tests, such as (please describe tests).

(or)

This change added tests and can be verified as follows:

(example:)

• Added integration tests for end-to-end deployment with large payloads (10MB)
• Extended integration test for recovery after broker failure

Does this pull request potentially affect one of the following parts:

If the box was checked, please highlight the changes

• Dependencies (add or upgrade a dependency)
• The public API
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

Matching PR in forked repository

PR in forked repository:
zhanghaou#2

[lhotari]

LGTM, thanks for the contribution @zhanghaou

[Copilot]

Pull request overview

This PR fixes a bug where clearing the backlog for a namespace or namespace bundle would silently skip topics whose bundle was not owned by any broker (i.e., unloaded). It refactors four synchronous admin methods into fully-async variants and updates the core backlog clearing logic to fetch topics from metadata (instead of only in-memory loaded topics), loading them on demand when needed.

Changes:

• Introduce internalClearNamespaceBacklogAsync, internalClearNamespaceBundleBacklogAsync, internalClearNamespaceBacklogForSubscriptionAsync, and internalClearNamespaceBundleBacklogForSubscriptionAsync (replacing their synchronous counterparts) in NamespacesBase.
• Update v1 and v2 Namespaces REST handlers to use @Suspended AsyncResponse + the new async methods, consistent with existing async patterns (e.g., getMaxProducersPerTopic).
• Add integration tests verifying bundle backlog clearing works on unloaded bundles (both all-subscriptions and per-subscription cases).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
NamespacesBase.java	Core logic: new async backlog-clear methods, clearBacklogAsync now queries metadata for all persistent topics and filters by bundle, with readOnly=false to allow acquiring ownership of unloaded bundles
v2/Namespaces.java	REST layer updated to async response pattern for all four backlog-clear endpoints
v1/Namespaces.java	Same async refactoring applied to v1 (deprecated) endpoints
AdminApiTest.java	Two new parameterized integration tests verifying unloaded bundle backlog clearing (all subscriptions and per-subscription)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 65.97222% with 49 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.73%. Comparing base (735b429) to head (3f022dc).

Files with missing lines	Patch %	Lines
...pache/pulsar/broker/admin/impl/NamespacesBase.java	61.16%	24 Missing and 16 partials ⚠️
.../org/apache/pulsar/broker/admin/v2/Namespaces.java	74.07%	7 Missing ⚠️
...ache/pulsar/broker/namespace/NamespaceService.java	85.71%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #25272      +/-   ##
============================================
- Coverage     72.95%   72.73%   -0.22%     
+ Complexity    34343    34259      -84     
============================================
  Files          1954     1954              
  Lines        154715   154732      +17     
  Branches      17704    17706       +2     
============================================
- Hits         112871   112548     -323     
- Misses        32838    33129     +291     
- Partials       9006     9055      +49     

Flag	Coverage Δ
inttests	25.80% <0.00%> (-0.37%)	⬇️
systests	22.58% <0.00%> (-0.03%)	⬇️
unittests	73.71% <65.97%> (-0.22%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
.../org/apache/pulsar/broker/admin/AdminResource.java	77.32% <ø> (+0.26%)	⬆️
...ache/pulsar/broker/namespace/NamespaceService.java	73.33% <85.71%> (-0.04%)	⬇️
.../org/apache/pulsar/broker/admin/v2/Namespaces.java	91.65% <74.07%> (-0.01%)	⬇️
...pache/pulsar/broker/admin/impl/NamespacesBase.java	78.83% <61.16%> (-0.22%)	⬇️

... and 81 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[zhanghaou]

Add a new method getOwnedPersistentTopicListForNamespaceBundle to reduce blocking call.

[coderzc]

LGTM

[coderzc]

@zhanghaou Please rebase on master.

[zhanghaou]

@coderzc @lhotari PTAL, rebase the master and convert validation synchronous throws to failed futures in async methods. Personal CI passed.