livepeer / livepeer/go-livepeer
Document O selection and reliability strategy
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 586
- Forks
- 226
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 19
Description
**Is your feature request related to a problem? Please describe.**
We're starting to accumulate quite a bit of "oral knowledge" on how the O selection mechanism works, the overall reliability strategy, and the justifications for that strategy. It would be good to document those.
There are two possible audiences here that the documentation should be addressed towards: developers working on the goclient, and users of the goclient (B/O/T operators).
This probably means separate sections or separate pages; it would be good to clearly identify the target audience when writing.
**Describe the solution you'd like**
A `docs/reliability.md` page describing our accumulated knowledge and strategy.
**Describe alternatives you've considered**
Separate pages, one for developers and another for users. Whichever is more appropriate probably depends on the depth of each.
It may be enough to begin with a high-level description suitable for users, then drill down into details suitable for developers.
**Additional context**
Some things to describe, off the top of my head:
* Reliability and load control: round robin, retries
* Backpressure: One segment in flight
* Load balancing: `-maxSessions`
* BroadcasterManager list refresh intervals https://github.com/livepeer/go-livepeer/pull/806#discussion_r274187906
* Front running prevention: External storage prefix for multi-O
* Justification for each of these mechanisms, the problem(s) they solve and how
(this list is not exhaustive)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the goclient's existing documentation and the BroadcasterManager refresh-interval discussion in pull request #806. Create docs/reliability.md covering round robin, retries, one segment in flight, -maxSessions, list refresh intervals, and the external storage prefix for multi-O, with the rationale for each and clear audience sections. Done means the accumulated reliability and load-control strategy is documented for both operators and developers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100