서버 API와 옵션
기준 소스: Server와 serverOption.
import { Server } from 'iosignal';
const server = new Server({ port: 7777 });
server.on('ready', () => console.log('연결 수신 준비'));
자주 쓰는 옵션입니다. 생성 시 port(WebSocket), httpServer(기존 HTTP 서버), congPort(CongSocket) 중 하나 이상을 지정해야 합니다.
| 생성 옵션 | 의미 |
|---|---|
port | WebSocket 연결 포트. 브라우저와 Node.js IO 클라이언트가 사용합니다. |
httpServer, wsPath | 기존 HTTP 서버에 WebSocket을 연결하고 경로를 지정합니다. |
congPort | CongSocket 연결 포트. Arduino와 해당 Node.js 클라이언트에 사용합니다. |
heartbeatInterval, heartbeatGrace | 연결 확인 주기와 응답 유예 시간(ms). |
logMessages, logStats | 받은 메시지의 종류·태그 로그(내용은 남기지 않음)와 N ms마다 한 줄 집계. 현재 집계는 server.stats()로 읽습니다. |
maxPayload, maxBufferedBytes | WebSocket 메시지·CongSocket 프레임의 최대 크기와, 보내지 못한 데이터가 이 크기를 넘은 연결을 닫는 한도(bytes). |
trustProxy | X-Forwarded-For/-Proto를 믿을 경로. 'private'(기본, loopback·사설 주소에서만), true, false, 또는 신뢰할 프록시 수. |
membersOnly | 인증하지 않은 연결의 시그널을 버립니다. 인증 공급자나 localAuth와 함께 구성하세요. |
localAuth | 8.1.0부터. 키 목록 없는 로컬 테스트 로그인. 'idKey'(키 = ID) 또는 { mode: 'sharedKey', key, role, quota }; CID는 로그인 ID입니다. authManager 인자와 함께 쓸 수 없습니다. 로컬 테스트 로그인 |
duplicateLogin | 8.0.0부터. 같은 인증 CID가 이미 접속 중일 때 'keepNew'(기본)는 기존 연결을 교체하고 'keepOld'는 새 연결을 거부합니다. 이 서버의 인증 관리자에만 적용됩니다. |
quotas, anonymousQuota | 이름 붙은 쿼터 프로필과 미인증 연결이 쓸 프로필. 운영자가 직접 설정하며 고정값이 아닙니다. |
retain | retain 사용 여부(enabled)와 크기·개수, 소유자별 저장 예산. 실행 중 server.retain에서 조정합니다. |
Quota와 제한
quota는 운영자가 정하는 정책이며 고정값이 아닙니다. 9.0부터 연결의 역할(무엇을 할 수 있는지)과 쿼터 프로필(얼마나 보낼 수 있는지)이 나뉩니다.
- 쿼터 프로필은
quotas옵션에 이름으로 정의하는 제한 묶음입니다.maxMessageBytes,fanout(발행 한 건이 전달되는 구독자 수),msgPerSec,bytesPerSec, 계정별maxConnections를 지정하며null은 무제한입니다. 서버가 항상 적용하며, 실행 중에도server.quotas에서 조정할 수 있습니다. - 미인증 연결은
anonymousQuota프로필을, 로그인한 연결은 키 항목의 quota 또는BohoAuth의resolveQuota(authInfo, role)결과를 씁니다. - 내장 프로필(
anonymous,basic,pro,unlimited)은 운영자가 조정할 시작값입니다. 기본값은serverOption을 참고하세요. - 클라이언트는 서버가 보내는
QUOTA메시지로io.quota.maxMessageBytes를 받습니다(ready전에 도착,null은 제한 없음). 초당 메시지·바이트 한도를 넘은 메시지는 알림 없이 버려집니다.
const server = new Server({
port: 7777,
quotas: { anonymous: { maxMessageBytes: 64 * 1024 }, basic: { fanout: 200 } },
anonymousQuota: 'anonymous'
});
태그와 구독 목록의 255바이트는 quota가 아닌 프로토콜 제한입니다.
장치별 수신 정책
9.6.0부터 소유자가 있는 장치는 누구의 CID 직접 송신(장치CID@topic)을 받을지 정할 수 있습니다. 소유자는 로그인한 키 항목의 uid입니다. 내장 키 제공자(File·String·Redis·Local)는 uid를 넘기지 않으므로, 이 기능은 getAuth(id)가 uid와 rxPolicy를 함께 돌려주는 직접 만든 키 제공자에서 쓰입니다. uid가 없는 장치는 걸러지지 않습니다.
// 키 제공자의 getAuth(id)가 돌려주는 authInfo의 일부
{ cid: 'lamp1', uid: 'user-a', rxPolicy: {
v: 1,
mode: 'allowlist', // 'open'(기본) | 'allowlist' | 'denylist'
anonymous: 'deny', // 미인증 송신자: allowlist는 기본 deny, denylist는 기본 allow
publish: 'all', // 'policy'이면 CID 발행(@topic, @$topic) 구독자도 같은 규칙으로 거름
allow: { cids: ['panel1'], uids: ['user-b'] },
deny: { cids: [], uids: [] }
} }
- 판정은 처음 맞는 규칙을 따릅니다: 장치 자신·같은 소유자
uid·admin역할 → 허용, 인증된 송신자의 CID가deny.cids/allow.cids에 있으면 거부/허용, 송신자uid가deny.uids/allow.uids에 있으면 거부/허용, 미인증 송신자는anonymous, 나머지는mode의 기본값입니다. 목록은 각각 200개까지입니다. - 거부된 송신자는 오프라인 CID와 같은
Invalid cid응답을 받으므로 차단 여부를 알 수 없습니다. - 접속 중인 장치의 정책은
server.manager.setDeliveryPolicy(cid, policy)로 바로 바꿀 수 있습니다. 잘못된 정책은 예외, 해당 장치가 없거나 소유자가 없으면false를 돌려줍니다. 다음 로그인에서는 키 제공자의 정책을 다시 읽습니다. - 거부될 때마다
server.stats()의counters.policyDenied가 늘고, 리스너가 있으면 서버가'delivery:denied'이벤트(kind,cid,did,owner,other,at)를 냅니다.
서버 호스트
9.13.0부터 server.host(name, options)로 서버 안에서 실행되는 판정 로직(게임, 퀴즈 등)을 등록합니다. 사용법과 태그 규칙은 서버 안의 게임 로직에, 실행해 볼 수 있는 예제는 Host Quiz에 있습니다.
| 호출 | 설명 |
|---|---|
server.host(name, { inbound, own, fanout, retain }) | 호스트를 등록하고 Host를 돌려줍니다. name은 영문·숫자·_.- 1~64자. inbound(필수): 클라이언트가 호스트에게 보내는 채널 태그, own: 호스트만 보낼 채널 태그와 @토픽. 끝의 *는 접두사. fanout: 한 번 발행의 최대 수신자(기본 제한 없음). retain: { tags, bytes }: 호스트 보관 예산(기본 retain.tagsPerOwner·bytesPerOwner) |
host.on('message', (from, tag, ...args)) | inbound 태그로 온 입력. from은 { cid, uid, role, authorized, nick, ssid }이며 서버가 정한 값입니다. args는 클라이언트 message 이벤트와 같은 형태입니다 |
host.on('leave', (from, reason)) | 입력을 보낸 적 있는 연결이 끊겼을 때. 그 CID가 다른 연결로 넘어간 경우에는 오지 않습니다 |
host.on('error', (err)) | message·leave 처리 함수에서 난 예외. 서버는 계속 동작합니다 |
host.publish(tag, ...args) | own 채널로 발행하고 전달한 연결 수를 돌려줍니다. 태그에 $가 있으면 보관합니다. own이 아닌 태그는 예외 |
host.to(cid, topic, ...args) | 한 연결에 보냅니다. 받는 쪽 태그는 '@' + topic. 연결이 없거나 상대 수신 버퍼보다 크면 false |
host.participants, host.forget(cid) | 입력을 보낸 연결 목록(Map<cid, from>), 목록에서 빼기(leave를 보내지 않음) |
host.report(values) | 9.14.0. 대시보드에 보여 줄 값(숫자·짧은 글자·참거짓, 20개까지)을 합칩니다. 값이 null이면 그 키를 지웁니다 |
host.loop(ms, fn) | 9.14.0. ms마다 fn(now)를 실행하고 틱 간격과 처리 시간을 잽니다. 멈춤 함수를 돌려줍니다. fn의 예외는 'error'로 알리고 계속합니다. host.loopStats()로 측정값을 읽습니다 |
host.counters, host.activity(), host.journal(after) | 9.14.0. 호스트별 누적 카운터(inbound, rejected, denied, published, delivered, sent, joins, leaves, errors, handlerMs), 참가자별 입력 수·처음·마지막 시각, 최근 입장·퇴장·차단·오류 이력 |
host.close() | 등록 해제. 태그는 보통 채널로 돌아가고 호스트가 보관한 값은 지워집니다. server.close()도 호스트를 닫습니다 |
server.on('host:denied', (remote, tag, hostName)) | 클라이언트가 호스트 전용 태그로 보내 버려졌을 때 |
server.stats()의 counters에 hostInbound(호스트에 넘긴 입력), hostRejected(E2E·해석할 수 없는 페이로드로 넘기지 않은 입력), hostDenied(호스트 전용 태그로 와서 버린 메시지)가 있습니다.
대시보드
9.14.0부터 new Server({ dashboard })로 서버와 호스트의 상태를 보여 주는 웹페이지를 켭니다. 기본은 꺼짐입니다. 화면 구성과 권한 설명은 서버 대시보드에 있습니다.
| 옵션 | 기본값 | 설명 |
|---|---|---|
dashboard | 꺼짐 | true 또는 아래 항목을 가진 객체 |
path | '/dashboard' | 페이지 주소. path + '/io.js'로 브라우저 클라이언트를 함께 제공합니다 |
access | 'open' | 'open', { token }(8자 이상), { login: { roles, cids } }(로그인한 연결 중 roles 이상의 역할 또는 cids의 CID, roles 기본 ['admin']) |
panels | 전부 | 처음 보여 줄 패널: server, traffic, hosts, game, participants, events |
history | 300 | 그래프 기록(초), 10~3600 |
maxViewers | 20 | 동시에 보는 사람 수, 1~200 |
showIdentities | access가 'open'이면 false | 참가자 CID와 이름을 보여 줄지 |
port로 서버를 열면 서버가 HTTP 서버를 직접 만들어 페이지와 WebSocket을 같은 포트에서 제공합니다.httpServer를 넘기면 요청 처리에서server.dashboard.handle(req, res)를 먼저 부릅니다(대시보드 주소면true).- 대시보드는
iosignal.dashboard호스트를 씁니다(iosignal.dashboard#in,@iosignal.dashboard). 이 태그는 다른 호스트가 쓸 수 없습니다. - 잘못된 옵션은
new Server()에서 예외입니다.
서비스
서버 서비스는 server.attach(name, service)로 등록합니다. 서비스에는 commands 배열과 checkPermission(remote, req) 함수가 필요하며, 명령별 메서드 또는 call(remote, req)를 구현합니다. 반환 응답과 권한 검사를 포함한 예제는 replyService와 attach 테스트를 참고하세요.
8.0.0부터 서비스가 onRemoteClose(remote)를 구현하면 연결이 끊길 때 서버가 직접 호출합니다. RPC 권한 검사와 명령 목록을 거치지 않으므로 연결별 정리에 사용합니다. 권한은 역할로 검사합니다(hasRole(remote, 'admin'), 역할은 낮은 것부터 anonymous, device, service, admin). 내장 sudo 서비스는 admin 역할만, RedisService(client, minRole)는 기본적으로 service 이상만 허용합니다. 인증 없이 실습하려면 new RedisService(client, 'anonymous')처럼 명시합니다.
연결 검사와 종료
heartbeatInterval,heartbeatGrace: 연결 확인 주기와 응답 유예 시간(ms)입니다.server.stats(): 연결·채널·retain·트래픽 집계(쿼터로 버려진 메시지 수 포함)를 반환합니다.security.maxClockSkewMs,security.authChallengeMaxAgeMs,security.maxReplayEntries: 각각 시각 오차·인증 challenge 수명·재전송 검사 보관 개수입니다. 양의 안전한 정수를 사용하며 단위와 기본값은serverOption을 확인하세요.server.close(callback): 연결과 서버 자원을 종료한 뒤 콜백을 호출합니다.
인증은 생성자의 두 번째 인자로 BohoAuth를 전달하여 구성할 수 있습니다. 파일·Redis 제공자와 실행 절차는 인증 서버 설정을 참고하세요. TLS와 포트 설정은 연결 환경에 모았습니다. 같은 ID의 중복 로그인 정책과 onAuthEvent는 중복 로그인을 참고하세요.