Files

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);

替换为真实服务

  1. 修改 vde-service.json 的 id/name/version/capabilities(capability 用 service: 前缀);
  2. 修改 kServiceId、kOperation 与处理逻辑;保留 request_id/协议校验/错误响应/退出码;
  3. 如输出不止一个文件,按协议扩展 outputs 数组(每个 path 仍需位于工作目录);大文件/流式接口属后续扩展;
  4. 生产实现建议换正式 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 测试钩子,不实现协作式取消。