@thejrsoft/subway-protocol 1.3.0

package/src/index.ts

@@ -0,0 +1,792 @@
+/**
+ * JRSoft Subway 统一WebSocket协议定义
+ * 版本: 1.0
+ * 
+ * 功能特性:
+ * 1. 统一消息格式定义
+ * 2. 支持设备注册、命令执行、心跳等核心功能
+ * 3. 支持 Edge 代理模式
+ */
+
+// 消息类型枚举
+export enum MessageType {
+  // 连接管理
+  REGISTER = 'REGISTER',
+  REGISTER_ACK = 'REGISTER_ACK',
+  UNREGISTER = 'UNREGISTER',
+  UNREGISTER_ACK = 'UNREGISTER_ACK',
+  
+  // 心跳
+  HEARTBEAT = 'HEARTBEAT',
+  HEARTBEAT_ACK = 'HEARTBEAT_ACK',
+  
+  // 命令执行
+  COMMAND = 'COMMAND',
+  COMMAND_RESPONSE = 'COMMAND_RESPONSE',
+  
+  // 程序管理
+  PROGRAM = 'PROGRAM',
+  PROGRAM_RESPONSE = 'PROGRAM_RESPONSE',
+  
+  // 进度更新
+  PROGRESS_UPDATE = 'PROGRESS_UPDATE',
+  
+  // 错误
+  ERROR = 'ERROR'
+}
+
+// 客户端类型
+export enum ClientType {
+  DEVICE = 'DEVICE',
+  BACKEND = 'BACKEND',
+  EDGE = 'EDGE',
+  GATEWAY = 'GATEWAY'  // 添加缺失的 GATEWAY 类型
+}
+
+// 操作类型
+export enum OperationType {
+  READ = 'READ',
+  WRITE = 'WRITE',
+  QUERY = 'QUERY',
+  UPDATE = 'UPDATE',
+  CONTROL = 'CONTROL'
+}
+
+// 优先级
+export enum Priority {
+  LOW = 'LOW',
+  NORMAL = 'NORMAL',
+  HIGH = 'HIGH',
+  CRITICAL = 'CRITICAL',
+  EMERGENCY = 'EMERGENCY'
+}
+
+// 命令状态
+export enum CommandStatus {
+  COMPLETED = 'COMPLETED',
+  FAILED = 'FAILED',
+  TIMEOUT = 'TIMEOUT',
+  CANCELLED = 'CANCELLED',
+  IN_PROGRESS = 'IN_PROGRESS'  // Gateway特有
+}
+
+// 基础消息接口
+export interface BaseMessage {
+  type: MessageType;
+  timestamp: string;  // ISO 8601 格式
+  version: string;    // 协议版本 "1.0"
+}
+
+// 客户端信息（可选，用于扩展信息）
+export interface ClientInfo {
+  name?: string;
+  version?: string;
+  platform?: string;
+  capabilities?: string[];
+  deviceType?: string;  // 设备类型，用于设备端
+  description?: string;
+  metadata?: Record<string, any>;
+}
+
+// Edge 信息（设备端通过 Edge 注册时包含）
+export interface EdgeInfo {
+  edgeId: string;
+  edgeVersion?: string;
+  connectionTime?: string;
+}
+
+// 注册消息
+export interface RegisterMessage extends BaseMessage {
+  type: MessageType.REGISTER;
+  clientId: string;  // 客户端唯一标识符
+  clientType: ClientType;
+  clientInfo?: ClientInfo;
+  edgeInfo?: EdgeInfo;  // 当设备通过 Edge 注册时包含
+}
+
+// 注册确认消息
+export interface RegisterAckMessage extends BaseMessage {
+  type: MessageType.REGISTER_ACK;
+  clientId: string;              // 确认的客户端ID
+  success: boolean;              // 注册是否成功
+  sessionId?: string;            // 成功时分配的会话ID
+  error?: {                      // 失败时的错误信息
+    code: string;
+    message: string;
+  };
+  serverInfo?: {                 // 服务器信息
+    version: string;
+    capabilities: string[];
+    currentLoad?: number;        // 当前负载
+    maxClients?: number;         // 最大客户端数
+  };
+}
+
+// 注销消息
+export interface UnregisterMessage extends BaseMessage {
+  type: MessageType.UNREGISTER;
+  clientId: string;              // 客户端唯一标识符
+  reason?: string;               // 注销原因
+}
+
+// 注销确认消息
+export interface UnregisterAckMessage extends BaseMessage {
+  type: MessageType.UNREGISTER_ACK;
+  clientId: string;              // 客户端唯一标识符
+  success: boolean;              // 注销是否成功
+  cleanupInfo?: {                // 清理信息
+    messagesProcessed: number;   // 已处理的消息数
+    pendingMessages: number;     // 待处理的消息数
+    connectionDuration: number;  // 连接持续时间（秒）
+  };
+}
+
+// 引用生成的强类型命令
+import type { SpecificCommand as ImportedSpecificCommand, CommandTypeMap as ImportedCommandTypeMap } from './command-types';
+export type SpecificCommand = ImportedSpecificCommand;
+export type CommandTypeMap = ImportedCommandTypeMap;
+
+// 基础命令接口
+export interface BaseCommand {
+  commandCode: string;
+  parameters?: Record<string, any>;
+}
+
+// 简单命令接口（点对点）
+export interface SimpleCommand extends BaseCommand {
+  commandType: CommandType.SIMPLE;
+  deviceId: number | string;  // 必需：单个设备
+  deviceType: string;  // 必需
+  operationType: OperationType;  // 必需
+}
+
+// 批量命令接口（多设备）
+export interface BatchCommand extends BaseCommand {
+  commandType: CommandType.BATCH;
+  deviceId: number[] | string;  // 必需：设备数组或范围表达式
+  deviceType: string;  // 必需
+  operationType: OperationType;  // 必需
+}
+
+// 复杂命令接口（持续响应）
+export interface ComplexCommand extends BaseCommand {
+  commandType: CommandType.COMPLEX;
+  deviceId?: number | number[] | string;  // 可选
+  deviceType?: string;  // 可选
+  operationType?: OperationType;  // 可选
+}
+
+// 通用命令接口（用于运行时动态命令）
+// 注意：字段是否必需由 MessageValidator 根据 commandType 在运行时验证
+export interface GenericCommand extends BaseCommand {
+  commandType?: CommandType;  // 可选，默认为 SIMPLE
+  deviceId?: number | number[] | string;  // 可选，验证器会检查
+  deviceType?: string;  // 可选，验证器会检查
+  operationType?: OperationType;  // 可选，验证器会检查
+}
+
+// 命令详情 - 支持强类型和通用类型
+export type Command = SpecificCommand | SimpleCommand | BatchCommand | ComplexCommand | GenericCommand;
+
+// 命令类型
+export enum CommandType {
+  SIMPLE = 'SIMPLE',   // 点对点命令
+  BATCH = 'BATCH',     // 多设备命令
+  COMPLEX = 'COMPLEX'  // 持续响应命令
+}
+
+// 命令消息
+export interface CommandMessage extends BaseMessage {
+  type: MessageType.COMMAND;
+  requestRef: string;
+  targetClientId: string;   // 目标客户端 ID (所有类型必需)
+  command: Command;         // 所有类型都使用command字段
+  priority: Priority;
+  timeout: number;
+  retryCount?: number;
+  callback: string;  // 回调地址，用于接收命令响应
+  metadata?: Record<string, any>;
+}
+
+// 命令执行结果
+export interface CommandResult {
+  deviceType: string;
+  deviceId: number | string;
+  commandCode: string;
+  operationType: OperationType;
+  data: Record<string, any>;
+}
+
+// 命令响应消息
+export interface CommandResponseMessage extends BaseMessage {
+  type: MessageType.COMMAND_RESPONSE;
+  requestRef: string;
+  status: CommandStatus;
+  result?: CommandResult;            // 命令执行结果
+  report?: ReportMessage;
+  executionTime?: number;
+}
+// 注意：批量命令和复杂命令通过 progress_update 报告执行进度，最终返回简单的 command_response
+
+// 心跳消息
+export interface HeartbeatMessage extends BaseMessage {
+  type: MessageType.HEARTBEAT;
+  clientId: string;              // 客户端唯一标识符
+  sequence: number;              // 序列号，用于匹配请求和响应
+  clientTime: string;            // 客户端时间戳
+}
+
+// 心跳确认消息
+export interface HeartbeatAckMessage extends BaseMessage {
+  type: MessageType.HEARTBEAT_ACK;
+  clientId: string;              // 客户端唯一标识符
+  sequence: number;              // 原始序列号
+  clientTime: string;            // 原始客户端时间
+  serverTime: string;            // 服务器时间
+  latency?: number;              // 服务器处理延迟（毫秒）
+  serverStatus?: {               // 服务器状态
+    healthy: boolean;
+    activeConnections: number;
+    messageQueueSize: number;
+    cpuUsage?: number;
+    memoryUsage?: number;
+  };
+}
+
+// 错误消息
+export interface ErrorMessage extends BaseMessage {
+  type: MessageType.ERROR;
+  code: string;
+  message: string;
+  severity?: string;
+  category?: string;
+  context?: any;
+  retryable?: boolean;
+}
+
+// 程序类型
+export enum ProgramType {
+  DYNAMIC = 'DYNAMIC',
+  STATIC = 'STATIC'
+}
+
+// 程序方向
+export enum ProgramDirection {
+  LEFT_TO_RIGHT = 'LEFT_TO_RIGHT',
+  RIGHT_TO_LEFT = 'RIGHT_TO_LEFT'
+}
+
+// 程序上传参数
+export interface ProgramParameters {
+  deviceId: string;
+  taskId: string;  // Snowflake ID
+  programId: string;  // Snowflake ID
+  programName: string;
+  programNumber: number;  // 1-10
+  programType: ProgramType;
+  width: number;
+  height: number;
+  direction: ProgramDirection;
+  publishTime: string;  // 上刊时间
+  unpublishTime: string;  // 下刊时间
+  downloadUrl: string;
+  checksum: string;
+  hashAlgorithm: 'SHA256';
+  fileSize: number;
+}
+
+// 程序消息
+export interface ProgramMessage extends BaseMessage {
+  type: MessageType.PROGRAM;
+  requestRef: string;
+  targetClientId: string;  // 目标客户端 ID
+  command: {
+    commandCode: 'UPLOAD_PROGRAM';
+    parameters: ProgramParameters;
+  };
+  priority: Priority;
+  timeout: number;
+  callback: string;  // 回调地址，用于接收程序上传进度和结果
+}
+
+// 程序响应消息
+export interface ProgramResponseMessage extends BaseMessage {
+  type: MessageType.PROGRAM_RESPONSE;
+  requestRef: string;
+  status: CommandStatus;  // 使用相同的状态枚举
+  context?: ProgramContext;       // 上下文信息（可选）
+  report?: ReportMessage;  // 日志信息（可选）
+  executionTime?: number;  // 总执行时间（毫秒）
+}
+
+// 进度阶段
+export enum ProgressPhase {
+  DOWNLOAD = 'DOWNLOAD',      // 下载文件
+  DECOMPRESS = 'DECOMPRESS',  // 解压文件
+  PREPROCESS = 'PREPROCESS',  // 预处理
+  FRAMES = 'FRAMES',          // 创建帧
+  UPLOAD = 'UPLOAD',          // 上传到设备
+  STATS = 'STATS'             // 统计信息
+}
+
+// 设备操作记录
+export interface DeviceOperationRecord {
+  commandType: CommandType;     // 命令类型
+  commandCode: string;          // 命令代码
+  deviceType: string;           // 设备类型
+  deviceId: number | string;    // 设备ID
+  operationType: OperationType;  // 读写类型
+  result?: Record<string, any>; // 命令执行结果对象
+}
+
+// 进度状态
+export enum ProgressStatus {
+  PENDING = 'PENDING',
+  IN_PROGRESS = 'IN_PROGRESS',
+  PAUSED = 'PAUSED',
+  COMPLETED = 'COMPLETED',
+  FAILED = 'FAILED',
+  CANCELLED = 'CANCELLED'
+}
+
+// 程序上下文信息
+export interface ProgramContext {
+  taskId: string;          // Snowflake ID
+  programId: string;       // Snowflake ID
+  programName: string;     // 程序名称
+  programNumber: number;   // 1-10
+  programType: ProgramType; // dynamic | static
+}
+
+// 报告级别
+export enum ReportLevel {
+  DEBUG = 'DEBUG',
+  INFO = 'INFO',
+  WARNING = 'WARNING',
+  ERROR = 'ERROR',
+  CRITICAL = 'CRITICAL'
+}
+
+// 报告信息
+export interface ReportMessage {
+  level: ReportLevel;
+  message: string;         // 报告消息
+  code?: string;           // 标准化的消息代码
+  data?: Record<string, any>;  // 额外的数据对象
+}
+
+// 进度更新消息
+export interface ProgressUpdateMessage extends BaseMessage {
+  type: MessageType.PROGRESS_UPDATE;
+  requestRef: string;
+  status: ProgressStatus;      // 状态
+  phase: ProgressPhase | string;  // 当前阶段（支持自定义阶段）
+  progress: number;            // 0-100 进度百分比
+  sourceType: 'COMMAND' | 'SYSTEM';  // 来源类型：命令操作结果 或 系统类型结果
+  context?: ProgramContext;        // 上下文信息（用于程序上传相关的进度更新）
+  command?: DeviceOperationRecord;  // 设备操作记录（当涉及设备读写时）
+  report?: ReportMessage;                   // 日志信息（可选）
+  timestamp: string;           // ISO 8601 时间戳
+  version: string;             // 协议版本
+}
+
+// 类型守卫函数
+export function isRegisterMessage(msg: any): msg is RegisterMessage {
+  return msg && msg.type === MessageType.REGISTER;
+}
+
+export function isRegisterAckMessage(msg: any): msg is RegisterAckMessage {
+  return msg && msg.type === MessageType.REGISTER_ACK;
+}
+
+export function isUnregisterMessage(msg: any): msg is UnregisterMessage {
+  return msg && msg.type === MessageType.UNREGISTER;
+}
+
+export function isUnregisterAckMessage(msg: any): msg is UnregisterAckMessage {
+  return msg && msg.type === MessageType.UNREGISTER_ACK;
+}
+
+export function isHeartbeatMessage(msg: any): msg is HeartbeatMessage {
+  return msg && msg.type === MessageType.HEARTBEAT;
+}
+
+export function isHeartbeatAckMessage(msg: any): msg is HeartbeatAckMessage {
+  return msg && msg.type === MessageType.HEARTBEAT_ACK;
+}
+
+export function isCommandMessage(msg: any): msg is CommandMessage {
+  return msg && msg.type === MessageType.COMMAND;
+}
+
+export function isCommandResponseMessage(msg: any): msg is CommandResponseMessage {
+  return msg && msg.type === MessageType.COMMAND_RESPONSE;
+}
+
+export function isProgramMessage(msg: any): msg is ProgramMessage {
+  return msg && msg.type === MessageType.PROGRAM;
+}
+
+export function isProgramResponseMessage(msg: any): msg is ProgramResponseMessage {
+  return msg && msg.type === MessageType.PROGRAM_RESPONSE;
+}
+
+export function isProgressUpdateMessage(msg: any): msg is ProgressUpdateMessage {
+  return msg && msg.type === MessageType.PROGRESS_UPDATE;
+}
+
+export function isErrorMessage(msg: any): msg is ErrorMessage {
+  return msg && msg.type === MessageType.ERROR;
+}
+
+
+// 消息工厂类 - 创建符合新协议的消息
+export class MessageFactory {
+
+  /**
+   * 创建注册消息
+   */
+  static createRegisterMessage(
+    clientId: string,
+    clientType: ClientType,
+    clientInfo?: ClientInfo
+  ): RegisterMessage {
+    return {
+      type: MessageType.REGISTER,
+      clientId,
+      clientType,
+      clientInfo,
+      timestamp: new Date().toISOString(),
+      version: '1.0'
+    };
+  }
+
+  /**
+   * 创建命令消息
+   */
+  static createCommandMessage(
+    requestRef: string,
+    targetClientId: string,
+    command: Command,
+    callback: string,
+    options?: {
+      priority?: Priority;
+      timeout?: number;
+      retryCount?: number;
+    }
+  ): CommandMessage {
+    return {
+      type: MessageType.COMMAND,
+      requestRef,
+      targetClientId,
+      command: {
+        ...command,
+        commandType: command.commandType || CommandType.SIMPLE
+      },
+      priority: options?.priority || Priority.NORMAL,
+      timeout: options?.timeout || DEFAULT_TIMEOUT,
+      retryCount: options?.retryCount || 0,  // 默认值 0
+      callback,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建心跳消息
+   */
+  static createHeartbeatMessage(clientId: string, sequence: number): HeartbeatMessage {
+    const now = new Date().toISOString();
+    return {
+      type: MessageType.HEARTBEAT,
+      clientId,
+      sequence,
+      clientTime: now,
+      timestamp: now,
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建注销消息
+   */
+  static createUnregisterMessage(clientId: string, reason?: string): UnregisterMessage {
+    return {
+      type: MessageType.UNREGISTER,
+      clientId,
+      reason,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建程序上传消息
+   */
+  static createProgramMessage(
+    requestRef: string,
+    targetClientId: string,
+    parameters: ProgramParameters,
+    callback: string,
+    options?: {
+      priority?: Priority;
+      timeout?: number;
+    }
+  ): ProgramMessage {
+    return {
+      type: MessageType.PROGRAM,
+      requestRef,
+      targetClientId,
+      command: {
+        commandCode: 'UPLOAD_PROGRAM',
+        parameters
+      },
+      priority: options?.priority || Priority.NORMAL,
+      timeout: options?.timeout || 1800000, // 30分钟
+      callback,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建进度更新消息
+   */
+  static createProgressUpdateMessage(
+    requestRef: string,
+    phase: ProgressPhase | string,
+    progress: number,
+    message?: string,
+    status: ProgressStatus = ProgressStatus.IN_PROGRESS,
+    options?: {
+      level?: ReportLevel;
+      code?: string;
+      data?: Record<string, any>;
+      context?: ProgramContext;
+      command?: DeviceOperationRecord;
+    }
+  ): ProgressUpdateMessage {
+    return {
+      type: MessageType.PROGRESS_UPDATE,
+      requestRef,
+      status,
+      phase,
+      progress,
+      sourceType: options?.command ? 'COMMAND' : 'SYSTEM',  // 根据是否有command自动判断
+      context: options?.context,
+      command: options?.command,
+      report: message ? {
+        level: options?.level || ReportLevel.INFO,
+        message,
+        code: options?.code,
+        data: options?.data
+      } : undefined,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建命令响应消息 (Backend 急需)
+   */
+  static createCommandResponseMessage(
+    requestRef: string,
+    status: CommandStatus,
+    result: any,
+    message?: string,
+    options?: {
+      executionTime?: number;
+      report?: ReportMessage;
+      version?: string;
+      commandStartTime?: number;  // 命令开始时间戳（毫秒）
+    }
+  ): CommandResponseMessage {
+    // 如果提供了开始时间但没有 executionTime，自动计算
+    const executionTime = options?.executionTime || 
+      (options?.commandStartTime ? Date.now() - options.commandStartTime : undefined);
+    
+    return {
+      type: MessageType.COMMAND_RESPONSE,
+      requestRef,
+      status,
+      result,
+      report: options?.report || (message ? {
+        level: ReportLevel.INFO,
+        message
+      } : undefined),
+      executionTime,
+      timestamp: new Date().toISOString(),
+      version: options?.version || PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建程序响应消息
+   */
+  static createProgramResponseMessage(
+    requestRef: string,
+    status: CommandStatus,
+    result: any,
+    message?: string,
+    options?: {
+      executionTime?: number;
+      programStartTime?: number;  // 程序开始时间戳（毫秒）
+    }
+  ): ProgramResponseMessage {
+    // 如果提供了开始时间但没有 executionTime，自动计算
+    const executionTime = options?.executionTime || 
+      (options?.programStartTime ? Date.now() - options.programStartTime : undefined);
+    
+    return {
+      type: MessageType.PROGRAM_RESPONSE,
+      requestRef,
+      status,
+      context: result,
+      report: message ? {
+        level: ReportLevel.INFO,
+        message
+      } : undefined,
+      executionTime,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建错误消息 (Gateway & Backend 都需要)
+   */
+  static createErrorMessage(
+    code: string,
+    message: string,
+    requestRef?: string,
+    options?: {
+      level?: ReportLevel;
+      data?: Record<string, any>;
+      severity?: string;
+      category?: string;
+      retryable?: boolean;
+    }
+  ): ErrorMessage {
+    return {
+      type: MessageType.ERROR,
+      code,
+      message,
+      severity: options?.severity || 'ERROR',
+      category: options?.category,
+      context: {
+        requestRef,
+        data: options?.data
+      },
+      retryable: options?.retryable,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建心跳确认消息 (Gateway 急需)
+   */
+  static createHeartbeatAckMessage(
+    sequence: number,
+    clientId?: string,
+    clientTime?: string,
+    options?: {
+      latency?: number;
+      heartbeatReceivedTime?: number;  // 收到心跳的时间戳（毫秒）
+    }
+  ): HeartbeatAckMessage {
+    const now = new Date().toISOString();
+    const nowMs = Date.now();
+    
+    // 如果提供了接收时间但没有 latency，自动计算处理延迟
+    const latency = options?.latency || 
+      (options?.heartbeatReceivedTime ? nowMs - options.heartbeatReceivedTime : undefined);
+    
+    return {
+      type: MessageType.HEARTBEAT_ACK,
+      clientId: clientId || '',
+      sequence,
+      clientTime: clientTime || now,  // 使用传入的客户端时间或当前时间
+      serverTime: now,
+      latency,
+      timestamp: now,
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建注册确认消息 (Gateway 需要)
+   */
+  static createRegisterAckMessage(
+    clientId: string,
+    success: boolean,
+    message?: string,
+    sessionId?: string
+  ): RegisterAckMessage {
+    return {
+      type: MessageType.REGISTER_ACK,
+      clientId,
+      success,
+      sessionId,
+      error: !success && message ? {
+        code: 'REGISTRATION_FAILED',
+        message
+      } : undefined,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+
+  /**
+   * 创建注销确认消息
+   */
+  static createUnregisterAckMessage(
+    clientId: string,
+    success: boolean
+  ): UnregisterAckMessage {
+    return {
+      type: MessageType.UNREGISTER_ACK,
+      clientId,
+      success,
+      timestamp: new Date().toISOString(),
+      version: PROTOCOL_VERSION
+    };
+  }
+}
+
+
+// 导出所有类型
+export type AnyMessage = 
+  | RegisterMessage
+  | RegisterAckMessage
+  | UnregisterMessage
+  | UnregisterAckMessage
+  | CommandMessage
+  | CommandResponseMessage
+  | ProgramMessage
+  | ProgramResponseMessage
+  | HeartbeatMessage
+  | HeartbeatAckMessage
+  | ProgressUpdateMessage
+  | ErrorMessage;
+
+// 导出常量
+export const PROTOCOL_VERSION = '1.0';
+export const DEFAULT_TIMEOUT = 10000;
+export const DEFAULT_PRIORITY = Priority.NORMAL;
+
+// 导出强类型命令系统
+export * from './command-types';
+export * from './command-factory';
+
+// 导出消息验证器
+export { MessageValidator, ValidationResult } from './message-validator';
+
+// 导出协议工具类
+export { ProtocolUtils } from './protocol-utils';
+
+// 导出 Gateway 扩展 (暂时禁用，有编译错误)
+// export * from './gateway-extensions';
+
+// 导出 Edge 代理模式 (暂时禁用，有编译错误)
+// export * from './edge-proxy';