Skip to main content

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.

  1. 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.
  2. 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.
  3. You hear about a closed connection at once. When a connection that has sent input closes, the host gets a leave event.

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​

ExampleWhereMeaning
'quiz#in'inboundInput from clients to the host. Not delivered to other subscribers
'quiz#state'ownA channel only the host publishes. Clients sending to it are dropped
'quiz#$state'ownWith $ the server keeps the last value, so a screen that subscribes later gets it at once
'@quiz.you'ownA topic sent to one connection. Other clients cannot imitate it with '<cid>@quiz.you'
'room:*'inbound, ownA 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 @topic is 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 inbound and own cannot 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.
  • leave comes only for connections that have sent input. When the same account replaces its connection (duplicateLogin: 'keepNew'), closing the old one sends no leave.
  • 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) => ...) or hostInbound, hostRejected and hostDenied in server.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):

CaseServer CPUTick interval p99
A 30 Hz physics game, 12 playersabout 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.