@highway1/core 0.1.53 → 0.1.55

package/src/transport/relay-client.ts

@@ -1,437 +0,0 @@
-/**
- * CVP-0011: WebSocket relay client with reconnection logic
- */
-
-import { WebSocket } from 'ws';
-import { encode as encodeCBOR, decode as decodeCBOR } from 'cbor-x';
-import { createLogger } from '../utils/logger.js';
-import { TransportError } from '../utils/errors.js';
-import { sign } from '../identity/keys.js';
-import type { KeyPair } from '../identity/keys.js';
-import type { AgentCard } from '../discovery/agent-card-types.js';
-import type {
-  RelayMessage,
-  HelloMessage,
-  WelcomeMessage,
-  DeliverMessage,
-  DiscoveredAgent,
-  DeliveryReportMessage,
-} from './relay-types.js';
-
-const logger = createLogger('relay-client');
-
-export interface RelayClientConfig {
-  relayUrls: string[];
-  did: string;
-  keyPair: KeyPair;
-  card: AgentCard;
-  reconnect?: {
-    baseMs?: number;
-    jitterMs?: number;
-    maxDelayMs?: number;
-    stableAfterMs?: number;
-  };
-}
-
-export type MessageDeliveryHandler = (msg: DeliverMessage) => Promise<void>;
-export type DeliveryReportHandler = (msg: DeliveryReportMessage) => void;
-
-export interface RelayClient {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  sendEnvelope(toDid: string, envelopeBytes: Uint8Array): Promise<void>;
-  discover(query: string, minTrust?: number, limit?: number): Promise<DiscoveredAgent[]>;
-  fetchCard(did: string): Promise<AgentCard | null>;
-  onDeliver(handler: MessageDeliveryHandler): void;
-  onDeliveryReport(handler: DeliveryReportHandler): void;
-  isConnected(): boolean;
-  getConnectedRelays(): string[];
-  getPeerCount(): number;
-}
-
-interface RelayConnection {
-  url: string;
-  ws: WebSocket | null;
-  connected: boolean;
-  reconnectAttempt: number;
-  reconnectTimer: NodeJS.Timeout | null;
-  stableTimer: NodeJS.Timeout | null;
-  pingTimer: NodeJS.Timeout | null;  // CVP-0011 §2.5: PING every 30s
-  peerCount: number;
-}
-
-const DEFAULT_RECONNECT = {
-  baseMs: 1000,
-  jitterMs: 2000,
-  maxDelayMs: 30000,
-  stableAfterMs: 60000,
-};
-
-export function createRelayClient(config: RelayClientConfig): RelayClient {
-  const { relayUrls, did, keyPair, card } = config;
-  const reconnectConfig = { ...DEFAULT_RECONNECT, ...config.reconnect };
-
-  const connections: RelayConnection[] = relayUrls.map((url) => ({
-    url,
-    ws: null,
-    connected: false,
-    reconnectAttempt: 0,
-    reconnectTimer: null,
-    stableTimer: null,
-    pingTimer: null,
-    peerCount: 0,
-  }));
-
-  let deliveryHandler: MessageDeliveryHandler | null = null;
-  let deliveryReportHandler: DeliveryReportHandler | null = null;
-  let stopped = false;
-
-  async function connectToRelay(conn: RelayConnection): Promise<void> {
-    if (stopped) return;
-
-    try {
-      logger.info('Connecting to relay', { url: conn.url });
-
-      const ws = new WebSocket(conn.url);
-      conn.ws = ws;
-
-      await new Promise<void>((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          reject(new Error('Connection timeout'));
-        }, 10000);
-
-        ws.on('open', async () => {
-          clearTimeout(timeout);
-          logger.info('WebSocket connected', { url: conn.url });
-
-          try {
-            // Send HELLO message (CBOR-encoded)
-            const timestamp = Date.now();
-            const helloData = encodeCBOR({ did, card, timestamp });
-            const signature = await sign(helloData, keyPair.privateKey);
-
-            const hello: HelloMessage = {
-              type: 'HELLO',
-              protocolVersion: 1,
-              did,
-              card,
-              timestamp,
-              signature,
-            };
-
-            ws.send(encodeCBOR(hello));
-            resolve();
-          } catch (err) {
-            reject(err);
-          }
-        });
-
-        ws.on('error', (err) => {
-          clearTimeout(timeout);
-          reject(err);
-        });
-      });
-
-      // Set up message handler (CBOR decoding)
-      ws.on('message', async (data: Buffer) => {
-        try {
-          const msg: RelayMessage = decodeCBOR(data);
-          await handleRelayMessage(conn, msg);
-        } catch (err) {
-          logger.warn('Failed to parse relay message', { error: (err as Error).message });
-        }
-      });
-
-      ws.on('close', () => {
-        logger.info('WebSocket closed', { url: conn.url });
-        conn.connected = false;
-        conn.ws = null;
-
-        // Clear timers
-        if (conn.stableTimer) {
-          clearTimeout(conn.stableTimer);
-          conn.stableTimer = null;
-        }
-        if (conn.pingTimer) {
-          clearInterval(conn.pingTimer);
-          conn.pingTimer = null;
-        }
-
-        if (!stopped) {
-          scheduleReconnect(conn);
-        }
-      });
-
-      ws.on('error', (err) => {
-        logger.warn('WebSocket error', { url: conn.url, error: err.message });
-      });
-    } catch (err) {
-      logger.warn('Failed to connect to relay', { url: conn.url, error: (err as Error).message });
-      conn.ws = null;
-      conn.connected = false;
-
-      if (!stopped) {
-        scheduleReconnect(conn);
-      }
-    }
-  }
-
-  function scheduleReconnect(conn: RelayConnection): void {
-    if (conn.reconnectTimer) return;
-
-    const delay = Math.min(
-      reconnectConfig.baseMs * Math.pow(2, conn.reconnectAttempt) + Math.random() * reconnectConfig.jitterMs,
-      reconnectConfig.maxDelayMs
-    );
-
-    conn.reconnectAttempt++;
-    logger.debug('Scheduling reconnect', { url: conn.url, attempt: conn.reconnectAttempt, delayMs: delay });
-
-    conn.reconnectTimer = setTimeout(() => {
-      conn.reconnectTimer = null;
-      connectToRelay(conn);
-    }, delay);
-  }
-
-  async function handleRelayMessage(conn: RelayConnection, msg: RelayMessage): Promise<void> {
-    switch (msg.type) {
-      case 'WELCOME': {
-        const welcome = msg as WelcomeMessage;
-        logger.info('Received WELCOME', { relayId: welcome.relayId, peers: welcome.peers });
-        conn.connected = true;
-        conn.peerCount = welcome.peers;
-        conn.reconnectAttempt = 0;
-
-        // Start stable timer
-        if (conn.stableTimer) clearTimeout(conn.stableTimer);
-        conn.stableTimer = setTimeout(() => {
-          conn.reconnectAttempt = 0;
-          logger.debug('Connection stable', { url: conn.url });
-        }, reconnectConfig.stableAfterMs);
-
-        // CVP-0011 §2.5: Start PING heartbeat (every 30s)
-        if (conn.pingTimer) clearInterval(conn.pingTimer);
-        conn.pingTimer = setInterval(() => {
-          if (conn.ws && conn.connected) {
-            conn.ws.send(encodeCBOR({ type: 'PING' }));
-            logger.debug('Sent PING', { url: conn.url });
-          }
-        }, 30000); // 30 seconds
-
-        break;
-      }
-
-      case 'DELIVER': {
-        const deliver = msg as DeliverMessage;
-        logger.info('Received DELIVER', { messageId: deliver.messageId, from: deliver.from });
-        if (deliveryHandler) {
-          await deliveryHandler(deliver);
-        }
-        // CVP-0011 §2.7: Send ACK after processing message
-        if (conn.ws && conn.connected) {
-          conn.ws.send(encodeCBOR({ type: 'ACK', messageId: deliver.messageId }));
-          logger.debug('Sent ACK', { messageId: deliver.messageId });
-        }
-        break;
-      }
-
-      case 'DELIVERY_REPORT': {
-        const report = msg as DeliveryReportMessage;
-        logger.info('Received DELIVERY_REPORT', { messageId: report.messageId, status: report.status });
-        if (deliveryReportHandler) {
-          deliveryReportHandler(report);
-        }
-        break;
-      }
-
-      case 'PONG': {
-        conn.peerCount = msg.peers;
-        logger.debug('Received PONG', { peers: msg.peers });
-        break;
-      }
-
-      case 'GOODBYE': {
-        // CVP-0011 §2.6: Handle graceful shutdown with reconnectAfter
-        const goodbye = msg as any;
-        const reconnectAfter = goodbye.reconnectAfter || 5000;
-        logger.info('Received GOODBYE', { url: conn.url, reconnectAfter });
-
-        // Close connection and schedule reconnection
-        if (conn.ws) {
-          conn.ws.close();
-        }
-
-        // Override reconnect delay with server's suggestion
-        setTimeout(() => {
-          if (!stopped) {
-            connectToRelay(conn);
-          }
-        }, reconnectAfter);
-        break;
-      }
-
-      default:
-        logger.debug('Received relay message', { type: msg.type });
-    }
-  }
-
-  function getConnectedConnection(): RelayConnection | null {
-    return connections.find((c) => c.connected && c.ws) || null;
-  }
-
-  async function sendToRelay(msg: RelayMessage): Promise<void> {
-    const conn = getConnectedConnection();
-    if (!conn || !conn.ws) {
-      throw new TransportError('No connected relay');
-    }
-
-    conn.ws.send(encodeCBOR(msg));
-  }
-
-  return {
-    async start(): Promise<void> {
-      stopped = false;
-      logger.info('Starting relay client', { relays: relayUrls.length });
-
-      // Stagger initial connections
-      for (let i = 0; i < connections.length; i++) {
-        const conn = connections[i];
-        setTimeout(() => {
-          connectToRelay(conn);
-        }, Math.random() * 2000);
-      }
-
-      // Wait for at least one connection
-      const maxWait = 15000;
-      const start = Date.now();
-      while (Date.now() - start < maxWait) {
-        if (getConnectedConnection()) {
-          logger.info('Relay client started');
-          return;
-        }
-        await new Promise((resolve) => setTimeout(resolve, 100));
-      }
-
-      throw new TransportError('Failed to connect to any relay');
-    },
-
-    async stop(): Promise<void> {
-      stopped = true;
-      logger.info('Stopping relay client');
-
-      for (const conn of connections) {
-        if (conn.reconnectTimer) {
-          clearTimeout(conn.reconnectTimer);
-          conn.reconnectTimer = null;
-        }
-        if (conn.stableTimer) {
-          clearTimeout(conn.stableTimer);
-          conn.stableTimer = null;
-        }
-        if (conn.pingTimer) {
-          clearInterval(conn.pingTimer);
-          conn.pingTimer = null;
-        }
-        if (conn.ws) {
-          conn.ws.close();
-          conn.ws = null;
-        }
-        conn.connected = false;
-      }
-
-      logger.info('Relay client stopped');
-    },
-
-    async sendEnvelope(toDid: string, envelopeBytes: Uint8Array): Promise<void> {
-      const msg: RelayMessage = {
-        type: 'SEND',
-        to: toDid,
-        envelope: envelopeBytes,
-      };
-
-      await sendToRelay(msg);
-      logger.debug('Sent envelope', { to: toDid, size: envelopeBytes.length });
-    },
-
-    async discover(query: string, minTrust?: number, limit?: number): Promise<DiscoveredAgent[]> {
-      const conn = getConnectedConnection();
-      const ws = conn?.ws;
-      if (!conn || !ws) {
-        throw new TransportError('No connected relay');
-      }
-
-      return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          reject(new TransportError('Discover timeout'));
-        }, 10000);
-
-        const handler = (data: Buffer) => {
-          try {
-            const msg: RelayMessage = decodeCBOR(data);
-            if (msg.type === 'DISCOVERED') {
-              clearTimeout(timeout);
-              ws.off('message', handler);
-              resolve(msg.agents);
-            }
-          } catch (err) {
-            // Ignore parse errors
-          }
-        };
-
-        ws.on('message', handler);
-        ws.send(encodeCBOR({ type: 'DISCOVER', query, minTrust, limit } as RelayMessage));
-      });
-    },
-
-    async fetchCard(did: string): Promise<AgentCard | null> {
-      const conn = getConnectedConnection();
-      const ws = conn?.ws;
-      if (!conn || !ws) {
-        throw new TransportError('No connected relay');
-      }
-
-      return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          reject(new TransportError('Fetch card timeout'));
-        }, 5000);
-
-        const handler = (data: Buffer) => {
-          try {
-            const msg: RelayMessage = decodeCBOR(data);
-            if (msg.type === 'CARD' && msg.did === did) {
-              clearTimeout(timeout);
-              ws.off('message', handler);
-              resolve(msg.card);
-            }
-          } catch (err) {
-            // Ignore parse errors
-          }
-        };
-
-        ws.on('message', handler);
-        ws.send(encodeCBOR({ type: 'FETCH_CARD', did } as RelayMessage));
-      });
-    },
-
-    onDeliver(handler: MessageDeliveryHandler): void {
-      deliveryHandler = handler;
-    },
-
-    onDeliveryReport(handler: DeliveryReportHandler): void {
-      deliveryReportHandler = handler;
-    },
-
-    isConnected(): boolean {
-      return getConnectedConnection() !== null;
-    },
-
-    getConnectedRelays(): string[] {
-      return connections.filter((c) => c.connected).map((c) => c.url);
-    },
-
-    getPeerCount(): number {
-      const conn = getConnectedConnection();
-      return conn ? conn.peerCount : 0;
-    },
-  };
-}

