@capaly/ react-web-cli (英语)

在网络应用程序中嵌入交互式Ably CLI终端的回放组件.

特征

• 内嵌 a ably CLI 完全定制 任何 React app 中的会话( xterm.js) .
• 使用 HMAC 签名的认证连接 Ably 终端服务器的安全 WebSocket 签名配置 财务报告和审定财务报表 签名。 。 。 .
• 一等站 UX:
  • 带有 ANSI 颜色的终端本地状态信息
  • 动画旋转器在( 重新) 连接时
  • 实况倒计时和清晰的指导(按下) 输入 取消/重试)
  • ASCII 重要状态信息模式框
• 强大的连接处理 :
  • 自动指数回放重接 (0 s, 2 s, 4 s, 8 s.)
  • 切换到手动重联之前可配置的最大重联尝试( 默认: 15)
  • 用特定错误代码妥善处理服务器启动的断开
• 复会 页面再装入或瞬间网络丢失(resumeOnReload) (中文(简体) ).
• 分屏模式 并同时有两个独立的终端会话.
• 工作在全屏或大抽屉中(见 examples/web-cli) (中文(简体) ).
• 以 TypeScript 写成, 完全可以树为轴 .

安装

# Using npm
npm install @ably/react-web-cli

# Using yarn
yarn add @ably/react-web-cli

# Using pnpm
pnpm add @ably/react-web-cli

先决条件

• 17.0.0以上反应
• Ably CLI 终端服务器的运行实例(参见 @cli-terminal-服务器(中文(简体) )
• 生成HMAC签名证书的后端签名端点(见下文执行指南)

使用量

import { useState, useEffect } from "react";
import { AblyCliTerminal } from "@ably/react-web-cli";

export default function MyTerminal() {
  const [status, setStatus] = useState("disconnected");
  const [signedConfig, setSignedConfig] = useState("");
  const [signature, setSignature] = useState("");

  // Sign credentials via your backend endpoint
  // See examples/web-cli/api/sign.ts for implementation reference
  async function signCredentials(apiKey: string) {
    const response = await fetch("/api/sign", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ apiKey }),
    });
    const { signedConfig, signature } = await response.json();
    setSignedConfig(signedConfig);
    setSignature(signature);
  }

  // Authenticate on mount (or when user provides credentials)
  useEffect(() => {
    const apiKey = "YOUR_ABLY_API_KEY"; // Get from user input or config
    signCredentials(apiKey);
  }, []);

  if (!signedConfig || !signature) {
    return <div>Loading...</div>;
  }

  return (
    <div style={{ height: 500 }}>
      <AblyCliTerminal
        websocketUrl="wss://web-cli.ably.com"
        signedConfig={signedConfig}
        signature={signature}
        initialCommand="ably --version"
        onConnectionStatusChange={setStatus}
        onSessionEnd={(reason) => console.log("session ended", reason)}
        onSessionId={(id) => console.log("session id", id)}
        resumeOnReload
        maxReconnectAttempts={15}
      />

      <p>Status: {status}</p>
    </div>
  );
}

道具

说明: 这个 signedConfig 财务报告和审定财务报表 signature 必须由 您的后端 使用HMAC-SHA256签名. 绝不在浏览器中签名 - 这将暴露您的签名秘密 .

参考执行情况:

• 维塞尔: 见 examples/web-cli/api/sign.ts 对于一个没有服务器的函数示例
• 节点.js: 见 examples/web-cli/server/sign-handler.ts 用于共享签名逻辑
• 维特·德夫: 见 examples/web-cli/vite.config.ts 用于开发中间软件

您的签名秘密必须符合终端服务器的 SIGNING_SECRET 配置 。 联系您的平台团队以获取这个秘密或参考 终端服务器文档。 。 。 .

执行签名终点

你个 必须 执行后端终点以签署证书。 这里有一个小例子:

// Example: /api/sign endpoint (Node.js/Express/Vercel)
import crypto from "crypto";

export default function handler(req, res) {
  const { apiKey } = req.body;
  const secret = process.env.SIGNING_SECRET; // From environment variable

  // Build config object
  const config = {
    apiKey,
    timestamp: Date.now(),
  };

  // Sign it with HMAC-SHA256
  const configString = JSON.stringify(config);
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(configString);
  const signature = hmac.digest("hex");

  res.json({ signedConfig: configString, signature });
}

安保要求:

• ⚠️ 从不 在客户端代码中嵌入您的签名秘密
• ⚠️ 永远 在您的安全后端服务器上签名
• QQ 签名密钥必须匹配终端服务器的配置
• QQ 生产时使用 HTTPS 保护 API 键

