huaweicloud-devkit 1.0.2-dev.1 → 1.0.2-dev.2

package/plugins/huaweicloud-core/src/ws-exec/hwlink-multiplexer.js

@@ -0,0 +1,227 @@
+import { Buffer } from 'node:buffer';
+
+import { FairQueue } from './hwlink-fair-queue.js';
+import { formatPacketOneLine, parsePacket } from './hwlink-packet.js';
+
+const WS_OPEN = 1;
+
+function addWsListener(ws, event, handler) {
+  if (typeof ws.on === 'function') {
+    ws.on(event, handler);
+    return;
+  }
+  if (typeof ws.addEventListener === 'function') {
+    ws.addEventListener(event, handler);
+    return;
+  }
+  throw new Error('WebSocket implementation does not support event listeners');
+}
+
+function closeQuietly(ws) {
+  try {
+    ws.close();
+  } catch {
+    // Close is best-effort during error settlement.
+  }
+}
+
+function extractMessageData(eventOrData) {
+  if (
+    eventOrData &&
+    typeof eventOrData === 'object' &&
+    !Buffer.isBuffer(eventOrData) &&
+    !(eventOrData instanceof ArrayBuffer) &&
+    !ArrayBuffer.isView(eventOrData) &&
+    'data' in eventOrData
+  ) {
+    return eventOrData.data;
+  }
+  return eventOrData;
+}
+
+function eventDataToUint8Array(data) {
+  if (data instanceof Uint8Array) return Promise.resolve(data);
+  if (Buffer.isBuffer(data)) {
+    return Promise.resolve(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+  }
+  if (data instanceof ArrayBuffer) return Promise.resolve(new Uint8Array(data));
+  if (ArrayBuffer.isView(data)) {
+    return Promise.resolve(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+  }
+  if (data && typeof data.arrayBuffer === 'function') {
+    return data.arrayBuffer().then((buffer) => new Uint8Array(buffer));
+  }
+  return Promise.reject(new Error(`unsupported websocket message data: ${typeof data}`));
+}
+
+function sendBinary(ws, data) {
+  if (ws.readyState !== WS_OPEN) return Promise.resolve();
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const done = (err) => {
+      if (settled) return;
+      settled = true;
+      if (err) reject(err);
+      else resolve();
+    };
+
+    try {
+      const maybePromise = ws.send(data, done);
+      if (maybePromise && typeof maybePromise.then === 'function') {
+        maybePromise.then(() => done(), done);
+        return;
+      }
+      if (ws.send.length < 2) done();
+    } catch (error) {
+      done(error);
+    }
+  });
+}
+
+class HwlinkWebSocketMultiplexer {
+  constructor(url, source, options = {}) {
+    const {
+      WebSocketImpl = globalThis.WebSocket,
+      protocol = 'devenv',
+      onFrame,
+      trace = false,
+    } = options;
+
+    if (typeof WebSocketImpl !== 'function') {
+      throw new Error('global WebSocket is unavailable; use Node.js 22+ or pass WebSocketImpl');
+    }
+    if (!Number.isInteger(source) || source < -0x80000000 || source > 0xffffffff) {
+      throw new Error('hwlink source must be an int32 or uint32 number');
+    }
+
+    this.url = url;
+    this.source = source;
+    this.onFrame = onFrame;
+    this.trace = trace;
+    this.channels = new Map();
+    this.unknownIdentifierHandler = null;
+    this.onClose = null;
+    this.onError = null;
+    this.closed = false;
+    this.queue = new FairQueue((data) => this.wsSend(data));
+    this.ws = new WebSocketImpl(url, protocol);
+
+    if ('binaryType' in this.ws) {
+      this.ws.binaryType = 'arraybuffer';
+    }
+
+    addWsListener(this.ws, 'open', () => {
+      for (const ch of this.channels.values()) ch.onopen();
+    });
+
+    addWsListener(this.ws, 'message', (eventOrData) => {
+      this.handleMessage(extractMessageData(eventOrData)).catch((error) => {
+        this.handleError(error);
+      });
+    });
+
+    addWsListener(this.ws, 'error', (eventOrError) => {
+      const error = eventOrError instanceof Error
+        ? eventOrError
+        : new Error('hwlink websocket error');
+      this.handleError(error);
+    });
+
+    addWsListener(this.ws, 'close', (eventOrCode, maybeReason) => {
+      this.closed = true;
+      const closeEvent = this.normalizeCloseEvent(eventOrCode, maybeReason);
+      for (const ch of this.channels.values()) ch.onclose(closeEvent);
+      if (this.onClose) this.onClose(closeEvent);
+    });
+  }
+
+  normalizeCloseEvent(eventOrCode, maybeReason) {
+    if (typeof eventOrCode === 'number') {
+      return {
+        code: eventOrCode,
+        reason: Buffer.isBuffer(maybeReason) ? maybeReason.toString() : String(maybeReason || ''),
+      };
+    }
+
+    return {
+      code: eventOrCode && typeof eventOrCode.code === 'number' ? eventOrCode.code : 0,
+      reason: eventOrCode && eventOrCode.reason ? String(eventOrCode.reason) : '',
+    };
+  }
+
+  register(ch) {
+    this.channels.set(ch.identifier, ch);
+    this.queue.register(ch);
+    if (this.ws.readyState === WS_OPEN) {
+      ch.onopen();
+    }
+  }
+
+  unregister(ch) {
+    this.channels.delete(ch.identifier);
+    this.queue.unregister(ch);
+  }
+
+  sendFairly(ch, data) {
+    this.queue.sendFairly(ch, data);
+  }
+
+  sendImmediately(data) {
+    this.queue.sendImmediately(data);
+  }
+
+  get readyState() {
+    return this.ws.readyState;
+  }
+
+  async handleMessage(data) {
+    const bytes = await eventDataToUint8Array(data);
+    const packet = parsePacket(bytes);
+    this.reportFrame('in', packet);
+
+    const ch = this.channels.get(packet.identifier);
+    if (ch) {
+      ch.onmessage(packet);
+      return;
+    }
+
+    if (this.unknownIdentifierHandler) {
+      this.unknownIdentifierHandler(packet, this);
+    }
+  }
+
+  wsSend(data) {
+    const packet = parsePacket(data);
+    this.reportFrame('out', packet);
+    return sendBinary(this.ws, data);
+  }
+
+  reportFrame(direction, packet) {
+    if (this.onFrame) {
+      this.onFrame({ direction, packet, line: formatPacketOneLine(packet) });
+    }
+    if (this.trace) {
+      const arrow = direction === 'in' ? '<-' : '->';
+      console.error(`${arrow} ${formatPacketOneLine(packet)}`);
+    }
+  }
+
+  handleError(error) {
+    for (const ch of this.channels.values()) ch.onerror(error);
+    if (this.onError) this.onError(error);
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    closeQuietly(this.ws);
+  }
+}
+
+export {
+  HwlinkWebSocketMultiplexer,
+  addWsListener,
+  closeQuietly,
+  eventDataToUint8Array,
+};

