@syllm/brickly-test-host 0.11.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.md +74 -0
- package/dist/host.cjs +40816 -0
- package/dist/index.cjs +40848 -0
- package/dist/sources.lst +233 -0
- package/index.d.ts +93 -0
- package/package.json +31 -0
package/README.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# @syllm/brickly-test-host
|
|
2
|
+
|
|
3
|
+
Brickly **真宿主测试工件**：把生产级 `HostGrpcServer`（含真 BrickStorageService 内存版）+ 测试控制面打成零依赖单文件 bundle，供各端 SDK 的契约 / conformance 测试使用。
|
|
4
|
+
|
|
5
|
+
- 协议：`brickly.runtime.v1`，版本号与 SDK 发布线对齐（0.11.0 起）
|
|
6
|
+
- 定位：替代各端手写 FakeHost 的"演好人"职责；SDK 单测仍需假宿主做低层故障注入时，可继续用本包的控制面故障注入（`SetNextError` 语义）
|
|
7
|
+
|
|
8
|
+
## 交付物
|
|
9
|
+
|
|
10
|
+
`npm i -D @syllm/brickly-test-host` 后得到：
|
|
11
|
+
|
|
12
|
+
| 文件 | 用途 |
|
|
13
|
+
|------|------|
|
|
14
|
+
| `dist/host.cjs` | 独立宿主进程入口（bin：`brickly-test-host`），零 npm 依赖，Node ≥18 即可运行 |
|
|
15
|
+
| `dist/index.cjs` | Node 库入口：`startTestHost`（进程内）/ `spawnTestHost`（子进程） |
|
|
16
|
+
| `dist/sources.lst` | bundle 输入文件清单（可追溯打进来的源码） |
|
|
17
|
+
|
|
18
|
+
## 跨语言用法（Go / .NET / Python 等）
|
|
19
|
+
|
|
20
|
+
### 1. spawn 协议
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
node node_modules/@syllm/brickly-test-host/dist/host.cjs
|
|
24
|
+
# 或安装后：npx brickly-test-host
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- **stdout 首行**输出就绪 JSON：
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{"dataEndpoint":"127.0.0.1:50051","controlEndpoint":"127.0.0.1:50052","runtimeToHostToken":"..."}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- **关闭**：stdin 结束 或 SIGINT/SIGTERM → 宿主优雅退出
|
|
34
|
+
- `dataEndpoint` 是 gRPC 数据面；`runtimeToHostToken` 是 SDK 连接宿主要带的运行时凭据
|
|
35
|
+
|
|
36
|
+
### 2. 控制面 HTTP（仅 127.0.0.1）
|
|
37
|
+
|
|
38
|
+
| 方法 | 路径 | 请求体 | 说明 |
|
|
39
|
+
|------|------|--------|------|
|
|
40
|
+
| POST | `/faults` | `{path, brickCode, message?, count?}` | 故障注入：命中 `path` 的下 `count` 次调用（默认 1）短路返回该 brick 错误，**无副作用**（真 handler 不执行） |
|
|
41
|
+
| POST | `/reset` | `{}` | 清空故障规则与调用录制（不清 storage 数据） |
|
|
42
|
+
| GET | `/calls` | — | `{"calls":[{"path","at"}]}` 调用录制 |
|
|
43
|
+
|
|
44
|
+
`path` 为完整 gRPC 方法路径，如 `/brickly.runtime.v1.BrickStorageService/KvGet`；
|
|
45
|
+
`brickCode` 为协议错误码，如 `BRICK_STORAGE_NOT_FOUND`、`LIMIT_EXCEEDED`。
|
|
46
|
+
|
|
47
|
+
### 3. 探针参考实现
|
|
48
|
+
|
|
49
|
+
`check/` 目录有 Go / .NET / Python 的最小探针（spawn → 就绪行 → `/calls` → `/reset`），可直接照抄到各独立仓库。
|
|
50
|
+
|
|
51
|
+
## Node 用法
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { spawnTestHost } from '@syllm/brickly-test-host'
|
|
55
|
+
|
|
56
|
+
const host = await spawnTestHost() // 拉起子进程
|
|
57
|
+
const client = new HostBrickStorageClient(host.dataEndpoint, host.runtimeToHostToken)
|
|
58
|
+
|
|
59
|
+
await host.setFault({ path: '/brickly.runtime.v1.BrickStorageService/KvSet', brickCode: 'LIMIT_EXCEEDED' })
|
|
60
|
+
const calls = await host.recordedCalls()
|
|
61
|
+
await host.reset()
|
|
62
|
+
await host.close() // 关 stdin，等退出（超时自动 SIGKILL）
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
进程内装配（不需要子进程隔离时）：`startTestHost()` 返回 `{ host, control, endpoint, spawnCredentials, close }`。
|
|
66
|
+
|
|
67
|
+
## 本地验证
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
npm run check --workspace @syllm/brickly-test-host
|
|
71
|
+
# 或仓库根：npm run test-host:check
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
执行：构建 bundle → Node 库自检 → Node spawn+gRPC 全链路 → Go/.NET/Python spawn 探针（工具链缺失则跳过该项）。
|