Connection

PulseBeam simplifies WebRTC connections, managing state, reconnections, and common edge cases. By abstracting the complexity, establishing a connection looks like:

peer.start();
peer.connect(otherPeer);

Connection State

To build responsive UIs that adapt to dynamic network, connection, and state conditions, you need to know the connection state. Specifically, the RTC Peer Connection State describes this connection state, representing the underlying WebRTC Peer connection state.

Accessing state

You can listen to underlying WebRTC connection state change with callback onconnectionstatechange or get current state connectionstate():

peer.onsession = (session) => {
  session.onconnectionstatechange = (state) => console.log(`WebRTC Connection state changed to: ${state}`);
  console.log(`The WebRTC connection state right now is: ${session.connectionstate()}`);
};

Understanding the State

Connection state flowchart

Note: This flowchart provides a high-level overview of typical behavior. It is meant to help you understand and conceptualize states and their meaning. WebRTC connections can exhibit unexpected transitions and/or flakiness.

Peer SDK insulates you from some flakiness in connection state, with shimming, polyfills, and auto retries on top of existing browser WebRTC implementation. As well as handling reconnection in recoverable states.

If you have any questions or comments, chat with us!

Expected State Transition Flows

Here are some expected UI flow snip bits. Here are how you should think about isolated sections of the connection sate

Connection Establishment Happy Path

new → connecting → connected

Broken Connection to Auto Recovery

connected → disconnected (auto retry loop) → connecting → connected

Broken Connection to Unrecoverable Detected

connected → disconnected (auto retry loop) → failed (max retry or timeout reached) → closed (automatically closed due to failed state)

Connection to Close Initiated by a Peer

connected → closed (peer.close())

Transitions and Flows in Your Application

Transitions should be smooth to avoid jarring UX, with clear differentiation between temporary (e.g., disconnected) and permanent (e.g., failed) states.

Example State-to-UI Summary Table

While your UI/UX will be highly application-dependent. The table below is meant to be as a learning resource and potentially a starting place. For fleshing out and understanding your UI with WebRTC.

Connection State	Suggested UI Elements	Desired User Action
`new`	Loading spinner, “Setting up connection…”	Wait for connection
`connecting`	Loading spinner, “Connecting to peers…”	Wait for connection
`connected`	Green badge, full experience enable	Access and interact with application
`disconnected`	Loading spinner, “Attempting to reconnect…”	Wait for reconnection or retry options
`failed`	Error message, troubleshooting options	Retry button, guide for troubleshooting
`closed`	Confirmation message	Option to restart connection

Best Practices

Transitions: Smoothly animate transitions between states to avoid jarring experiences.
Error Handling: Clearly differentiate between temporary (disconnected) and permanent (failed) issues.
Feedback Loop: Use tooltips or messages to keep users informed, particularly during connecting and disconnected states.
Accessibility: Use visual indicators (e.g., colors/icons) alongside textual cues for universal understanding.
Timeouts: Consider handling long connecting or disconnected states gracefully, e.g., by prompting the user after a timeout.

By carefully mapping connection states to user-friendly labels and actionable UI elements, you ensure a polished experience that minimizes confusion and frustration for your users.

We wish you the best and would love to chat and see what you build, connect with us!

Handling Token TTL

Tokens govern user access to PulseBeam’s platform. Including session lifetime.

You define token TTL (expiry), see Security for more information on TTL.

When a token expires and the user wants to maintain a connection, you should recreate peers and connections.

Scenarios to Consider:

Token Expiration During Active Session: If a token expires mid-session, the connection will terminate. Proactively monitor and refresh tokens to prevent disruptions.
Session Expiry: Upon session expiration, invalidate the peer and establish a new connection post-refresh.

Best Practices:

Monitor token TTL and current time
Reinitialize peers upon token refresh.
Handle reconnections gracefully during token transitions to avoid disrupting user experiences.

What happens when tokens expire during an active session?

The connection will be closed

PulseBeam’s Next Steps

We would love to change this in the future. Likely next improvement would be to add hooks for token refresh.

TODO: Add a demo and sample code here.

If there is enough interest from our community. So share your thoughts!

PulseBeam Peer State

For use cases including token invalidation, you can use PulseBeam Peer State defined in PulseBeam Peer JS SDK.

PulseBeam Peer State

You can listen to the Peer’s state change with a callback onstatechange, get current state with state(), and transition to closed with close():

peer.onstatechange = (state) => {
    console.log(`The peer state changed to: ${state}`);
}
console.log(`The peer's state is: ${peer.state()}`)

PulseBeam Peer State

The PulseBeam State is new or closed. When the state is closed the Peer must be recreated to transition back to new. State must be new to be able to make connections.

Code Samples

React Demo

Learn More

By understanding state and leveraging PulseBeam’s abstractions, you can build robust WebRTC applications with intuitive UI/UX and reliable connection management.