1tp 中文文档教程

Question

1tp

一个传输协议来统治它们——在各种通信协议之上提供网络套接字抽象

Summary

1tp 的目标是提供一个单一的解决方案来连接任何两个可用的端点——公共的、私有的、移动的、位于 NAT 盒后面的……为此，1tp 充当各种现有传输的包装器，例如 UDP、TCP、WebRTC 和 TURN（更多将在以后的版本中出现）。 这些传输的内部细节通过类似于节点的网络 API 的 API 隐藏，使用套接字和流。 此外，1tp 在两个端点之间建立连接时总是尝试使用“最便宜”的传输。 例如，如果两个端点共享同一网络，则 1tp 将设置 UDP 或 TCP 连接。 如果两个端点位于对称 NAT 框后面，则 1tp 将通过共享中继服务器协商 TURN 或 WebRTC 会话。

Features

• stream based API, highly inspired by node's net API
• current version includes UDP, TCP, WebRTC and TURN connectors -- extending UDP with hole punching + integrating other transports such as websockets, GCM and tor is WiP.
• connection setup mechanism tries to select the 'cheapest' transport -- using different schedulers to execute connection handshakes sequential (default) or in parallel (experimental)
• can be browserified (to be used in chrome and cordova apps)

Install

npm install 1tp

Usage

'use strict'

var onetp = require('1tp')
var net = onetp.net

// 1tp transports
var UdpTransport = onetp.transports.udp
var TcpTransport = onetp.transports.tcp
var TurnTransport = onetp.transports.turn
var WebRtcTransport = onetp.transports.webrtc

// local signaling service to exchange turn handshake messages
var LocalSignaling = onetp.signaling.local
var localSignaling = new LocalSignaling()

// 1tp-registrar signaling service to exchange turn handshake messages
var WebSocketSignaling = onetp.signaling.websocket

// specify which server transports to 'activate'
var serverTransports = []
serverTransports.push(new UdpTransport())
serverTransports.push(new TcpTransport())
serverTransports.push(new TurnTransport({
  turnServer: IP_ADDRESS,
  turnPort: PORT,
  turnUsername: USERNAME,
  turnPassword: PASSWORD,
  //signaling: localSignaling,
  signaling: new WebSocketSignaling({
    url: ONETP_REGISTRAR
  })
}))
serverTransports.push(new WebRtcTransport({
  config: { iceServers: [ { url: 'stun:stun.l.google.com:19305' } ] },
  //signaling: localSignaling,
  signaling: new WebSocketSignaling({
    url: ONETP_REGISTRAR
  })
}))
// create server instance
var onetpServer = net.createServer(serverTransports, function (connection) {
  console.log('server connection established')
  // create echo channel
  connection.pipe(connection)
})
// listen for connect event
onetpServer.on('listening', function () {
  // specify which client transports to 'activate'
  var clientTransports = []
  clientTransports.push(new UdpTransport())
  clientTransports.push(new TcpTransport())
  clientTransports.push(new TurnTransport({
    turnServer: IP_ADDRESS,
    turnPort: PORT,
    turnUsername: USERNAME,
    turnPassword: PASSWORD,
    //signaling: localSignaling,
    signaling: new WebSocketSignaling({
      url: ONETP_REGISTRAR
    })
  }))
  clientTransports.push(new WebRtcTransport({
    config: { iceServers: [ { url: 'stun:23.21.150.121' } ] }
    //signaling: localSignaling,
    signaling: new WebSocketSignaling({
      url: ONETP_REGISTRAR
    })
  }))

  //
  var onetpClient = net.createConnection(onetpServer.address(), clientTransports, function () {
    console.log('client connection established')
    onetpClient.write('hello world')
  })
  onetpClient.on('data', function (data) {
    console.log(data.toString())
  })

})
// launch server
onetpServer.listen()

API

var server = new Server([transports][, connectionListener])

创建一个新的 1tp 服务器实例。

可选的 connectionListener 参数自动设置为 connection 事件的侦听器。

transports 参数指定此服务器实例必须激活的可选传输协议数组。 1tp 的当前实现包括以下传输（另请参见上面的示例）：

