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

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:

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.