서버 안의 게임 로직 (server.host)
9.13.0부터 server.host()로 게임·퀴즈·투표처럼 서버가 판정하는 로직을 IOSignal 서버 안에 올릴 수 있습니다. 호스트는 세 가지를 해 줍니다.
- 보낸 사람을 서버가 알려 줍니다. 호스트가 받는 입력마다
from.cid가 붙습니다. 접속을 확인한 서버가 붙이는 값이라 페이로드에 다른 사람의 CID를 넣어도 소용이 없습니다. - 호스트 전용 태그를 지킵니다.
own에 넣은 태그로 클라이언트가 보내면 서버가 버립니다. 점수판, 판 결과, 한 사람에게 보내는 알림을 위조할 수 없습니다. - 접속이 끊기면 바로 알려 줍니다. 입력을 보낸 적 있는 연결이 끊기면
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: 서버 호스트에 있습니다.