iosignal 2.2.1 → 3.0.1

package/README.md

@@ -1,10 +1,8 @@
-# IOSignal
+[ English | [한국어](docs/README.ko.md) ]
 
-[En] iosignal supports real-time communication between web browsers, node.js, and arduino. It also provides secure authentication and encrypted communication.
-The signaling protocol is built-in, so the server can be used without programming.
+# IOSignal
 
-[Kr] iosignal 은 웹브라우저, node.js ,  arduino 간의 실시간 통신을 지원합니다.  또한 보안 인증과 암호통신 기능도 제공됩니다.
-시그널링 프로토콜이 내장되어 있어서 서버는 프로그래밍 없이 사용 가능합니다.
+IOSignal enables real-time communication across web browsers, Node.js, and Arduino. It features built-in secure authentication, encrypted communication, and a pre-configured signaling protocol, allowing server deployment without complex programming.
 
 ## Install
 
@@ -12,118 +10,183 @@ The signaling protocol is built-in, so the server can be used without programmin
 $ npm i iosignal
 ```
 
-## IOSignal Server
 
-### ESM
-```js
-import { Server } from "iosignal"
-const server = new Server( { port: 7777 } )
-```
-
-### CJS
-```js
-let { Server } = require('iosignal')
-const server = new Server( { port: 7777 } )
-```
-
-### server options
 
+## IOSignal Client
 
-```js
-let { Server } = require('iosignal')
-
-const server = new Server(
-  {
-    port: 7777,     
-    congPort: 8888, 
-    showMetric: 2,  
-    showMessage: 'message' // show signal message
-  })
 
+### React Client Example
+
+A sample React project is available in `examples/react-chat-js`. This example demonstrates how to integrate `iosignal` into a React application for real-time chat functionality.
+
+**Key Concepts:**
+
+-   **`useRef`**: To maintain a stable reference to the `io` instance across component re-renders.
+-   **`useEffect`**: To manage the lifecycle of the `io` instance, including initialization and cleanup. Event handlers are set up within this hook.
+- To release the `io` instance when the component unmounts, use `io.destroy()`. Event handlers registered during mount are also automatically removed.
+
+**To run the example:**
+
+1.  Navigate to the server directory and start the server:
+    ```shell
+    cd examples/server
+    npm install
+    node .
+    ```
+2.  In a new terminal, navigate to the React project directory, install dependencies, and start the development server:
+    ```shell
+    cd examples/react-chat-js
+    npm install
+    npm run dev
+    ```
+
+**Example Code (`App.jsx`):**
+
+If you open multiple browsers and enter a message, it will be delivered to each other via the server.
+
+```javascript
+import { useState, useEffect, useRef } from 'react';
+import './App.css';
+import IO from 'iosignal/io.js';
+
+const url = 'ws://localhost:7777';
+const channel_tag = 'channel#topic';
+
+function App() {
+  const [messages, setMessages] = useState([]);
+  const [input, setInput] = useState('Hello, World!');
+  const [ioState, setIoState] = useState(null);
+  const [cid, setCid] = useState(null);
+  const [counts, setCounts] = useState({ instances: 0, websockets: 0 });
+  const ioRef = useRef(null);
+  const messagesEndRef = useRef(null);
+
+  const scrollToBottom = () => {
+    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
+  };
+
+  useEffect(() => {
+    scrollToBottom();
+  }, [messages]);
+
+  useEffect(() => {
+    ioRef.current = new IO(url);
+    setCounts({ instances: IO.instanceCount, websockets: IO.webSocketCount });
+
+    const handleReady = () => {
+      console.log('ready cid:', ioRef.current.cid);
+      setCid(ioRef.current.cid);
+      ioRef.current.subscribe(channel_tag);
+    };
+
+    const handleChange = (state) => {
+      setIoState(state);
+      setCounts({ instances: IO.instanceCount, websockets: IO.webSocketCount });
+    };
+
+    const handleChannelMessage = (msgObj, tag) => {
+      console.log('Received message in App:', msgObj, tag);
+      if (typeof msgObj === 'string') {
+        msgObj = { text: msgObj, cid: 'cli unknown' };
+      }
+      setMessages((prevMessages) => [...prevMessages, `${msgObj.cid} : ${msgObj.text}`]);
+    };
+
+    const handleError = (error) => {
+      console.error('IO Error in App:', error);
+      setIoState(`Error: ${error.message}`);
+    };
+
+    ioRef.current.on('ready', handleReady);
+    ioRef.current.on('change', handleChange);
+    ioRef.current.on(channel_tag, handleChannelMessage);
+    ioRef.current.on('error', handleError);
+
+    return () => {
+      ioRef.current.destroy();
+      console.log('IO instance destroyed.');
+      ioRef.current = null;
+    };
+  }, []);
+
+  const sendMessage = () => {
+    if (input.trim()) {
+      const msgObj = { text: input, cid: ioRef.current.cid };
+      ioRef.current.signal(channel_tag, msgObj);
+      setInput('date' + Date.now());
+    }
+  };
+
+  const ioStateStyle = {
+    color: ioState === 'ready' ? 'green' : 'red',
+    fontWeight: 'bold',
+  };
+
+  return (
+    <div className="App">
+      <h1>React Chat Example</h1>
+      <div>URL: {url}</div>
+      <div>Channel: {channel_tag}</div>
+      <div>IO State: <span style={ioStateStyle}>{ioState}</span></div>
+      <div>Client ID: {cid}</div>
+      <div>IO Instances: {counts.instances}</div>
+      <div>WebSockets Created: {counts.websockets}</div>
+      <div className="messages">
+        {messages.map((msg, index) => (
+          <div key={index}>{msg}</div>
+        ))}
+        <div ref={messagesEndRef} />
+      </div>
+      <div className="input-area">
+        <input
+          type="text"
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          onKeyUp={(e) => e.key === 'Enter' && sendMessage()}
+          disabled={ioState !== 'ready'}
+        />
+        <button onClick={sendMessage} disabled={ioState !== 'ready'}>
+          Send
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export default App;
 ```
 
