@celljs/grpc 4.6.1 → 4.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.zh-cn.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Cell - gRPC 组件
|
|
2
|
+
|
|
3
|
+
Cell 上的 gRPC 服务器和客户端,基于 `node:http2`,内置 `.proto` 解析器和 protobuf 编解码:无第三方依赖,无代码生成。一元、服务器流、客户端流和双向方法;与其他 gRPC 实现互操作(双向对 `@grpc/grpc-js` 测试过)。
|
|
4
|
+
|
|
5
|
+
## 定义服务
|
|
6
|
+
|
|
7
|
+
将 `.proto` 文件保留在源中并解析一次。使用 Vite(`cell build`、`cell dev`、`createTestApp()`),`?raw` 导入捆绑其文本:
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// src/greeter.ts
|
|
11
|
+
import { Proto, type UnaryCall, type ServerStreamCall } from '@celljs/grpc';
|
|
12
|
+
import source from './greeter.proto?raw'; // 声明 module '*?raw' 一次,见 examples/grpc-app/src/raw.d.ts
|
|
13
|
+
|
|
14
|
+
export const Greeter = Proto.parse(source).service('helloworld.Greeter');
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`Proto.parse(...sources)` 接受服务需要的每个文件(导入按类型名跨源解析);`google/protobuf` 众所周知的类型(`empty`、`timestamp`、`duration`、`wrappers`、`struct`、`any`、`field_mask`)是内置的。名字是完整的(`helloworld.Greeter`)或明确时短的。`proto.message('HelloRequest')` 给出一个有 `encode()` / `decode()` 的消息类型,用于 protobuf 但不用 gRPC。
|
|
18
|
+
|
|
19
|
+
## 提供服务
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { GrpcError, GrpcService, GrpcStatus, type ServerCall } from '@celljs/grpc';
|
|
23
|
+
import { Greeter } from './greeter';
|
|
24
|
+
|
|
25
|
+
@GrpcService(Greeter)
|
|
26
|
+
export class GreeterService {
|
|
27
|
+
|
|
28
|
+
@Autowired(UserService) // 像任何其他组件一样的组件
|
|
29
|
+
protected readonly users: UserService;
|
|
30
|
+
|
|
31
|
+
// rpc SayHello (HelloRequest) returns (HelloReply)
|
|
32
|
+
sayHello({ name }: HelloRequest, call: ServerCall): HelloReply {
|
|
33
|
+
if (!name) {
|
|
34
|
+
throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'name is required');
|
|
35
|
+
}
|
|
36
|
+
return { message: `Hello ${name}` };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// rpc SayHelloStream (HelloRequest) returns (stream HelloReply)
|
|
40
|
+
async *sayHelloStream({ name }: HelloRequest): AsyncIterable<HelloReply> {
|
|
41
|
+
yield { message: `Hello ${name}` };
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// rpc SayHelloToAll (stream HelloRequest) returns (HelloReply)
|
|
45
|
+
async sayHelloToAll(requests: AsyncIterable<HelloRequest>): Promise<HelloReply> { ... }
|
|
46
|
+
|
|
47
|
+
// rpc Chat (stream HelloRequest) returns (stream HelloReply)
|
|
48
|
+
async *chat(requests: AsyncIterable<HelloRequest>): AsyncIterable<HelloReply> { ... }
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
从 DI 模块导入文件(`src/module.ts`)。应用启动时,如果至少有一个 `@GrpcService`,`GrpcServerLifecycle` 启动 gRPC 服务器(日志中 `gRPC serve 127.0.0.1:50051`);应用停止时关闭。方法是 `.proto` 方法的小驼峰(`SayHello` → `sayHello`);没有实现的方法答 `UNIMPLEMENTED`。类型 `UnaryHandler`、`ServerStreamHandler`、`ClientStreamHandler` 和 `BidiStreamHandler` 描述四个签名。
|
|
53
|
+
|
|
54
|
+
最后一个参数,`call: ServerCall`,有请求 `metadata`(小写键)、当客户端取消或截止时中止的 `signal`、`deadline`、`setHeader(key, value)`(在第一条响应前)和 `setTrailer(key, value)`。
|
|
55
|
+
|
|
56
|
+
错误:抛出 `GrpcError(code, details, metadata?)` 以答该状态。其他任何错误答 `UNKNOWN` 带错误信息并被记录。
|
|
57
|
+
|
|
58
|
+
```yaml
|
|
59
|
+
grpc:
|
|
60
|
+
server:
|
|
61
|
+
enabled: true # false:即使有 @GrpcService 组件也无服务器
|
|
62
|
+
port: 50051 # CELL_GRPC__SERVER__PORT;0 取自由端口
|
|
63
|
+
host: 127.0.0.1 # CELL_GRPC__SERVER__HOST=0.0.0.0 在容器中
|
|
64
|
+
maxReceiveMessageSize: 4194304
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
gRPC 服务器是 `@celljs/express-adapter` 的 HTTP 一旁的第二端口;没有 HTTP 的应用不需适配器(`cell build` 则警告没有组件提供 `http` 入口,这是预期的)。Cell 应用外,`new GrpcServer(options).addService(Greeter, impl).listen(port, host)` 做同样的事,`server.handleStream(stream, headers)` 从你自己的 HTTP/2 服务器的流提供(例如 `http2.createSecureServer()` 用于 TLS)。
|
|
68
|
+
|
|
69
|
+
## 调用它
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { GrpcChannel } from '@celljs/grpc';
|
|
73
|
+
|
|
74
|
+
export interface GreeterClient {
|
|
75
|
+
sayHello: UnaryCall<Partial<HelloRequest>, HelloReply>;
|
|
76
|
+
sayHelloStream: ServerStreamCall<Partial<HelloRequest>, HelloReply>;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const channel = new GrpcChannel('localhost:50051', { metadata: { authorization: 'Bearer ...' }, timeout: 5000 });
|
|
80
|
+
const greeter = channel.createClient<GreeterClient>(Greeter);
|
|
81
|
+
|
|
82
|
+
const { message } = await greeter.sayHello({ name: 'Cell' });
|
|
83
|
+
for await (const reply of greeter.sayHelloStream({ name: 'Cell' })) { ... } // break 取消调用
|
|
84
|
+
await greeter.sayHelloToAll([{ name: 'a' }, { name: 'b' }]); // 任何(异步)可迭代对象
|
|
85
|
+
await greeter.sayHello({ name: 'Cell' }, { timeout: 1000, signal, metadata: { 'x-trace-bin': bytes } });
|
|
86
|
+
channel.close();
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
一个通道是一条 HTTP/2 连接,在第一次调用时打开,丢失时重新打开;在同一服务器的客户端之间共享。空闲通道不让进程活着。失败的调用拒绝时返回 `GrpcError`(`code`、`details`、尾部 `metadata`):当服务器无法到达时 `UNAVAILABLE`、`DEADLINE_EXCEEDED`、`CANCELLED` 等。无法编码的请求在发送任何东西前拒绝,返回命名字段的 `TypeError`。
|
|
90
|
+
|
|
91
|
+
## 值
|
|
92
|
+
|
|
93
|
+
| Protobuf | JavaScript |
|
|
94
|
+
| --- | --- |
|
|
95
|
+
| 字段 `user_id` | 属性 `userId`(编码也接受 `user_id`) |
|
|
96
|
+
| `int32`、`uint32`、`sint32`、`fixed32`、`sfixed32`、`float`、`double` | `number` |
|
|
97
|
+
| `int64`、`uint64`、`sint64`、`fixed64`、`sfixed64` | 十进制 `string`(编码也接受 `number` 和 `bigint`) |
|
|
98
|
+
| `bool`、`string` | `boolean`、`string` |
|
|
99
|
+
| `bytes` | `Uint8Array`(编码也接受 base64) |
|
|
100
|
+
| 枚举 | 值名(编码也接受数字;未知数字解码为数字) |
|
|
101
|
+
| 消息 | 对象;`google.protobuf.Timestamp` 是 `{ seconds: '…', nanos: 0 }` |
|
|
102
|
+
| `repeated` / `map<K, V>` | 数组 / 带字符串键的普通对象 |
|
|
103
|
+
| `oneof kind` | 集合成员,和 `kind: 'memberName'` |
|
|
104
|
+
|
|
105
|
+
解码的消息在每个没有明确存在的字段处其默认值(`0`、`''`、`false`、第一个枚举值、`[]`、`{}`);消息字段、`optional` 字段和 oneof 成员未设置时被忽略。未知字段被跳过。
|
|
106
|
+
|
|
107
|
+
## 测试
|
|
108
|
+
|
|
109
|
+
在 `cell.test.yml` 中,`backend.grpc.server.port: 0` 给测试应用一个自由端口;从应用加载的生命周期读它:
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
const app = await createTestApp();
|
|
113
|
+
const { GrpcServerLifecycle } = await app.import('@celljs/grpc');
|
|
114
|
+
const channel = new GrpcChannel(`127.0.0.1:${app.get(GrpcServerLifecycle).port}`);
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## 限制
|
|
118
|
+
|
|
119
|
+
- 运行时:Node.js >= 18 和 Deno 2 用于服务器和客户端;Bun 作为客户端,1.4 及以后作为服务器(更早版本的 HTTP/2 明文服务器仅答 Bun 客户端)。不在 Cloudflare Workers 或 FaaS 预设上:服务器需要一个有自己端口的长期运行进程。
|
|
120
|
+
- 服务器说明文 HTTP/2(h2c);在其前终止 TLS,或从你自己的 TLS 服务器提供 `handleStream()`。
|
|
121
|
+
- 接收的消息可能用 gzip 或 deflate 压缩;发送的消息不压缩。
|
|
122
|
+
- `.proto`:proto2 和 proto3。选项、`reserved`、扩展和 `extend` 被读和忽略;组和版本被拒绝。无服务器反射、健康服务或 gRPC-Web。
|
|
@@ -51,7 +51,10 @@ async function start(server = {}) {
|
|
|
51
51
|
await app.start();
|
|
52
52
|
return container.get(grpc_server_lifecycle_1.GrpcServerLifecycle);
|
|
53
53
|
}
|
|
54
|
-
|
|
54
|
+
// Under Bun on Windows this spec hangs before any test ends, past bun's own timeout of a test, so the
|
|
55
|
+
// event loop is blocked (the other specs of this package, servers and clients included, pass there).
|
|
56
|
+
// Its cause is not found yet; it runs on Linux and macOS.
|
|
57
|
+
bun_test_1.describe.skipIf(process.platform === 'win32')('GrpcService in an application', () => {
|
|
55
58
|
(0, bun_test_1.it)('serves the @GrpcService components on the configured port, with their dependencies injected', async () => {
|
|
56
59
|
let Names = class Names {
|
|
57
60
|
format(name) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"grpc-server-lifecycle.spec.js","sourceRoot":"","sources":["../../../src/node/server/grpc-server-lifecycle.spec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAAA,uCAA2D;AAC3D,uCAAoD;AACpD,mGAAuF;AACvF,2EAAuE;AACvE,2EAAwE;AACxE,iHAAiH;AACjH,0FAAqE;AACrE,yDAA4D;AAC5D,wFAAiE;AACjE,qDAA4D;AAC5D,yDAAqD;AACrD,uDAAmC;AACnC,0CAAuC;AACvC,qDAAiD;AACjD,mEAA8D;AAC9D,iDAA6C;AAE7C,MAAM,OAAO,GAAG,aAAK,CAAC,KAAK,CAAC,wBAAU,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAE3D,IAAI,GAA4B,CAAC;AAEjC,6HAA6H;AAC7H,KAAK,UAAU,OAAO,CAAC,IAAsB;IACzC,IAAI,CAAC;QACD,MAAM,IAAI,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO,KAAkB,CAAC;IAC9B,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;AAC7C,CAAC;AACD,IAAA,oBAAS,EAAC,KAAK,IAAI,EAAE;IACjB,OAAM,GAAG,aAAH,GAAG,uBAAH,GAAG,CAAE,IAAI,EAAE,CAAA,CAAC;IAClB,GAAG,GAAG,SAAS,CAAC;AACpB,CAAC,CAAC,CAAC;AAEH,KAAK,UAAU,KAAK,CAAC,MAAM,GAA4B,EAAE;IACrD,mBAAW,CAAC,SAAS,GAAG,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,EAAE,EAAE,CAAC;IACnI,MAAM,SAAS,GAAG,IAAI,qBAAS,CAAC,uBAAgB,EAAE,uBAAc,EAAE,gBAAU,EAAE,IAAA,oBAAQ,GAAE,CAAC,CAAC;IAC1F,GAAG,GAAG,SAAS,CAAC,GAAG,CAAc,kCAAW,CAAC,CAAC;IAC9C,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;IAClB,OAAO,SAAS,CAAC,GAAG,CAAC,2CAAmB,CAAC,CAAC;AAC9C,CAAC;AAED,
|
|
1
|
+
{"version":3,"file":"grpc-server-lifecycle.spec.js","sourceRoot":"","sources":["../../../src/node/server/grpc-server-lifecycle.spec.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/grpc",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.7.0",
|
|
4
4
|
"description": "gRPC servers and clients for Cell over node:http2, with a built-in .proto parser and protobuf codec",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cell-component"
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"watch": "tsc -b -w --preserveWatchOutput"
|
|
34
34
|
},
|
|
35
35
|
"dependencies": {
|
|
36
|
-
"@celljs/core": "4.
|
|
36
|
+
"@celljs/core": "4.7.0"
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
39
39
|
"@grpc/grpc-js": "^1.14.7",
|
|
@@ -41,7 +41,10 @@ async function start(server: Record<string, unknown> = {}) {
|
|
|
41
41
|
return container.get(GrpcServerLifecycle);
|
|
42
42
|
}
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
// Under Bun on Windows this spec hangs before any test ends, past bun's own timeout of a test, so the
|
|
45
|
+
// event loop is blocked (the other specs of this package, servers and clients included, pass there).
|
|
46
|
+
// Its cause is not found yet; it runs on Linux and macOS.
|
|
47
|
+
describe.skipIf(process.platform === 'win32')('GrpcService in an application', () => {
|
|
45
48
|
it('serves the @GrpcService components on the configured port, with their dependencies injected', async () => {
|
|
46
49
|
@Component()
|
|
47
50
|
class Names {
|