@f2a/network 0.1.2

package/packages/openclaw-adapter/src/logger.ts

@@ -0,0 +1,51 @@
+/**
+ * OpenClaw Adapter 统一日志模块
+ * 
+ * 设计说明：
+ * - 提供统一的日志接口，便于维护和测试
+ * - 支持结构化日志输出
+ * - 默认使用 console，未来可扩展为其他日志系统
+ */
+
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+/** 默认日志前缀 */
+const DEFAULT_PREFIX = '[F2A]';
+
+/**
+ * 创建日志记录器
+ * @param component 组件名称（可选）
+ */
+export function createLogger(component?: string): Logger {
+  const prefix = component ? `[F2A:${component}]` : DEFAULT_PREFIX;
+
+  return {
+    debug(message: string, ...args: unknown[]): void {
+      console.log(`${prefix} ${message}`, ...args);
+    },
+    info(message: string, ...args: unknown[]): void {
+      console.log(`${prefix} ${message}`, ...args);
+    },
+    warn(message: string, ...args: unknown[]): void {
+      console.warn(`${prefix} ${message}`, ...args);
+    },
+    error(message: string, ...args: unknown[]): void {
+      console.error(`${prefix} ${message}`, ...args);
+    }
+  };
+}
+
+/** 默认日志记录器 */
+export const logger = createLogger();
+
+/** 组件专用日志记录器 */
+export const webhookLogger = createLogger('Webhook');
+export const taskGuardLogger = createLogger('TaskGuard');
+export const queueLogger = createLogger('Queue');
+export const nodeLogger = createLogger('Node');
+export const pluginLogger = createLogger('Plugin');

package/packages/openclaw-adapter/src/network-client.test.ts

@@ -0,0 +1,266 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { F2ANetworkClient } from './network-client';
+import { F2ANodeConfig } from './types';
+
+// Mock global fetch
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe('F2ANetworkClient', () => {
+  let client: F2ANetworkClient;
+  const mockConfig: F2ANodeConfig = {
+    nodePath: './F2A',
+    controlPort: 9001,
+    controlToken: 'test-token',
+    p2pPort: 9000,
+    enableMDNS: true,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new F2ANetworkClient(mockConfig);
+  });
+
+  describe('HTTP request handling', () => {
+    it('should include correct headers in requests', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, data: [] }),
+      });
+
+      await client.getConnectedPeers();
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:9001/peers',
+        expect.objectContaining({
+          headers: {
+            'Authorization': 'Bearer test-token',
+            'Content-Type': 'application/json',
+          },
+        })
+      );
+    });
+
+    it('should handle HTTP errors correctly', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        text: async () => 'Unauthorized',
+      });
+
+      const result = await client.getConnectedPeers();
+
+      expect(result.success).toBe(false);
+      // 新的 Result 类型中 error 是 F2AError 对象
+      if (!result.success) {
+        expect(result.error.message).toContain('401');
+        expect(result.error.code).toBe('CONNECTION_FAILED');
+      }
+    });
+
+    it('should handle network errors', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('Connection refused'));
+
+      const result = await client.getConnectedPeers();
+
+      expect(result.success).toBe(false);
+      // 新的 Result 类型中 error 是 F2AError 对象
+      if (!result.success) {
+        expect(result.error.message).toBe('Connection refused');
+        expect(result.error.code).toBe('CONNECTION_FAILED');
+      }
+    });
+
+    it('should handle JSON parsing errors', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => { throw new Error('Invalid JSON'); },
+      });
+
+      const result = await client.getConnectedPeers();
+
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('discoverAgents', () => {
+    it('should discover agents without capability filter', async () => {
+      const mockAgents = [
+        { peerId: 'peer-1', displayName: 'Agent 1', capabilities: [] },
+      ];
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockAgents,
+      });
+
+      const result = await client.discoverAgents();
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(mockAgents);
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:9001/discover',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({ capability: undefined }),
+        })
+      );
+    });
+
+    it('should discover agents with capability filter', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, data: [] }),
+      });
+
+      await client.discoverAgents('code-generation');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:9001/discover',
+        expect.objectContaining({
+          body: JSON.stringify({ capability: 'code-generation' }),
+        })
+      );
+    });
+  });
+
+  describe('delegateTask', () => {
+    it('should send task delegation request', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, data: { result: 'done' } }),
+      });
+
+      const result = await client.delegateTask({
+        peerId: 'peer-1',
+        taskType: 'test-task',
+        description: 'Test description',
+        parameters: { key: 'value' },
+        timeout: 30000,
+      });
+
+      expect(result.success).toBe(true);
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:9001/delegate',
+        expect.objectContaining({
+          method: 'POST',
+          body: expect.stringContaining('peer-1'),
+        })
+      );
+    });
+  });
+
+  describe('sendTaskResponse', () => {
+    it('should send task response with all fields', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      const result = await client.sendTaskResponse('peer-1', {
+        taskId: 'task-123',
+        status: 'success',
+        result: { output: 'hello' },
+        latency: 100,
+      });
+
+      expect(result.success).toBe(true);
+      const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(callBody).toMatchObject({
+        peerId: 'peer-1',
+        taskId: 'task-123',
+        status: 'success',
+      });
+    });
+  });
+
+  describe('registerWebhook', () => {
+    it('should register webhook with default events', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      const result = await client.registerWebhook('http://localhost:9002/webhook');
+
+      expect(result.success).toBe(true);
+      const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(callBody).toEqual({
+        url: 'http://localhost:9002/webhook',
+        events: ['discover', 'delegate', 'status'],
+      });
+    });
+  });
+
+  describe('updateAgentInfo', () => {
+    it('should update agent info', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      const result = await client.updateAgentInfo({
+        displayName: 'Test Agent',
+        capabilities: [{ name: 'test', description: 'Test capability', tools: [] }],
+      });
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('getPendingTasks', () => {
+    it('should get pending tasks', async () => {
+      const mockTasks = [{ taskId: 'task-1', description: 'Test' }];
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockTasks,
+      });
+
+      const result = await client.getPendingTasks();
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(mockTasks);
+    });
+  });
+
+  describe('confirmConnection', () => {
+    it('should confirm connection', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      const result = await client.confirmConnection('peer-1');
+
+      expect(result.success).toBe(true);
+      const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(callBody).toEqual({ peerId: 'peer-1' });
+    });
+  });
+
+  describe('rejectConnection', () => {
+    it('should reject connection with reason', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      const result = await client.rejectConnection('peer-1', 'suspicious');
+
+      expect(result.success).toBe(true);
+      const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(callBody).toEqual({ peerId: 'peer-1', reason: 'suspicious' });
+    });
+
+    it('should reject connection without reason', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true }),
+      });
+
+      await client.rejectConnection('peer-1');
+
+      const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(callBody).toEqual({ peerId: 'peer-1', reason: undefined });
+    });
+  });
+});

