中继混合连接 Node API 概述

项目
08/28/2023

概述

Azure 中继混合连接的 hyco-ws Node 包基于 ws NPM 包构建并对其进行了扩展。此包将重新导出该基程序包的所有导出，并添加允许与 Azure 中继服务混合连接功能集成的新导出。

在现有应用程序中，require('ws') 可以改为结合使用此包与 require('hyco-ws')，从而还可以实现混合方案，其中应用程序可以同时从“防火墙内”和通过混合连接本地侦听 WebSocket 连接。

文档

各个 API 记录在主 ws 包中。本文介绍此包与该基线有何不同。

基程序包和此 ‘hyco-ws’ 之间的主要区别是添加了新的服务器类、通过 require('hyco-ws').RelayedServer 导出以及添加了一些帮助程序方法。

包帮助程序方法

包导出上提供了几种实用方法，可按以下方式引用：

const WebSocket = require('hyco-ws');

var listenUri = WebSocket.createRelayListenUri('namespace.servicebus.chinacloudapi.cn', 'path');
listenUri = WebSocket.appendRelayToken(listenUri, 'ruleName', '...key...')
...

帮助程序方法可用于此包，但也可用于节点服务器，使 Web 或设备客户端能够创建侦听器或发件人。服务器使用这些方法时，向它们传递嵌入生存期较短的令牌的 URI。这些 URI 也可用于不支持设置 WebSocket 握手的 HTTP 头的常见 WebSocket 堆栈。将授权令牌嵌入到 URI 主要针对这些库外使用方案。

createRelayListenUri

var uri = createRelayListenUri([namespaceName], [path], [[token]], [[id]])

为给定命名空间和路径创建有效的 Azure 中继混合连接侦听器 URI。此 URI 随后可用于 WebSocketServer 类的中继版本。

namespaceName（必需）- 要使用的 Azure 中继命名空间的域限定名称。
path（必需）- 该命名空间中现有 Azure 中继混合连接的名称。
token（可选）- 以前颁发的中继访问令牌，嵌入到侦听器 URI 中（请参阅以下示例）。
id（可选）- 用于启用请求的端到端诊断跟踪的跟踪标识符。

token 值是可选的，仅在不可能发送 HTTP 头和 WebSocket 握手时使用，这与 W3C WebSocket 堆栈的情况相同。

createRelaySendUri

var uri = createRelaySendUri([namespaceName], [path], [[token]], [[id]])

为给定命名空间和路径创建有效的 Azure 中继混合连接发送 URI。此 URI 可与任何 WebSocket 客户端配合使用。

namespaceName（必需）- 要使用的 Azure 中继命名空间的域限定名称。
path（必需）- 该命名空间中现有 Azure 中继混合连接的名称。
token（可选）- 以前颁发的中继访问令牌，嵌入到发送 URI 中（请参阅以下示例）。
id（可选）- 用于启用请求的端到端诊断跟踪的跟踪标识符。

token 值是可选的，仅在不可能发送 HTTP 头和 WebSocket 握手时使用，这与 W3C WebSocket 堆栈的情况相同。

createRelayToken

var token = createRelayToken([uri], [ruleName], [key], [[expirationSeconds]])

为给定目标 URI、SAS 规则和 SAS 规则密钥创建 Azure 中继共享访问签名 (SAS) 令牌，其有效期为指定的数秒钟或者如果忽略到期参数，则为从当前时刻起一小时。

uri（必需）- 为之颁发令牌的 URI。规范化此 URI 以使用 HTTP 方案，且将除去查询字符串信息。
ruleName（必需）- 由给定 URI 表示的实体的 SAS 规则名称，或者由 URI 主机部分表示的命名空间的 SAS 规则名称。
key（必需）- SAS 规则的有效密钥。
expirationSeconds（可选）- 已生成的令牌过期之前的秒数。如果未指定，则默认值为 1 小时 (3600)。

颁发的令牌在给定的时间段内授予指定的 SAS 规则相关的权限。

appendRelayToken

var uri = appendRelayToken([uri], [ruleName], [key], [[expirationSeconds]])

此方法在功能上等效于之前记录的 createRelayToken 方法，但返回正确追加到输入 URI 的令牌。

Class ws.RelayedServer

hycows.RelayedServer 类可替代 ws.Server 类，不侦听本地网络，但委托侦听 Azure 中继服务。

这两个类通常为协定兼容，也就是说，使用 ws.Server 类的现有应用程序可以轻易改为使用中继版本。主要差异在于构造函数和可用选项。

构造函数

var ws = require('hyco-ws');
var server = ws.RelayedServer;

var wss = new server(
    {
        server: ws.createRelayListenUri(ns, path),
        token: function() { return ws.createRelayToken('http://' + ns, keyrule, key); }
    });

RelayedServer 构造函数支持一组不同的参数，而不支持 Server，因为该函数既不是独立侦听器，也不能嵌入到现有 HTTP 侦听器框架中。自从将 WebSocket 管理大幅委托到中继服务后，也有少数选项可用。

构造函数参数：

server（必需）- 要侦听的混合连接名称的完全限定 URI，通常使用 WebSocket.createRelayListenUri() 帮助程序方法构造。
token（必需）- 此参数可以保留以前颁发的令牌字符串，也可以保留为获得此类令牌字符串而调用的回调函数。在启用令牌续订时，首选回调选项。

事件

RelayedServer 实例会发出三个事件，以便能够处理传入的请求、建立连接，以及检测错误条件。订阅 connect 事件后才能处理消息。

headers

function(headers)

接受传入连接前会引发 headers 事件，实现将标头的修改发送到客户端。

连接

function(socket)

接受新的 WebSocket 连接时发出。此对象的类型为 ws.WebSocket，与基程序包相同。

error

function(error)

如果基础服务器发出错误，则会转发到此处。

帮助程序

为了简化中继服务器的启动和对传入连接的即时订阅，该包公开了一个简单的帮助程序函数，该函数也用于本示例中，如下所示：

createRelayedListener

var WebSocket = require('hyco-ws');

var wss = WebSocket.createRelayedServer(
    {
        server: WebSocket.createRelayListenUri(ns, path),
        token: function() { return WebSocket.createRelayToken('http://' + ns, keyrule, key); }
    }, 
    function (ws) {
        console.log('connection accepted');
        ws.onmessage = function (event) {
            console.log(JSON.parse(event.data));
        };
        ws.on('close', function () {
            console.log('connection closed');
        });       
});

createRelayedServer

var server = createRelayedServer([options], [connectCallback] )

此方法调用构造函数以创建 RelayedServer 的新实例，并订阅提供的 'connection' 事件的回调。

relayedConnect

在函数中镜像 createRelayedServer 帮助程序。 relayedConnect 方法创建客户端连接，并订阅结果套接字上的 'open' 事件。

var uri = WebSocket.createRelaySendUri(ns, path);
WebSocket.relayedConnect(
    uri,
    WebSocket.createRelayToken(uri, keyrule, key),
    function (socket) {
        ...
    }
);

后续步骤

若要了解有关 Azure 中继的详细信息，请访问以下链接：

通过