@thejrsoft/subway-protocol 1.3.0

package/src/gateway-extensions.ts

@@ -0,0 +1,278 @@
+/**
+ * Gateway 特定的协议扩展
+ * 基于 PROTOCOL_SPECIFICATION.md v2.0
+ */
+
+import { 
+  BaseMessage, 
+  MessageType,
+  Priority,
+  Command,
+  CommandMessage,
+  CommandType 
+} from './index';
+
+// Gateway 特殊 clientId
+export const GATEWAY_SITE_ID = 'gateway';
+
+
+// 批量消息
+export interface BatchMessage extends BaseMessage {
+  type: 'batch';
+  messages: BaseMessage[];
+}
+
+
+// 认证信息
+export interface AuthInfo {
+  method: 'token' | 'certificate' | 'apikey';
+  credentials: string;
+}
+
+// 扩展的注册消息（支持认证）
+export interface ExtendedRegisterMessage extends BaseMessage {
+  type: MessageType.REGISTER;
+  clientId: string;
+  clientType: string;
+  clientInfo?: {
+    version?: string;
+    platform?: string;
+    capabilities?: string[];
+  };
+  auth?: AuthInfo;              // 认证信息
+  features?: string[];          // 支持的特性
+}
+
+// 进度更新详情
+export interface ProgressDetails {
+  bytesDownloaded?: number;
+  totalBytes?: number;
+  speed?: string;
+  estimatedTimeRemaining?: number;
+}
+
+// 扩展的进度更新消息
+export interface ExtendedProgressUpdateMessage extends BaseMessage {
+  type: MessageType.PROGRESS_UPDATE;
+  requestRef: string;
+  progress: number;
+  phase?: string;
+  message?: string;
+  details?: ProgressDetails;
+}
+
+// Gateway 命令代码
+export enum GatewayCommand {
+  // 设备管理
+  GET_DEVICE_STATUS = 'GET_DEVICE_STATUS',
+  LIST_DEVICES = 'LIST_DEVICES',
+  DISCONNECT_DEVICE = 'DISCONNECT_DEVICE',
+  
+  // 统计信息
+  GET_STATS = 'GET_STATS',
+  GET_METRICS = 'GET_METRICS',
+  
+  // 配置管理
+  GET_GATEWAY_CONFIG = 'GET_GATEWAY_CONFIG',
+  UPDATE_GATEWAY_CONFIG = 'UPDATE_GATEWAY_CONFIG',
+  
+  // 路由管理
+  GET_ROUTES = 'GET_ROUTES',
+  ADD_ROUTE = 'ADD_ROUTE',
+  REMOVE_ROUTE = 'REMOVE_ROUTE'
+}
+
+// 设备信息
+export interface DeviceInfo {
+  clientId: string;
+  clientType: string;
+  status: 'online' | 'offline';
+  connectedAt: string;
+  lastHeartbeat: string;
+  clientInfo?: Record<string, any>;
+  statistics?: {
+    commandsSent: number;
+    commandsReceived: number;
+    errors: number;
+    uptime: number;
+  };
+}
+
+// Gateway 统计信息
+export interface GatewayStats {
+  uptime: number;
+  connections: {
+    total: number;
+    byType: Record<string, number>;
+    byStatus: Record<string, number>;
+  };
+  messages: {
+    received: number;
+    sent: number;
+    errors: number;
+    byType: Record<string, number>;
+  };
+  performance: {
+    averageLatency: number;
+    messageRate: number;
+    errorRate: number;
+  };
+}
+
+// 消息签名
+export interface SignedMessage extends BaseMessage {
+  signature?: string;  // 消息签名
+  signatureMethod?: 'sha256' | 'sha512';
+}
+
+// Gateway 工具类
+export class GatewayUtils {
+  /**
+   * 检查是否为 Gateway 命令
+   */
+  static isGatewayCommand(message: CommandMessage): boolean {
+    return message.targetClientId === GATEWAY_SITE_ID;
+  }
+
+  /**
+   * 检查是否为批量命令
+   */
+  static isBatchCommand(message: CommandMessage): boolean {
+    return message.command?.commandType === CommandType.BATCH;
+  }
+
+  /**
+   * 检查命令类型
+   */
+  static getCommandType(message: CommandMessage): CommandType {
+    // 从 command 对象中获取 commandType
+    if (message.command?.commandType) {
+      return message.command.commandType as CommandType;
+    }
+    // 如果有 filter 或 clientId 为 *，则为 batch 类型
+    if (message.filter || message.clientId === BROADCAST_SITE_ID) {
+      return CommandType.BATCH;
+    }
+    // 默认为 simple 类型
+    return CommandType.SIMPLE;
+  }
+
+  /**
+   * 创建查询设备状态的命令
+   */
+  static createDeviceStatusQuery(
+    targetClientId: string,
+    requestRef: string
+  ): CommandMessage {
+    return {
+      type: MessageType.COMMAND,
+      requestRef,
+      targetClientId: GATEWAY_SITE_ID,
+      command: {
+        commandType: CommandType.SIMPLE,
+        commandCode: GatewayCommand.GET_DEVICE_STATUS,
+        deviceType: 'gateway',
+        deviceId: 0,
+        operationType: 'read',
+        parameters: { targetClientId }
+      },
+      priority: Priority.NORMAL,
+      timeout: 5000,
+      timestamp: new Date().toISOString(),
+      version: '1.0'
+    };
+  }
+
+  /**
+   * 创建列出设备的命令
+   */
+  static createListDevicesCommand(
+    filter?: DeviceFilter,
+    requestRef?: string
+  ): CommandMessage {
+    return {
+      type: MessageType.COMMAND,
+      requestRef: requestRef || `list-${Date.now()}`,
+      targetClientId: GATEWAY_SITE_ID,
+      command: {
+        commandType: CommandType.SIMPLE,
+        commandCode: GatewayCommand.LIST_DEVICES,
+        deviceType: 'gateway',
+        operationType: 'read',
+        parameters: { filter: filter || {} }
+      },
+      priority: Priority.NORMAL,
+      timeout: 5000,
+      timestamp: new Date().toISOString(),
+      version: '1.0'
+    };
+  }
+
+
+  /**
+   * 创建complex类型命令（持续响应）
+   */
+  static createComplexCommand(
+    targetClientId: string,
+    command: Command,
+    options?: {
+      priority?: Priority;
+      timeout?: number;
+      requestRef?: string;
+    }
+  ): CommandMessage {
+    return {
+      type: MessageType.COMMAND,
+      requestRef: options?.requestRef || `complex-${Date.now()}`,
+      targetClientId,
+      command: {
+        ...command,
+        commandType: CommandType.COMPLEX
+      },
+      priority: options?.priority || Priority.NORMAL,
+      timeout: options?.timeout || 30000,  // Complex命令通常需要更长时间
+      timestamp: new Date().toISOString(),
+      version: '1.0'
+    };
+  }
+
+  /**
+   * 签名消息
+   */
+  static signMessage(
+    message: BaseMessage,
+    secret: string,
+    method: 'sha256' | 'sha512' = 'sha256'
+  ): SignedMessage {
+    // 实际实现需要加密库
+    const signature = `${method}:mock-signature-${Date.now()}`;
+    
+    return {
+      ...message,
+      signature,
+      signatureMethod: method
+    };
+  }
+
+  /**
+   * 验证消息签名
+   */
+  static verifyMessageSignature(
+    message: SignedMessage,
+    secret: string
+  ): boolean {
+    if (!message.signature || !message.signatureMethod) {
+      return false;
+    }
+    
+    // 实际实现需要验证签名
+    return true;
+  }
+}
+
+// 导出所有扩展类型
+export type GatewayMessage = 
+  | ExtendedCommandMessage
+  | ExtendedRegisterMessage
+  | ExtendedProgressUpdateMessage
+  | BatchMessage;