feat(pubsub): add APIs to shutdown subscriber

[dbolduc]

Most of the work for #5024 (the rest are cleanups)

Provide a way for applications to both signal and await a shutdown of a subscriber message stream.

---

Docs look like:

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.98%. Comparing base (c295557) to head (54c485d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5257   +/-   ##
=======================================
  Coverage   97.98%   97.98%           
=======================================
  Files         215      215           
  Lines       44904    44904           
=======================================
  Hits        43999    43999           
  Misses        905      905           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[suzmue]

nit: PR title description

The PR title could be more descriptive about what this PR is actually doing. maybe "feat(pubsub): make subscriber shutdown public with documentation" or something

There are two PRs that have the same title (minus type) which makes it harder to browse the history to identify which PRs are responsible for what.

[dbolduc]

nit: PR title

Fixed.