Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FAQ entries on how to use ion-sfu #496

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

FAQ entries on how to use ion-sfu #496

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d8e82bb
FAQ entries on how to use ion-sfu
grahamking Mar 29, 2021
09d42c7
feat: updating readme to reflect golang API
Apr 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,45 @@
# Frequenty Asked Questions

### Can I / should I build on ion-sfu?

Ion-sfu is considered "stable beta" and you can safely build on it. Many features are still under development, and the API is subject to change rapidly in future releases. If you want to build production-ready apps with ion-sfu, you need a strong grasp of WebRTC fundamentals and modern web development, and some experience with pion and golang is strongly recommended. You'll need to design your own Application Layer, responsible for transmitting signalling messages, validating client input, authenticating your users, administering room membership, and orchestrating scaling decisions.

### Is ion-sfu actively maintained or supported? Can I get help?

Ion-sfu actively developed and supported by an awesome community of volunteers! As an open source project in the pion community, the people who support this project are just the same volunteers who've made time to build and release it. You can join us in the gophers slack in #ion, we have a helpful and positive community and many people are always glad to talk about the project! Once you learn and use ion-sfu, you can help make the community better, too!

### Which API should I use?

There are many strong opinions about the answer to this question!

- Library API - Use ion-sfu as a library. Start by embedding the SFU struct. Use the grpc or jsonrpc examples as a guide.

- JSONRPC - a websocket interface for bi-directional json messages; it is a simpler and lighter protocol. It is very easy to parse and handle the messages in any language. The internal javascript examples mostly use jsonrpc because it is easy to read and understand.

- GRPC - uses bi-directional message streams and protobufs. The client code is automatically generated for consumers, with strong typing definitions. Typically, no manual message parsing is required.

- "All RPC" - package is jsonrpc + grpc at the same time, for convenient testing between a cmd line publisher and a bowser subscriber (or vice-versa).

**None of these** are designed for end-users to connect directly to them. Always build an Application Server, either by using ion-sfu as a library, or using the grpc API to talk to a local ion-sfu. (?? Is using internal GRPC "officially supported"?)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tarrence + Orlando, can you 2 confirm whether using the grpc API (internally, after validating SDPs in an upstream application server) should currently be considered a "supported" usecase? Can we safely advise people to use the grpc or jsonrpc docker images internally as long as input is sanitized?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should move the included signaling to be "examples" and the batteries included deployment should be "ion"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I think that represents a major change needed to the above advice, we will have to reword it to avoid saying jsonrpc/grpc are official interfaces people should build upon, I will mark this as a Draft and we can try to adjust the verbiage this week

Copy link
Collaborator

@tarrencev tarrencev Mar 30, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. The reason i think this is the right direction is there are a million different ways to signal and it is very dependent on your goals. I would prefer to remove it as a source of distraction. Then it will hopefully be more clear that authors should extend their own implementation rather than try to generalize the examples to other use cases.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I took some time to think about it and I understand why it seems like the best option - and the GoLang API is undoubtedly the strongest one to support. It is also the hardest to use, and adds a new requirement that everyone write GoLang to use ion-sfu.

I have to say, I do see this as breaking support for most existing projects built on ion-sfu -- including mine. Granted, by moving the entrypoints to examples/ you are leaving a backup option, but I feel like you are suggesting we deprecate "official" support for 2 APIs that most people have been building on. Tarrence, you yourself told me I should build a python client to talk to SFU over grpc... I know this means lots of re-thinking and re-structuring and re-work for me and many others.

I tried to maintain my own SFU wrapper in golang, but it was a source of constant frustration and bugs, I abandoned the code after wasting 4mo evenings and weekends on the effort, I much preferred to be able to write an API client in a language I am familiar with. Mainstream support for grpc and jsonrpc has been implied (at least since the early versions of the codebase), by both the name of the folder they live in and their repeat appearance in related SDK project examples, and further reinforced by the prevailing discussions in the slack channel. I'm sad nobody spoke up and said "don't build on this grpc entrypoint, it should not be an official entrypoint" much sooner.

I'm always happy to see ion-sfu become a better project, but as a maintainer who devotes most of his resources to helping teach newcomers and share knowledge, I expect I'll be dealing with frustrated and sad users. We'll be best off to add a section to the FAQ "What happened to cmd/signal?" at the very least. I'll prepare the necessary changes.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand you concern and I definitely don't think that we should kill it. We should still continue maintaining it in its current form. My main point is to move away from it being seen as a signaling layer that competes with i.e. janus or jitsi signaling. Our goal is to move almost everything to happen over webrtc (using datachannels) so the out of bound signaling will be very simple. Anything on top will be application specific. I know it is frustrating to have a moving target, but we are all learning together and make mistakes. I think we would change a lot about how we do signaling if we knew then what we know now.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe deprecating this is the wrong move. I do not understand why we're reluctant to say its supported because nearly all the web examples are built on it. From my perspective jsonrpc should be supported as a first class project. We are already doing this at tandem, and we're happy to continue supporting it in our codebase. I'm happy to think through and write up a more formal proposal on how to handle this at the org level, but pushing everyone to ion which is way more complex and heavy than jsonrpc is the wrong move in my opinion.


### What do you mean by "Application Server"?

Ion-sfu is designed to be a building block that forwards video streams, not a finished product. It contains no mechanisms for validating user accounts or published streams; you must ensure that UIDs are not duplicated or spoofed. You must parse all incoming Offer signals to parse the SDP, and determine if the expected audio codecs are being sent, or the video is of a supported resolution. If a node has too many users, maybe you want to shard your sessions across a cluster of ion-sfu -- scaling decisions are left up to you.

If you don't want to build an Application Server, we officially recommend the pion/ion project, but please note that many of the features described above are still Work-in-Progress in the ion project - which is alpha/pre-release quality - and we are eager for your contributions to our community!

### Are the jsonrpc/grpc signalling servers in cmd/signal/ going to continue to be supported?

The provided jsonrpc and grpc APIs are provided for testing purposes only. The official ion-sfu API is via golang imports; you can create a new SFU service by embedding the SFU struct in just a few lines of code, with any signalling interface you prefer. We have provided examples of jsonrpc and grpc servers, and the docker images to use those services internally, but they should not be exposed to accept unvalidated client input.
"Signalling will always be pluggable" -- tarrencev

### How do I build the client?

Use one of the official SDKs:
- Browser: [ion-sdk-js](https://github.com/pion/ion-sdk-js)
- Go application: [ion-sdk-go](https://github.com/pion/ion-sdk-go)
- Mobile: [ion-sdk-flutter](https://github.com/pion/ion-sdk-flutter)

### How can I join a session receive-only, without sending any media?

If you are using [ion-sdk-js](https://github.com/pion/ion-sdk-js) this should work by default. If not, read on.
Expand Down