Host nodes
A host joins the session without media and offers its gateway.
Many sessions already have a machine that hosts them: an app server that runs the session, a community server, or the desktop app of the participant who started the session. Freehop can make that machine the session's gateway. It joins the room as a gateway member, sends no media of its own, and offers its gateway to the members who need it.
An example
Ben and Kai are both on phone hotspots behind carrier NATs that pick a new random port for every destination. On their own they cannot connect: the home-lab test scenario hard-pair shows exactly that. Now they join a session that runs on a community server with a public address, and the server calls hostSession() for its room:
- The server joins the room through the gates with an id that starts with
gw_. - Ben and Kai each greet it with a sealed envelope. Only then does it send each of them its gateway address and a credential minted for that person.
- Ben and Kai first try each other directly. After 5 seconds (plus one grace period while checks are getting answers) their pair moves to the session phase and adds the host node's gateway.
- Both allocate a relay on the host node, and their media meets there. The path is reported as
relayvia the host node.
In the home-lab network tests this was scenario hard-pair-host-node: three passes out of three with Chromium, plus a cross-engine pass with Firefox and WebKit as the two participants, at 62 to 73 KB of gate traffic per run. The same route worked in simulated profiles for two participants on different UDP-blocking office networks (udpblock-pair-host-node), who reached the host node with TURN over TCP.
What a gateway member does, and does not do
- It captures no media of its own. It relays encrypted media packets for participants, without decoding or re-encoding them.
- It only helps members. A gate's roster is just a hint. The host node hands out credentials only after a peer proves room membership with an authenticated envelope, and each credential is minted for that peer and that room.
- Its role must be earned. The
gw_prefix of its id is only a hint. Clients accept the gateway role only from the member's sealed capabilities, and accept at most 4 gateway members per room. - It follows kicks. When the room rotates its secret, the host node moves to the new room tag and revokes every old-epoch credential and allocation, including aliases.
- It keeps credentials fresh. It renews them well before they expire.
Who should be a host node
A host node spends its own upload on the pairs that need it. That is why the right host is a machine that already belongs to the session:
| Good host | Why |
|---|---|
| A community server that runs the session | It hosts the session anyway, and its operator chose to |
| The desktop app of the participant hosting the session | It belongs to the call and can open its front door |
| Your application server | You choose to carry session media and budget for its bandwidth and compute |
For a small meeting room or an embedded call, choose a reachable host from the infrastructure available to that session. A participant-owned host contributes their upload; a server you rent uses your hosting budget.
Using it
import { hostSession } from 'freehop/host';
const host = await hostSession(ticket); // a ticket for the room, issued by your authority
if (!host.available) {
// No public address and no router mapping: this machine has nothing to offer.
}
await host.update(nextTicket, { dropped: [peerId] }); // after a kick
await host.close(); // says goodbye and revokes the room
The host node needs to be reachable from outside: either a public address, or a router that grants a port mapping. One gateway per process serves every room the process hosts. Host sessions lists the options.
Next
When nobody in the session has a gateway, forwarding is the last step that stays inside the call.