iosignal 3.0.0 → 3.1.0

package/src/client/IOWS.js

@@ -1,4 +1,5 @@
 import { IOCore } from "./IOCore.js";
+import { STATES } from "../common/constants.js";
 import { WebSocket } from "ws";
 
 //  Node.js 'ws' websocket
@@ -10,32 +11,28 @@ export class IOWS extends IOCore {
 
 
 
+  /**
+   * Closes ws WebSocket and cleans resources.
+   */
   close() {
     if (this.socket) {
-      this.socket.onclose = null
-      this.socket.onmessage = null
-      this.socket.onerror = null
-      this.socket.close();
-      this.socket = null;
+      this.socket.removeAllListeners();
+      if (this.socket.readyState !== WebSocket.CLOSED) {
+        this.socket.close();
+      }
     }
-    this.emit('close')
+    super.close();
   }
 
 
-
-  stop() {
-    this.close()
-    clearInterval(this.connectionCheckerIntervalID);
-    this.connectionCheckerIntervalID = null
-  }
-
   keepAlive() {
-    if (!this.socket || this.socket?.readyState === 3) {
+    if (!this.autoReconnect) return;
+    // Reconnect only if the socket is closed and the state reflects that.
+    if ((!this.socket || this.socket.readyState === WebSocket.CLOSED) && this.state === STATES.CLOSED) {
       this.open();
     }
   }
 
-
   createConnection(url) {
     // node WebSocket
     this.socket = new WebSocket(url);

package/src/client/browser/IOWebSocket.js

@@ -3,23 +3,79 @@ import { IOCore } from "../IOCore.js";
 import Boho from 'boho'
 import * as constants from '../../common/constants.js'
 
+/**
+ * @typedef {import("boho").Boho} Boho
+ * @typedef {import("boho").MBP} MBP
+ * @typedef {import("boho").Buffer} Buffer
+ */
+
 const Buffer = Boho.Buffer
 
-// Browser WebSocket
+/**
+ * Browser WebSocket client extending IOCore.
+ * @augments {IOCore}
+ */
 export default class IO extends IOCore {
+  /**
+   * The version of the client.
+   * @type {string}
+   */
   static version = version
+  /**
+   * The binary type for WebSocket messages.
+   * @type {string}
+   */
   static binaryType = "arraybuffer"
+  /**
+   * The Boho library instance.
+   * @type {Boho}
+   */
   static Boho = Boho;
+  /**
+   * The MBP (MessagePack-Boho) instance.
+   * @type {MBP}
+   */
   static MBP = Boho.MBP;
+  /**
+   * The Buffer class from Boho.
+   * @type {Buffer}
+   */
   static Buffer = Boho.Buffer;
+  /**
+   * Constants used by the client.
+   * @type {object}
+   */
   static constants = constants
 
+  /**
+   * Tracks the number of IO instances created.
+   * @type {number}
+   */
+  static instanceCount = 0;
+
+  /**
+   * Tracks the number of WebSocket objects created.
+   * @type {number}
+   */
+  static webSocketCount = 0;
+
+
+
+  /**
+   * Creates an instance of IO.
+   * @param {string} url - The WebSocket URL to connect to.
+   */
   constructor(url) {
     super(url);
-    document.addEventListener('visibilitychange', this.browserVisiblePing.bind(this));
+    IO.instanceCount++;
+    this.boundBrowserVisiblePing = this.browserVisiblePing.bind(this)
+    document.addEventListener('visibilitychange', this.boundBrowserVisiblePing);
     if (url) this.open();
   }
 
+  /**
+   * Pings the server when the browser tab becomes visible.
+   */
   browserVisiblePing() {
     if (document.visibilityState === 'visible') {
       this.ping()
@@ -27,41 +83,57 @@ export default class IO extends IOCore {
   }
 
 
-  close() {
-    if (this.socket) {
-      this.socket.onclose = null
-      this.socket.onmessage = null
-      this.socket.onerror = null
-      this.socket.close();
-      this.socket = null;
-    }
-    this.emit('close')
-  }
-
+  
 
+  /**
+   * Permanently stops the connection and cleans up its specific resources.
+   * For complete cleanup and to make the instance unusable, use destroy().
+   */
   stop() {
-    this.close()
-    clearInterval(this.connectionCheckerIntervalID);
-    this.connectionCheckerIntervalID = null
+    super.stop();
+  }
+
+  /**
+   * Permanently destroys the instance, cleaning up all resources including global event listeners.
+   * The instance will not be usable after this.
+   */
+  destroy() {
+    document.removeEventListener('visibilitychange', this.boundBrowserVisiblePing);
+    super.destroy();
   }
 
 
+  /**
+   * Keeps the connection alive by re-opening if closed.
+   */
   keepAlive() {
-    if (!this.socket || this.socket?.readyState === 3) {
+    if (!this.autoReconnect) return;
+    // Reconnect only if the socket is closed and the state reflects that.
+    if ((!this.socket || this.socket.readyState === WebSocket.CLOSED) && this.state === IO.constants.STATES.CLOSED) {
       this.open();
     }
   }
 
 
 
+  /**
+   * Creates a new WebSocket connection.
+   * @param {string} url - The WebSocket URL to connect to.
+   */
   createConnection(url) {
     // Web Browser WebSocket
+    IO.webSocketCount++;
     this.socket = new WebSocket(url);
     this.socket.binaryType = IO.binaryType
 
     this.stateChange('opening')
 
     this.socket.onopen = () => {
+
+      if (!this.socket) {
+        return;
+      }
+
       if (this.socket.binaryType == "arraybuffer") {
         this.socket.onmessage = this.onWebSocketMessage.bind(this);
       } else {  // blob
@@ -79,6 +151,10 @@ export default class IO extends IOCore {
     }
   }
 
+  /**
+   * Handles incoming WebSocket messages (arraybuffer type).
+   * @param {MessageEvent} event - The WebSocket message event.
+   */
   onWebSocketMessage(event) {
     // event.data is arrayBuffer  or text_message
     this.rxCounter++;
@@ -88,6 +164,10 @@ export default class IO extends IOCore {
     this.emit('socket_data', buffer);
   }
 
+  /**
+   * Handles incoming WebSocket messages (blob type).
+   * @param {MessageEvent} event - The WebSocket message event.
+   */
   async onWebSocketMessageBlob(event) {
     // event.data is Blob or text_message
     this.rxCounter++;
@@ -103,6 +183,10 @@ export default class IO extends IOCore {
     this.emit('socket_data', buffer);
   }
 
+  /**
+   * Sends data over the WebSocket.
+   * @param {BufferSource} data - The data to send.
+   */
   socket_send(data) {
     if (this.socket?.readyState === 1) {
       this.socket.send(data)

package/src/common/constants.js

@@ -1,4 +1,16 @@
 
+/**
+ * @typedef {object} STATES
+ * @property {number} OPENING
+ * @property {number} OPEN
+ * @property {number} CLOSING
+ * @property {number} CLOSED
+ * @property {number} SERVER_READY
+ * @property {number} AUTH_FAIL
+ * @property {number} AUTH_READY
+ * @property {number} READY
+ * @property {number} REDIRECTING
+ */
 // Client STATES: name and number
 export const STATES = {
   OPENING: 0,
@@ -13,7 +25,17 @@ export const STATES = {
 }
 for (let c in STATES) { STATES[STATES[c]] = c }
 
-// server side client state
+/**
+ * @typedef {object} CLIENT_STATE
+ * @property {number} INIT
+ * @property {number} SENT_SERVER_READY
+ * @property {number} RECV_AUTH_REQ
+ * @property {number} SENT_SERVER_NONCE
+ * @property {number} RECV_AUTH_HMAC
+ * @property {number} AUTH_FAIL
+ * @property {number} AUTH_READY
+ * @property {number} CID_READY
+ */
 export const CLIENT_STATE = {
   INIT: 0,
   SENT_SERVER_READY: 1,
@@ -26,6 +48,12 @@ export const CLIENT_STATE = {
 }
 for (let c in CLIENT_STATE) { CLIENT_STATE[CLIENT_STATE[c]] = c }
 
+/**
+ * @typedef {object} ENC_MODE
+ * @property {number} NO
+ * @property {number} YES
+ * @property {number} AUTO
+ */
 export let ENC_MODE = {
   NO: 0,
   YES: 1,
@@ -35,6 +63,15 @@ export let ENC_MODE = {
 for (let c in ENC_MODE) { ENC_MODE[ENC_MODE[c]] = c }
 
 
+/**
+ * @typedef {object} SIZE_LIMIT
+ * @property {number} TAG_LEN1
+ * @property {number} TAG_LEN2
+ * @property {number} CONNECTION_CHECKER_PERIOD
+ * @property {number} PROMISE_TIMEOUT
+ * @property {number} DID
+ * @property {number} CID
+ */
 export const SIZE_LIMIT = {
   TAG_LEN1: 255,
   TAG_LEN2: 65535,
@@ -44,6 +81,15 @@ export const SIZE_LIMIT = {
   CID: 12
 }
 
+/**
+ * @typedef {object} PAYLOAD_TYPE
+ * @property {number} EMPTY
+ * @property {number} TEXT
+ * @property {number} BINARY
+ * @property {number} OBJECT
+ * @property {number} MJSON
+ * @property {number} MBA
+ */
 export let PAYLOAD_TYPE = {
   EMPTY: 0,
   TEXT: 1,
@@ -55,6 +101,40 @@ export let PAYLOAD_TYPE = {
 for (let c in PAYLOAD_TYPE) { PAYLOAD_TYPE[PAYLOAD_TYPE[c]] = c }
 
 
+/**
+ * @typedef {object} IOMsg
+ * @property {number} SERVER_READY
+ * @property {number} CID_REQ
+ * @property {number} CID_RES
+ * @property {number} QUOTA_LEVEL
+ * @property {number} SERVER_CLEAR_AUTH
+ * @property {number} SERVER_REDIRECT
+ * @property {number} LOOP
+ * @property {number} ECHO
+ * @property {number} PING
+ * @property {number} PONG
+ * @property {number} CLOSE
+ * @property {number} SIGNAL
+ * @property {number} SIGNAL_REQ
+ * @property {number} SIGNAL_E2E
+ * @property {number} SUBSCRIBE
+ * @property {number} SUBSCRIBE_REQ
+ * @property {number} UNSUBSCRIBE
+ * @property {number} SERVER_SIGNAL
+ * @property {number} IAM
+ * @property {number} IAM_RES
+ * @property {number} SET
+ * @property {number} RESPONSE_CODE
+ * @property {number} RESPONSE_MBP
+ * @property {number} REQUEST
+ * @property {number} RESPONSE
+ * @property {number} FLOW_MODE
+ * @property {number} WAIT
+ * @property {number} RESUME
+ * @property {number} TIME_OUT
+ * @property {number} OVER_SIZE
+ * @property {number} OVER_FLOW
+ */
 // IO message's one-byte headers.
 export let IOMsg = {
 
@@ -134,11 +214,21 @@ export let IOMsg = {
 for (let c in IOMsg) { IOMsg[IOMsg[c]] = c }
 // console.log( IOMsg );
 
+/**
+ * @typedef {object} API_TYPE
+ * @property {string} REQUEST_RESPONSE
+ * @property {string} ONE_WAY
+ */
 export const API_TYPE = {
   'REQUEST_RESPONSE': 'requet_response',
   'ONE_WAY': 'one_way'
 }
 
+/**
+ * @typedef {object} STATUS
+ * @property {number} OK
+ * @property {number} ERROR
+ */
 // api response status code
 export const STATUS = {
   OK: 0,

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist/types",
+    "allowJs": true,
+    "moduleResolution": "node",
+    "target": "es2015",
+    "lib": ["es2020", "dom"],
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": ["src/*"]
+    }
+  },
+  "include": [
+    "src/client/browser/IOWebSocket.js",
+    "src/client/IOCore.js",
+    "src/common/constants.js",
+    "package.json"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/docs/README.kr.md

@@ -1,230 +0,0 @@
-[ [en](../README.md) | kr ]
-
-# IOSignal
-
-IOSignal은 웹 브라우저, Node.js, 아두이노 간의 실시간 통신을 지원합니다. 또한 안전한 인증 및 암호화된 통신을 제공합니다. 시그널링 프로토콜이 내장되어 있어 프로그래밍 없이 서버를 사용할 수 있습니다.
-
-## 설치
-
-```shell
-$ npm i iosignal
-```
-
-## IOSignal 클라이언트
-
-### 브라우저 클라이언트 : ESM
-
-- 로컬 파일: "dist/io.js"
-- CDN: https://cdn.jsdelivr.net/npm/iosignal/dist/io.js
-
-```html
-<html>
-
-  <script type="module">
-    import IO from "../dist/io.js"
-
-    const io = new IO('wss://io.iosignal.net/ws')
-    io.listen('channel#topic', (...args)=>{
-      console.log( args )
-    })
-
-    io.on('ready',()=>{
-      console.log('ready cid:', io.cid )
-    })
-
-  </script>
-
-</html>
-```
-
-### 브라우저 클라이언트 : UMD(IIFE)
-- 로컬 파일: "dist/io.min.js"
-- CDN: https://cdn.jsdelivr.net/npm/iosignal/dist/io.min.js
-
-```html
-<html>
-  <script src="../dist/io.min.js"></script>
-  <script>
-    console.log('IO', IO)  // 기본 전역 변수 이름은 IO
-
-    var io1 = new IO('ws://localhost:7777')
-    var io2 = new IO('ws://localhost:7777')
-    var io3 = new IO('ws://localhost:7777')
-
-    io1.on('error', errorHandler )
-    io2.on('error', errorHandler )
-    io3.on('error', errorHandler )
-
-    let channelName = 'io'
-
-    // 고전적인 스타일의 구독
-    io1.on('ready',e=>{
-      io1.subscribe(channelName)
-      io1.on(channelName, (...args)=>{
-        // console.log('io1 received', args )
-        let msg = '[io1] ' + JSON.stringify( args )
-        addMessage(msg)
-      })
-    })
-
-    // iosignal 스타일의 구독
-    io2.listen(channelName, (...args)=>{
-      // console.log('io2 receive', args )
-      let msg = '[io2] ' + JSON.stringify( args )
-        addMessage(msg)
-    })
-
-    setInterval(e=>{
-      io3.signal(channelName, 'single string')   // 단일 문자열 페이로드
-      io3.signal(channelName, Date.now(), 'a', 2 , {key: 3} ) // 다중 페이로드
-      io3.signal(channelName ) // 페이로드 없는 순수 시그널
-    },3000)
-
-    function addMessage(msg){
-      // ...
-    }
-
-    function errorHandler(e){
-      // ...
-    }
-  </script>
-
-</html>
-```
-
-### NodeJS 클라이언트
-```js
-  import { IO } from "iosignal"
-
-  const io = new IO('wss://io.iosignal.net/ws')
-
-  io.on('ready', ()=>{
-    console.log('ready cid:', io.cid)
-    io.signal('#screen','playToggle')
-  });
-
-  io.listen('#notify', (...args)=>{
-    console.log( args )
-  })
-
-  io.on('error',err=>{
-      console.log('err', err)
-  })
-
-```
-
-## IOSignal 서버
-
-```js
-import { Server } from "iosignal"
-
-const server = new Server(
-  {
-    port: 7777,
-    congPort: 8888,
-    showMetric: 2,
-    showMessage: 'message' // 시그널 메시지 표시
-  })
-
-```
-
-- port: <Number> WebSocket을 통한 IOSignal
-- congPort: <Number> CongSocket을 통한 IOSignal
-- showMetric: 1|2|3 클라이언트 CID(상태) 정보 표시
-- showMessage: "none"|"message" 시그널 버퍼 메시지 표시
-- timeout <milliseconds> 핑 주기 및 타임아웃 (최소 1000)
-
-### IOSignal API
-
-IOSignal API 예시
-- src/api_reply.js  // 'echo', 'date', 'unixtime'
-- src/api_sudo.js   // 서버 관리자 모니터링 명령어
-- src/RedisAPI.js   // Redis 명령어 및 응답 서비스
-
-
-서버에 API 서비스를 등록하려면 api() 메서드를 사용합니다.
-
-`api('api_name', module )`
-
-```js
-// node.js
-import { Server ,api_reply  } from 'iosignal'
-const server = new Server( { port: 7777 }  )
-server.api('reply', api_reply) // API 모듈 연결
-```
-
-클라이언트가 reply API를 호출하는 예시
-
-```js
-  // 웹 브라우저 API 클라이언트 예시
-  <script src="../dist/io.min.js"></script>
-  <script>
-      const io = new IO('ws://localhost:7777')
-
-      io.on('ready', async ()=>{
-        let res_echo = await io.req('reply', 'echo', 'hello' )
-        let res_date = await io.req('reply', 'date' )
-        let res_unixtime = await io.req('reply', 'unixtime' )
-
-        if( res_echo.ok ) console.log( res_echo.body  )
-        if( res_date.ok ) console.log( res_date.body  )
-        if( res_unixtime.ok ) console.log( res_unixtime.body  )
-      });
-  </script>
-
-// 결과
-[ 'hello' ]
-Fri, 09 Feb 2024 14:24:37 GMT
-1707488677
-
-```
-
-## 기능
-
-### 내장 메시지 전송 프로토콜
-- 채널 이름을 통한 pub/sub 멀티캐스트.
-- 유니캐스트: CID를 통한 일대일 메시징.
-- `CID`는 통신 ID입니다.
-- CID 구독: CID를 사용하여 하나의 피어 구독.
-- HomeChannel: IP 주소별 그룹화.
-
-### 내장 보안
-- 인증
-- 암호화
-- E2EE
-- `Boho` 덕분입니다 [ [github](https://github.com/remocons/boho) ]
-
-## 연결
- - 웹 브라우저는 WebSocket을 사용합니다.
- - Node.js는 WebSocket 또는 CongSocket을 사용합니다.
- - 아두이노는 CongSocket을 사용합니다.
-
-## IOSignal 서버 아키텍처
-![IOSignal](./iosignal_architecture.png)
-
-## IOSignal 저장소
-
-- Javascript: `iosignal` [ [github](https://github.com/remocons/iosignal) | [npm](https://www.npmjs.com/package/iosignal) ]
-    - Node.js 서버 (WebSocket, CongSocket)
-    - Node.js 클라이언트 (WebSocket, CongSocket)
-    - 웹 브라우저 클라이언트 (WebSocket)
-
-- CLI 프로그램
-    - `iosignal-cli` [ [github](https://github.com/remocons/iosignal-cli) | [npm](https://www.npmjs.com/package/iosignal-cli) ]
-    - 설치: `npm i -g iosignal-cli` 또는 `sudo npm i -g iosignal-cli`
-    - Mac, Linux, Windows 지원.
-    - 서버 및 클라이언트
-
-- 아두이노 iosignal 라이브러리 및 예시:
-    - 아두이노 라이브러리 관리자 사용: `iosignal`
-    - 또는 `iosignal-arduino` [ [github](https://github.com/remocons/iosignal-arduino) ]
-    - 웹 앱 : http://test.iosignal.net
-
-- 아두이노 remocon 라이브러리 및 예시:
-    - 아두이노 라이브러리 관리자 사용: `remocon`
-    - 또는 `remocon-arduino` [ [github](https://github.com/remocons/remocon-arduino) ]
-    - 웹 앱 : https://remocon.kr
-
-## 라이선스
-
-이 코드는 MIT 라이선스에 따라 배포됩니다.