Rainway Network

The Rainway Network is how apps using Rainway find each other.

Each entity connected to the network is a Peer, identified by its Rainway Peer ID.

Peers on the Rainway Network exchange connection requests and session information in order to establish a peer-to-peer connection. Once a connection between Peers has been established, they no longer use the Rainway Network to communicate.

First steps

In order to connect to the Rainway Network, a Public Key must be specified. To obtain your first Public Key, use the following steps:

1. Sign in to The Hub and navigate to the API Keys section.
2. Create a new Key - feel free to name it whatever you'd like.
3. Note that both a Public and Secret Key are generated. We'll talk more about Secret Keys later, in Rainway API: Getting Started.
4. Use the Public Key below, when connecting to Rainway services.

Connecting to the Rainway network is done with rainway.connect() which returns a Promise that will resolve if the connection succeeds, or reject if it fails. You can see an example of that below:

📘

By the way, externalId is a string identifying a user or entity within your app. It's optional, but can be used to easily tie an incoming connection back to a user in your app, if you'd like.

import rainway from "@rainway/web";

// listen for Rainway component log events
rainway.addEventListener("log", (level, target, message) => {
  console.log(`[${level}] ${target}: ${message}`)
});

// connect to Rainway services
const conn = await rainway.connect({ apiKey: "your-org-api-key", externalId: "Jane Doe" });

At this stage, conn is ready to use, and we're connected to the Rainway network. It's time to get connected peer-to-peer!

Peer IDs

The first time a connection is established from a device, a Peer ID is generated and stored in localStorage. This is a 63-bit number that uniquely identifies the device on the Rainway Network.

To connect your device to another over Rainway, you must know the other's Peer ID. A device's Peer ID is exposed through the id property.

// building on the above sample
// retrieve your assigned peer id from the rainway services connection
const peerId = conn.id;

How you store Peer IDs will vary depending on how your application uses Rainway. For example, you could store them in your application database to let Peers know about each other.

Connecting to a Peer

Once you have a Peer's ID, you can call connect to establish the connection:

// building on the above sample
// connect to another peer (identified by 123456) on the Rainway network
const peer = await conn.connect(BigInt(123456));

This promise will resolve if the Peer accepts your connection request, otherwise it will reject.

To test against the example C# host app, try running it on another device and connecting from your web app to its peer ID.

Multiple Peers

Rainway lets you connect to multiple Peers at a time. The peers property on RainwayConnection tracks every established Peer, mapped by their Peer IDs.