package/packages/openclaw-adapter/src/network-client.ts

@@ -0,0 +1,251 @@
+/**
+ * F2A Network Client
+ * 与 F2A Node 的 HTTP API 通信
+ */
+
+import type { 
+  F2ANodeConfig, 
+  AgentInfo, 
+  PeerInfo, 
+  TaskRequest, 
+  TaskResponse,
+  DelegateOptions
+} from './types.js';
+import { Result, failure, success, createError } from './types.js';
+import { nodeLogger as logger } from './logger.js';
+
+/** 默认请求超时（毫秒） */
+const DEFAULT_TIMEOUT_MS = 30000;
+
+/** 默认重试配置 */
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+
+/** 可重试的错误码 */
+const RETRYABLE_ERROR_CODES = [
+  'ECONNRESET',
+  'ENOTFOUND',
+  'ETIMEDOUT',
+  'ECONNREFUSED',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EAI_AGAIN'
+];
+
+/** 可重试的 HTTP 状态码 */
+const RETRYABLE_STATUS_CODES = [502, 503, 504, 429];
+
+export class F2ANetworkClient {
+  private baseUrl: string;
+  private token: string;
+  private timeoutMs: number;
+  private maxRetries: number;
+  private baseDelayMs: number;
+
+  constructor(config: F2ANodeConfig) {
+    this.baseUrl = `http://localhost:${config.controlPort}`;
+    this.token = config.controlToken;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.baseDelayMs = config.retryDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  }
+
+  /**
+   * 判断错误是否可重试
+   */
+  private isRetryableError(error: unknown): boolean {
+    if (error instanceof Error) {
+      // 网络错误
+      if (RETRYABLE_ERROR_CODES.some(code => error.message.includes(code))) {
+        return true;
+      }
+      // 超时错误
+      if (error.name === 'AbortError' || error.message.includes('timeout')) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * 计算重试延迟（指数退避 + 抖动）
+   */
+  private calculateDelay(attempt: number): number {
+    const exponentialDelay = this.baseDelayMs * Math.pow(2, attempt);
+    const jitter = Math.random() * this.baseDelayMs * 0.5;
+    return Math.min(exponentialDelay + jitter, 30000); // 最大 30 秒
+  }
+
+  /**
+   * 延迟函数
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  private async request<T>(
+    method: string, 
+    path: string, 
+    body?: unknown
+  ): Promise<Result<T>> {
+    // P1 修复：初始化 lastError 为有意义的默认值，避免 null 问题
+    let lastError: Error = new Error('Request failed before any attempt');
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      // 使用 AbortController 设置超时
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+
+      try {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+          method,
+          headers: {
+            'Authorization': `Bearer ${this.token}`,
+            'Content-Type': 'application/json'
+          },
+          body: body ? JSON.stringify(body) : undefined,
+          signal: controller.signal
+        });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          
+          // 检查是否是可重试的 HTTP 错误
+          if (RETRYABLE_STATUS_CODES.includes(response.status) && attempt < this.maxRetries) {
+            lastError = new Error(`HTTP ${response.status}: ${errorText}`);
+            const delayMs = this.calculateDelay(attempt);
+            logger.info(`Retrying request to ${path} after ${delayMs}ms (attempt ${attempt + 1}/${this.maxRetries})`);
+            clearTimeout(timeoutId);
+            await this.delay(delayMs);
+            continue;
+          }
+          
+          return failure(createError(
+            'CONNECTION_FAILED',
+            `HTTP ${response.status}: ${errorText}`
+          ));
+        }
+
+        const data = await response.json() as T;
+        return success(data);
+
+      } catch (error) {
+        // 处理超时错误
+        if (error instanceof Error && error.name === 'AbortError') {
+          if (attempt < this.maxRetries) {
+            const delayMs = this.calculateDelay(attempt);
+            logger.info(`Retrying request to ${path} after timeout (${delayMs}ms, attempt ${attempt + 1}/${this.maxRetries})`);
+            clearTimeout(timeoutId);
+            await this.delay(delayMs);
+            continue;
+          }
+          // 所有重试都因超时失败
+          return failure(createError(
+            'CONNECTION_FAILED',
+            `Request timed out after ${this.timeoutMs}ms`
+          ));
+        }
+        
+        // 检查是否可重试
+        if (this.isRetryableError(error) && attempt < this.maxRetries) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          const delayMs = this.calculateDelay(attempt);
+          logger.info(`Retrying request to ${path} after ${delayMs}ms (attempt ${attempt + 1}/${this.maxRetries})`);
+          clearTimeout(timeoutId);
+          await this.delay(delayMs);
+          continue;
+        }
+        
+        // P1 修复：确保返回有意义的错误信息
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        lastError = error instanceof Error ? error : new Error(errorMessage);
+        
+        return failure(createError(
+          'CONNECTION_FAILED',
+          errorMessage
+        ));
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+
+    // 所有重试都失败了
+    // P1 修复：lastError 此时一定有值，不再需要 optional chaining
+    return failure(createError(
+      'CONNECTION_FAILED',
+      lastError.message
+    ));
+  }
+
+  /**
+   * 发现网络中的 Agents
+   */
+  async discoverAgents(capability?: string): Promise<Result<AgentInfo[]>> {
+    return this.request<AgentInfo[]>('POST', '/discover', { capability });
+  }
+
+  /**
+   * 获取已连接的 Peers
+   */
+  async getConnectedPeers(): Promise<Result<PeerInfo[]>> {
+    return this.request<PeerInfo[]>('GET', '/peers');
+  }
+
+  /**
+   * 委托任务给特定 Peer
+   */
+  async delegateTask(options: DelegateOptions): Promise<Result<unknown>> {
+    return this.request<unknown>('POST', '/delegate', options);
+  }
+
+  /**
+   * 发送任务响应
+   */
+  async sendTaskResponse(
+    peerId: string, 
+    response: TaskResponse
+  ): Promise<Result<void>> {
+    return this.request<void>('POST', '/task/response', {
+      peerId,
+      ...response
+    });
+  }
+
+  /**
+   * 注册 Webhook
+   */
+  async registerWebhook(webhookUrl: string): Promise<Result<void>> {
+    return this.request<void>('POST', '/webhook/register', { 
+      url: webhookUrl,
+      events: ['discover', 'delegate', 'status']
+    });
+  }
+
+  /**
+   * 更新 Agent 信息
+   */
+  async updateAgentInfo(agentInfo: Partial<AgentInfo>): Promise<Result<void>> {
+    return this.request<void>('POST', '/agent/update', agentInfo);
+  }
+
+  /**
+   * 获取待处理任务
+   */
+  async getPendingTasks(): Promise<Result<TaskRequest[]>> {
+    return this.request<TaskRequest[]>('GET', '/tasks/pending');
+  }
+
+  /**
+   * 确认连接请求
+   */
+  async confirmConnection(peerId: string): Promise<Result<void>> {
+    return this.request<void>('POST', '/connection/confirm', { peerId });
+  }
+
+  /**
+   * 拒绝连接请求
+   */
+  async rejectConnection(peerId: string, reason?: string): Promise<Result<void>> {
+    return this.request<void>('POST', '/connection/reject', { peerId, reason });
+  }
+}