자주 하는 실수
처음 코드를 작성할 때와 AI에게 코드를 맡길 때 모두 이 목록으로 확인하세요. 증상별 진단은 문제 해결을 참고하세요.
꼭 알아야 할 동작
- 연결 준비: 소켓
open과 IOSignalready는 다릅니다. CID 사용·수동 구독·송신은ready이후에 합니다. - 채널 범위:
room또는room#topic은 명시한 채널입니다.#topic은 서버가 외부 IP 기반으로 구분하는 HOME CHANNEL입니다. HOME CHANNEL은 사용자 인증이나 신뢰 경계가 아닙니다. 태그, 홈채널 참조. - 직접 수신:
peerCid@rtc로 보낸 메시지는on('@rtc')로 받으며message로 오지 않습니다.@와@rtc에 같은 처리를 등록하면 두 번 처리됩니다. - 구독 순서:
on()은 구독하지 않습니다. 수동 구독은ready마다 등록합니다. 구독 안내를 따르세요. - 리디렉션: 공개 서버는 초기 연결을 다른 서버로 넘길 수 있습니다.
ready이전의 정상 리디렉션과 준비 완료 이후의 단절을 구분하고 연결 대기 시간에 상한을 둡니다. - 역할 구분: IOSignal은 메시지 전달을 담당합니다. 방의 인원·참여 권한, 장치 명령의 의미, WebRTC offer 생성자 등은 응용 앱의 규칙입니다.
- 성공 판정:
signal()호출은 상대의 업무 처리가 끝났다는 확인이 아닙니다. 필요하면 응용 메시지로 응답을 설계하고 실제 결과를 검사하세요.
자료형은 payload, 태그 길이는 클라이언트 API, quota는 서버 API를 확인합니다. 문서와 설치 버전이 다르면 그 버전의 타입·소스로 확인하세요.
흔한 오해와 실제 동작
| 흔한 오해 | 실제 동작 | 근거 |
|---|---|---|
브라우저에서 import { IO } from 'iosignal' | iosignal 루트 엔트리는 Node.js용입니다. 브라우저 번들러는 import IO from 'iosignal/io', CDN은 IIFE·ESM 브라우저 빌드를 사용합니다. | 클라이언트 API |
ready 전에 subscribe() 호출 | 수동 구독은 ready 핸들러 안에서 호출합니다. 서버가 CID를 발급하기 전에는 세션과 구독 순서가 확정되지 않습니다. | 연결 수명주기와 구독 |
listen()이 호출 즉시 구독한다고 가정 | 일반 태그의 listen()은 핸들러와 태그만 등록합니다. 구독 패킷은 CID를 받아 ready가 된 시점에 전송됩니다. | 연결 수명주기와 구독 |
직접 시그널을 message 이벤트로 수신 | 직접 시그널은 message로 전달되지 않습니다. on('@', ...) 또는 정확한 @topic 이벤트로 받습니다. | 클라이언트 API |
subscribe('@topic')로 직접 수신 등록 | 직접 수신 태그는 서버 구독 대상이 아닙니다. subscribe('@topic')와 unsubscribe('@topic')는 TypeError를 던지며 서버로 전송하지 않습니다. on()·listen()으로 등록합니다. | 연결 수명주기와 구독 |
| 태그 길이를 문자열 문자 수로 계산 | 태그 제한은 UTF-8 기준 255 bytes입니다. 가 85개는 255 bytes이고 86개는 초과합니다. | 클라이언트 API |
| quota를 배포 공통 고정값으로 가정 | quota는 서버 운영자가 설정합니다. 클라이언트는 ready 이후 io.quota.maxMessageBytes로 확인하고, 특정 값을 코드에 넣지 않습니다. | 서버 API |
| CID가 재접속 후에도 같다고 가정 | 연결이 끊기면 CID는 무효가 되고 새 연결에서 새 CID를 받을 수 있습니다. ready마다 io.cid를 다시 읽고 수동 subscribe()도 다시 등록합니다. | 인증 |
payload의 from을 인증된 신원으로 신뢰 | from은 앱이 넣은 응용 필드이며 IOSignal이 검증한 발신자 ID가 아닙니다. 권한 판단에는 서버 인증 결과나 앱의 검증을 사용합니다. | 서버 인증 설정 |
signal('room', 42)가 숫자로 수신 | 숫자 하나는 TEXT로 변환되어 문자열 '42'로 수신됩니다. 숫자를 유지하려면 객체나 여러 인자를 사용합니다. | 데이터 형식 |
| Arduino도 JS 객체를 자동 복원 | Arduino 콜백에는 유형값·원시 바이트·길이가 전달됩니다. OBJECT/MJSON/MBA를 객체나 여러 인자로 복원하려면 앱에서 파싱합니다. | 데이터 형식 |
Quota와 제한
quota는 라이브러리 고정값이 아니라 서버 운영자가 정하는 정책입니다(quotas 쿼터 프로필, anonymousQuota, 계정의 역할·쿼터). 공개 서버는 제공자의 정책을 따릅니다. 태그 255바이트처럼 프로토콜이 고정한 제한과 구분하세요.