Host sessions
hostSession() makes the machine that hosts a session the session's gateway. It starts (or reuses) a gateway, joins the room through the gates as a gateway member without any media, and offers that gateway to the members with per-peer credentials. Use it on the machine that already hosts the session: your application server, a community server or a participant's desktop app. The host nodes concept page shows when it helps.
import { hostSession } from 'freehop/host';
const host = await hostSession(await authority.ticket('room-42')); // a ticket with no member
console.log(host.available ? `hosting as ${host.id}` : 'not reachable from outside');
// After a kick, follow the rotation:
const { hostTicket } = await authority.kick('room-42', 'user-3');
await host.update(hostTicket, { dropped: [kickedPeerId] });
// When the session ends:
await host.close();
A host node relays media for the pairs that need it. A participant can contribute their connection, or you can host it on your infrastructure and pay for its bandwidth and compute. Gates carry signalling only.
hostSession(ticket, options)
ticket is a ticket object or an encoded ticket string; an invalid ticket throws a TypeError. Issue it with authority.ticket(roomId) without a member, or use the hostTicket that authority.kick() returns.
| Option | Default | Meaning |
|---|---|---|
gateway | 'auto' | 'auto' uses one gateway per process, shared by every hosted room. Pass a gateway from startGateway() to use your own, or null for none. |
gatewayOptions | none | Options for the automatic gateway, as in Desktop (Electron): host, port, relayPortRange, portMapping, externalAddress, credentialTtlSeconds, limits. |
log | none | (event, details) => void. A gateway that cannot start is reported as gateway-unavailable. |
The host object
When the machine cannot be reached from outside (no public address and no router mapping), hostSession() resolves to { available: false } with no-op update() and close() methods, refresh() resolving to false, and stats() returning { available: false }. Otherwise:
| Member | What it does |
|---|---|
available | true |
id | The gateway member's peer id, starting with gw_ |
gateway | The gateway in use |
update(ticket, { dropped }) | Moves to an unexpired newer ticket for the same app and room with a new secret; revokes every old-epoch allocation, including aliases, and adopts the new ticket's gates. The new room is admitted before the old one is torn down, so a refused rotation leaves the host serving and can be retried. Returns false for an invalid update. |
refresh(ticket) | Applies a reissued ticket for the same epoch with a later expiry (fresh gate tokens). Returns false for an invalid refresh. |
drop(peerId) | Revokes one peer's credentials and allocations now |
stats() | { available, epoch, member, gateway }: peers served, envelopes, revocations, mappings and TURN counters |
close() | Says goodbye to the members it served, leaves the gates and revokes every room tag it served |
freehop/host also exports sharedGateway(options) and closeSharedGateway(), for processes that host many rooms and want to manage the shared gateway's lifetime themselves.
available reflects gateway startup, not a continuous external reachability probe. Automatic recovery after router mapping loss or address changes is not yet implemented.
Requirements
- Reachability. A public address, or a router that grants a port mapping (PCP, NAT-PMP or UPnP IGD).
- A WebSocket implementation. The gateway member connects to gates with the runtime's global
WebSocket, which Node.js provides from version 22. - Freehop gates. The gateway member connects through
wss://gates. It does not use tracker gates (bt+wss://), so list at least one Freehop gate in tickets for hosted rooms.
What the host node does on the wire
It joins every Freehop WebSocket gate in the ticket with an id that starts with gw_. When a member greets it with an authenticated envelope, it answers with sealed capabilities that carry role: "gateway" and credentials minted for that member alone. It captures no media and never acts as a decoding/re-encoding participant bridge. Its TURN gateway forwards encrypted packets, and the member renews credentials before they expire. Clients accept at most 4 gateway members per room.
Next
Gate service covers deploying your own signalling service.