# socket

WebSocket utilities for real-time bidirectional communication.

## Functions

| Function    | Description                              | Example                                        |
| ----------- | ---------------------------------------- | ---------------------------------------------- |
| `info`      | Get socket library information           | `dphelper.socket.info()`                       |
| `start`     | Initialize and start a socket connection | `dphelper.socket.start(element, server, name)` |
| `connect`   | Connect to a WebSocket server            | `dphelper.socket.connect(server, name)`        |
| `open`      | Open a named socket connection           | `dphelper.socket.open(id, server, name)`       |
| `send`      | Send data through socket                 | `dphelper.socket.send(message, type, name)`    |
| `receive`   | Set up message receiver                  | `dphelper.socket.receive(element, name)`       |
| `keepAlive` | Maintain connection with ping/pong       | `dphelper.socket.keepAlive(name)`              |
| `ping`      | Send ping to server                      | `dphelper.socket.ping(name)`                   |
| `check`     | Check and cleanup closed connections     | `dphelper.socket.check()`                      |
| `list`      | List all active WebSocket connections    | `dphelper.socket.list()`                       |

## Description

Complete WebSocket management toolkit:

* **Connection Management** - Connect, disconnect, keep-alive
* **Messaging** - Send and receive data
* **Monitoring** - Track active connections
* **Security** - Enforces WSS (TLS) for production

## Usage Examples

### Basic Connection

```javascript
// Initialize a socket connection
dphelper.socket.connect('wss://example.com/socket', 'myConnection');

// Set up message receiver
dphelper.socket.receive('#messageContainer', 'myConnection');

// Send a message
dphelper.socket.send('Hello World', 'message', 'myConnection');
```

### Complete Real-time Chat

```javascript
// Initialize chat connection
function initChat() {
  const server = 'wss://chat.example.com/ws';
  const name = 'chat';

  // Connect to server
  dphelper.socket.connect(server, name);

  // Set up message handler
  dphelper.socket.receive('#chatMessages', name);

  // Keep connection alive
  dphelper.socket.keepAlive(name);
}

// Send message
function sendMessage(text) {
  dphelper.socket.send(text, 'chat', 'chat');
}

// HTML: <div id="chatMessages"></div>
// HTML: <input type="text" id="chatInput">
// HTML: <button onclick="sendMessage(document.getElementById('chatInput').value)">Send</button>
```

### Multiple Socket Connections

```javascript
// Create multiple named connections
dphelper.socket.connect('wss://api.example.com/notifications', 'notifications');
dphelper.socket.connect('wss://api.example.com/updates', 'updates');
dphelper.socket.connect('wss://api.example.com/chat', 'chat');

// Send to specific connection
dphelper.socket.send('New user', 'notification', 'notifications');
dphelper.socket.send('Update data', 'update', 'updates');

// List all active connections
const connections = dphelper.socket.list();
console.log(`Active connections: ${connections.length}`);
```

### Keep-Alive Implementation

```javascript
// Maintain connection with automatic ping/pong
dphelper.socket.keepAlive('mainConnection');

// Manual ping
dphelper.socket.ping('mainConnection');

// Check connection health
dphelper.socket.check();
```

### Form Submission via Socket

```javascript
// Send form data through socket
document.querySelector('form').addEventListener('submit', (e) => {
  e.preventDefault();

  const formData = new FormData(e.target);
  const data = Object.fromEntries(formData);

  dphelper.socket.send(JSON.stringify(data), 'form', 'mainConnection');
});
```

## Security Features

* **TLS Enforcement** - Only allows secure WebSocket connections (wss\://)
* **URL Validation** - Prevents arbitrary origin connections
* **Same-origin fallback** - Supports relative URLs

## Details

* **Author:** Dario Passariello
* **Version:** 0.0.2
* **Creation Date:** 20210101
* **Last Modified:** 20260220
* **Environment:** Client-side only (browser)

***

*Automatically generated document*