package/src/transport/relay-types.ts

@@ -1,196 +0,0 @@
-/**
- * CVP-0011: Relay wire protocol types (shared between relay server and relay client)
- */
-
-import type { AgentCard } from '../discovery/agent-card-types.js';
-
-export const RELAY_PROTOCOL_VERSION = 1;
-
-export type RelayMessageType =
-  | 'HELLO'
-  | 'WELCOME'
-  | 'SEND'
-  | 'DELIVER'
-  | 'DISCOVER'
-  | 'DISCOVERED'
-  | 'PING'
-  | 'PONG'
-  | 'ACK'
-  | 'DELIVERY_REPORT'
-  | 'FETCH_CARD'
-  | 'CARD'
-  | 'GOODBYE'
-  | 'INDEX_SYNC'
-  | 'ROUTE'
-  | 'SYNC_HELLO'
-  | 'SYNC_REQUEST'
-  | 'SYNC_RESPONSE'
-  | 'SYNC_PUSH'
-  | 'SYNC_RECONCILE';
-
-export interface HelloMessage {
-  type: 'HELLO';
-  protocolVersion: number;
-  did: string;
-  card: AgentCard;
-  timestamp: number;
-  signature: Uint8Array;
-  extensions?: string[];
-}
-
-export interface WelcomeMessage {
-  type: 'WELCOME';
-  protocolVersion: number;
-  relayId: string;
-  peers: number;
-  federatedRelays: string[];
-  yourAddr: string;
-}
-
-export interface SendMessage {
-  type: 'SEND';
-  to: string;
-  envelope: Uint8Array;
-}
-
-export interface DeliverMessage {
-  type: 'DELIVER';
-  messageId: string;
-  from: string;
-  envelope: Uint8Array;
-}
-
-export interface DiscoverMessage {
-  type: 'DISCOVER';
-  query: string;
-  minTrust?: number;
-  limit?: number;
-}
-
-export interface DiscoveredAgent {
-  did: string;
-  card: AgentCard;
-  online: boolean;
-  homeRelay?: string;
-}
-
-export interface DiscoveredMessage {
-  type: 'DISCOVERED';
-  agents: DiscoveredAgent[];
-}
-
-export interface AckMessage {
-  type: 'ACK';
-  messageId: string;
-}
-
-export interface DeliveryReportMessage {
-  type: 'DELIVERY_REPORT';
-  messageId: string;
-  status: 'delivered' | 'expired' | 'queue_full' | 'unknown_recipient';
-  timestamp: number;
-}
-
-export interface PingMessage {
-  type: 'PING';
-}
-
-export interface PongMessage {
-  type: 'PONG';
-  peers: number;
-}
-
-export interface FetchCardMessage {
-  type: 'FETCH_CARD';
-  did: string;
-}
-
-export interface CardMessage {
-  type: 'CARD';
-  did: string;
-  card: AgentCard | null;
-}
-
-export interface GoodbyeMessage {
-  type: 'GOODBYE';
-  reconnectAfter?: number;  // CVP-0011 §2.6: Milliseconds to wait before reconnecting
-}
-
-export interface PresenceProof {
-  did: string;
-  homeRelay: string;
-  expiry: number;
-  signature: Uint8Array;
-}
-
-export interface SyncEvent {
-  seq: number;
-  type: 'JOIN' | 'LEAVE' | 'UPDATE';
-  did: string;
-  homeRelay: string;
-  cardHash?: string;
-  capabilityKeys?: string[];
-  online: boolean;
-  ts: number;
-  presenceProof?: PresenceProof;
-}
-
-export interface IndexSyncMessage {
-  type: 'INDEX_SYNC';
-  events: SyncEvent[];
-}
-
-export interface RouteMessage {
-  type: 'ROUTE';
-  to: string;
-  envelope: Uint8Array;
-  ttl: number;
-}
-
-export interface SyncHelloMessage {
-  type: 'SYNC_HELLO';
-  relayId: string;
-  seq: number;
-}
-
-export interface SyncRequestMessage {
-  type: 'SYNC_REQUEST';
-  fromSeq: number;
-}
-
-export interface SyncResponseMessage {
-  type: 'SYNC_RESPONSE';
-  events: SyncEvent[];
-}
-
-export interface SyncPushMessage {
-  type: 'SYNC_PUSH';
-  event: SyncEvent;
-}
-
-export interface SyncReconcileMessage {
-  type: 'SYNC_RECONCILE';
-  dids: string[];
-}
-
-export type RelayMessage =
-  | HelloMessage
-  | WelcomeMessage
-  | SendMessage
-  | DeliverMessage
-  | DiscoverMessage
-  | DiscoveredMessage
-  | AckMessage
-  | DeliveryReportMessage
-  | PingMessage
-  | PongMessage
-  | FetchCardMessage
-  | CardMessage
-  | GoodbyeMessage
-  | IndexSyncMessage
-  | RouteMessage
-  | SyncHelloMessage
-  | SyncRequestMessage
-  | SyncResponseMessage
-  | SyncPushMessage
-  | SyncReconcileMessage;