본문으로 건너뛰기

서버 안의 게임 로직 (server.host)

9.13.0부터 server.host()로 게임·퀴즈·투표처럼 서버가 판정하는 로직을 IOSignal 서버 안에 올릴 수 있습니다. 호스트는 세 가지를 해 줍니다.

  1. 보낸 사람을 서버가 알려 줍니다. 호스트가 받는 입력마다 from.cid가 붙습니다. 접속을 확인한 서버가 붙이는 값이라 페이로드에 다른 사람의 CID를 넣어도 소용이 없습니다.
  2. 호스트 전용 태그를 지킵니다. own에 넣은 태그로 클라이언트가 보내면 서버가 버립니다. 점수판, 판 결과, 한 사람에게 보내는 알림을 위조할 수 없습니다.
  3. 접속이 끊기면 바로 알려 줍니다. 입력을 보낸 적 있는 연결이 끊기면 leave 이벤트가 옵니다.

클라이언트 쪽은 바뀌지 않습니다. 브라우저·Node.js·Arduino·CLI 모두 지금처럼 signal과 subscribe만 씁니다.

언제 쓰나​

일반 채널만으로는 클라이언트끼리 메시지를 주고받을 수 있지만, 메시지에 보낸 사람이 붙지 않고 누구나 어떤 채널에든 발행할 수 있습니다. 점수나 승패를 서버가 정해야 하는 응용에서는 이것이 문제입니다. 호스트는 그런 판정 로직을 위한 자리입니다.

  • 멀티플레이 게임: 입력을 받아 이동·충돌·점수를 계산하고 상태를 방송
  • 퀴즈·투표: 한 사람에 한 번만 답을 받고 결과를 발표
  • 공유 상태를 지켜야 하는 앱: 정해진 서버 코드만 상태를 바꿈

호스트는 자기 서버에서만 쓸 수 있습니다. 서버 프로세스 안에서 실행되므로 공개 서비스(io.iosignal.net)에는 등록할 수 없습니다.

실행해 보는 예제​

이 문서의 코드는 Host Quiz 예제에서 가져왔습니다. 문제 진행과 채점을 서버 안의 호스트가 맡고, 브라우저는 답만 보냅니다. 화면의 위조해 보기로 점수판·개인 결과 위조와 남의 CID를 넣은 답이 막히는 것을 직접 확인할 수 있습니다.

git clone https://github.com/remocons/iosignal-examples.git
cd iosignal-examples/iosignal_host-quiz
npm ci
npm start

http://localhost:5181을 두 창 이상에서 열고 닉네임으로 입장합니다. 웹 페이지와 IOSignal WebSocket(/ws)이 한 포트에서 실행되고, /dashboard에서 서버 대시보드로 호스트의 입력·위조 차단을 볼 수 있습니다. npm test는 실제 소켓으로 두 명이 푸는 시험과 위조 태그 차단 시험을 실행합니다.

서버 코드​

import { Server } from 'iosignal' // 9.13.0 이상

const server = new Server({ port: 7777 })

const host = server.host('quiz', {
inbound: ['quiz#in'], // 클라이언트 → 호스트. 다른 구독자에게는 가지 않습니다
own: ['quiz#$state', '@quiz.you'], // 호스트만 보낼 수 있습니다
})

host.on('message', (from, tag, msg) => {
// from.cid: 서버가 확인한 보낸 사람. msg 안의 값은 믿지 않습니다.
if (msg?.op === 'answer') game.answer(from.cid, msg.choice)
host.publish('quiz#$state', game.state()) // 구독자 모두에게
})

host.on('leave', (from) => game.leave(from.cid)) // 연결이 끊긴 참가자

host.to(cid, 'quiz.you', { correct: true }) // 한 연결에만. 받는 쪽 태그는 '@quiz.you'

클라이언트 코드​

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)) // 구독하지 않아도 도착