• onetp.transports.udp -- creates UDP dgram socket
• onetp.transports.tcp -- creates TCP net server socket
• onetp.transports.turn -- creates TURN socket
• onetp.transports.webrtc -- creates WebRTC socket

onetp.transports.udp 和 onetp.transports.tcp 不需要额外的属性。 onetp.transports.turn，相比之下，接受以下规范：

• turnServer (mandatory): IP address of the TURN server to interact with
• turnPort (mandatory): port number of that TURN server
• turnUserName (mandatory): username to access this TURN server
• turnPassword (mandatory): user password to access TURN server
• turnProtocol (optional): transport protocol to interact with TURN server -- default is UDP, see example for using TCP instead
• signaling (mandatory): specify which signaling server to use (loopback or 1tp-registrar). When using 1tp-registrar), you need to specify the URL of the server

onetp.transports.webrtc 还需要指定它应该使用的signaling 服务器. 此外，此传输接受所有 simple-peer（数据通道）选项。

在未指定要使用的传输方式的情况下创建服务器实例时，1tp

• activates the transports that are compatible with the runtime -- see compatibility table below, and
• activates TURN if environment variables TURN_ADDR, TURN_PORT, TURN_USER, TURN_PASS and ONETP_REGISTRAR are all set

server.listen([listeningInfo][, callback])

指示 1tp 服务器开始接受连接。

listeningInfo 参数指定一个可选的传输绑定属性数组。 1tp 在指示它们开始接受连接时将这些参数传递给关联的传输协议。 下面的示例说明了一个 listeningInfo 对象通知 1tp 将其 udp 传输绑定到 127.0.0.1/20000 并将其 tcp 传输绑定到 127.0.0.1/20001 请

[{
  transportType: 'udp',
  transportInfo: {
    address: '127.0.0.1',
    port: 20000
  }
}, {
  transportType: 'tcp',
  transportInfo: {
    address: '127.0.0.1',
    port: 20001
  }
}]

注意 listeningInfo 数据是指示性的. 如果由于 listeningInfo 数据不正确（例如地址不可用）导致监听操作失败，则 1tp 服务器会在没有 listeningInfo 的情况下重试执行此操作。

可选的 callback 参数自动设置为 listening 事件的侦听器。

server.listenP([listeningInfo])

指示 1tp 服务器开始接受连接。 此函数不会触发 listening 事件，而是返回一个承诺，一旦所有已注册的传输协议都接受连接，该承诺就会实现。 此 promise 返回与 server.address() 相同的 connectionInfo —— 见下文

server.address()

返回活动传输生成的 connectionInfo。 此 connectionInfo 是传输特定端点信息的数组。 下面的示例说明了 1tp 服务器的 connectionInfo 地址

[ { transportType: 'udp',
    transportInfo: { address: '192.168.1.30', port: 61773 },
    version: '0.17.4' },
  { transportType: 'udp',
    transportInfo: { address: '192.168.241.1', port: 61773 },
    version: '0.17.4' },
  { transportType: 'tcp',
    transportInfo: { address: '192.168.1.30', port: 61564 },
    version: '0.17.4' },
  { transportType: 'tcp',
    transportInfo: { address: '192.168.241.1', port: 61564 },
    version: '0.17.4' },
  { transportType: 'turn-tcp',
    transportInfo:
     { type: 'websocket-signaling',
       uid: '1636e5e5437eb1733e1d22d21a50e478',
       url: 'http://1.2.3.4/' },
    version: '0.17.4' } ]

server.close()

阻止服务器接受新连接并保持现有连接。 此函数是异步的，当所有连接结束并且服务器发出“关闭”事件时，服务器最终关闭。 一旦“关闭”事件发生，将调用可选的回调。 [从 nodejs 文档复制]

var socket = new Socket([transports][, args])

创建一个新的 1tp 套接字（客户端）对象。

可选的 transports 参数指定此套接字应该使用哪些传输协议来建立与 1tp 服务器的连接。 有关这些传输协议规范的更多详细信息，请参见上文。

