Socket

📖 Socket Module

The socket module in the ono-web package provides a WebSocket client to subscribe and listen to real-time updates from the ONO core node network.

---

📦 Importing

To use the socket module, import it as follows:

const OnoSocketClient = require('ono-web').socket;

---

🚀 Class: OnoSocketClient

The OnoSocketClient class allows you to connect, subscribe to events, and receive real-time updates from the ONO blockchain network.

---

🔨 Constructor

new OnoSocketClient(coreHost?)

Creates a new instance of the socket client. If no coreHost is provided, it defaults to ws://core.ono.gg.

📥 Parameters

Name	Type	Required	Description
coreHost	string	Optional	Custom ONO core node WebSocket address (e.g., ws://127.0.0.1:5001)

📝 Example

const client = new OnoSocketClient(); // Uses default ws://core.ono.gg
const client = new OnoSocketClient('http://127.0.0.1:5001'); // Custom address

---

📡 Methods

1. subscribe(handler, errorHandler)

Connects to the WebSocket server and subscribes to real-time blockchain updates (like new blocks, transactions, etc.).

📥 Parameters

Name	Type	Description
handler	function	Callback that handles incoming messages. Receives (message, socketClient)
errorHandler	function	Callback to handle JSON parsing or connection errors. Receives (error)

✅ Behavior

• Establishes a WebSocket connection.

• Automatically manages connection open/close state.

• Calls handler when a message is received.

• Calls errorHandler if there’s an error processing a message.

📝 Example

const client = new OnoSocketClient();

client.subscribe(
    (message, socket) => {
        console.log('Received message:', message);
    },
    (error) => {
        console.error('Socket error:', error);
    }
);

---

2. setCoreHost(address)

Changes the WebSocket core host after initialization, allowing reconnection to a different node.

📥 Parameters

Name	Type	Description
address	string	New WebSocket address for core node (e.g., http://127.0.0.1:5001)

📝 Example

client.setCoreHost('http://127.0.0.1:5001');

---

3. disconnect()

Gracefully closes the WebSocket connection and unsubscribes from updates.

📝 Example

client.disconnect();

---

📚 Usage Example (Full Flow)

const OnoSocketClient = require('ono-web').socket;

// Initialize client
const client = new OnoSocketClient('http://127.0.0.1:5001');

// Subscribe to blockchain events
client.subscribe(
    (message, socket) => {
        console.log('New update:', message);
    },
    (error) => {
        console.error('Failed to handle message:', error);
    }
);

// After some time, disconnect if needed
setTimeout(() => {
    client.disconnect();
    console.log('Disconnected from ONO core node.');
}, 60000); // Disconnect after 1 minute

---

⚙️ Internal Mechanics

• Each client instance gets a unique node-id using UUID, passed as query parameter for identification: ws://core.ono.gg?node-id=generated-uuid

• Automatically manages:

  • Connection opening

  • Re-subscription protection

  • Message parsing and error handling

---

🚨 Notes

• Make sure your core node allows external WebSocket connections if using a remote or custom host.

• Handle sensitive events securely when working with /secure WebSocket updates.

• Always manage disconnect() properly to avoid memory leaks or dangling connections.