[Doc] Client Specification Document
- Dominant language
- Java
- Stars
- 15.3k
- Forks
- 3.8k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 160
Description
### Search before asking
- [X] I searched in the [issues](https://github.com/apache/pulsar/issues) and found nothing similar.
### What issue do you find in Pulsar docs?
Pulsar, like many other distributed systems, is able to achieve scalability by off-loading some responsibilities to clients. This means that many features will include some client component, often non-trivial. For example, in the case of delayed delivery, or DLQs, it is the client's responsibility for handing off messages to the appropriate topic.
This results in complex client behaviours. Each time a new client is implemented, these behaviours must be implemented faithfully, to ensure a consistent feature experience in the Pulsar ecosystem irrespective of client language. However, no single resource exists that describes these client responsibilities in an accessible manner and so client implementation, or even understanding features, requires delving through the Java client code. This problem is compounded by **incomplete protocol documentation** #17258.
### What is your suggestion?
We should write a **client specification** document that is a companion to the [binary protocol specification](https://pulsar.apache.org/docs/next/developing-binary-protocol/). This should capture any non-trivial client-side behaviours that form a component of a Pulsar feature.
#### Methodology
* Audit Pulsar features
* Filter by those that have some component that must be implemented in the client
* Prioritise by feature adoption and then complexity
* Create issues for the documentation of each feature
* Work through issues
### Any reference?
_No response_
### Are you willing to submit a PR?
- [X] I'm willing to submit a PR!
Contributor guide
Research direction
Start by reading the binary protocol specification and auditing Pulsar features for non-trivial client-side behavior, using the Java client code where needed. Prioritize candidate features by adoption and complexity, create documentation issues for them, and define the client specification as complete when those responsibilities are documented as a companion to the protocol specification.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- distributed-systems, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100