可选的 args 对象包括指定此套接字行为的附加标志。 目前，仅支持 parallelConnectionSetup 标志，指示套接字并行而不是顺序安排所有连接尝试（这是默认行为）。 请注意，这仍然是一个高度实验的功能。

socket.connect(connectionInfo[, connectListener])

设置与 1tp 服务器的连接。

connectionInfo 参数指定要连接的 1tp 服务器。 如上所述，此 connectionInfo 对象是传输特定端点信息的集合。

可选的 connectListener 参数自动设置为 connect 事件的侦听器。

socket.isConnected()

如果其中一种传输协议已与 1tp 服务器建立连接，则返回 true。

socket.remoteAddress

包含已连接对等方的 connectionInfo。

socket.destroy()

关闭套接字，完成此操作后无法再进行通信。 关闭连接时发出 close 事件。

socket.end()

半关闭套接字，服务器可能仍会结束一些数据。

socket.setTimeout(timeout[, callback])

在 timeout 毫秒不活动后将套接字设置为超时。 套接字然后触发 timeout 事件。

如果 timeout 为 0，则禁用现有的空闲超时。

可选的 callback 自动设置为 timeout 事件的一次性侦听器。

socket.write(data[, encoding][, callback])

在套接字上发送数据。

net.createServer([transports][, connectionListener])

创建并返回一个新的 1tp 服务器实例。

transports 参数指定此服务器实例必须激活的可选传输协议数组。 有关更多详细信息，请参见上文。

可选的 connectionListener 参数自动设置为 connection 事件的侦听器。

net.createConnection(connectionInfo[, transports][, args][, connectListener])

创建并返回一个新的 1tp 套接字实例。

connectionInfo 参数指定要连接的端点。 如上所述，此 connectionInfo 是传输特定端点信息的数组。

可选的 transports 参数指定此套接字应该使用哪些传输协议来建立与 1tp 服务器的连接。 有关这些传输协议规范的更多详细信息，请参见上文。

可选的 args 对象包括指定此套接字行为的附加标志。 有关此选项的更多详细信息，请参见上文。

可选的 connectListener 参数自动设置为 connect 事件的侦听器。

Events

server.on('connection', function(socket) {})

建立新连接时发出。 socket 是 1tp 的 net.Socket 的实例。

server.on('error', function(error) {})

发生错误时发出。

server.on('listening', function() {})

在调用 server.listen 后所有已注册的传输协议都接受连接时发出。

socket.on('connect', function() {})

当成功建立套接字连接时发出——即传输协议之一已与 1tp 服务器建立连接。

socket.on('data', function(data) {})

收到数据时发出。 data 参数是一个缓冲区。

socket.on('end', function() {})

当连接的套接字结束其写入流时发出。

socket.on('finish', function() {})

当套接字的读取流中没有更多数据可供使用时发出。

socket.on('close', function() {})

在套接字完全关闭后发出——在执行 socket.destroy

socket.on('error', function(error) {})

发生错误时发出。

socket.on('timeout', function() {})

如果套接字因不活动而超时，则发出——通知套接字已空闲。

Chrome and cordova apps

gulp browserify [--production]

在 build 文件夹中创建 1tp.debug.js 和 1tp.min.js，可用于 chrome 和 cordova 应用程序。 在cordova应用中集成1tp时，使用cordova-plugin-chrome-apps-sockets-udp和cordova-plugin-chrome-apps-system-network插件~~和 cordova-plugin-chrome-apps-sockets-tcp 和 cordova-plugin-chrome-apps-sockets-tcpserver plugins~~（tcp cordova 插件产生错误）：

cordova plugin add cordova-plugin-chrome-apps-sockets-udp
cordova plugin add cordova-plugin-networkinterface

Compatibility -- current status

	UDP	TCP	TURN+UDP	TURN+TCP	WebRTC
node.js x86	+	+	+	+	+
node.js arm	+	+	+	+	-
chrome browser	-	-	-	-	+
chrome app	+	+	+	+	+
cordova android	+	-	+	-	+
cordova ios	+	-	+	-	-

Examples

见示例目录。