Arduino도 같습니다. io.signal("quiz#in", "A,1");처럼 보내고 @quiz.you는 onMessage에서 받습니다.

메시지가 지나가는 길​

태그 규칙​

예위치뜻
'quiz#in'inbound클라이언트가 호스트에게 보내는 입력. 다른 구독자에게 전달되지 않습니다
'quiz#state'own호스트만 발행하는 채널. 클라이언트가 보내면 버려집니다
'quiz#$state'own$가 있으면 서버가 마지막 값을 보관해서, 나중에 구독한 화면도 바로 받습니다
'@quiz.you'own한 연결에 보내는 토픽. 다른 클라이언트가 '<cid>@quiz.you'로 흉내 낼 수 없습니다
'room:*'inbound, own끝의 *는 접두사입니다. 방이 여러 개인 응용에 씁니다(room:1#in, room:2#in)
  • 태그는 전역 채널 태그만 씁니다. #로 시작하는 홈채널 태그와 $로 시작하는 태그는 쓸 수 없습니다.
  • own의 @토픽 금지는 서버 전체에 적용됩니다. 여러 응용이 한 서버를 함께 쓴다면 @quiz.you처럼 응용 이름을 붙이세요.
  • 두 호스트가 같은 태그(또는 겹치는 접두사)를 맡을 수 없고, 한 호스트의 inbound와 own도 겹칠 수 없습니다. 등록할 때 오류가 납니다.
  • host.close()를 하면 태그가 다시 보통 채널이 되고, 호스트가 보관한 값은 지워집니다.

알아 둘 점​

  • 익명 연결의 CID는 다시 접속할 때마다 바뀝니다. 재접속한 사람을 같은 참가자로 이어 가려면 인증을 쓰세요. 로그인한 연결은 CID가 그대로입니다.
  • leave는 입력을 보낸 적 있는 연결에만 옵니다. 같은 계정이 새 연결로 바꿔 접속하면(duplicateLogin: 'keepNew') 옛 연결이 닫혀도 오지 않습니다.
  • E2E 암호화 메시지(signal_e2e)는 호스트가 읽을 수 없으므로 받지 않습니다.
  • 버려진 메시지에 대해 보낸 쪽은 응답을 받지 않습니다. 서버에서 server.on('host:denied', (remote, tag, hostName) => ...)나 server.stats()의 hostInbound·hostRejected·hostDenied로 확인합니다.
  • 입력도 연결의 쿼터를 그대로 따릅니다. 초당 메시지 수를 넘는 입력은 호스트에 오기 전에 버려집니다.
  • 여러 서버로 나눠 운영할 때는 한 방의 참가자가 같은 서버에 접속해야 합니다. 호스트는 자기 서버에 붙은 연결만 봅니다.

성능​

호스트를 등록하지 않은 서버는 이 검사를 바로 건너뜁니다. 9.13.0으로 만든 게임 서버를 한 코어에서 시험한 결과입니다(Apple M2).

상황서버 CPU틱 간격 p99
30Hz 물리 게임, 참가자 12명약 4%35ms (목표 33ms)
같은 게임 + 관전 화면 1,000개 (초당 9.4MB 송신)약 16%40ms
참가자마다 초당 200개 입력 (쿼터 초과분은 서버가 버림)약 9%35ms

일반 메시지 한 개를 처리하는 시간은 호스트가 1개일 때 거의 같고(약 240ns), 접두사 태그가 40개인 호스트 21개를 등록해도 0.2µs 정도 늘어납니다.

상태 보기​

9.14.0부터 new Server({ dashboard: true })를 켜면 호스트마다 참가자, 초당 입력, 위조 차단, 처리 시간을 웹페이지에서 실시간으로 볼 수 있습니다. 게임 루프를 host.loop(ms, fn)로 돌리면 틱 간격도 함께 보입니다. 서버 대시보드

메서드와 이벤트 목록은 서버 API: 서버 호스트에 있습니다.