[improve][broker] Documentation for AuthenticationState contract

[michaeljmarshall]

PIP 97: #12105

Motivation

While working on PIP 97, I noticed that we do not have a clear contract for the AuthenticationState interface. We use the interface in one way in the ServerCnx class, but some of our official implementations do not align with the usage and the API. The PR itself provides my proposed authoritative documentation.

When we agree on the content of this PR, I will follow up with some changes to the TokenAuthenticationState class and potentially others.

Modifications

• Add documentation on how the AuthenticationState interface will be used by Pulsar.

Verifying this change

I have studied the code closely to understand how it works, and more importantly, how it should work.

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

This change could affect how plugins interact with the AuthenticationState object.

Documentation

• doc

This is a documentation change.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.87%. Comparing base (334c3a5) to head (1709da8).
⚠️ Report is 2982 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #19283      +/-   ##
============================================
+ Coverage     47.04%   52.87%   +5.83%     
- Complexity     9190    22399   +13209     
============================================
  Files           607     1824    +1217     
  Lines         57677   136687   +79010     
  Branches       6007    15044    +9037     
============================================
+ Hits          27132    72275   +45143     
- Misses        27598    56913   +29315     
- Partials       2947     7499    +4552     

Flag	Coverage Δ
inttests	22.47% <ø> (?)
systests	24.82% <ø> (?)
unittests	47.08% <ø> (+0.04%)	⬆️

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

Files with missing lines	Coverage Δ
...sar/broker/authentication/AuthenticationState.java	9.09% <ø> (ø)

... and 1365 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.