grpc-libp2p-client

grpc-libp2p-client 是一个在浏览器环境中运行的 gRPC 客户端库，它构建于 libp2p 之上。它使得浏览器可以直接与基于 libp2p 的 gRPC 服务端进行安全、高效的点对点通信。

本库完整支持四种 gRPC通信模式：
* Unary (一元调用)
* Server Streaming (服务端流)
* Client Streaming (客户端流)
* Bidirectional Streaming (双向流)

---

目录

- 安装
- 快速上手
- 用法示例
- 1. Unary (请求-响应)
- 2. Server Streaming (服务端流)
- 3. Client Streaming (客户端流)
- 4. Bidirectional (双向流)
- API 参考

---

安装

``bash
npm install grpc-libp2p-client


或者


yarn add grpc-libp2p-client
`

快速上手

下面是一个快速设置并初始化客户端的示例。

`javascript
import { createLibp2p } from 'libp2p';
import { webRTC } from '@libp2p/webrtc';
import { noise } from '@chainsafe/libp2p-noise';
import { yamux } from '@chainsafe/libp2p-yamux';
import { Libp2pGrpcClient } from 'grpc-libp2p-client';

// 1. 创建并启动一个 libp2p 节点
// 这是客户端运行的基础，负责网络连接和数据传输
const node = await createLibp2p({
transports: [
webRTC()
],
connectionEncryption: [
noise()
],
streamMuxers: [
yamux()
]
});
await node.start();
console.log('Libp2p node started with Peer ID:', node.peerId.toString());


// 2. 定义服务端信息
const serverPeerAddr = '/ip4/x.x.x.x/tcp/4006/p2p/12D3KooW...'; // 替换为你的 gRPC 服务端的 PeerAddr
const serverProtocol = '/my-grpc-service/1.0.0'; // 替换为服务端使用的协议ID

// 3. 实例化 gRPC 客户端
// 将 libp2p 节点实例和服务端信息传入
const grpcClient = new Libp2pGrpcClient(node, serverPeerAddr, "",serverProtocol);

console.log('gRPC client is ready to make calls.');
`

用法示例

在初始化客户端后，你可以根据需要选择不同的模式与服务端通信。

注意: 所有模式中，请求体(messageBytes)都需要预先使用 protobuf 进行编码。

$3

这是最基础的模式，客户端发送一个请求，服务端返回一个响应。

`javascript
// 假设 messageBytes 是已经编码好的请求数据
// const messageBytes = MyRequest.encode({ field: 'value' }).finish();

try {
const responseData = await grpcClient.unaryCall(
"/myservice.Service/MyMethod", // gRPC 方法路径
messageBytes, // Protobuf 编码后的请求字节流
3000 // 调用超时时间 (ms)
);

// 解码响应数据
// const response = MyResponse.decode(responseData);
console.log('Unary call successful, response:', responseData);

} catch (error) {
console.error('Unary call failed:', error);
}
`

$3

客户端发送一个请求，服务端以流的形式持续返回多个响应。

`javascript
// 定义一个回调函数来处理服务端发来的每一条数据
const onDataCallback = (payload: Uint8Array) => {
// const message = MyStreamResponse.decode(payload);
console.log('Received stream data:', payload);
};

await grpcClient.Call(
"/myservice.Service/MyServerStreamMethod",
messageBytes,
30000,
"server-streaming",
onDataCallback,
);
`

$3

客户端以流的形式发送多个请求，服务端在接收完所有请求后返回一个响应。

`javascript
// 创建一个异步迭代器，用于持续提供要发送的数据
const dataSourceCallback = async function* (): AsyncIterable {
for (let i = 0; i < 5; i++) {
// const requestPart = MyStreamRequest.encode({ part: i }).finish();
const requestPart = new Uint8Array([i]); // 示例数据
yield requestPart;
await new Promise(resolve => setTimeout(resolve, 500)); // 模拟异步发送
}
};

// 定义数据回调，只会在服务端最终响应时触发一次
const onDataCallback = (payload: Uint8Array) => {
// const finalResponse = MyFinalResponse.decode(payload);
console.log('Client stream finished, final response:', payload);
};

await grpcClient.Call(
"/myservice.Service/MyClientStreamMethod",
messageBytes, // 初始消息体
30000,
"client-streaming",
onDataCallback,
dataSourceCallback,
);
`

$3

客户端和服务端可以同时向对方发送数据流，实现全双工通信。

`javascript
// 定义数据回调，处理服务端发来的每一条数据
const onDataCallback = (payload: Uint8Array) => {
console.log('Bidi: Received data from server:', payload);
};

// 定义数据源，持续向服务端发送数据
const dataSourceCallback = async function* (): AsyncIterable {
for (let i = 0; i < 5; i++) {
const requestPart = new Uint8Array([i]);
console.log(Bidi: Sending data to server: ${i});
yield requestPart;
await new Promise(resolve => setTimeout(resolve, 500));
}
};

// 定义结束和错误处理回调
const onEndCallback = () => console.log('Bidi stream ended.');
const onErrorCallback = (err: unknown) => console.error('Bidi stream error:', err);

await grpcClient.Call(
"/myservice.Service/MyBidiMethod",
messageBytes, // 可以发送一个初始消息
30000,
"bidirectional",
onDataCallback,
dataSourceCallback,
onEndCallback,
onErrorCallback
);
`

---

API 参考

$3

- node (Libp2p): 一个已创建并启动的 libp2p 节点实例。
- serverPeerAddr (string): 目标 gRPC 服务端的p2p地址字符串。
- token (string): 目标 gRPC 服务端要求的认证信息,在http2头的authorization字段中提交,可以为空。
- protocol (string): 双方协定好的、用于 gRPC 通信的 libp2p 协议 ID。

$3

用于发起一次性的请求-响应调用。

- 返回: Promise - 服务端返回的 Protobuf 编码后的字节流。

$3

用于发起所有类型的流式调用。

- path (string): gRPC 方法的完整路径。
- payload (Uint8Array | null): 初始请求的字节流。
- timeout (number): 调用超时时间 (ms)。
- mode (string): 调用模式。
- "server-streaming"
- "client-streaming"
- "bidirectional"
- onDataCallback ((data: Uint8Array) => void): 接收数据的回调。
- dataSourceCallback? (() => AsyncIterable): 提供发送数据的异步迭代器 (用于客户端流和双向流)。
- onEndCallback? (() => void): 流正常结束时的回调。
- onErrorCallback? ((err: unknown) => void): 发生错误时的回调。
- context? ( { signal?: AbortSignal }`): 中间取消。