livepeer / livepeer/go-livepeer

Document O selection and reliability strategy

Open
#868 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: broadcasting help wanted status: backlog type: documentation
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.