-- port: <Number> IOSignal over WebSocket
-- congPort: <Number> IOsignal over CongSocket
-- showMetric: 1|2|3 show clients cid(state) info
-- showMessage: "none"|"message" show signal buffer message
-- timeout <milliseconds> ping period & timeout (min. 1000)
-
-### IOSignal API
 
-IOSignal API examples
-- src/api_reply.js  // 'echo', 'date', 'unixtime'
-- src/api_sudo.js   // server admin monitoring command
-- src/RedisAPI.js   // redis command and response service
-
-
-To register an API service with the server, use the api() method
+### Browser client : ESM
 
-`api('api_name', module )`
+- local file: "dist/io.js"
+- CDN: https://cdn.jsdelivr.net/npm/iosignal/dist/io.js
 
-```js
-// node.js
-import { Server ,api_reply  } from 'iosignal'
-const server = new Server( { port: 7777 }  )
-server.api('reply', api_reply) // attach api module
-```
+```html
+<html>
 
-Example of a client calling the reply API
+  <script type="module">
+    import IO from "../dist/io.js"
 
-```js
-  // web browser api client example
-  <script src="../dist/io.min.js"></script>
-  <script>
-      const io = new IO('ws://localhost:7777')
+    const io = new IO('wss://io.iosignal.net/ws')
+    io.listen('channel#topic', (...args)={
+      console.log( args )
+    })
 
-      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' )
+    io.on('ready',()=>{
+      console.log('ready cid:', io.cid )
+    })
 
-        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>
 
-// result
-[ 'hello' ]
-Fri, 09 Feb 2024 14:24:37 GMT
-1707488677
-
+</html>
 ```
 
 
-## IOSignal Client
-
-### NodeJS Client
-```js
-  // ESM
-  import { IO } from "iosignal"
-
-  // CJS
-  // const { IO } = require('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)
-  })
-
-```
-
 ### Browser Client : UMD(IIFE)
-- local file: "./dist/io.min.js"
-- CDN: https://cdn.jsdelivr.net/npm/iosignal@2.2.0/dist/io.min.js
+- local file: "dist/io.min.js"
+- CDN: https://cdn.jsdelivr.net/npm/iosignal/dist/io.min.js
+
 ```html
 <html>
   <script src="../dist/io.min.js"></script>
@@ -175,31 +238,101 @@ Fri, 09 Feb 2024 14:24:37 GMT
 </html>
 ```
 
-### Browser client : ESM
 
-- local file: "./dist/io.js"
-- CDN: https://cdn.jsdelivr.net/npm/iosignal@2.2.0/dist/io.js
 
-```html
-<html>
 
-  <script type="module">
-    import IO from "../dist/io.js"
+### NodeJS Client
+```js
+  import { IO } from "iosignal"
 
-    const io = new IO('wss://io.iosignal.net/ws')
-    io.listen('channel#topic', (...args)={
-      console.log( args )
-    })
+  const io = new IO('wss://io.iosignal.net/ws')
 
-    io.on('ready',()=>{
-      console.log('ready cid:', io.cid )
-    })
+  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 Server
+
+
+```js
+import { Server } from "iosignal"
+
+const server = new Server(
+  {
+    port: 7777,     
+    congPort: 8888, 
+    showMetric: 2,  
+    showMessage: 'message' // show signal message
+  })
+
+```
 
+- port: <Number> IOSignal over WebSocket
+- congPort: <Number> IOsignal over CongSocket
+- showMetric: 1|2|3 show clients cid(state) info
+- showMessage: "none"|"message" show signal buffer message
+- timeout <milliseconds> ping period & timeout (min. 1000)
+
+### IOSignal API
+
+IOSignal API examples
+- src/api_reply.js  // 'echo', 'date', 'unixtime'
+- src/api_sudo.js   // server admin monitoring command
+- src/RedisAPI.js   // redis command and response service
+
+
+To register an API service with the server, use the api() method
+
+`api('api_name', module )`
+
+```js
+// node.js
+import { Server ,api_reply  } from 'iosignal'
+const server = new Server( { port: 7777 }  )
+server.api('reply', api_reply) // attach api module
+```
+
+Example of a client calling the reply API
+
+```js
+  // web browser api client example
+  <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>
 
-</html>
+// result
+[ 'hello' ]
+Fri, 09 Feb 2024 14:24:37 GMT
+1707488677
+
 ```
 
+
 ## Features
 
 ### Built-in Message Trasport Protocol
@@ -220,7 +353,8 @@ Fri, 09 Feb 2024 14:24:37 GMT
  - Node.js use WebSocket or CongSocket.
  - Arduino use CongSocket.
 
-![IOSignal](./img/iosignal_stack.png)
+## IOSignal Server Architecture
+![IOSignal](./docs/iosignal_architecture.png)
 
 ## IOSignal repositories.