Add vitepress docs

docs/net/connection.md

@@ -0,0 +1,78 @@
+# 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.