全面实施的实例:

• 见 examples/web-cli/ 完整工作示例目录
• 包括 Vercel 无服务器功能、 Vite dev 中间软件和 React 集成

中断更改和迁移

HMAC 签名认证( 正在更改)

这是一个突破性的变化. 认证机制已经更新,以便使用HMAC签署的证书来改进安全.

旧 API( 过期 ) :

<AblyCliTerminal
  websocketUrl="wss://web-cli.ably.com"
  ablyApiKey="YOUR_ABLY_API_KEY"           // ❌ Removed
  ablyAccessToken="YOUR_ABLY_TOKEN"        // ❌ Removed
  ablyEndpoint="nonprod:sandbox"           // ❌ Removed
  ablyControlHost="staging-control..."     // ❌ Removed
/>

新建 API( 需要):

<AblyCliTerminal
  websocketUrl="wss://web-cli.ably.com"
  signedConfig={signedConfig}              // ✅ Required
  signature={signature}                    // ✅ Required
/>

移徙步骤:

1. 执行后端签名 : 创建一个 /api/sign 后端的端点(见上文“执行签名端点”部分)
2. 获得签名秘密 : 获取 SIGNING_SECRET 来自您的平台团队( 必须匹配终端服务器配置)
3. 更新您的反应代码 :
   • 删除旧道具 : ablyApiKey, (中文(简体) ), ablyAccessToken, (中文(简体) ), ablyEndpoint, (中文(简体) ), ablyControlHost
   • 打电话给你 /api/sign 要得到的终点 signedConfig 财务报告和审定财务报表 signature
   • 将签名的证书传递给 AblyCliTerminal

为什么改变?

新的由 HMAC 签名的认证可以防止证书被篡改,并确保配置设置(如端点和控制主机)由服务器认证. 这为嵌入式终端会话提供了更好的安全.

连接国

该组件管理多个连接, 声明您的应用程序可以响应 :

• initial: 终端正在初始化
• connecting: 试图连接到服务器
• connected: 成功连接和准备
• disconnected: 服务器或用户手动关闭的连接
• reconnecting: 连接中断后试图重新连接
• error: 连接错误或其他终端错误

服务器启动断接

终端以特定的 WebSocket 关闭代码妥善处理服务器启动的断开:

对于其他WebSocket关闭代码,终端会自动尝试使用指数后退策略重新连接.

会话恢复

何时 resumeOnReload 启用,终端将把会话ID存储到 sessionStorage 并尝试在重新装入一页后恢复会话。 这使得在导航出行后和回行后可以进行无缝体验.

分块模式

何时 enableSplitScreen 设置为 true,组件在终端右上角显示一个分割图标。 点击此图标可以将视图分割为两个独立的终端会话并排.

分屏模式的特性 :

• 两个完全独立的终端会话,共享相同的证书
• 每个终端都有自己的有关闭按钮的标签
• 两个终端自动调整大小,以保持最佳布局
• 每个终端独立进行状态和连接管理
• 关闭任一终端返回到单页模式

该功能是为需要同时运行多条指令的开发者设计的,比如在一个面板上订阅一个频道,同时在另一个面板上发布.

设置终端服务器

此组件所需的终端服务器由单独的寄存器提供. 请参看 @cli-terminal-服务器 用于:

• 安装指令
• 配置选项
• 本地运行服务器
• Docker 部署指令

用于生产,Ably网络CLI连接到 wss://web-cli.ably.com 默认情况下,这是终端服务器的主机实例.

页:1

• 航站楼需要一个容器来进行尺寸,所以要确保母元素有被定义的高度和宽度.
• 该组件会用指数回放自动处理重联.
• 仅 ably, (中文(简体) ), clear,以及 exit 命令默认在终端中可用.
• 终端支持完整的xterm.js功能,包括颜色和Unicode.

调试Verbose 日志( V)

装有内置动词记录器的部件船 默认禁用。 。 。 . 以下列任何方式启用 在此之前 组件挂载 :

1. 查询字符串旗 - 简单添加 ?cliDebug=true 到页面 URL. 示例 http://localhost:5173/?cliDebug=true (国旗可与其他查询参数合并

2. 运行时全球旗帜 - 从浏览器 DevTools 控制台运行:

window.ABLY_CLI_DEBUG = true;

终端将发布详细寿命周期日志,其前缀为 [AblyCLITerminal DEBUG]。删除旗帜或刷新而无需查询 参数返回到无声模式.

示例项目

使用该组件的完整实例,见 网络 cli 实例 在 Ably CLI 存储器中.

发展

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

许可证

阿帕奇 - 2.0