@zucker-framework/gateway 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,304 @@
+import { Transport } from '@zucker-framework/network';
+import { UpstreamMessage, DownstreamMessage, ThingManager, ThingsDataService } from '@zucker-framework/things';
+import { Logger } from '@nestjs/common';
+
+/**
+ * 设备会话 — 对应 jetlinks DeviceSession
+ *
+ * 代表一个已连接设备的网络会话，负责消息的收发与状态跟踪。
+ */
+
+/**
+ * 设备会话状态
+ */
+declare enum SessionState {
+    /** 会话正常，设备在线 */
+    CONNECTED = "connected",
+    /** 会话已关闭 */
+    CLOSED = "closed",
+    /** 会话空闲（超时告警） */
+    IDLE = "idle"
+}
+/**
+ * 设备会话接口 — 对应 jetlinks DeviceSession
+ */
+interface DeviceSession {
+    /** 会话唯一 ID */
+    readonly sessionId: string;
+    /** 关联的设备（物）ID */
+    readonly thingId: string;
+    /** 所属网关 ID */
+    readonly gatewayId: string;
+    /** 传输协议 */
+    readonly transport: Transport;
+    /** 会话创建时间 */
+    readonly connectTime: number;
+    /** 最后活跃时间 */
+    lastPingTime: number;
+    /** 当前状态 */
+    state: SessionState;
+    /**
+     * 发送下行消息（原始字节/对象）到设备
+     * 对应 jetlinks DeviceSession.send()
+     */
+    send(payload: unknown): Promise<void>;
+    /**
+     * 关闭会话
+     * 对应 jetlinks DeviceSession.close()
+     */
+    close(): Promise<void>;
+    /**
+     * 更新心跳
+     * 对应 jetlinks DeviceSession.ping()
+     */
+    ping(): void;
+    /**
+     * 是否存活
+     * 对应 jetlinks DeviceSession.isAlive()
+     */
+    isAlive(): boolean;
+}
+/**
+ * 子设备会话 — 对应 jetlinks ChildDeviceSession
+ *
+ * 通过父设备（如网关设备）代理的子设备会话。
+ */
+interface ChildDeviceSession extends DeviceSession {
+    /** 父设备 ID */
+    readonly parentThingId: string;
+}
+
+/**
+ * 消息编解码器 — 对应 jetlinks ProtocolSupport / MessageCodec
+ *
+ * 负责原始协议消息 ↔ ThingMessage 的互转。
+ * 不同协议（MQTT/HTTP/TCP）提供不同的 Codec 实现。
+ */
+
+/**
+ * 上行消息解码上下文 — 对应 jetlinks MessageDecodeContext
+ */
+interface DecodeContext {
+    /** 接收到的原始消息 */
+    payload: unknown;
+    /** 原始主题/路径/端点（MQTT topic、HTTP path 等） */
+    topic?: string;
+    /** 请求头/消息头 */
+    headers?: Record<string, string>;
+    /** 关联的设备会话 */
+    session: DeviceSession;
+}
+/**
+ * 下行消息编码上下文 — 对应 jetlinks MessageEncodeContext
+ */
+interface EncodeContext {
+    /** 要发送的平台消息 */
+    message: DownstreamMessage;
+    /** 关联的设备会话 */
+    session: DeviceSession;
+}
+/**
+ * 编码结果
+ */
+interface EncodedMessage {
+    /** 编码后的载荷 */
+    payload: unknown;
+    /** 目标主题/路径 */
+    topic?: string;
+    /** 附加头信息 */
+    headers?: Record<string, string>;
+}
+/**
+ * 消息编解码器接口 — 对应 jetlinks DeviceMessageCodec / ProtocolSupport
+ */
+interface MessageCodec {
+    /**
+     * 解码上行消息（原始 → ThingMessage[]）
+     * 对应 jetlinks DeviceMessageCodec.decode()
+     * 一条原始消息可能解析出多条逻辑消息（如批量属性上报）
+     */
+    decode(context: DecodeContext): Promise<UpstreamMessage[]>;
+    /**
+     * 编码下行消息（ThingMessage → 原始）
+     * 对应 jetlinks DeviceMessageCodec.encode()
+     */
+    encode(context: EncodeContext): Promise<EncodedMessage>;
+}
+/**
+ * 协议支持描述 — 对应 jetlinks ProtocolSupport
+ */
+interface ProtocolSupport {
+    /** 协议唯一 ID */
+    readonly id: string;
+    /** 协议名称 */
+    readonly name: string;
+    /** 支持的传输协议 schema 列表，如 ['mqtt', 'http', 'tcp'] */
+    readonly transports: string[];
+    /** 获取对应传输协议的编解码器 */
+    getCodec(transport: string): MessageCodec | undefined;
+}
+/**
+ * 协议注册表 — 对应 jetlinks ProtocolSupportManager
+ */
+declare class ProtocolRegistry {
+    private readonly protocols;
+    register(protocol: ProtocolSupport): void;
+    unregister(id: string): void;
+    get(id: string): ProtocolSupport | undefined;
+    getAll(): ProtocolSupport[];
+}
+
+/**
+ * 设备网关接口 — 对应 jetlinks DeviceGateway
+ *
+ * 网关是协议层（network）与业务层（things）的桥接器：
+ *   - 接收设备连接，建立 DeviceSession
+ *   - 调用 MessageCodec 解码上行消息，发布到消息总线
+ *   - 接收下行消息，编码后通过 DeviceSession 发送给设备
+ */
+
+/**
+ * 网关状态
+ */
+declare enum GatewayState {
+    STARTING = "starting",
+    RUNNING = "running",
+    PAUSED = "paused",
+    STOPPED = "stopped"
+}
+/**
+ * 网关配置
+ */
+interface DeviceGatewayConfig {
+    id: string;
+    name: string;
+    /** 关联的 network 配置 ID */
+    networkId: string;
+    /** 使用的协议 ID */
+    protocolId: string;
+    /** 传输 schema（与 protocol.getCodec(schema) 对应）*/
+    transport: string;
+}
+/**
+ * 设备网关接口 — 对应 jetlinks DeviceGateway
+ */
+interface DeviceGateway {
+    readonly config: DeviceGatewayConfig;
+    readonly state: GatewayState;
+    /** 启动网关 */
+    start(): Promise<void>;
+    /** 暂停（不再接受新连接，已有连接保持）*/
+    pause(): Promise<void>;
+    /** 停止网关并关闭所有连接 */
+    shutdown(): Promise<void>;
+    /** 获取活跃会话数量 */
+    getSessionCount(): number;
+    /** 获取指定设备的会话 */
+    getSession(thingId: string): DeviceSession | undefined;
+    /** 发送下行消息到指定设备 */
+    sendDownstream(thingId: string, payload: unknown): Promise<void>;
+}
+/**
+ * 抽象网关基类 — 提供会话管理 + 消息路由公共逻辑
+ * 子类只需实现协议特定的 start/pause/shutdown
+ *
+ * 对应 jetlinks AbstractDeviceGateway
+ */
+declare abstract class AbstractDeviceGateway implements DeviceGateway {
+    readonly config: DeviceGatewayConfig;
+    protected readonly protocol: ProtocolSupport;
+    protected readonly thingManager: ThingManager;
+    protected readonly dataService: ThingsDataService;
+    protected readonly logger: Logger;
+    protected readonly sessions: Map<string, DeviceSession>;
+    state: GatewayState;
+    constructor(config: DeviceGatewayConfig, protocol: ProtocolSupport, thingManager: ThingManager, dataService: ThingsDataService);
+    abstract start(): Promise<void>;
+    abstract pause(): Promise<void>;
+    abstract shutdown(): Promise<void>;
+    getSessionCount(): number;
+    getSession(thingId: string): DeviceSession | undefined;
+    sendDownstream(thingId: string, payload: unknown): Promise<void>;
+    /**
+     * 处理设备连接 — 注册会话并触发上线
+     */
+    protected onSessionConnected(session: DeviceSession): Promise<void>;
+    /**
+     * 处理设备断开 — 移除会话并触发离线
+     */
+    protected onSessionClosed(session: DeviceSession): Promise<void>;
+    /**
+     * 处理上行原始消息 — 解码后路由到对应处理器
+     * 对应 jetlinks AbstractDeviceGateway.doMessage()
+     */
+    protected handleIncoming(context: DecodeContext): Promise<void>;
+    /**
+     * 将解码后的消息路由到业务处理 — 对应 jetlinks DeviceMessageBus.publish()
+     */
+    private routeMessage;
+    /**
+     * 关闭所有会话
+     */
+    protected closeAllSessions(): Promise<void>;
+}
+
+/**
+ * HTTP 网关实现
+ *
+ * 用法：
+ * ```typescript
+ * const gateway = new HttpDeviceGateway(config, protocol, thingManager, dataService);
+ * await gateway.start();
+ *
+ * // 当收到 HTTP 请求时：
+ * await gateway.handleRequest('device-001', requestBody);
+ * ```
+ */
+declare class HttpDeviceGateway extends AbstractDeviceGateway {
+    constructor(config: DeviceGatewayConfig, protocol: ProtocolSupport, thingManager: ThingManager, dataService: ThingsDataService);
+    start(): Promise<void>;
+    pause(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * 处理来自设备的 HTTP 请求
+     * 由 NestJS Controller 调用
+     *
+     * @param thingId 设备 ID（从路径参数或认证信息中提取）
+     * @param body 请求体
+     */
+    handleRequest(thingId: string, body: unknown): Promise<void>;
+}
+
+declare class GatewayManager {
+    readonly protocolRegistry: ProtocolRegistry;
+    private readonly logger;
+    private readonly gateways;
+    constructor(protocolRegistry: ProtocolRegistry);
+    register(gateway: DeviceGateway): void;
+    unregister(gatewayId: string): void;
+    get(gatewayId: string): DeviceGateway | undefined;
+    getAll(): DeviceGateway[];
+    /** 启动所有已注册的网关 */
+    startAll(): Promise<void>;
+    /** 停止所有网关 */
+    shutdownAll(): Promise<void>;
+    /** 汇总统计 */
+    getSummary(): {
+        total: number;
+        running: number;
+        stopped: number;
+        totalSessions: number;
+    };
+}
+
+/**
+ * GatewayModule — 协议网关 NestJS 模块
+ *
+ * 提供：
+ *   - ProtocolRegistry（协议注册表）
+ *   - GatewayManager（网关生命周期管理）
+ */
+declare class GatewayModule {
+}
+
+export { AbstractDeviceGateway, type ChildDeviceSession, type DecodeContext, type DeviceGateway, type DeviceGatewayConfig, type DeviceSession, type EncodeContext, type EncodedMessage, GatewayManager, GatewayModule, GatewayState, HttpDeviceGateway, type MessageCodec, ProtocolRegistry, type ProtocolSupport, SessionState };