C++ 外部服务模板(echo)
VDE 进程外服务最小可构建模板:C++17、只依赖标准库、不链接 VDE 内核/插件 ABI。 复制本目录即可作为自定义
vde-service服务的起点;把echo处理逻辑替换为真实算法, CLI、响应字段和退出码保持不变。不加入 VDE 默认构建。
目录
| 文件 | 说明 |
|---|---|
vde_service_echo.cpp |
服务实现:JSON 解析、路径校验、--request/--response、响应构造 |
vde-service.json |
服务清单(id/protocol/executable/capabilities/timeouts/sandbox/limits) |
CMakeLists.txt |
独立 CMake 工程;产物目录 <build>/service/ |
README.md |
本文件 |
构建
cmake -S plugins/external/templates/cpp_service -B build/wp-p4-13-template/cpp -G Ninja
cmake --build build/wp-p4-13-template/cpp
# 产物:build/wp-p4-13-template/cpp/service/vde_service_echo.exe + vde-service.json
cmake -S plugins/external/templates/cpp_service -B build/wp-p4-13-template/cpp -G Ninja
cmake --build build/wp-p4-13-template/cpp
直接调用(协议契约)
服务只接受两个参数,request/response 均为 JSON 文件:
vde_service_echo --request request.json --response response.json
请求示例(request.json):
{
"protocol": "vde-service/0.1",
"request_id": "echo-1",
"operation": "echo",
"input": "D:/tmp/work/input.txt",
"output": "D:/tmp/work/output.txt",
"args": { "message": "hello", "sleep_ms": 0 }
}
成功响应(response.json):
{
"protocol": "vde-service/0.1",
"request_id": "echo-1",
"status": "ok",
"service_id": "com.vde.template.echo.cpp",
"outputs": [{ "path": "output.txt", "format": "text", "role": "result" }],
"metrics": { "bytes_in": 12, "bytes_out": 12 },
"diagnostics": ["template echo service: replace 'echo' with real processing"]
}
input可选:存在时按二进制复制到output;否则写入args.message(默认一句模板提示);output必须位于request.json所在目录内(拒绝..与目录外路径);- 响应
outputs[].path固定返回文件名(相对 request 目录),因此同一响应在 直接进程模式与容器模式(宿主工作目录挂载到/vde/work)下都能通过宿主 outputs 白名单校验; args.sleep_ms是测试钩子,用于验证 runner/宿主的超时强制终止,生产请求不要使用;- 退出码:
0成功、2用法错误、3协议/校验错误、5输入输出失败。
错误响应示例:
{ "protocol": "vde-service/0.1", "request_id": "echo-1", "status": "error",
"service_id": "com.vde.template.echo.cpp", "code": "unsupported_operation",
"message": "only 'echo' is supported, got 'solve'" }
宿主 / runner 调用
# runner(需可构建的 C++17 工具链;本工作树 MinGW 8.1 的 <filesystem> 头不可用,见下)
vde_service_runner --list build/wp-p4-13-template/cpp
vde_service_runner --run --manifest build/wp-p4-13-template/cpp/service/vde-service.json \
--request request.json --timeout-ms 15000
vde::plugin::ExternalServiceInvokeOptions opts;
opts.timeout_ms = 15000;
vde::plugin::ExternalServiceResult r;
std::string err;
const bool ok = pm.invoke_external_service("com.vde.template.echo.cpp", request_json, opts, &r, &err);
替换为真实服务
- 修改
vde-service.json的id/name/version/capabilities(capability 用service:前缀); - 修改
kServiceId、kOperation与处理逻辑;保留request_id/协议校验/错误响应/退出码; - 如输出不止一个文件,按协议扩展
outputs数组(每个 path 仍需位于工作目录);大文件/流式接口属后续扩展; - 生产实现建议换正式 JSON 库并做 schema 校验(本模板内置的解析器只覆盖协议所需子集)。
容器模式
容器清单示例见 ../container/vde-service.cpp.container.json,镜像构建命令见
../README.md 与 ../container/Dockerfile.cpp。容器内入口为 /opt/vde/vde_service_echo,
请求中的 input/output 使用 /vde/work/... 路径;响应仍返回文件名。
已知限制
- 本模板只做
echo,不含真实几何/求解算法; - 不使用
<filesystem>是有意为之(兼容旧 MinGW/GCC 8.1 的模板构建);复杂路径处理请自行引入; - 超时终止由 runner/宿主负责;服务侧只提供
sleep_ms测试钩子,不实现协作式取消。