Skip to main content

Introduction

Maglev is a high-performance RPC library with first-class web support and automatic peer-to-peer connection management. Better performance, lower costs

It is strikingly simple to use and you can safely skip this page if you just wish to get started using it. But what lies under the hood allows for some truly unique abilities in the world of browsers. Maglev can be broken down into a few key pieces of technology...

Peer-To-Peer Connection Management#

Connections are an abstract concept in Maglev, but developers don't need to understand any networking intricacies to reap the benefit of Maglev's networking protocol.

Connections#

Connection start life when one Maglev Node is trying to reach another node through a Maglev "Relay". This relay acts similar to how most web "peer to peer" applications work currently: messages are sent from node A through a server before they are sent to node B. This is costly (in server and bandwidth expense) and slow (in latency and bandwidth limits) when all you wanted was to send a message from A to B. It does however allow a Maglev Node to connect almost instantly and reliably to another node and immediately begin sending RPC traffic back and forth.

In the background, Maglev begins negotiating a direct peer-to-peer connection between nodes. This usually results in a route being found that doesn't require a server anywhere in the middle, node A will connect directly to node B. Maglev uses WebRTC Data Channels to achieve this, which themselves use a form of NAT-traversal hole-punching so that neither side needs to expose a public port.

When a connection upgrade is available, Maglev internally switches to it. What's important to note is that this is transparent to developers. Any streaming RPC that was already active will automatically switch over to the new peer-to-peer transport, and packets will be delivered by an internal reliability layer, resulting in consistent behavior regardless of transport.

Multiplexing#

Maglev can use unordered peer-to-peer transports built on top of UDP (provided by WebRTC for web). This means that two (possibly streaming) RPC calls made concurrently won't block one another if a packet is lost in transit. Traditionally, with a ordered-delivery transport like TCP/WebSocket a dropped packet results in Head-of-line Blocking. Not so for Maglev, which will keep one RPC stream alive while another is blocked waiting for a packet re-transmission. This same technology is what allows Maglev to transparently switch between transports.

Peer-to-Peer#

You'll notice we use the term "node" instead of "server" and "client". That's because Maglev allows any node to invoke an RPC on any other node, which means the concepts of a traditional sever/client vanishes. Any node (even a browser) can act as a traditional "server", and any node (even the same node) can act as a "client". To access another node in Maglev you simply grab a reference to it via it's Node ID, then you can start invoking RPCs on it. This is a fundamental paradigm shift from the traditional server/client architecture and is far more flexible.

Remote Procedure Calls (RPC)#

On tops of Maglev's powerful networking stack rests Maglev RPC, which is based on Google Protocol Buffers. There is a great deal of fantastic documentation already out there on Protocol Buffers (protobuf or proto for short) but the core idea behind protobuf is to allow developers to:

  • Use an IDL to define strongly-typed RPC interfaces with forward compatibility called proto3.
  • Generate stub code in many languages (Maglev alpha only supports TypeScript and Javascript for node and web) using the Maglev CLI.
  • Use that stub code along with the Maglev core library to invoke high performance RPCs on any node with an easy to use API.

Enough Talk#

This all sounds complicated, but using Maglev is strikingly simple. Let's jump right in!