본문으로 건너뛰기

서버 API와 옵션

기준 소스: Server와 serverOption.

import { Server } from 'iosignal';

const server = new Server({ port: 7777 });
server.on('ready', () => console.log('연결 수신 준비'));

자주 쓰는 옵션입니다. 생성 시 port(WebSocket), httpServer(기존 HTTP 서버), congPort(CongSocket) 중 하나 이상을 지정해야 합니다.

생성 옵션의미
portWebSocket 연결 포트. 브라우저와 Node.js IO 클라이언트가 사용합니다.
httpServer, wsPath기존 HTTP 서버에 WebSocket을 연결하고 경로를 지정합니다.
congPortCongSocket 연결 포트. Arduino와 해당 Node.js 클라이언트에 사용합니다.
heartbeatInterval, heartbeatGrace연결 확인 주기와 응답 유예 시간(ms).
logMessages, logStats받은 메시지의 종류·태그 로그(내용은 남기지 않음)와 N ms마다 한 줄 집계. 현재 집계는 server.stats()로 읽습니다.
maxPayload, maxBufferedBytesWebSocket 메시지·CongSocket 프레임의 최대 크기와, 보내지 못한 데이터가 이 크기를 넘은 연결을 닫는 한도(bytes).
trustProxyX-Forwarded-For/-Proto를 믿을 경로. 'private'(기본, loopback·사설 주소에서만), true, false, 또는 신뢰할 프록시 수.
membersOnly인증하지 않은 연결의 시그널을 버립니다. 인증 공급자나 localAuth와 함께 구성하세요.
localAuth8.1.0부터. 키 목록 없는 로컬 테스트 로그인. 'idKey'(키 = ID) 또는 { mode: 'sharedKey', key, role, quota }; CID는 로그인 ID입니다. authManager 인자와 함께 쓸 수 없습니다. 로컬 테스트 로그인
duplicateLogin8.0.0부터. 같은 인증 CID가 이미 접속 중일 때 'keepNew'(기본)는 기존 연결을 교체하고 'keepOld'는 새 연결을 거부합니다. 이 서버의 인증 관리자에만 적용됩니다.
quotas, anonymousQuota이름 붙은 쿼터 프로필과 미인증 연결이 쓸 프로필. 운영자가 직접 설정하며 고정값이 아닙니다.
retainretain 사용 여부(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가 아닌 프로토콜 제한입니다.

서비스​

서버 서비스는 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는 중복 로그인을 참고하세요.