package/plugins/huaweicloud-core/src/ws-exec/hwlink-packet.js

@@ -0,0 +1,202 @@
+const FIXED_HEADER_LEN = 20;
+const MAX_SEND_CHUNK_SIZE = 8 * 1024;
+
+const OpCode = Object.freeze({
+  OpCreateTcpTunnel: 0x03,
+  OpTcpTunnelData: 0x04,
+  OpListenTcpTunnel: 0x05,
+  OpReverseCreateTcpTunnel: 0x43,
+  OpCmdTerminalResize: 0xfa,
+  OpNewCmdTerminal: 0xfb,
+  OpCmdTerminalInit: 0xfc,
+  OpCmdTerminalData: 0xfd,
+
+  OpFileSuccess: 0x03 << 8,
+  OpSubStreamPing: 0x06 << 8,
+  OpSubStreamPong: 0x07 << 8,
+  OpTunnelSuccess: 0x08 << 8,
+
+  OpDisconnect: 0x03 << 16,
+
+  ErrCmdTerminal: 0x0d << 24,
+  ErrTcpTunnel: 0x0e << 24,
+});
+
+const ReserveSource = Object.freeze({
+  Web: 0x00,
+});
+
+let nextId = 1;
+
+function nextIdentifier() {
+  nextId = ((nextId + 1) & 0xffffffff) >>> 0;
+  return nextId;
+}
+
+function isOpTunnelSuccess(op) {
+  return (op & 0xff00) === OpCode.OpTunnelSuccess;
+}
+
+function isOpTcpTunnelData(op) {
+  return (op & 0xff) === OpCode.OpTcpTunnelData;
+}
+
+function isOpFailed(op) {
+  return (op >> 24) !== 0;
+}
+
+function isOpCreateTcpTunnel(op) {
+  return (op & 0xff) === OpCode.OpCreateTcpTunnel;
+}
+
+function isOpReverseCreateTcpTunnel(op) {
+  return (op & 0xff) === OpCode.OpReverseCreateTcpTunnel;
+}
+
+function isOpCmdTerminalData(op) {
+  return (op & 0xff) === OpCode.OpCmdTerminalData;
+}
+
+function isOpListenTcpTunnel(op) {
+  return (op & 0xff) === OpCode.OpListenTcpTunnel;
+}
+
+function isSubStreamPing(op) {
+  return (op & 0xff00) === OpCode.OpSubStreamPing;
+}
+
+function hex2(n) {
+  return `0x${n.toString(16).padStart(2, '0').toUpperCase()}`;
+}
+
+function operationToString(op) {
+  return [
+    hex2((op >> 24) & 0xff),
+    hex2((op >> 16) & 0xff),
+    hex2((op >> 8) & 0xff),
+    hex2(op & 0xff),
+  ].join(' ');
+}
+
+function formatPacketOneLine(packet) {
+  const err = (packet.operation >> 24) & 0xff;
+  const ctl = (packet.operation >> 16) & 0xff;
+  const sync = (packet.operation >> 8) & 0xff;
+  const data = packet.operation & 0xff;
+  const dataLen = packet.data ? packet.data.length : 0;
+  return (
+    `[${String(packet.headerLength).padStart(2)}]` +
+    `[${hex2(packet.reserve)}]` +
+    `[${String(packet.packetLength).padStart(5)}]` +
+    `[${hex2(err)} ${hex2(ctl)} ${hex2(sync)} ${hex2(data)}]` +
+    `[${String(packet.srcPort).padStart(5)}]` +
+    `[${String(packet.dstPort).padStart(5)}]` +
+    `[${String(packet.identifier).padStart(10)}]` +
+    `[${String(packet.source).padStart(10)}]` +
+    `[${String(dataLen).padStart(6)}B]`
+  );
+}
+
+function toUint8Array(bytes) {
+  if (bytes instanceof Uint8Array) return bytes;
+  if (bytes instanceof ArrayBuffer) return new Uint8Array(bytes);
+  if (ArrayBuffer.isView(bytes)) {
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+  throw new TypeError('packet bytes must be an ArrayBuffer or Uint8Array');
+}
+
+function createPacket(opts) {
+  const {
+    operation,
+    reserve = 0,
+    srcPort = 0,
+    dstPort = 0,
+    identifier = 0,
+    source = 0,
+    payload = null,
+  } = opts;
+
+  const payloadLen = payload ? payload.length : 0;
+  const total = FIXED_HEADER_LEN + payloadLen;
+  const buf = new ArrayBuffer(total);
+  const view = new DataView(buf);
+  const u8 = new Uint8Array(buf);
+
+  view.setUint8(0, FIXED_HEADER_LEN / 4);
+  view.setUint8(1, reserve);
+  view.setUint16(2, total, false);
+  view.setUint32(4, operation, false);
+  view.setUint16(8, srcPort, false);
+  view.setUint16(10, dstPort, false);
+  view.setUint32(12, identifier, false);
+  view.setUint32(16, source, false);
+
+  if (payload && payloadLen) {
+    u8.set(payload, FIXED_HEADER_LEN);
+  }
+
+  return u8;
+}
+
+function parsePacket(bytes) {
+  const u8 = toUint8Array(bytes);
+  if (u8.byteLength < FIXED_HEADER_LEN) {
+    throw new Error(`packet too short: ${u8.byteLength} bytes`);
+  }
+
+  const view = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  const headerLength = view.getUint8(0) * 4;
+  const reserve = view.getUint8(1);
+  const packetLength = view.getUint16(2, false);
+  const operation = view.getUint32(4, false);
+  const srcPort = view.getUint16(8, false);
+  const dstPort = view.getUint16(10, false);
+  const identifier = view.getUint32(12, false);
+  const source = view.getUint32(16, false);
+
+  if (headerLength < FIXED_HEADER_LEN) {
+    throw new Error(`invalid hwlink packet header length: ${headerLength}`);
+  }
+  if (packetLength > u8.byteLength) {
+    throw new Error(`incomplete hwlink packet: ${packetLength} > ${u8.byteLength}`);
+  }
+
+  let data = null;
+  if (packetLength > FIXED_HEADER_LEN) {
+    data = u8.subarray(FIXED_HEADER_LEN, packetLength);
+  }
+
+  return {
+    headerLength,
+    reserve,
+    packetLength,
+    operation,
+    srcPort,
+    dstPort,
+    identifier,
+    source,
+    data,
+  };
+}
+
+export {
+  FIXED_HEADER_LEN,
+  MAX_SEND_CHUNK_SIZE,
+  OpCode,
+  ReserveSource,
+  createPacket,
+  formatPacketOneLine,
+  isOpCmdTerminalData,
+  isOpCreateTcpTunnel,
+  isOpFailed,
+  isOpListenTcpTunnel,
+  isOpReverseCreateTcpTunnel,
+  isOpTcpTunnelData,
+  isOpTunnelSuccess,
+  isSubStreamPing,
+  nextIdentifier,
+  operationToString,
+  parsePacket,
+  toUint8Array,
+};

package/plugins/huaweicloud-core/src/ws-exec/hwlink-terminal-channel.js

@@ -0,0 +1,158 @@
+import {
+  OpCode,
+  ReserveSource,
+  FIXED_HEADER_LEN,
+  MAX_SEND_CHUNK_SIZE,
+  createPacket,
+  isOpCmdTerminalData,
+  isOpFailed,
+  isSubStreamPing,
+  nextIdentifier,
+} from './hwlink-packet.js';
+
+const encoder = new TextEncoder();
+const MAX_TERMINAL_PAYLOAD_SIZE = MAX_SEND_CHUNK_SIZE - FIXED_HEADER_LEN;
+
+class HwlinkTerminalChannel {
+  constructor(username = 'root') {
+    this.username = username;
+    this.identifier = nextIdentifier();
+    this.mux = null;
+    this.closed = false;
+    this.opened = false;
+    this.onDataCb = null;
+    this.onCloseCb = null;
+    this.onErrorCb = null;
+    this.onReadyCb = null;
+  }
+
+  onData(cb) {
+    this.onDataCb = cb;
+  }
+
+  onClose(cb) {
+    this.onCloseCb = cb;
+  }
+
+  onError(cb) {
+    this.onErrorCb = cb;
+  }
+
+  onReady(cb) {
+    this.onReadyCb = cb;
+  }
+
+  get isClosed() {
+    return this.closed;
+  }
+
+  attach(mux) {
+    this.mux = mux;
+    mux.register(this);
+  }
+
+  onopen() {
+    if (this.closed || this.opened) return;
+    this.opened = true;
+    this.sendRaw(createPacket({
+      operation: OpCode.OpNewCmdTerminal,
+      reserve: ReserveSource.Web,
+      identifier: this.identifier,
+      source: this.mux ? this.mux.source : 0,
+      payload: encoder.encode(this.username),
+    }));
+    if (this.onReadyCb) this.onReadyCb();
+  }
+
+  onmessage(packet) {
+    if (this.closed) return;
+
+    if (isOpFailed(packet.operation)) {
+      this.handleError(new Error(`hwlink terminal failed: 0x${packet.operation.toString(16)}`));
+      return;
+    }
+
+    if (isSubStreamPing(packet.operation)) {
+      this.sendRaw(createPacket({
+        operation: OpCode.OpCmdTerminalData | OpCode.OpSubStreamPong,
+        reserve: ReserveSource.Web,
+        identifier: this.identifier,
+        source: this.mux ? this.mux.source : 0,
+        payload: new Uint8Array(0),
+      }));
+      return;
+    }
+
+    if (isOpCmdTerminalData(packet.operation) && packet.data) {
+      if (this.onDataCb) this.onDataCb(packet.data);
+    }
+  }
+
+  onerror(error) {
+    if (this.onErrorCb) this.onErrorCb(error);
+  }
+
+  onclose() {
+    this.close();
+  }
+
+  sendInput(data) {
+    if (this.closed) return;
+    for (let offset = 0; offset < data.byteLength; offset += MAX_TERMINAL_PAYLOAD_SIZE) {
+      const payload = data.subarray(offset, offset + MAX_TERMINAL_PAYLOAD_SIZE);
+      this.sendTerminalData(payload);
+    }
+  }
+
+  sendTerminalData(payload) {
+    this.sendRaw(createPacket({
+      operation: OpCode.OpCmdTerminalData | OpCode.OpSubStreamPong,
+      reserve: ReserveSource.Web,
+      identifier: this.identifier,
+      source: this.mux ? this.mux.source : 0,
+      payload,
+    }));
+  }
+
+  sendText(text) {
+    this.sendInput(encoder.encode(text));
+  }
+
+  resize(cols, rows) {
+    if (this.closed) return;
+    const payload = new Uint8Array(4);
+    const view = new DataView(payload.buffer);
+    view.setUint16(0, rows, false);
+    view.setUint16(2, cols, false);
+    this.sendRaw(createPacket({
+      operation: OpCode.OpCmdTerminalResize,
+      reserve: ReserveSource.Web,
+      identifier: this.identifier,
+      source: this.mux ? this.mux.source : 0,
+      payload,
+    }));
+  }
+
+  sendRaw(data) {
+    if (this.mux) this.mux.sendFairly(this, data);
+  }
+
+  handleError(error) {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.mux) this.mux.unregister(this);
+    if (this.onErrorCb) this.onErrorCb(error);
+    if (this.onCloseCb) this.onCloseCb();
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.mux) this.mux.unregister(this);
+    if (this.onCloseCb) this.onCloseCb();
+  }
+}
+
+export {
+  HwlinkTerminalChannel,
+};

package/plugins/huaweicloud-core/src/ws-exec/index.js

@@ -0,0 +1,19 @@
+import * as hwlinkExec from './hwlink-exec-client.js';
+import * as hwlinkPacket from './hwlink-packet.js';
+import * as wsExec from './ws-exec-client.js';
+import { HwlinkWebSocketMultiplexer } from './hwlink-multiplexer.js';
+import { HwlinkTerminalChannel } from './hwlink-terminal-channel.js';
+
+export * from './ws-exec-client.js';
+export * from './hwlink-exec-client.js';
+export { HwlinkTerminalChannel } from './hwlink-terminal-channel.js';
+export { HwlinkWebSocketMultiplexer } from './hwlink-multiplexer.js';
+export { hwlinkPacket };
+
+export default {
+  ...wsExec,
+  ...hwlinkExec,
+  HwlinkTerminalChannel,
+  HwlinkWebSocketMultiplexer,
+  hwlinkPacket,
+};