54 lines
3.3 KiB
Markdown
54 lines
3.3 KiB
Markdown
# 外部 Worker SDK
|
||
|
||
通过 Port 和外部 Adapter，把 Python、JavaScript、Go 或 C/C++ 库接入 Dever。Worker 在独立进程中运行，Dever 负责通信、取消和回收。
|
||
|
||
应用接入先看 [完整示例](../skills/references/external-lib.md)，无需手写协议或操作注册表。
|
||
|
||
## 处理函数
|
||
|
||
| 语言 | 接口 |
|
||
| --- | --- |
|
||
| Python | 异步函数，使用 `Worker.from_manifest(manifest, handlers)` |
|
||
| JavaScript | 接收 AbortSignal，使用 `Worker.fromManifest(manifest, handlers)` |
|
||
| Go | 接收 context.Context，使用 `NewFromManifest` 和 `RegisterHandlers` |
|
||
| C/C++ | 同步 `dever_ffi_handler` 回调，使用 `dever_ffi_serve` |
|
||
|
||
函数名对应 Port 操作名，输入输出及业务错误由编译器生成的接口定义检查。结果按命名字段返回 JSON；业务拒绝使用已声明的 BusinessError。stdout 只用于协议，日志写 stderr。
|
||
|
||
Python/JavaScript/Go 处理函数须响应取消信号。一秒内不退出会使 Worker 停止接收新调用；已取消调用的结果不再交付。自行调用 Go Serve 时，还须解除自己提供的 Reader 阻塞。
|
||
|
||
Worker 调用没有统一的固定倒计时，启动握手、写入和停止清理各自有限时。Worker 不是不可信代码沙箱，文件、网络和设备权限由运行环境管理。
|
||
|
||
## 接口与运行资源
|
||
|
||
编译器通过 `ExternalWorkerContract::sdk_manifest()` 生成接口定义，SDK 在 hello 时核对身份并读取配置。通信为 4 字节大端长度加 UTF-8 JSON；示例中的 fixture-schema-v1 仅用于测试。
|
||
|
||
运行时使用锁定的目标解释器、依赖和 Worker 资源，不借用宿主 PATH。Python 使用 `-I -S -B` 启动，再加载打包的 SDK、Adapter 和依赖。
|
||
|
||
`dever lib install <project>` 恢复已有锁；当前 CLI 不提供 Lib add/update。源码构建及目标运行资源由发行方准备，不能用本机 Python/Node/Go 代替缺失资源。
|
||
|
||
## C/C++
|
||
|
||
使用 `external exec "worker/native" {}`，shim 包含 `c/dever_ffi.h` 并与 `c/dever_ffi.c` 编译为目标平台程序。
|
||
|
||
- ABI 为 DEVER_FFI_ABI_V1。open 初始化一次，invoke 串行处理操作，close 释放状态。
|
||
- operation、setting 和 payload 是当前回调借用的字节或 JSON，不保证 NUL 结尾，不得保留指针。
|
||
- 输出缓冲由 SDK 分配。只写容量以内的数据并设置 size，不替换或释放缓冲。
|
||
- DEVER_FFI_OK 返回结果 JSON；DEVER_FFI_ERROR 返回声明错误及 payload；其他状态作为运行故障。
|
||
- C++ 异常不得跨 C ABI。同步原生调用不保证协作取消，宽限结束后由进程监管终止。
|
||
|
||
原生库须与目标系统 ABI 匹配。它们运行在 Worker 中，不直接加载进 Dever 主进程。
|
||
|
||
## 验证
|
||
|
||
从仓库根执行，指定已准备好的工具绝对路径：
|
||
|
||
```sh
|
||
python3 -B test/external-sdk/check.py --python /path/to/python3 --node /path/to/node --go /path/to/go
|
||
python3 -B test/external-sdk/test_c_ffi.py --cc /path/to/cc
|
||
```
|
||
|
||
未提供的语言会报告 unavailable。SDK 测试验证真实通信和类型，普通应用测试使用 Port fake；后者不证明第三方库可以实际运行。
|
||
|
||
`sdk/python-runtime.py` 可从锁定摘要的 Python Build Standalone 归档准备解释器输入，参数见 `--help`；它不下载资源。脚本验证目标 ELF、glibc、模块及移动后的解释器，并保留许可证，默认 glibc 上限为 2.17。
|