外部 Worker SDK
通过 Port 和外部 Adapter,把 Python、JavaScript、Go 或 C/C++ 库接入 Dever。Worker 在独立进程中运行,Dever 负责通信、取消和回收。
应用接入先看 完整示例,无需手写协议或操作注册表。
处理函数
| 语言 | 接口 |
|---|---|
| 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 主进程。
验证
从仓库根执行,指定已准备好的工具绝对路径:
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。