Game logic inside the server (server.host)
From 9.13.0, server.host() puts logic that the server decides, such as a game, a quiz or a vote, inside the IOSignal server. A host gives you three things.
- The server tells you who sent each input. Every input a host receives comes with
from.cid. The server sets it from the connection it checked, so putting someone else's CID in the payload does nothing. - Host-only tags stay host-only. When a client sends to a tag listed in
own, the server drops it. Scoreboards, round results and messages for one player cannot be forged. - You hear about a closed connection at once. When a connection that has sent input closes, the host gets a
leaveevent.
Clients do not change. Browsers, Node.js, Arduino and the CLI keep using signal and subscribe.
When to use it
With channels alone, clients can exchange messages, but a message does not say who sent it and anyone can publish to any channel. That is a problem when the server must decide scores or winners. A host is the place for that logic.
- Multiplayer games: take inputs, compute movement, collisions and scores, and broadcast the state
- Quizzes and votes: accept one answer per person and announce the result
- Apps whose shared state must be protected: only the server code changes it
A host runs only on your own server. It runs inside the server process, so it cannot be registered on the public service (io.iosignal.net).
Example to run
The code on this page comes from the Host Quiz example. The host inside the server runs the questions and scores them; browsers only send answers. Its cheating panel (the example's screens are in Korean) lets you send a forged scoreboard, a forged personal result and an answer carrying someone else's CID, and see each one stopped.
git clone https://github.com/remocons/iosignal-examples.git
cd iosignal-examples/iosignal_host-quiz
npm ci
npm start
Open http://localhost:5181 in two or more windows and join with a nickname. The web page and the IOSignal WebSocket (/ws) share one port, and /dashboard shows the host's inputs and blocked forgeries on the server dashboard. npm test runs a two-player game over real sockets and checks that forged tags are dropped.
Server code
import { Server } from 'iosignal' // 9.13.0 or later
const server = new Server({ port: 7777 })
const host = server.host('quiz', {
inbound: ['quiz#in'], // client -> host; not delivered to other subscribers
own: ['quiz#$state', '@quiz.you'], // only the host may send these
})
host.on('message', (from, tag, msg) => {
// from.cid: the sender as the server knows it. Do not trust values inside msg.
if (msg?.op === 'answer') game.answer(from.cid, msg.choice)
host.publish('quiz#$state', game.state()) // to every subscriber
})
host.on('leave', (from) => game.leave(from.cid)) // a player's connection closed
host.to(cid, 'quiz.you', { correct: true }) // to one connection; it receives '@quiz.you'
Client code
io.on('ready', () => io.subscribe('quiz#$state'))
io.signal('quiz#in', { op: 'answer', choice: 1 })
io.on('message', (tag, state) => draw(state))
io.on('@quiz.you', (tag, result) => showResult(result)) // arrives without subscribing
Arduino works the same way: send with io.signal("quiz#in", "A,1"); and receive @quiz.you in onMessage.
How a message travels
Tag rules
| Example | Where | Meaning |
|---|---|---|
'quiz#in' | inbound | Input from clients to the host. Not delivered to other subscribers |
'quiz#state' | own | A channel only the host publishes. Clients sending to it are dropped |
'quiz#$state' | own | With $ the server keeps the last value, so a screen that subscribes later gets it at once |
'@quiz.you' | own | A topic sent to one connection. Other clients cannot imitate it with '<cid>@quiz.you' |
'room:*' | inbound, own | A trailing * is a prefix, for apps with several rooms (room:1#in, room:2#in) |
- Use global channel tags only. Tags starting with
#(HOME CHANNEL) or$are not allowed. - An
own@topicis blocked server-wide. When several apps share a server, prefix it with the app name, as in@quiz.you. - Two hosts cannot claim the same tag (or overlapping prefixes), and one host's
inboundandowncannot overlap. Registration throws. - After
host.close()the tags are ordinary channels again and the host's retained values are removed.
Things to know
- An anonymous connection gets a new CID on every reconnect. Use authentication to keep a returning player as the same participant; a logged-in connection keeps its CID.
leavecomes only for connections that have sent input. When the same account replaces its connection (duplicateLogin: 'keepNew'), closing the old one sends noleave.- End-to-end encrypted messages (
signal_e2e) cannot be read by a host, so they are not accepted. - A sender gets no reply when its message is dropped. On the server, watch
server.on('host:denied', (remote, tag, hostName) => ...)orhostInbound,hostRejectedandhostDeniedinserver.stats(). - Input follows the connection's quota. Messages over the per-second limit are dropped before they reach the host.
- When you run several servers, the players of one room must connect to the same server. A host sees only the connections on its own server.
Performance
A server without hosts skips this check entirely. Results from games built on 9.13.0, on one core (Apple M2):
| Case | Server CPU | Tick interval p99 |
|---|---|---|
| A 30 Hz physics game, 12 players | about 4% | 35 ms (target 33 ms) |
| Same game + 1,000 watching screens (9.4 MB/s out) | about 16% | 40 ms |
| 200 inputs a second per player (the server drops what exceeds the quota) | about 9% | 35 ms |
Handling one ordinary message takes about the same time with one host (about 240 ns); 21 hosts with 40 prefix tags add about 0.2 µs.
Watching the state
From 9.14.0, new Server({ dashboard: true }) shows each host's participants, inputs per second, blocked forgeries and handler time live on a web page. Run the game loop with host.loop(ms, fn) to see tick timing too. Server dashboard
Methods and events are listed in Server API: server host.