Ticruz
79 lines
2.0 KiB
Markdown
79 lines
2.0 KiB
Markdown
# Connection
|
|
|
|
The `Connection` class is the core building block for relay communication in `@welshman/net`. It manages the complete lifecycle of a relay connection, including socket handling, message queuing, authentication, and statistics tracking.
|
|
|
|
## Overview
|
|
|
|
A Connection handles:
|
|
- WebSocket lifecycle
|
|
- Message queuing and throttling
|
|
- Connection state tracking
|
|
- Relay authentication
|
|
- Connection statistics
|
|
|
|
## Basic Usage
|
|
|
|
```typescript
|
|
import {Connection} from '@welshman/net'
|
|
|
|
// Create connection
|
|
const connection = new Connection("wss://relay.example.com")
|
|
|
|
// Listen for events
|
|
connection.on('event', (conn, subId, event) => {
|
|
console.log(`Got event from ${conn.url}`)
|
|
})
|
|
|
|
// Send a subscription
|
|
connection.send(["REQ", "my-sub", {kinds: [1], limit: 10}])
|
|
|
|
// Clean up when done
|
|
connection.cleanup()
|
|
```
|
|
|
|
## Handling Authentication
|
|
|
|
The `connection.open()` promise resolves when the WebSocket connection is fully established and ready for communication.
|
|
However, it's important to understand the authentication flow:
|
|
|
|
```typescript
|
|
import {Connection} from '@welshman/net'
|
|
|
|
const connection = new Connection("wss://relay.example.com")
|
|
|
|
// Basic open
|
|
await connection.open()
|
|
// Promise resolves when WebSocket is connected
|
|
// BUT might not be auth-ready yet!
|
|
|
|
// Complete open with auth handling
|
|
const openRelay = async (url: string) => {
|
|
const connection = new Connection(url)
|
|
|
|
// Open socket
|
|
await connection.open()
|
|
|
|
// Check if relay requires auth
|
|
if (connection.auth.status === 'requested') {
|
|
try {
|
|
// Handle auth challenge
|
|
await connection.auth.attempt(3000) // 3s timeout
|
|
} catch (e) {
|
|
console.error('Auth failed:', e)
|
|
return null
|
|
}
|
|
}
|
|
|
|
// NOW connection is fully ready
|
|
return connection
|
|
}
|
|
```
|
|
|
|
The key states after `open()` resolves:
|
|
- Socket is connected
|
|
- Messages can be queued
|
|
- BUT relay might request authentication
|
|
- AND authentication might fail
|
|
|
|
Always check `connection.auth.status` if you need to ensure the connection is fully authenticated before use.
|