From fedee6d03afed1336b20568c50a071f223ce1773 Mon Sep 17 00:00:00 2001 From: retoor Date: Sat, 24 Oct 2026 04:31:12 +0200 Subject: [PATCH] feat(clients): runtime: Agent Engine reasoningEngines client, discovery-checked call table, typed deployment spec, demo routes Co-Authored-By: Claude Sonnet 5.5 --- example/app/agent/RuntimeDemo.cpp | 328 +++++++++++++++++- example/assets/agent_runtime.js | 44 +++ src/google/runtime/SPEC.md | 136 ++++++++ src/google/runtime/agent_runtime.cpp | 307 ++++++++++++++++ src/google/runtime/agent_runtime.h | 112 ++++++ src/google/runtime/calls.cpp | 92 +++++ src/google/runtime/calls.h | 45 +++ src/google/runtime/caps.h | 29 ++ src/google/runtime/deployment_spec.cpp | 324 +++++++++++++++++ src/google/runtime/deployment_spec.h | 92 +++++ src/google/runtime/engine.cpp | 128 +++++++ src/google/runtime/engine.h | 54 +++ src/google/runtime/tools/check_discovery.py | 97 ++++++ tests/example/agent/runtime/create_test.cpp | 21 ++ tests/example/agent/runtime/delete_test.cpp | 20 ++ tests/example/agent/runtime/get_test.cpp | 18 + tests/example/agent/runtime/list_test.cpp | 19 + .../example/agent/runtime/operation_test.cpp | 21 ++ tests/example/agent/runtime/page_test.cpp | 18 + tests/example/agent/runtime/query_test.cpp | 20 ++ tests/example/agent/runtime/status_test.cpp | 24 ++ tests/src/google/runtime/test_runtime.cpp | 316 +++++++++++++++++ 22 files changed, 2262 insertions(+), 3 deletions(-) create mode 100644 example/assets/agent_runtime.js create mode 100644 src/google/runtime/SPEC.md create mode 100644 src/google/runtime/agent_runtime.cpp create mode 100644 src/google/runtime/agent_runtime.h create mode 100644 src/google/runtime/calls.cpp create mode 100644 src/google/runtime/calls.h create mode 100644 src/google/runtime/caps.h create mode 100644 src/google/runtime/deployment_spec.cpp create mode 100644 src/google/runtime/deployment_spec.h create mode 100644 src/google/runtime/engine.cpp create mode 100644 src/google/runtime/engine.h create mode 100644 src/google/runtime/tools/check_discovery.py create mode 100644 tests/example/agent/runtime/create_test.cpp create mode 100644 tests/example/agent/runtime/delete_test.cpp create mode 100644 tests/example/agent/runtime/get_test.cpp create mode 100644 tests/example/agent/runtime/list_test.cpp create mode 100644 tests/example/agent/runtime/operation_test.cpp create mode 100644 tests/example/agent/runtime/page_test.cpp create mode 100644 tests/example/agent/runtime/query_test.cpp create mode 100644 tests/example/agent/runtime/status_test.cpp create mode 100644 tests/src/google/runtime/test_runtime.cpp diff --git a/example/app/agent/RuntimeDemo.cpp b/example/app/agent/RuntimeDemo.cpp index 112d57c..e26d8c4 100644 --- a/example/app/agent/RuntimeDemo.cpp +++ b/example/app/agent/RuntimeDemo.cpp @@ -1,13 +1,335 @@ #include "../AgentDemos.hpp" +#include + #include "../../fw/Router.hpp" +#include "../../fw/Templates.hpp" +#include "google/resource.h" +#include "google/runtime/agent_runtime.h" +#include "google/runtime/calls.h" +#include "google/runtime/caps.h" namespace molo::example::app { -// Agent Platform: runtime. Stub: the module agent fills this in. +// Agent Platform: Agent Runtime (Agent Engine, reasoningEngines) over the +// real src/google/runtime part. GET routes need no credential. Every route +// that calls Google is a POST: 503 google_not_configured without a +// credential, 422 on bad input. Create never waits (deployments can take +// long): it answers the operation name; poll it with /agent/runtime/operation. +// Delete is a dry run unless the body says "confirm":true. + +namespace { + +namespace rt = google::runtime; +using Json = clients::body::Json; + +constexpr std::size_t kMaxBody = 256 * 1024; +constexpr std::size_t kMaxStreamEventsShown = 100; + +const char kPage[] = R"RUNTIME({% extends "base.html" %} +{% block content %} +

Agent Runtime

+

Deploy and call agents on Agent Engine (reasoningEngines). +Lists and queries only; create and delete stay behind explicit calls.

+

Checking Google credentials...

+
+ +
+ + +
+ + +
+ + +
+ +

+
+ + +{% endblock %} +)RUNTIME"; + +std::string quote(const std::string& s) { return "\"" + fw::json_escape(s) + "\""; } + +fw::Response json_out(const Json& j, int status = 200) { + fw::Response res = fw::JsonResponse(j.dump(), status); + res.headers.set("Cache-Control", "no-store"); + return res; +} + +[[noreturn]] void rethrow(const google::GoogleError& e) { + if (e.http_status() == 503 && e.status() == "NOT_CONFIGURED") + throw fw::HttpError(503, "google_not_configured", e.message()); + if (e.service().empty() && e.status() == "INVALID_ARGUMENT") + throw fw::HttpError(422, "validation_error", e.message()); + throw fw::HttpError(502, "google_error", e.status() + ": " + e.message()); +} + +template +auto guarded(F&& f) -> decltype(f()) { + try { + return f(); + } catch (const google::GoogleError& e) { + rethrow(e); + } +} + +[[noreturn]] void bad(const std::string& why) { + throw fw::HttpError(422, "validation_error", why); +} + +Json parse_body(const fw::Request& req) { + if (req.body.size() > kMaxBody) throw fw::HttpError(413, "payload_too_large", "body too large"); + if (req.body.empty()) return Json::object(); + try { + Json j = Json::parse(req.body); + if (!j.is_object()) bad("body must be a JSON object"); + return j; + } catch (const clients::body::JsonError&) { + bad("body is not valid JSON"); + } +} + +std::string text(const Json& body, const char* key, bool required = false) { + const Json* v = body.find(key); + if (!v || v->is_null()) { + if (required) bad(std::string(key) + " is required"); + return ""; + } + if (!v->is_string()) bad(std::string(key) + " must be a string"); + return v->as_string(); +} + +std::optional number(const Json& body, const char* key) { + const Json* v = body.find(key); + if (!v || v->is_null()) return std::nullopt; + if (!v->is_number()) bad(std::string(key) + " must be a number"); + return static_cast(v->as_int()); +} + +std::string engine_id(const Json& body) { + std::string id = text(body, "id", true); + if (!google::valid_segment(id)) bad("id must be 1-128 chars of A-Z a-z 0-9 . _ -"); + return id; +} + +Json engine_summary(const rt::Engine& e) { + Json o = Json::object(); + o.set("name", Json(e.name)); + o.set("id", Json(e.id())); + o.set("displayName", Json(e.display_name)); + o.set("createTime", Json(e.create_time)); + o.set("updateTime", Json(e.update_time)); + o.set("agentFramework", Json(e.spec.agent_framework)); + return o; +} + +Json operation_json(const google::Operation& op) { + Json o = Json::object(); + o.set("operation", Json(op.name)); + o.set("done", Json(op.done)); + if (op.failed()) o.set("error", Json(op.error_message)); + if (op.done && op.response.is_object()) o.set("response", op.response); + return o; +} + +rt::EngineDraft draft_from(const Json& body) { + rt::EngineDraft d; + d.display_name = text(body, "displayName", true); + d.description = text(body, "description"); + d.spec.agent_framework = text(body, "agentFramework"); + std::string image = text(body, "imageUri"); + if (!image.empty()) d.spec.container = rt::ContainerSpec{image, std::nullopt}; + std::string identity = text(body, "identityType"); + if (!identity.empty()) { + if (identity != "SERVICE_ACCOUNT" && identity != "AGENT_IDENTITY") + bad("identityType must be SERVICE_ACCOUNT or AGENT_IDENTITY"); + d.spec.identity = rt::identity_type_from(identity); + } + d.spec.service_account = text(body, "serviceAccount"); + rt::DeploymentSpec dep; + bool has_dep = false; + if (auto n = number(body, "minInstances")) { dep.min_instances = n; has_dep = true; } + if (auto n = number(body, "maxInstances")) { dep.max_instances = n; has_dep = true; } + dep.cpu = text(body, "cpu"); + dep.memory = text(body, "memory"); + if (!dep.cpu.empty() || !dep.memory.empty()) has_dep = true; + if (has_dep) d.spec.deployment = dep; + try { + d.validate(); // local rules first: 422 before any credential check + } catch (const google::GoogleError& e) { + rethrow(e); + } + return d; +} + +} // namespace + void register_agent_runtime_demo(fw::Router& router, Services& services) { - (void)router; - (void)services; + if (!services.google) services.google = google::GoogleClient::from_env(); + auto client = services.google; + fw::Environment* env = services.templates.get(); + services.templates->add_template("agent_runtime.html", kPage); + services.add_feature("agent-runtime", "/agent/runtime"); + + // Fresh per request so the environment is read when the call happens. + auto runtime = [client]() { + if (!client->configured()) throw google::NotConfiguredError("aiplatform"); + return rt::AgentRuntime(client, google::CloudContext::from_env()); + }; + + router.get("/agent/runtime", "agent-runtime-page", [env](fw::Request req) { + (void)req; + fw::TemplateCtx ctx; + ctx["title"] = std::string("Agent Runtime"); + return fw::Response(200, env->render("agent_runtime.html", ctx), "text/html; charset=utf-8"); + }); + + router.get("/agent/runtime/status", "agent-runtime-status", [client](fw::Request req) { + (void)req; + google::CloudContext ctx = google::CloudContext::from_env(); + Json o = Json::object(); + o.set("configured", Json(client->configured())); + o.set("project_set", Json(!ctx.project.empty())); + o.set("location", Json(ctx.location)); + o.set("max_stream_events", Json(static_cast(kMaxStreamEventsShown))); + return json_out(o); + }); + + // The discovery-checked call table, for humans. + router.get("/agent/runtime/calls", "agent-runtime-calls", [](fw::Request req) { + (void)req; + Json arr = Json::array(); + for (int c = static_cast(rt::Call::kCreate); c <= static_cast(rt::Call::kRevisionStreamQuery); ++c) { + const rt::CallSpec& s = rt::spec_of(static_cast(c)); + Json row = Json::object(); + row.set("http", Json(s.http_method)); + row.set("path", Json(s.path)); + row.set("version", Json(s.version)); + row.set("rpc", Json(s.rpc_id)); + arr.push(row); + } + Json o = Json::object(); + o.set("calls", arr); + return json_out(o); + }); + + router.post("/agent/runtime/list", "agent-runtime-list", [runtime](fw::Request req) { + Json body = parse_body(req); + std::string filter = text(body, "filter"); + if (filter.size() > rt::RuntimeCaps::kMaxFilterChars) bad("filter too long"); + return guarded([&] { + Json arr = Json::array(); + for (const auto& e : runtime().list(filter)) arr.push(engine_summary(e)); + Json o = Json::object(); + o.set("engines", arr); + return json_out(o); + }); + }); + + router.post("/agent/runtime/get", "agent-runtime-get", [runtime](fw::Request req) { + Json body = parse_body(req); + std::string id = engine_id(body); + return guarded([&] { return json_out(runtime().get(id).raw); }); + }); + + router.post("/agent/runtime/create", "agent-runtime-create", [runtime](fw::Request req) { + Json body = parse_body(req); + rt::EngineDraft draft = draft_from(body); + return guarded([&] { return json_out(operation_json(runtime().create_start(draft)), 202); }); + }); + + router.post("/agent/runtime/operation", "agent-runtime-operation", [runtime](fw::Request req) { + Json body = parse_body(req); + std::string name = text(body, "name", true); + if (name.rfind("projects/", 0) != 0 || name.size() > 512 || name.find("..") != std::string::npos) + bad("name must be an operation name starting with projects/"); + return guarded([&] { return json_out(operation_json(runtime().operation(name))); }); + }); + + auto query_args = [](const Json& body, std::string& id, Json& input, std::string& method) { + id = engine_id(body); + const Json* in = body.find("input"); + input = in && in->is_object() ? *in : Json::object(); + if (in && !in->is_object() && !in->is_null()) bad("input must be a JSON object"); + method = text(body, "classMethod"); + if (!method.empty()) { + try { + rt::AgentRuntime::query_body(input, method); // validates method and size + } catch (const google::GoogleError& e) { + rethrow(e); + } + } + }; + + router.post("/agent/runtime/query", "agent-runtime-query", [runtime, query_args](fw::Request req) { + Json body = parse_body(req); + std::string id, method; + Json input; + query_args(body, id, input, method); + return guarded([&] { + auto r = runtime(); + return json_out(method.empty() ? r.query(id, input) : r.query(id, input, method)); + }); + }); + + // Streams server side, answers the first events as one JSON array. + router.post("/agent/runtime/stream", "agent-runtime-stream", [runtime, query_args](fw::Request req) { + Json body = parse_body(req); + std::string id, method; + Json input; + query_args(body, id, input, method); + return guarded([&] { + auto r = runtime(); + Json events = Json::array(); + auto sink = [&](const Json& e) { + events.push(e); + return events.as_array().size() < kMaxStreamEventsShown; + }; + if (method.empty()) r.stream_query(id, input, sink); + else r.stream_query(id, input, sink, method); + Json o = Json::object(); + o.set("events", events); + return json_out(o); + }); + }); + + router.post("/agent/runtime/async", "agent-runtime-async", [runtime](fw::Request req) { + Json body = parse_body(req); + std::string id = engine_id(body); + std::string in = text(body, "inputGcsUri", true), out = text(body, "outputGcsUri", true); + if (in.rfind("gs://", 0) != 0 || out.rfind("gs://", 0) != 0) + bad("inputGcsUri and outputGcsUri must be gs:// URIs"); + return guarded([&] { return json_out(operation_json(runtime().async_query(id, in, out)), 202); }); + }); + + // Destructive: a dry run unless "confirm":true; force is its own field. + router.post("/agent/runtime/delete", "agent-runtime-delete", [runtime](fw::Request req) { + Json body = parse_body(req); + std::string id = engine_id(body); + const Json* f = body.find("force"); + if (f && !f->is_bool()) bad("force must be true or false"); + const Json* c = body.find("confirm"); + if (c && !c->is_bool()) bad("confirm must be true or false"); + bool force = f && f->as_bool(); + if (!(c && c->as_bool())) { + Json o = Json::object(); + o.set("dry_run", Json(true)); + o.set("would_delete", Json(id)); + o.set("force", Json(force)); + o.set("hint", Json("send confirm:true to delete")); + return json_out(o); + } + return guarded([&] { return json_out(operation_json(runtime().destroy_start(id, force)), 202); }); + }); } } // namespace molo::example::app diff --git a/example/assets/agent_runtime.js b/example/assets/agent_runtime.js new file mode 100644 index 0000000..1ff8756 --- /dev/null +++ b/example/assets/agent_runtime.js @@ -0,0 +1,44 @@ +// Agent Runtime page: thin client over /agent/runtime/* (all limits server side). +(function () { + "use strict"; + var $ = function (id) { return document.getElementById(id); }; + var out = $("rt-out"), err = $("rt-error"); + + function post(path, body) { + err.textContent = ""; + out.textContent = "..."; + return fetch(path, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body) + }).then(function (res) { + return res.text().then(function (t) { + var j; + try { j = JSON.parse(t); } catch (e) { j = { message: t }; } + if (!res.ok) { + err.textContent = j.message || ("HTTP " + res.status); + out.textContent = ""; + } else { + out.textContent = JSON.stringify(j, null, 2); + } + }); + }).catch(function (e) { err.textContent = String(e); out.textContent = ""; }); + } + function queryBody() { + var input; + try { input = JSON.parse($("rt-input").value || "{}"); } + catch (e) { err.textContent = "Input is not valid JSON"; return null; } + return { id: $("rt-id").value.trim(), input: input, classMethod: $("rt-method").value.trim() }; + } + + fetch("/agent/runtime/status").then(function (r) { return r.json(); }).then(function (s) { + $("rt-config").textContent = s.configured + ? "Google credential found. Location " + s.location + (s.project_set ? "." : "; set GOOGLE_CLOUD_PROJECT.") + : "No Google credential: calls answer 503 until one is configured."; + }); + + $("rt-list").onclick = function () { post("/agent/runtime/list", {}); }; + $("rt-get").onclick = function () { post("/agent/runtime/get", { id: $("rt-id").value.trim() }); }; + $("rt-query").onclick = function () { var b = queryBody(); if (b) post("/agent/runtime/query", b); }; + $("rt-stream").onclick = function () { var b = queryBody(); if (b) post("/agent/runtime/stream", b); }; +})(); diff --git a/src/google/runtime/SPEC.md b/src/google/runtime/SPEC.md new file mode 100644 index 0000000..eb3868c --- /dev/null +++ b/src/google/runtime/SPEC.md @@ -0,0 +1,136 @@ +# Agent Runtime (Agent Engine) - Specification + +Owned directory: `src/google/runtime/`. Namespace `molo::google::runtime`. +Depends on the `src/google` foundation (`GoogleClient`, `Service`, +`operation.h`, `resource.h`). Plan: `plans/16-agent-platform.md`. + +## 1. Scope + +The `reasoningEngines` resource on `aiplatform.googleapis.com`: create, get, +list, patch, delete, query, streamQuery, asyncQuery, cancelAsyncQuery, +executeCode, IAM (get, set, test), the engine's `operations`, and runtime +revisions (v1beta1: get, list, delete, query, streamQuery). Typed deployment +spec (package, container, source, env, secret env, scaling, resource limits, +service account or agent identity, build spec, KMS key). Unknown fields stay +raw Json and are sent back unchanged. + +Not here: sessions, memories, sandboxes (other modules), A2A endpoints +(`a2a`, `a2aTasks`, owner: adk), `examples` and `feedbackEntries` (v1beta1, +not implemented, see Gaps). + +## 2. Module map + +| File | Concern | +|---|---| +| `caps.h` | Static ceilings (`RuntimeCaps`) | +| `calls.h/.cpp` | The ONE table of REST calls (`kCalls`) and used schema fields (`kSchemas`); `render`, `method_of`, `endpoint_of` | +| `deployment_spec.h/.cpp` | `EngineSpec`, `DeploymentSpec`, `PackageSpec`, `ContainerSpec`, `SourceCodeSpec`, `IdentityType` (validate, to/from Json, updateMask parts) | +| `engine.h/.cpp` | `Engine` (response), `EngineDraft` (create), `EngineUpdate` (patch with derived `updateMask`) | +| `agent_runtime.h/.cpp` | `AgentRuntime : Service`, `Revision` | +| `tools/check_discovery.py` | Fails when any row of the call table or schema table is absent from Google's Discovery documents | + +## 3. Static caps + +| Knob | Value | +|---|---| +| displayName / description | 128 / 1000 chars | +| labels, key and value | 64, 63 chars | +| env + secret env variables | 100, value 4096 chars | +| minInstances / maxInstances | 0..75 / 1..1000 (Google ranges), min <= max | +| containerConcurrency | 1..1000 | +| cpu / memory | 1,2,4,6,8 / 1Gi..32Gi (Google "only supported values") | +| query input / execute inputs / policy | 1 MiB serialized | +| classMethod | 1..64 of `[A-Za-z0-9_]` | +| list filter | 512 chars; page size 50, 20 pages max | +| stream events delivered | 5000 (example route: 100) | +| updateMask | 512 chars | +| wait for an operation | 600 s / 400 polls (`operation.h`), multi-day work uses `*_start` plus `operation()` | +| ids | `valid_segment`; operation names must start `projects/`, no `..` or `?` | + +## 4. Contracts + +- Every URL comes from `kCalls`; no path literal elsewhere. +- Input is validated before any network traffic; invalid input is + `GoogleError` 400 `INVALID_ARGUMENT`. No credential: `NotConfiguredError`. +- `create`, `update`, `destroy` wait via `wait_operation`; `*_start` return + the `Operation`. `create` finishes with a `get` of the new engine. +- Destructive calls are `destroy`/`destroy_start`/`destroy_revision`; `force` + has no default. The example `delete` route is a dry run unless + `"confirm":true`. +- `identityType AGENT_IDENTITY` rejects a `serviceAccount` (documented rule). +- `effectiveIdentity` is output only and never sent. +- `streamQuery` is read through `GoogleClient::stream_json` (plain JSON or SSE). +- Triggers: Google exposes no API that wires BigQuery or Pub/Sub events to an + engine. The real surface for batch is `asyncQuery`/`cancelAsyncQuery` + (Cloud Storage in and out, long-running, implemented). Event-driven use is + a pattern only: Eventarc or a Pub/Sub push subscription calls + `reasoningEngines.query` through a Cloud Run or Workflows target. Nothing + is implemented for it; this is not an API of this part. + +## 5. Example routes (`/agent/runtime`) + +GET `/agent/runtime` (page), `/status`, `/calls` (the call table). POST +`/list`, `/get`, `/create` (starts, answers 202 and the operation name), +`/operation`, `/query`, `/stream`, `/async`, `/delete`. No credential: 503 +`google_not_configured`; bad input: 422; oversize body: 413. + +## Sources + +- Discovery documents, fetched 2026-10-24 (revision 20261012 for both): + `https://aiplatform.googleapis.com/$discovery/rest?version=v1` and + `?version=v1beta1`. +- `https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest/v1/projects.locations.reasoningEngines` + and its `query`, `streamQuery`, `create`, `delete`, `list`, `patch`, + `asyncQuery`, `cancelAsyncQuery` pages (semantics, defaults, ranges). +- Web search for Eventarc/Pub/Sub/BigQuery triggers for Agent Engine: no + Agent Engine target found (Eventarc targets Cloud Run, Functions, GKE, + Workflows). + +## Verified against discovery + +`python3 -I src/google/runtime/tools/check_discovery.py`, run 2026-10-24: +`discovery ok: 22 calls, 20 schemas, revisions v1 20261012, v1beta1 20261012`. +Checks HTTP method, path, rpc id, query parameters, request body fields and +every schema field the code reads or writes. Findings it caught or confirmed: +revision list items key is `reasoningEngineRuntimeRevisions` (not +`runtimeRevisions`), v1 `setIamPolicy` takes only `policy`, secret env uses +`secretRef{secret,version}`. + +## Verified live + +2026-10-24, express key (`AQ.`), project from `GOOGLE_CLOUD_PROJECT`, +read-only (`MOLO_LIVE_NET=1`, test `runtime_live.read_only_calls`): + +| Call | Result | +|---|---| +| `GET .../locations/us-central1/reasoningEngines` | 200, 0 engines | +| `GET .../locations/europe-west4/reasoningEngines` | 200, 0 engines | +| `GET .../reasoningEngines/1234567890123` | 404 NOT_FOUND | +| `POST .../reasoningEngines/1234567890123:query` | 404 NOT_FOUND | +| `GET .../reasoningEngines/molo-does-not-exist` | 400 INVALID_ARGUMENT (ids are numeric) | + +Everything else (create, patch, delete, streamQuery, asyncQuery, executeCode, +IAM, operations, revisions) is verified by discovery only: no OAuth token is +available and no resource may be created. Rerun: +`MOLO_LIVE_NET=1 GOOGLE_CLOUD_PROJECT=... GOOGLE_API_KEY=... make google-test`. + +## Unverified + +- Whether the create/patch operation `response` is a `ReasoningEngine` with + `name` (discovery types it as `Any`; `create` fails loudly with 502 + `BAD_RESPONSE` if no name is present). +- The streamQuery wire format (discovery: `HttpBody`; decoded as plain JSON + or SSE by the foundation decoder). +- Nested `updateMask` names such as `spec.deploymentSpec` (FieldMask dotted + syntax per docs; not exercised, no write credential). +- That an express key can call any mutating method (list/get/query do work). +- `executeCode` chunk shape (`Chunk`) is passed through as raw Json. + +## Gaps + +- v1beta1 `examples`, `feedbackEntries` and `a2a*` resources are not typed + here (A2A belongs to adk). +- `trafficConfig`, `revisionGarbageCollectionStrategy` (v1beta1 engine + fields) travel as raw `extra` only on the v1beta1 revision path; the v1 + `Engine` does not carry them. +- No OAuth refresh (foundation gap). diff --git a/src/google/runtime/agent_runtime.cpp b/src/google/runtime/agent_runtime.cpp new file mode 100644 index 0000000..9fd3863 --- /dev/null +++ b/src/google/runtime/agent_runtime.cpp @@ -0,0 +1,307 @@ +#include "google/runtime/agent_runtime.h" + +#include + +#include "clients/url.h" +#include "google/errors.h" +#include "google/runtime/caps.h" + +namespace molo::google::runtime { + +using clients::body::Json; + +namespace { + +void check_method(const std::string& m) { + if (m.empty() || m.size() > RuntimeCaps::kMaxMethodChars) + throw GoogleError::invalid("bad classMethod"); + for (char c : m) + if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || + c == '_')) + throw GoogleError::invalid("bad classMethod"); +} + +void check_gcs(const std::string& uri, const char* what) { + if (uri.rfind("gs://", 0) != 0 || uri.size() <= 5 || + uri.size() > RuntimeCaps::kMaxUriChars) + throw GoogleError::invalid(std::string(what) + " must be a gs:// URI"); + for (char c : uri) + if (static_cast(c) <= 0x20) throw GoogleError::invalid("bad gs:// URI"); +} + +void check_size(const Json& j, const char* what) { + if (j.dump().size() > RuntimeCaps::kMaxInputBytes) + throw GoogleError::invalid(std::string(what) + " too large"); +} + +std::string enc(const std::string& s) { return clients::Url::encode_component(s); } + +} // namespace + +Revision Revision::from_json(const Json& doc) { + Revision r; + r.raw = doc; + if (!doc.is_object()) return r; + auto s = [&](const char* k) { + const Json* v = doc.find(k); + return v && v->is_string() ? v->as_string() : std::string(); + }; + r.name = s("name"); + r.state = s("state"); + r.create_time = s("createTime"); + if (const Json* sp = doc.find("spec")) r.spec = EngineSpec::from_json(*sp); + return r; +} + +AgentRuntime::AgentRuntime(std::shared_ptr client, CloudContext context, + Sleeper sleeper) + : Service(std::move(client), endpoints::aiplatform(context.location)), + context_(std::move(context)), + sleeper_(std::move(sleeper)) {} + +std::string AgentRuntime::name_of(const std::string& id) const { + return context_.child("reasoningEngines", id); +} + +std::string AgentRuntime::revision_of(const std::string& id, const std::string& revision) const { + if (!valid_segment(revision)) throw GoogleError::invalid("bad revision id"); + return name_of(id) + "/runtimeRevisions/" + revision; +} + +std::string AgentRuntime::checked_operation(const std::string& name) { + if (name.rfind("projects/", 0) != 0 || name.size() > 512 || + name.find("..") != std::string::npos || name.find('?') != std::string::npos) + throw GoogleError::invalid("bad operation name"); + return name; +} + +Json AgentRuntime::send(Call call, const std::string& target, const std::string& query, + const Json* body) const { + std::string path = render(call, target) + query; + return client_->request(method_of(call), endpoint_of(call, context_.location), path, body); +} + +std::size_t AgentRuntime::stream_call(Call call, const std::string& target, const Json& body, + const GoogleClient::EventSink& sink) const { + std::size_t n = 0; + client_->stream_json(endpoint_of(call, context_.location), render(call, target), body, + [&](const Json& event) { + ++n; + bool more = sink(event); + return more && n < RuntimeCaps::kMaxStreamEvents; + }); + return n; +} + +Json AgentRuntime::list_items(Call call, const std::string& parent, const std::string& key, + const std::string& filter) const { + if (filter.size() > RuntimeCaps::kMaxFilterChars) throw GoogleError::invalid("filter too long"); + std::string path = render(call, parent) + "?pageSize=50"; + if (!filter.empty()) path += "&filter=" + enc(filter); + return list_all(*client_, endpoint_of(call, context_.location), path, key, + RuntimeCaps::kMaxListPages); +} + +Operation AgentRuntime::finish(Operation op) const { + if (!op.done) return wait_operation(*client_, endpoint_, checked_operation(op.name), sleeper_); + if (op.failed()) throw GoogleError(502, "OPERATION_FAILED", op.error_message, endpoint_.name); + return op; +} + +Engine AgentRuntime::engine_from(const Operation& op) const { + if (op.response.is_object()) { + Engine e = Engine::from_json(op.response); + if (!e.name.empty()) return get(e.id()); + } + throw GoogleError(502, "BAD_RESPONSE", "operation finished without an engine name", + endpoint_.name); +} + +// --- engines --------------------------------------------------------------- + +Operation AgentRuntime::create_start(const EngineDraft& draft) const { + Json body = draft.to_json(); + return Operation::from_json(send(Call::kCreate, context_.parent(), "", &body)); +} + +Engine AgentRuntime::create(const EngineDraft& draft) const { + return engine_from(finish(create_start(draft))); +} + +Engine AgentRuntime::get(const std::string& id) const { + return Engine::from_json(send(Call::kGet, name_of(id))); +} + +std::vector AgentRuntime::list(const std::string& filter) const { + Json items = list_items(Call::kList, context_.parent(), "reasoningEngines", filter); + std::vector out; + for (const Json& j : items.as_array()) out.push_back(Engine::from_json(j)); + return out; +} + +Operation AgentRuntime::update_start(const std::string& id, const EngineUpdate& update) const { + std::string name = name_of(id); + Json body = update.to_json(); + body.set("name", Json(name)); + return Operation::from_json( + send(Call::kPatch, name, "?updateMask=" + enc(update.update_mask()), &body)); +} + +Engine AgentRuntime::update(const std::string& id, const EngineUpdate& update_in) const { + finish(update_start(id, update_in)); + return get(id); +} + +Operation AgentRuntime::destroy_start(const std::string& id, bool force) const { + return Operation::from_json( + send(Call::kDelete, name_of(id), force ? "?force=true" : "?force=false")); +} + +Operation AgentRuntime::destroy(const std::string& id, bool force) const { + return finish(destroy_start(id, force)); +} + +// --- queries --------------------------------------------------------------- + +Json AgentRuntime::query_body(const Json& input, const std::string& class_method) { + check_method(class_method); + if (!input.is_object()) throw GoogleError::invalid("input must be a JSON object"); + check_size(input, "input"); + Json body = Json::object(); + body.set("input", input); + body.set("classMethod", Json(class_method)); + return body; +} + +Json AgentRuntime::query(const std::string& id, const Json& input, + const std::string& class_method) const { + Json body = query_body(input, class_method); + return send(Call::kQuery, name_of(id), "", &body); +} + +std::size_t AgentRuntime::stream_query(const std::string& id, const Json& input, + const GoogleClient::EventSink& sink, + const std::string& class_method) const { + return stream_call(Call::kStreamQuery, name_of(id), query_body(input, class_method), sink); +} + +Operation AgentRuntime::async_query(const std::string& id, const std::string& input_gcs_uri, + const std::string& output_gcs_uri) const { + check_gcs(input_gcs_uri, "inputGcsUri"); + check_gcs(output_gcs_uri, "outputGcsUri"); + Json body = Json::object(); + body.set("inputGcsUri", Json(input_gcs_uri)); + body.set("outputGcsUri", Json(output_gcs_uri)); + return Operation::from_json(send(Call::kAsyncQuery, name_of(id), "", &body)); +} + +void AgentRuntime::cancel_async_query(const std::string& id, + const std::string& operation_name) const { + Json body = Json::object(); + body.set("operationName", Json(checked_operation(operation_name))); + send(Call::kCancelAsyncQuery, name_of(id), "", &body); +} + +Json AgentRuntime::execute_code(const std::string& id, const Json& inputs) const { + if (!inputs.is_array() || inputs.as_array().empty()) + throw GoogleError::invalid("inputs must be a non-empty array of chunks"); + check_size(inputs, "inputs"); + Json body = Json::object(); + body.set("inputs", inputs); + return send(Call::kExecuteCode, name_of(id), "", &body); +} + +// --- IAM ------------------------------------------------------------------- + +Json AgentRuntime::get_iam_policy(const std::string& id, int policy_version) const { + if (policy_version < 0 || policy_version > 3) throw GoogleError::invalid("policy version 0..3"); + std::string q = policy_version ? "?options.requestedPolicyVersion=" + std::to_string(policy_version) + : ""; + return send(Call::kGetIamPolicy, name_of(id), q); +} + +Json AgentRuntime::set_iam_policy(const std::string& id, const Json& policy) const { + if (!policy.is_object()) throw GoogleError::invalid("policy must be an object"); + check_size(policy, "policy"); + Json body = Json::object(); + body.set("policy", policy); + return send(Call::kSetIamPolicy, name_of(id), "", &body); +} + +std::vector AgentRuntime::test_iam_permissions( + const std::string& id, const std::vector& permissions) const { + if (permissions.empty() || permissions.size() > 64) + throw GoogleError::invalid("1 to 64 permissions"); + std::string q; + for (const auto& p : permissions) { + if (p.empty() || p.size() > 128) throw GoogleError::invalid("bad permission"); + for (char c : p) + if (!std::isalnum(static_cast(c)) && c != '.' && c != '_') + throw GoogleError::invalid("bad permission"); + q += (q.empty() ? "?permissions=" : "&permissions=") + enc(p); + } + Json reply = send(Call::kTestIamPermissions, name_of(id), q); + std::vector out; + if (const Json* a = reply.find("permissions"); a && a->is_array()) + for (const Json& p : a->as_array()) + if (p.is_string()) out.push_back(p.as_string()); + return out; +} + +// --- operations ------------------------------------------------------------ + +Operation AgentRuntime::operation(const std::string& operation_name) const { + return Operation::from_json(send(Call::kOperationGet, checked_operation(operation_name))); +} + +Operation AgentRuntime::wait(const std::string& operation_name) const { + return wait_operation(*client_, endpoint_, checked_operation(operation_name), sleeper_); +} + +std::vector AgentRuntime::list_operations(const std::string& id) const { + Json items = list_items(Call::kOperationList, name_of(id), "operations", ""); + std::vector out; + for (const Json& j : items.as_array()) out.push_back(Operation::from_json(j)); + return out; +} + +void AgentRuntime::cancel_operation(const std::string& operation_name) const { + send(Call::kOperationCancel, checked_operation(operation_name)); +} + +void AgentRuntime::delete_operation(const std::string& operation_name) const { + send(Call::kOperationDelete, checked_operation(operation_name)); +} + +// --- revisions ------------------------------------------------------------- + +Revision AgentRuntime::get_revision(const std::string& id, const std::string& revision) const { + return Revision::from_json(send(Call::kRevisionGet, revision_of(id, revision))); +} + +std::vector AgentRuntime::list_revisions(const std::string& id) const { + Json items = list_items(Call::kRevisionList, name_of(id), "reasoningEngineRuntimeRevisions", ""); + std::vector out; + for (const Json& j : items.as_array()) out.push_back(Revision::from_json(j)); + return out; +} + +Operation AgentRuntime::destroy_revision(const std::string& id, const std::string& revision) const { + return finish(Operation::from_json(send(Call::kRevisionDelete, revision_of(id, revision)))); +} + +Json AgentRuntime::query_revision(const std::string& id, const std::string& revision, + const Json& input, const std::string& class_method) const { + Json body = query_body(input, class_method); + return send(Call::kRevisionQuery, revision_of(id, revision), "", &body); +} + +std::size_t AgentRuntime::stream_query_revision(const std::string& id, const std::string& revision, + const Json& input, + const GoogleClient::EventSink& sink, + const std::string& class_method) const { + return stream_call(Call::kRevisionStreamQuery, revision_of(id, revision), + query_body(input, class_method), sink); +} + +} // namespace molo::google::runtime diff --git a/src/google/runtime/agent_runtime.h b/src/google/runtime/agent_runtime.h new file mode 100644 index 0000000..3abd675 --- /dev/null +++ b/src/google/runtime/agent_runtime.h @@ -0,0 +1,112 @@ +#pragma once + +// Agent Runtime (Agent Engine): the reasoningEngines resource on the +// aiplatform host. Every URL comes from the discovery-checked table in +// calls.h. Long-running calls come in two forms: *_start returns the +// Operation at once (use for multi-day work and poll operation()), the plain +// form waits with wait_operation (capped, see operation.h). + +#include +#include +#include +#include + +#include "google/operation.h" +#include "google/resource.h" +#include "google/runtime/calls.h" +#include "google/runtime/engine.h" +#include "google/service.h" + +namespace molo::google::runtime { + +// A runtime revision (v1beta1): one immutable deployment of an engine. +struct Revision { + std::string name; + std::string state; // ACTIVE, ARCHIVED + std::string create_time; + EngineSpec spec; + clients::body::Json raw; + static Revision from_json(const clients::body::Json& doc); +}; + +class AgentRuntime : public Service { + public: + AgentRuntime(std::shared_ptr client, CloudContext context, + Sleeper sleeper = nullptr); + + const CloudContext& context() const { return context_; } + + // --- engines (v1) --------------------------------------------------- + Operation create_start(const EngineDraft& draft) const; + Engine create(const EngineDraft& draft) const; + Engine get(const std::string& id) const; + std::vector list(const std::string& filter = "") const; + Operation update_start(const std::string& id, const EngineUpdate& update) const; + Engine update(const std::string& id, const EngineUpdate& update) const; + // Destructive: explicit method, explicit force (no default). + Operation destroy_start(const std::string& id, bool force) const; + Operation destroy(const std::string& id, bool force) const; + + // --- queries -------------------------------------------------------- + // Body builder, public so callers and tests can inspect what is sent. + static clients::body::Json query_body(const clients::body::Json& input, + const std::string& class_method); + // Returns the whole response document ("output" inside). + clients::body::Json query(const std::string& id, const clients::body::Json& input, + const std::string& class_method = "query") const; + // Events go to sink; false stops early. Returns events delivered (capped). + std::size_t stream_query(const std::string& id, const clients::body::Json& input, + const GoogleClient::EventSink& sink, + const std::string& class_method = "stream_query") const; + // Batch pattern: asyncQuery with Cloud Storage in and out; may run for days. + Operation async_query(const std::string& id, const std::string& input_gcs_uri, + const std::string& output_gcs_uri) const; + void cancel_async_query(const std::string& id, const std::string& operation_name) const; + // Stateless code execution; inputs is a Json array of Chunk objects. + clients::body::Json execute_code(const std::string& id, + const clients::body::Json& inputs) const; + + // --- IAM ------------------------------------------------------------ + clients::body::Json get_iam_policy(const std::string& id, int policy_version = 0) const; + clients::body::Json set_iam_policy(const std::string& id, + const clients::body::Json& policy) const; + std::vector test_iam_permissions( + const std::string& id, const std::vector& permissions) const; + + // --- operations ----------------------------------------------------- + Operation operation(const std::string& operation_name) const; // one poll + Operation wait(const std::string& operation_name) const; // capped wait + std::vector list_operations(const std::string& id) const; + void cancel_operation(const std::string& operation_name) const; + void delete_operation(const std::string& operation_name) const; + + // --- runtime revisions (v1beta1) ------------------------------------- + Revision get_revision(const std::string& id, const std::string& revision) const; + std::vector list_revisions(const std::string& id) const; + Operation destroy_revision(const std::string& id, const std::string& revision) const; + clients::body::Json query_revision(const std::string& id, const std::string& revision, + const clients::body::Json& input, + const std::string& class_method = "query") const; + std::size_t stream_query_revision(const std::string& id, const std::string& revision, + const clients::body::Json& input, + const GoogleClient::EventSink& sink, + const std::string& class_method = "stream_query") const; + + private: + std::string name_of(const std::string& id) const; + std::string revision_of(const std::string& id, const std::string& revision) const; + static std::string checked_operation(const std::string& name); + clients::body::Json send(Call call, const std::string& target, const std::string& query = "", + const clients::body::Json* body = nullptr) const; + std::size_t stream_call(Call call, const std::string& target, const clients::body::Json& body, + const GoogleClient::EventSink& sink) const; + clients::body::Json list_items(Call call, const std::string& parent, + const std::string& items_key, const std::string& filter) const; + Engine engine_from(const Operation& op) const; + Operation finish(Operation op) const; + + CloudContext context_; + Sleeper sleeper_; +}; + +} // namespace molo::google::runtime diff --git a/src/google/runtime/calls.cpp b/src/google/runtime/calls.cpp new file mode 100644 index 0000000..a247c98 --- /dev/null +++ b/src/google/runtime/calls.cpp @@ -0,0 +1,92 @@ +#include "google/runtime/calls.h" + +#include + +#include "google/errors.h" +#include "google/resource.h" + +namespace molo::google::runtime { + +// CALLS-BEGIN (parsed by tools/check_discovery.py; one row per line) +static const CallSpec kCalls[] = { + {Call::kCreate, "POST", "v1/{+parent}/reasoningEngines", "v1", "aiplatform.projects.locations.reasoningEngines.create", "displayName,description,labels,spec,encryptionSpec", ""}, + {Call::kGet, "GET", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.get", "", ""}, + {Call::kList, "GET", "v1/{+parent}/reasoningEngines", "v1", "aiplatform.projects.locations.reasoningEngines.list", "", "filter,pageSize,pageToken"}, + {Call::kPatch, "PATCH", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.patch", "name,displayName,description,labels,spec", "updateMask"}, + {Call::kDelete, "DELETE", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.delete", "", "force"}, + {Call::kQuery, "POST", "v1/{+name}:query", "v1", "aiplatform.projects.locations.reasoningEngines.query", "input,classMethod", ""}, + {Call::kStreamQuery, "POST", "v1/{+name}:streamQuery", "v1", "aiplatform.projects.locations.reasoningEngines.streamQuery", "input,classMethod", ""}, + {Call::kAsyncQuery, "POST", "v1/{+name}:asyncQuery", "v1", "aiplatform.projects.locations.reasoningEngines.asyncQuery", "inputGcsUri,outputGcsUri", ""}, + {Call::kCancelAsyncQuery, "POST", "v1/{+name}:cancelAsyncQuery", "v1", "aiplatform.projects.locations.reasoningEngines.cancelAsyncQuery", "operationName", ""}, + {Call::kExecuteCode, "POST", "v1/{+name}:executeCode", "v1", "aiplatform.projects.locations.reasoningEngines.executeCode", "inputs", ""}, + {Call::kGetIamPolicy, "POST", "v1/{+resource}:getIamPolicy", "v1", "aiplatform.projects.locations.reasoningEngines.getIamPolicy", "", "options.requestedPolicyVersion"}, + {Call::kSetIamPolicy, "POST", "v1/{+resource}:setIamPolicy", "v1", "aiplatform.projects.locations.reasoningEngines.setIamPolicy", "policy", ""}, + {Call::kTestIamPermissions, "POST", "v1/{+resource}:testIamPermissions", "v1", "aiplatform.projects.locations.reasoningEngines.testIamPermissions", "", "permissions"}, + {Call::kOperationGet, "GET", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.operations.get", "", ""}, + {Call::kOperationList, "GET", "v1/{+name}/operations", "v1", "aiplatform.projects.locations.reasoningEngines.operations.list", "", "filter,pageSize,pageToken"}, + {Call::kOperationCancel, "POST", "v1/{+name}:cancel", "v1", "aiplatform.projects.locations.reasoningEngines.operations.cancel", "", ""}, + {Call::kOperationDelete, "DELETE", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.operations.delete", "", ""}, + {Call::kRevisionGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.get", "", ""}, + {Call::kRevisionList, "GET", "v1beta1/{+parent}/runtimeRevisions", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.list", "", "filter,pageSize,pageToken"}, + {Call::kRevisionDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.delete", "", ""}, + {Call::kRevisionQuery, "POST", "v1beta1/{+name}:query", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.query", "input,classMethod", ""}, + {Call::kRevisionStreamQuery, "POST", "v1beta1/{+name}:streamQuery", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.streamQuery", "input,classMethod", ""}, +}; +// CALLS-END + +// SCHEMAS-BEGIN (parsed by tools/check_discovery.py; one row per line) +static const SchemaFields kSchemas[] = { + {"ReasoningEngine", "v1", "name,displayName,description,labels,spec,etag,createTime,updateTime,encryptionSpec,contextSpec"}, + {"ReasoningEngineSpec", "v1", "agentFramework,packageSpec,containerSpec,sourceCodeSpec,deploymentSpec,buildSpec,identityType,serviceAccount,effectiveIdentity,classMethods"}, + {"ReasoningEngineSpecPackageSpec", "v1", "pythonVersion,pickleObjectGcsUri,dependencyFilesGcsUri,requirementsGcsUri"}, + {"ReasoningEngineSpecContainerSpec", "v1", "imageUri,port"}, + {"ReasoningEngineSpecSourceCodeSpec", "v1", "pythonSpec,inlineSource,developerConnectSource,imageSpec,agentConfigSource"}, + {"ReasoningEngineSpecSourceCodeSpecPythonSpec", "v1", "version,entrypointModule,entrypointObject,requirementsFile"}, + {"ReasoningEngineSpecBuildSpec", "v1", "serviceAccount,workerPool"}, + {"ReasoningEngineSpecDeploymentSpec", "v1", "env,secretEnv,resourceLimits,minInstances,maxInstances,containerConcurrency,pscInterfaceConfig,keepAliveProbe,agentGatewayConfig"}, + {"EnvVar", "v1", "name,value"}, + {"SecretEnvVar", "v1", "name,secretRef"}, + {"SecretRef", "v1", "secret,version"}, + {"EncryptionSpec", "v1", "kmsKeyName"}, + {"ListReasoningEnginesResponse", "v1", "reasoningEngines,nextPageToken"}, + {"QueryReasoningEngineResponse", "v1", "output"}, + {"ExecuteCodeResponse", "v1", "outputs"}, + {"ReasoningEngine", "v1beta1", "trafficConfig,revisionGarbageCollectionStrategy"}, + {"ReasoningEngineRuntimeRevision", "v1beta1", "name,state,createTime,spec"}, + {"ListReasoningEngineRuntimeRevisionsResponse", "v1beta1", "reasoningEngineRuntimeRevisions,nextPageToken"}, + {"ReasoningEngineSpecDeploymentSpec", "v1beta1", "agentServerMode"}, + {"ReasoningEngineSpec", "v1beta1", "agentCard"}, +}; +// SCHEMAS-END + +const CallSpec& spec_of(Call call) { + for (const CallSpec& s : kCalls) + if (s.call == call) return s; + throw GoogleError::invalid("unknown call"); +} + +clients::Method method_of(Call call) { + const char* m = spec_of(call).http_method; + if (!std::strcmp(m, "GET")) return clients::Method::kGet; + if (!std::strcmp(m, "POST")) return clients::Method::kPost; + if (!std::strcmp(m, "PATCH")) return clients::Method::kPatch; + return clients::Method::kDelete; +} + +ServiceEndpoint endpoint_of(Call call, const std::string& location) { + return std::strcmp(spec_of(call).version, "v1beta1") == 0 + ? endpoints::aiplatform_beta(location) + : endpoints::aiplatform(location); +} + +std::string render(Call call, const std::string& target) { + std::string path = spec_of(call).path; + path.erase(0, path.find('/') + 1); // drop the version prefix; the endpoint has it + for (const char* key : {"{+name}", "{+parent}", "{+resource}"}) { + auto at = path.find(key); + if (at != std::string::npos) path.replace(at, std::strlen(key), target); + } + return "/" + path; +} + +} // namespace molo::google::runtime diff --git a/src/google/runtime/calls.h b/src/google/runtime/calls.h new file mode 100644 index 0000000..a5abed9 --- /dev/null +++ b/src/google/runtime/calls.h @@ -0,0 +1,45 @@ +#pragma once + +// The ONE table of REST calls this module makes. Every row is checked against +// Google's Discovery document by tools/check_discovery.py. Code builds every +// URL from this table, never from a literal. + +#include + +#include "clients/request.h" +#include "google/endpoints.h" + +namespace molo::google::runtime { + +enum class Call { + kCreate, kGet, kList, kPatch, kDelete, kQuery, kStreamQuery, kAsyncQuery, + kCancelAsyncQuery, kExecuteCode, kGetIamPolicy, kSetIamPolicy, kTestIamPermissions, + kOperationGet, kOperationList, kOperationCancel, kOperationDelete, + kRevisionGet, kRevisionList, kRevisionDelete, kRevisionQuery, kRevisionStreamQuery, +}; + +struct CallSpec { + Call call; + const char* http_method; // as in discovery: GET POST PATCH DELETE + const char* path; // discovery "path", e.g. "v1/{+name}:query" + const char* version; // "v1" or "v1beta1" + const char* rpc_id; // discovery method id + const char* body_fields; // comma list: request body fields we send + const char* query_params; // comma list: query parameters we send +}; + +struct SchemaFields { + const char* schema; // discovery schema name without the version prefix + const char* version; // "v1" or "v1beta1" + const char* fields; // comma list: fields we read or write +}; + +const CallSpec& spec_of(Call call); +clients::Method method_of(Call call); +// Endpoint for the call's API version in a location. +ServiceEndpoint endpoint_of(Call call, const std::string& location); +// Path under the endpoint base: "/projects/.../reasoningEngines/x:query". +// `target` replaces the {+name}, {+parent} or {+resource} placeholder. +std::string render(Call call, const std::string& target); + +} // namespace molo::google::runtime diff --git a/src/google/runtime/caps.h b/src/google/runtime/caps.h new file mode 100644 index 0000000..a90ce88 --- /dev/null +++ b/src/google/runtime/caps.h @@ -0,0 +1,29 @@ +#pragma once + +// Static ceilings for Agent Runtime. Never autotuned. + +#include + +namespace molo::google::runtime { + +struct RuntimeCaps { + static constexpr std::size_t kMaxDisplayName = 128; + static constexpr std::size_t kMaxDescription = 1000; + static constexpr std::size_t kMaxLabels = 64; + static constexpr std::size_t kMaxLabelChars = 63; + static constexpr std::size_t kMaxEnvVars = 100; + static constexpr std::size_t kMaxEnvValueChars = 4096; + static constexpr std::size_t kMaxUriChars = 1024; + static constexpr std::size_t kMaxServiceAccountChars = 256; + static constexpr int kMinInstancesMax = 75; // minInstances in [0, 75] + static constexpr int kMaxInstancesMax = 1000; // maxInstances in [1, 1000] + static constexpr int kMaxConcurrency = 1000; + static constexpr std::size_t kMaxInputBytes = 1024 * 1024; // serialized query input + static constexpr std::size_t kMaxMethodChars = 64; + static constexpr std::size_t kMaxFilterChars = 512; + static constexpr std::size_t kMaxMaskChars = 512; + static constexpr int kMaxListPages = 20; + static constexpr std::size_t kMaxStreamEvents = 5000; +}; + +} // namespace molo::google::runtime diff --git a/src/google/runtime/deployment_spec.cpp b/src/google/runtime/deployment_spec.cpp new file mode 100644 index 0000000..328ef5f --- /dev/null +++ b/src/google/runtime/deployment_spec.cpp @@ -0,0 +1,324 @@ +#include "google/runtime/deployment_spec.h" + +#include +#include + +#include "google/errors.h" +#include "google/resource.h" +#include "google/runtime/caps.h" + +namespace molo::google::runtime { + +using clients::body::Json; + +namespace { + +[[noreturn]] void bad(const std::string& what) { throw GoogleError::invalid(what); } + +bool valid_env_name(const std::string& n) { + if (n.empty() || n.size() > 128) return false; + if (std::isdigit(static_cast(n[0]))) return false; + for (char c : n) + if (!std::isalnum(static_cast(c)) && c != '_') return false; + return true; +} + +bool printable_token(const std::string& s, std::size_t max) { + if (s.empty() || s.size() > max) return false; + for (char c : s) + if (static_cast(c) <= 0x20 || c == 0x7f) return false; + return true; +} + +void check_gcs(const std::string& uri, const char* what) { + if (uri.empty()) return; + if (uri.rfind("gs://", 0) != 0 || !printable_token(uri, RuntimeCaps::kMaxUriChars)) + bad(std::string(what) + " must be a gs:// URI"); +} + +void check_python(const std::string& v) { + static const std::set ok = {"3.10", "3.11", "3.12", "3.13", "3.14"}; + if (!v.empty() && !ok.count(v)) bad("python version must be 3.10 to 3.14"); +} + +std::string str(const Json& doc, const char* key) { + const Json* v = doc.is_object() ? doc.find(key) : nullptr; + return v && v->is_string() ? v->as_string() : ""; +} + +void put(Json& obj, const char* key, const std::string& v) { + if (!v.empty()) obj.set(key, Json(v)); +} + +Json known_free(const Json& doc, const std::set& known) { + Json rest = Json::object(); + if (!doc.is_object()) return rest; + for (const auto& [k, v] : doc.as_object()) + if (!known.count(k)) rest.set(k, v); + return rest; +} + +} // namespace + +const char* identity_type_name(IdentityType t) { + switch (t) { + case IdentityType::kServiceAccount: return "SERVICE_ACCOUNT"; + case IdentityType::kAgentIdentity: return "AGENT_IDENTITY"; + default: return "IDENTITY_TYPE_UNSPECIFIED"; + } +} + +IdentityType identity_type_from(const std::string& name) { + if (name == "SERVICE_ACCOUNT") return IdentityType::kServiceAccount; + if (name == "AGENT_IDENTITY") return IdentityType::kAgentIdentity; + return IdentityType::kUnspecified; +} + +// --- DeploymentSpec ------------------------------------------------------- + +void DeploymentSpec::validate() const { + if (env.size() + secret_env.size() > RuntimeCaps::kMaxEnvVars) + bad("too many environment variables"); + std::set seen; + for (const auto& e : env) { + if (!valid_env_name(e.name)) bad("bad environment variable name"); + if (e.value.size() > RuntimeCaps::kMaxEnvValueChars) bad("environment value too long"); + if (!seen.insert(e.name).second) bad("duplicate environment variable"); + } + for (const auto& s : secret_env) { + if (!valid_env_name(s.name)) bad("bad secret environment variable name"); + if (!valid_segment(s.secret)) bad("bad secret id"); + if (!s.version.empty() && !valid_segment(s.version)) bad("bad secret version"); + if (!seen.insert(s.name).second) bad("duplicate environment variable"); + } + static const std::set cpus = {"1", "2", "4", "6", "8"}; + if (!cpu.empty() && !cpus.count(cpu)) bad("cpu must be 1, 2, 4, 6 or 8"); + if (!memory.empty()) { // 1Gi .. 32Gi + bool okm = memory.size() >= 3 && memory.size() <= 4 && memory.substr(memory.size() - 2) == "Gi"; + int gi = 0; + if (okm) { + for (std::size_t i = 0; i + 2 < memory.size(); ++i) { + if (!std::isdigit(static_cast(memory[i]))) okm = false; + else gi = gi * 10 + (memory[i] - '0'); + } + } + if (!okm || gi < 1 || gi > 32) bad("memory must be 1Gi to 32Gi"); + } + if (min_instances && (*min_instances < 0 || *min_instances > RuntimeCaps::kMinInstancesMax)) + bad("minInstances must be 0..75"); + if (max_instances && (*max_instances < 1 || *max_instances > RuntimeCaps::kMaxInstancesMax)) + bad("maxInstances must be 1..1000"); + if (min_instances && max_instances && *min_instances > *max_instances) + bad("minInstances exceeds maxInstances"); + if (container_concurrency && + (*container_concurrency < 1 || *container_concurrency > RuntimeCaps::kMaxConcurrency)) + bad("containerConcurrency must be 1..1000"); +} + +Json DeploymentSpec::to_json() const { + Json o = Json::object(); + if (!env.empty()) { + Json a = Json::array(); + for (const auto& e : env) { + Json v = Json::object(); + v.set("name", Json(e.name)); + v.set("value", Json(e.value)); + a.push(v); + } + o.set("env", a); + } + if (!secret_env.empty()) { + Json a = Json::array(); + for (const auto& s : secret_env) { + Json ref = Json::object(); + ref.set("secret", Json(s.secret)); + if (!s.version.empty()) ref.set("version", Json(s.version)); + Json v = Json::object(); + v.set("name", Json(s.name)); + v.set("secretRef", ref); + a.push(v); + } + o.set("secretEnv", a); + } + if (!cpu.empty() || !memory.empty()) { + Json lim = Json::object(); + put(lim, "cpu", cpu); + put(lim, "memory", memory); + o.set("resourceLimits", lim); + } + if (min_instances) o.set("minInstances", Json(*min_instances)); + if (max_instances) o.set("maxInstances", Json(*max_instances)); + if (container_concurrency) o.set("containerConcurrency", Json(*container_concurrency)); + if (!psc_interface_config.is_null()) o.set("pscInterfaceConfig", psc_interface_config); + if (extra.is_object()) + for (const auto& [k, v] : extra.as_object()) o.set(k, v); + return o; +} + +DeploymentSpec DeploymentSpec::from_json(const Json& doc) { + DeploymentSpec d; + if (!doc.is_object()) return d; + if (const Json* a = doc.find("env"); a && a->is_array()) + for (const Json& e : a->as_array()) d.env.push_back({str(e, "name"), str(e, "value")}); + if (const Json* a = doc.find("secretEnv"); a && a->is_array()) + for (const Json& e : a->as_array()) { + const Json* ref = e.is_object() ? e.find("secretRef") : nullptr; + d.secret_env.push_back( + {str(e, "name"), ref ? str(*ref, "secret") : "", ref ? str(*ref, "version") : ""}); + } + if (const Json* lim = doc.find("resourceLimits")) { + d.cpu = str(*lim, "cpu"); + d.memory = str(*lim, "memory"); + } + auto num = [&](const char* k) -> std::optional { + const Json* v = doc.find(k); + if (v && v->is_number()) return static_cast(v->as_int()); + return std::nullopt; + }; + d.min_instances = num("minInstances"); + d.max_instances = num("maxInstances"); + d.container_concurrency = num("containerConcurrency"); + if (const Json* p = doc.find("pscInterfaceConfig")) d.psc_interface_config = *p; + d.extra = known_free(doc, {"env", "secretEnv", "resourceLimits", "minInstances", "maxInstances", + "containerConcurrency", "pscInterfaceConfig"}); + return d; +} + +// --- EngineSpec ----------------------------------------------------------- + +void EngineSpec::validate() const { + static const std::set frameworks = {"google-adk", "langchain", "langgraph", + "ag2", "llama-index", "custom"}; + if (!agent_framework.empty() && !frameworks.count(agent_framework)) + bad("unknown agentFramework"); + int sources = (package ? 1 : 0) + (container ? 1 : 0) + (source ? 1 : 0); + if (sources > 1) bad("set only one of package, container, source"); + if (package) { + check_python(package->python_version); + check_gcs(package->pickle_object_gcs_uri, "pickleObjectGcsUri"); + check_gcs(package->dependency_files_gcs_uri, "dependencyFilesGcsUri"); + check_gcs(package->requirements_gcs_uri, "requirementsGcsUri"); + } + if (container && !printable_token(container->image_uri, RuntimeCaps::kMaxUriChars)) + bad("containerSpec.imageUri is required"); + if (source) { + check_python(source->python_version); + for (const std::string* s : {&source->entrypoint_module, &source->entrypoint_object, + &source->requirements_file}) + if (s->size() > 256) bad("source entrypoint field too long"); + } + if (container && container->port && (*container->port < 1 || *container->port > 65535)) + bad("containerSpec.port must be 1..65535"); + if (deployment) deployment->validate(); + if (build_service_account.size() > RuntimeCaps::kMaxServiceAccountChars || + build_worker_pool.size() > 512) + bad("buildSpec field too long"); + if (!service_account.empty()) { + if (identity == IdentityType::kAgentIdentity) + bad("serviceAccount must not be set with AGENT_IDENTITY"); + if (!printable_token(service_account, RuntimeCaps::kMaxServiceAccountChars) || + service_account.find('@') == std::string::npos) + bad("serviceAccount must be an email address"); + } +} + +Json EngineSpec::to_json() const { + validate(); + Json o = extra.is_object() ? extra : Json::object(); + put(o, "agentFramework", agent_framework); + if (package) { + Json p = Json::object(); + put(p, "pythonVersion", package->python_version); + put(p, "pickleObjectGcsUri", package->pickle_object_gcs_uri); + put(p, "dependencyFilesGcsUri", package->dependency_files_gcs_uri); + put(p, "requirementsGcsUri", package->requirements_gcs_uri); + o.set("packageSpec", p); + } + if (container) { + Json c = Json::object(); + c.set("imageUri", Json(container->image_uri)); + if (container->port) c.set("port", Json(*container->port)); + o.set("containerSpec", c); + } + if (source) { + Json py = Json::object(); + put(py, "entrypointModule", source->entrypoint_module); + put(py, "entrypointObject", source->entrypoint_object); + put(py, "requirementsFile", source->requirements_file); + put(py, "version", source->python_version); + Json s = source->source_extra.is_object() ? source->source_extra : Json::object(); + s.set("pythonSpec", py); + o.set("sourceCodeSpec", s); + } + if (deployment) o.set("deploymentSpec", deployment->to_json()); + if (!build_service_account.empty() || !build_worker_pool.empty()) { + Json b = Json::object(); + put(b, "serviceAccount", build_service_account); + put(b, "workerPool", build_worker_pool); + o.set("buildSpec", b); + } + if (identity != IdentityType::kUnspecified) o.set("identityType", Json(identity_type_name(identity))); + put(o, "serviceAccount", service_account); + if (class_methods.is_array()) o.set("classMethods", class_methods); + return o; +} + +EngineSpec EngineSpec::from_json(const Json& doc) { + EngineSpec s; + if (!doc.is_object()) return s; + s.agent_framework = str(doc, "agentFramework"); + if (const Json* p = doc.find("packageSpec")) { + PackageSpec ps; + ps.python_version = str(*p, "pythonVersion"); + ps.pickle_object_gcs_uri = str(*p, "pickleObjectGcsUri"); + ps.dependency_files_gcs_uri = str(*p, "dependencyFilesGcsUri"); + ps.requirements_gcs_uri = str(*p, "requirementsGcsUri"); + s.package = ps; + } + if (const Json* c = doc.find("containerSpec")) { + ContainerSpec cs; + cs.image_uri = str(*c, "imageUri"); + if (const Json* p = c->find("port"); p && p->is_number()) cs.port = static_cast(p->as_int()); + s.container = cs; + } + if (const Json* b = doc.find("buildSpec")) { + s.build_service_account = str(*b, "serviceAccount"); + s.build_worker_pool = str(*b, "workerPool"); + } + s.effective_identity = str(doc, "effectiveIdentity"); + if (const Json* c = doc.find("sourceCodeSpec")) { + SourceCodeSpec ss; + if (const Json* py = c->find("pythonSpec")) { + ss.entrypoint_module = str(*py, "entrypointModule"); + ss.entrypoint_object = str(*py, "entrypointObject"); + ss.requirements_file = str(*py, "requirementsFile"); + ss.python_version = str(*py, "version"); + } + ss.source_extra = known_free(*c, {"pythonSpec"}); + s.source = ss; + } + if (const Json* d = doc.find("deploymentSpec")) s.deployment = DeploymentSpec::from_json(*d); + s.identity = identity_type_from(str(doc, "identityType")); + s.service_account = str(doc, "serviceAccount"); + if (const Json* m = doc.find("classMethods"); m && m->is_array()) s.class_methods = *m; + s.extra = known_free(doc, {"agentFramework", "packageSpec", "containerSpec", "sourceCodeSpec", + "deploymentSpec", "identityType", "serviceAccount", "classMethods", + "buildSpec", "effectiveIdentity"}); + return s; +} + +std::vector EngineSpec::mask() const { + std::vector m; + if (!agent_framework.empty()) m.push_back("spec.agentFramework"); + if (package) m.push_back("spec.packageSpec"); + if (container) m.push_back("spec.containerSpec"); + if (source) m.push_back("spec.sourceCodeSpec"); + if (deployment) m.push_back("spec.deploymentSpec"); + if (!build_service_account.empty() || !build_worker_pool.empty()) m.push_back("spec.buildSpec"); + if (identity != IdentityType::kUnspecified) m.push_back("spec.identityType"); + if (!service_account.empty()) m.push_back("spec.serviceAccount"); + if (class_methods.is_array()) m.push_back("spec.classMethods"); + return m; +} + +} // namespace molo::google::runtime diff --git a/src/google/runtime/deployment_spec.h b/src/google/runtime/deployment_spec.h new file mode 100644 index 0000000..2666bd5 --- /dev/null +++ b/src/google/runtime/deployment_spec.h @@ -0,0 +1,92 @@ +#pragma once + +// Typed deployment description of a reasoning engine (Agent Engine). Unknown +// fields are kept as raw Json (`extra`) and sent back unchanged. + +#include +#include +#include + +#include "clients/body/json.h" + +namespace molo::google::runtime { + +enum class IdentityType { kUnspecified, kServiceAccount, kAgentIdentity }; +const char* identity_type_name(IdentityType t); +IdentityType identity_type_from(const std::string& name); + +// Python package deployment (packageSpec). +struct PackageSpec { + std::string python_version; // 3.10 .. 3.14 + std::string pickle_object_gcs_uri; + std::string dependency_files_gcs_uri; // tar.gz + std::string requirements_gcs_uri; +}; + +// Container deployment (containerSpec). +struct ContainerSpec { + std::string image_uri; // Artifact Registry image + std::optional port; +}; + +// Deploy from source (sourceCodeSpec.pythonSpec); inline or Developer Connect +// source stay in `source_extra`. +struct SourceCodeSpec { + std::string entrypoint_module; + std::string entrypoint_object; + std::string requirements_file; + std::string python_version; + clients::body::Json source_extra; // inlineSource / developerConnectSource +}; + +struct EnvVar { + std::string name; + std::string value; +}; + +struct SecretEnvVar { + std::string name; + std::string secret; // Secret Manager secret id + std::string version; // "latest" or a number +}; + +// deploymentSpec: runtime environment and scaling. +struct DeploymentSpec { + std::vector env; + std::vector secret_env; + std::string cpu; // resourceLimits.cpu, e.g. "4" + std::string memory; // resourceLimits.memory, e.g. "8Gi" + std::optional min_instances; // [0, 75], Google default 1 + std::optional max_instances; // [1, 1000], Google default 100 + std::optional container_concurrency; // Google default 9 + clients::body::Json psc_interface_config; // raw, null when unset + clients::body::Json extra; // keepAliveProbe, agentGatewayConfig, agentServerMode (beta), ... + + void validate() const; + clients::body::Json to_json() const; + static DeploymentSpec from_json(const clients::body::Json& doc); +}; + +// spec of a reasoning engine. At most one deployment source may be set. +struct EngineSpec { + std::string agent_framework; // google-adk, langchain, langgraph, ag2, llama-index, custom + std::optional package; + std::optional container; + std::optional source; + std::optional deployment; + IdentityType identity = IdentityType::kUnspecified; + std::string service_account; // must be empty for AGENT_IDENTITY + std::string build_service_account; // buildSpec.serviceAccount + std::string build_worker_pool; // buildSpec.workerPool + std::string effective_identity; // output only, never sent + clients::body::Json class_methods; // raw OpenAPI array, null when unset + clients::body::Json extra; // unknown spec fields, merged on output + + void validate() const; + clients::body::Json to_json() const; + static EngineSpec from_json(const clients::body::Json& doc); + // updateMask entries for the parts that are set ("spec.deploymentSpec", ...). + std::vector mask() const; +}; + +} // namespace molo::google::runtime diff --git a/src/google/runtime/engine.cpp b/src/google/runtime/engine.cpp new file mode 100644 index 0000000..eaf4238 --- /dev/null +++ b/src/google/runtime/engine.cpp @@ -0,0 +1,128 @@ +#include "google/runtime/engine.h" + +#include "google/errors.h" +#include "google/runtime/caps.h" + +namespace molo::google::runtime { + +using clients::body::Json; + +namespace { + +void check_text(const std::string& s, std::size_t max, const char* what) { + if (s.size() > max) throw GoogleError::invalid(std::string(what) + " too long"); +} + +void check_labels(const std::map& labels) { + if (labels.size() > RuntimeCaps::kMaxLabels) + throw GoogleError::invalid("too many labels"); + for (const auto& [k, v] : labels) { + if (k.empty() || k.size() > RuntimeCaps::kMaxLabelChars || + v.size() > RuntimeCaps::kMaxLabelChars) + throw GoogleError::invalid("bad label"); + } +} + +Json labels_json(const std::map& labels) { + Json o = Json::object(); + for (const auto& [k, v] : labels) o.set(k, Json(v)); + return o; +} + +std::string str(const Json& doc, const char* key) { + const Json* v = doc.find(key); + return v && v->is_string() ? v->as_string() : ""; +} + +} // namespace + +std::string Engine::id() const { + auto slash = name.rfind('/'); + return slash == std::string::npos ? name : name.substr(slash + 1); +} + +Engine Engine::from_json(const Json& doc) { + Engine e; + e.raw = doc; + if (!doc.is_object()) return e; + e.name = str(doc, "name"); + e.display_name = str(doc, "displayName"); + e.description = str(doc, "description"); + e.etag = str(doc, "etag"); + e.create_time = str(doc, "createTime"); + e.update_time = str(doc, "updateTime"); + if (const Json* l = doc.find("labels"); l && l->is_object()) + for (const auto& [k, v] : l->as_object()) + if (v.is_string()) e.labels[k] = v.as_string(); + if (const Json* s = doc.find("spec")) e.spec = EngineSpec::from_json(*s); + if (const Json* k = doc.find("encryptionSpec")) e.kms_key_name = str(*k, "kmsKeyName"); + return e; +} + +void EngineDraft::validate() const { + if (display_name.empty()) throw GoogleError::invalid("displayName is required"); + check_text(display_name, RuntimeCaps::kMaxDisplayName, "displayName"); + check_text(description, RuntimeCaps::kMaxDescription, "description"); + check_labels(labels); + check_text(kms_key_name, 512, "kmsKeyName"); + spec.validate(); +} + +Json EngineDraft::to_json() const { + validate(); + Json o = Json::object(); + o.set("displayName", Json(display_name)); + if (!description.empty()) o.set("description", Json(description)); + if (!labels.empty()) o.set("labels", labels_json(labels)); + Json s = spec.to_json(); + if (!s.as_object().empty()) o.set("spec", s); + if (!kms_key_name.empty()) { + Json k = Json::object(); + k.set("kmsKeyName", Json(kms_key_name)); + o.set("encryptionSpec", k); + } + return o; +} + +void EngineUpdate::validate() const { + if (!display_name && !description && !labels && !spec) + throw GoogleError::invalid("nothing to update"); + if (display_name) { + if (display_name->empty()) throw GoogleError::invalid("displayName must not be empty"); + check_text(*display_name, RuntimeCaps::kMaxDisplayName, "displayName"); + } + if (description) check_text(*description, RuntimeCaps::kMaxDescription, "description"); + if (labels) check_labels(*labels); + if (spec) { + spec->validate(); + if (spec->mask().empty()) throw GoogleError::invalid("spec has no fields to update"); + } +} + +Json EngineUpdate::to_json() const { + validate(); + Json o = Json::object(); + if (display_name) o.set("displayName", Json(*display_name)); + if (description) o.set("description", Json(*description)); + if (labels) o.set("labels", labels_json(*labels)); + if (spec) o.set("spec", spec->to_json()); + return o; +} + +std::string EngineUpdate::update_mask() const { + validate(); + std::string m; + auto add = [&](const std::string& part) { + if (!m.empty()) m += ","; + m += part; + }; + if (display_name) add("displayName"); + if (description) add("description"); + if (labels) add("labels"); + if (spec) + for (const auto& p : spec->mask()) add(p); + if (m.size() > RuntimeCaps::kMaxMaskChars) throw GoogleError::invalid("updateMask too long"); + return m; +} + +} // namespace molo::google::runtime diff --git a/src/google/runtime/engine.h b/src/google/runtime/engine.h new file mode 100644 index 0000000..56106f0 --- /dev/null +++ b/src/google/runtime/engine.h @@ -0,0 +1,54 @@ +#pragma once + +// A reasoning engine (Agent Engine) as Google returns it, plus the input +// types for create and update. + +#include +#include +#include + +#include "clients/body/json.h" +#include "google/runtime/deployment_spec.h" + +namespace molo::google::runtime { + +struct Engine { + std::string name; // projects/{p}/locations/{l}/reasoningEngines/{id} + std::string display_name; + std::string description; + std::string etag; + std::string create_time; + std::string update_time; + std::map labels; + EngineSpec spec; + std::string kms_key_name; // encryptionSpec.kmsKeyName + clients::body::Json raw; // the full response document + + std::string id() const; // last segment of name + static Engine from_json(const clients::body::Json& doc); +}; + +struct EngineDraft { + std::string display_name; // required + std::string description; + std::map labels; + EngineSpec spec; + std::string kms_key_name; // optional customer-managed key + + void validate() const; + clients::body::Json to_json() const; +}; + +// Only the set fields are sent; updateMask is derived from them. +struct EngineUpdate { + std::optional display_name; + std::optional description; + std::optional> labels; + std::optional spec; + + void validate() const; + clients::body::Json to_json() const; + std::string update_mask() const; // comma separated, never empty after validate() +}; + +} // namespace molo::google::runtime diff --git a/src/google/runtime/tools/check_discovery.py b/src/google/runtime/tools/check_discovery.py new file mode 100644 index 0000000..0ca48df --- /dev/null +++ b/src/google/runtime/tools/check_discovery.py @@ -0,0 +1,97 @@ +#!/usr/bin/env python3 +"""Check src/google/runtime/calls.cpp against Google's Discovery documents. + +Fails (exit 1) when a declared call is absent, its HTTP method or path +differs, or a request body field, query parameter or schema field we use is +not in the discovery document. Python 3 stdlib only, no credentials needed. + + python3 -I src/google/runtime/tools/check_discovery.py +""" +import json +import os +import re +import sys +import urllib.request + +HERE = os.path.dirname(os.path.abspath(__file__)) +CALLS = os.path.join(HERE, "..", "calls.cpp") +URL = "https://aiplatform.googleapis.com/$discovery/rest?version=%s" +PREFIX = {"v1": "GoogleCloudAiplatformV1", "v1beta1": "GoogleCloudAiplatformV1beta1"} + +ROW = re.compile(r'^\s*\{(.*)\},?\s*$') +STR = re.compile(r'"([^"]*)"') + + +def block(text, begin, end): + a = text.index(begin) + b = text.index(end) + rows = [] + for line in text[a:b].splitlines()[1:]: + m = ROW.match(line) + if m and '"' in line: + rows.append(STR.findall(m.group(1))) + return rows + + +def fetch(version): + with urllib.request.urlopen(URL % version, timeout=60) as r: + return json.load(r) + + +def methods(node, out): + for m in node.get("methods", {}).values(): + out[m["id"]] = m + for child in node.get("resources", {}).values(): + methods(child, out) + + +def main(): + text = open(CALLS).read() + calls = block(text, "// CALLS-BEGIN", "// CALLS-END") + schemas = block(text, "// SCHEMAS-BEGIN", "// SCHEMAS-END") + docs, index = {}, {} + for v in ("v1", "v1beta1"): + docs[v] = fetch(v) + index[v] = {} + methods(docs[v], index[v]) + bad = [] + for http, path, version, rpc, body, query in calls: + m = index[version].get(rpc) + if not m: + bad.append("missing rpc " + rpc) + continue + if m["httpMethod"] != http: + bad.append("%s: http %s != %s" % (rpc, http, m["httpMethod"])) + if m["path"] != path: + bad.append("%s: path %s != %s" % (rpc, path, m["path"])) + params = m.get("parameters", {}) + for q in filter(None, query.split(",")): + if q not in params or params[q].get("location") != "query": + bad.append("%s: query param %s absent" % (rpc, q)) + fields = [f for f in body.split(",") if f] + if fields: + ref = m.get("request", {}).get("$ref") + props = docs[version]["schemas"].get(ref, {}).get("properties", {}) + for f in fields: + if f not in props: + bad.append("%s: body field %s absent in %s" % (rpc, f, ref)) + for name, version, fields in schemas: + props = docs[version]["schemas"].get(PREFIX[version] + name, {}).get("properties") + if props is None: + bad.append("missing schema %s %s" % (version, name)) + continue + for f in fields.split(","): + if f not in props: + bad.append("schema %s.%s absent" % (name, f)) + revs = {v: docs[v].get("revision") for v in docs} + if bad: + print("DISCOVERY CHECK FAILED (revisions %s)" % revs) + for b in bad: + print(" " + b) + return 1 + print("discovery ok: %d calls, %d schemas, revisions %s" % (len(calls), len(schemas), revs)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/example/agent/runtime/create_test.cpp b/tests/example/agent/runtime/create_test.cpp new file mode 100644 index 0000000..5169bb5 --- /dev/null +++ b/tests/example/agent/runtime/create_test.cpp @@ -0,0 +1,21 @@ +// Route: POST /agent/runtime/create (starts the operation, never waits) +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig rig(false); + Fixture f(rig.client); + std::string ok = "{\"displayName\":\"Agent\",\"agentFramework\":\"google-adk\",\"imageUri\":\"us-docker.pkg.dev/p/r/a:1\",\"maxInstances\":10,\"cpu\":\"4\",\"memory\":\"8Gi\"}"; + auto res = f.client->post("/agent/runtime/create", ok, "application/json"); + check(res.status == 503 && contains(res.body, "google_not_configured"), "no credential is 503"); + check(f.client->post("/agent/runtime/create", "{}", "application/json").status == 422, "missing displayName is 422"); + check(f.client->post("/agent/runtime/create", "{\"displayName\":\"a\",\"maxInstances\":5000}", "application/json").status == 422, "maxInstances over 1000 is 422"); + check(f.client->post("/agent/runtime/create", "{\"displayName\":\"a\",\"cpu\":\"3\"}", "application/json").status == 422, "cpu 3 is 422"); + check(f.client->post("/agent/runtime/create", "{\"displayName\":\"a\",\"identityType\":\"AGENT_IDENTITY\",\"serviceAccount\":\"a@b.c\"}", "application/json").status == 422, "agent identity with service account is 422"); + check(f.client->post("/agent/runtime/create", "{\"displayName\":\"a\",\"agentFramework\":\"magic\"}", "application/json").status == 422, "unknown framework is 422"); + check(f.client->get("/agent/runtime/create").status == 405, "get is 405"); + check(rig.mock->send_count() == 0, "nothing reached Google"); + return finish("agent/runtime/create"); +} diff --git a/tests/example/agent/runtime/delete_test.cpp b/tests/example/agent/runtime/delete_test.cpp new file mode 100644 index 0000000..b272a25 --- /dev/null +++ b/tests/example/agent/runtime/delete_test.cpp @@ -0,0 +1,20 @@ +// Route: POST /agent/runtime/delete (dry run unless confirm:true) +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig rig(false); + Fixture f(rig.client); + auto dry = f.client->post("/agent/runtime/delete", "{\"id\":\"123\",\"force\":true}", "application/json"); + check(dry.status == 200 && contains(dry.body, "\"dry_run\":true") && contains(dry.body, "\"force\":true"), "default is a dry run"); + auto real = f.client->post("/agent/runtime/delete", "{\"id\":\"123\",\"confirm\":true}", "application/json"); + check(real.status == 503 && contains(real.body, "google_not_configured"), "confirmed delete without credential is 503"); + check(f.client->post("/agent/runtime/delete", "{}", "application/json").status == 422, "missing id is 422"); + check(f.client->post("/agent/runtime/delete", "{\"id\":\"1\",\"force\":\"yes\"}", "application/json").status == 422, "non-bool force is 422"); + check(f.client->post("/agent/runtime/delete", "{\"id\":\"1\",\"confirm\":\"yes\"}", "application/json").status == 422, "non-bool confirm is 422"); + check(f.client->get("/agent/runtime/delete").status == 405, "get is 405"); + check(rig.mock->send_count() == 0, "nothing reached Google"); + return finish("agent/runtime/delete"); +} diff --git a/tests/example/agent/runtime/get_test.cpp b/tests/example/agent/runtime/get_test.cpp new file mode 100644 index 0000000..905c8a3 --- /dev/null +++ b/tests/example/agent/runtime/get_test.cpp @@ -0,0 +1,18 @@ +// Route: POST /agent/runtime/get +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig rig(false); + Fixture f(rig.client); + auto res = f.client->post("/agent/runtime/get", "{\"id\":\"123\"}", "application/json"); + check(res.status == 503 && contains(res.body, "google_not_configured"), "no credential is 503"); + check(f.client->post("/agent/runtime/get", "{}", "application/json").status == 422, "missing id is 422"); + check(f.client->post("/agent/runtime/get", "{\"id\":\"../x\"}", "application/json").status == 422, "traversal id is 422"); + check(f.client->post("/agent/runtime/get", "{\"id\":\"a/b\"}", "application/json").status == 422, "slash id is 422"); + check(f.client->get("/agent/runtime/get").status == 405, "get is 405"); + check(rig.mock->send_count() == 0, "nothing reached Google"); + return finish("agent/runtime/get"); +} diff --git a/tests/example/agent/runtime/list_test.cpp b/tests/example/agent/runtime/list_test.cpp new file mode 100644 index 0000000..0bec58a --- /dev/null +++ b/tests/example/agent/runtime/list_test.cpp @@ -0,0 +1,19 @@ +// Route: POST /agent/runtime/list +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig rig(false); + Fixture f(rig.client); + auto res = f.client->post("/agent/runtime/list", "{}", "application/json"); + check(res.status == 503 && contains(res.body, "google_not_configured"), "no credential is 503"); + check(f.client->post("/agent/runtime/list", "not json", "application/json").status == 422, "bad json is 422"); + check(f.client->post("/agent/runtime/list", "{\"filter\":5}", "application/json").status == 422, "non-string filter is 422"); + check(f.client->post("/agent/runtime/list", "{\"filter\":\"" + std::string(600, 'f') + "\"}", "application/json").status == 422, "filter over cap is 422"); + check(f.client->post("/agent/runtime/list", std::string(300 * 1024, 'a'), "application/json").status == 413, "body over cap is 413"); + check(f.client->get("/agent/runtime/list").status == 405, "get is 405"); + check(rig.mock->send_count() == 0, "nothing reached Google"); + return finish("agent/runtime/list"); +} diff --git a/tests/example/agent/runtime/operation_test.cpp b/tests/example/agent/runtime/operation_test.cpp new file mode 100644 index 0000000..b6b39e7 --- /dev/null +++ b/tests/example/agent/runtime/operation_test.cpp @@ -0,0 +1,21 @@ +// Route: POST /agent/runtime/operation and /agent/runtime/async +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig rig(false); + Fixture f(rig.client); + auto op = f.client->post("/agent/runtime/operation", "{\"name\":\"projects/p/locations/l/operations/1\"}", "application/json"); + check(op.status == 503 && contains(op.body, "google_not_configured"), "operation: no credential is 503"); + check(f.client->post("/agent/runtime/operation", "{\"name\":\"../etc\"}", "application/json").status == 422, "operation: bad name is 422"); + check(f.client->post("/agent/runtime/operation", "{}", "application/json").status == 422, "operation: missing name is 422"); + auto as = f.client->post("/agent/runtime/async", "{\"id\":\"1\",\"inputGcsUri\":\"gs://in/q.json\",\"outputGcsUri\":\"gs://out/r.json\"}", "application/json"); + check(as.status == 503 && contains(as.body, "google_not_configured"), "async: no credential is 503"); + check(f.client->post("/agent/runtime/async", "{\"id\":\"1\",\"inputGcsUri\":\"http://x\",\"outputGcsUri\":\"gs://o\"}", "application/json").status == 422, "async: non gs uri is 422"); + check(f.client->get("/agent/runtime/operation").status == 405, "operation: get is 405"); + check(f.client->get("/agent/runtime/async").status == 405, "async: get is 405"); + check(rig.mock->send_count() == 0, "nothing reached Google"); + return finish("agent/runtime/operation"); +} diff --git a/tests/example/agent/runtime/page_test.cpp b/tests/example/agent/runtime/page_test.cpp new file mode 100644 index 0000000..47f2238 --- /dev/null +++ b/tests/example/agent/runtime/page_test.cpp @@ -0,0 +1,18 @@ +// Route: GET /agent/runtime (page, no credential needed) +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig rig(false); + Fixture f(rig.client); + auto res = f.client->get("/agent/runtime"); + check(res.status == 200, "status 200"); + check(contains(res.headers.get("Content-Type"), "text/html"), "html"); + check(contains(res.body, "Agent Runtime") && contains(res.body, "viewport"), "page and mobile viewport"); + check(contains(res.body, "/embedded/agent_runtime.js"), "script wired"); + check(f.client->post("/agent/runtime", "{}", "application/json").status == 405, "post is 405"); + check(rig.mock->send_count() == 0, "no network"); + return finish("agent/runtime"); +} diff --git a/tests/example/agent/runtime/query_test.cpp b/tests/example/agent/runtime/query_test.cpp new file mode 100644 index 0000000..0595547 --- /dev/null +++ b/tests/example/agent/runtime/query_test.cpp @@ -0,0 +1,20 @@ +// Route: POST /agent/runtime/query and /agent/runtime/stream +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig rig(false); + Fixture f(rig.client); + for (std::string route : {"/agent/runtime/query", "/agent/runtime/stream"}) { + auto res = f.client->post(route, "{\"id\":\"123\",\"input\":{\"message\":\"hi\"}}", "application/json"); + check(res.status == 503 && contains(res.body, "google_not_configured"), route + " no credential is 503"); + check(f.client->post(route, "{\"input\":{}}", "application/json").status == 422, route + " missing id is 422"); + check(f.client->post(route, "{\"id\":\"1\",\"input\":\"text\"}", "application/json").status == 422, route + " non-object input is 422"); + check(f.client->post(route, "{\"id\":\"1\",\"classMethod\":\"bad method\"}", "application/json").status == 422, route + " bad classMethod is 422"); + check(f.client->get(route).status == 405, route + " get is 405"); + } + check(rig.mock->send_count() == 0, "nothing reached Google"); + return finish("agent/runtime/query"); +} diff --git a/tests/example/agent/runtime/status_test.cpp b/tests/example/agent/runtime/status_test.cpp new file mode 100644 index 0000000..dfb95fc --- /dev/null +++ b/tests/example/agent/runtime/status_test.cpp @@ -0,0 +1,24 @@ +// Route: GET /agent/runtime/status and /agent/runtime/calls +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + GoogleRig off(false); + Fixture f(off.client); + auto res = f.client->get("/agent/runtime/status"); + check(res.status == 200, "status 200"); + check(contains(res.body, "\"configured\":false"), "reports no credential"); + check(contains(res.body, "\"project_set\":true"), "project read from env"); + auto calls = f.client->get("/agent/runtime/calls"); + check(calls.status == 200, "calls 200"); + check(contains(calls.body, "aiplatform.projects.locations.reasoningEngines.streamQuery"), "table lists streamQuery"); + check(contains(calls.body, "v1beta1/{+name}:query"), "table lists runtime revision query"); + GoogleRig on; + Fixture g(on.client); + check(contains(g.client->get("/agent/runtime/status").body, "\"configured\":true"), "reports credential"); + check(f.client->post("/agent/runtime/status", "{}", "application/json").status == 405, "post is 405"); + check(on.mock->send_count() == 0, "no network"); + return finish("agent/runtime/status"); +} diff --git a/tests/src/google/runtime/test_runtime.cpp b/tests/src/google/runtime/test_runtime.cpp new file mode 100644 index 0000000..02cce6d --- /dev/null +++ b/tests/src/google/runtime/test_runtime.cpp @@ -0,0 +1,316 @@ +// Agent Runtime: deterministic local tests (call table, request bodies, +// validation, caps, no-credential behavior) plus an opt-in live read-only +// check. No scripted Google replies: shapes are verified against Google's +// Discovery documents by src/google/runtime/tools/check_discovery.py and, +// where a credential allows, live (see src/google/runtime/SPEC.md). +#include +#include +#include + +#include "framework.h" +#include "clients/transports/http_transport.h" +#include "clients/transports/mock_transport.h" +#include "google/credentials.h" +#include "google/runtime/agent_runtime.h" +#include "google/runtime/calls.h" +#include "google/runtime/caps.h" + +using namespace molo::google; +using namespace molo::google::runtime; +using molo::clients::Method; +using molo::clients::body::Json; +using molo::clients::transports::MockTransport; + +namespace { + +// A runtime without credentials: any call that passes validation throws +// NotConfiguredError before network traffic, so validation is observable. +struct Rig { + MockTransport* mock; + std::unique_ptr rt; + Rig() { + auto t = std::make_unique(); + mock = t.get(); + auto client = std::make_shared(std::move(t), nullptr); + CloudContext ctx; + ctx.project = "p1"; + rt = std::make_unique(client, ctx); + } +}; + +EngineDraft draft() { + EngineDraft d; + d.display_name = "Support agent"; + d.spec.agent_framework = "google-adk"; + ContainerSpec c; + c.image_uri = "us-docker.pkg.dev/p1/r/agent:1"; + c.port = 8080; + d.spec.container = c; + DeploymentSpec dep; + dep.env.push_back({"MODE", "prod"}); + dep.secret_env.push_back({"API_KEY", "my-secret", "latest"}); + dep.min_instances = 1; + dep.max_instances = 10; + dep.container_concurrency = 9; + dep.cpu = "4"; + dep.memory = "8Gi"; + d.spec.deployment = dep; + d.spec.identity = IdentityType::kAgentIdentity; + d.spec.build_service_account = "build@p1.iam.gserviceaccount.com"; + d.kms_key_name = "projects/p1/locations/us-central1/keyRings/r/cryptoKeys/k"; + return d; +} + +template +bool invalid(F&& f) { + try { + f(); + } catch (const NotConfiguredError&) { + return false; // passed validation, stopped at the credential check + } catch (const GoogleError& e) { + return e.http_status() == 400 && e.status() == "INVALID_ARGUMENT"; + } + return false; +} +} // namespace + +TEST(runtime, call_table_paths) { + ASSERT_EQ(render(Call::kCreate, "projects/p/locations/l"), + "/projects/p/locations/l/reasoningEngines"); + ASSERT_EQ(render(Call::kQuery, "projects/p/locations/l/reasoningEngines/e"), + "/projects/p/locations/l/reasoningEngines/e:query"); + ASSERT_EQ(render(Call::kStreamQuery, "n"), "/n:streamQuery"); + ASSERT_EQ(render(Call::kGetIamPolicy, "n"), "/n:getIamPolicy"); + ASSERT_EQ(render(Call::kOperationList, "n"), "/n/operations"); + ASSERT_EQ(render(Call::kRevisionList, "n"), "/n/runtimeRevisions"); + ASSERT_TRUE(method_of(Call::kPatch) == Method::kPatch); + ASSERT_TRUE(method_of(Call::kDelete) == Method::kDelete); + ASSERT_EQ(endpoint_of(Call::kGet, "us-central1").base_url, + "https://us-central1-aiplatform.googleapis.com/v1"); + ASSERT_EQ(endpoint_of(Call::kRevisionGet, "us-central1").base_url, + "https://us-central1-aiplatform.googleapis.com/v1beta1"); +} + +TEST(runtime, create_body_matches_discovery_field_names) { + Json b = draft().to_json(); + ASSERT_EQ(b.find("displayName")->as_string(), "Support agent"); + ASSERT_TRUE(b.find("encryptionSpec")->find("kmsKeyName") != nullptr); + const Json* spec = b.find("spec"); + ASSERT_EQ(spec->find("agentFramework")->as_string(), "google-adk"); + ASSERT_EQ(spec->find("identityType")->as_string(), "AGENT_IDENTITY"); + ASSERT_EQ(spec->find("containerSpec")->find("port")->as_int(), 8080); + ASSERT_EQ(spec->find("buildSpec")->find("serviceAccount")->as_string(), + "build@p1.iam.gserviceaccount.com"); + const Json* dep = spec->find("deploymentSpec"); + ASSERT_EQ(dep->find("maxInstances")->as_int(), 10); + ASSERT_EQ(dep->find("containerConcurrency")->as_int(), 9); + ASSERT_EQ(dep->find("resourceLimits")->find("memory")->as_string(), "8Gi"); + ASSERT_EQ(dep->find("env")->as_array()[0].find("name")->as_string(), "MODE"); + ASSERT_EQ(dep->find("secretEnv")->as_array()[0].find("secretRef")->find("secret")->as_string(), + "my-secret"); +} + +TEST(runtime, spec_roundtrip_keeps_unknown_fields) { + Json doc = Json::parse( + "{\"name\":\"projects/p/locations/l/reasoningEngines/e1\",\"displayName\":\"x\"," + "\"spec\":{\"agentFramework\":\"custom\",\"futureField\":{\"a\":1}," + "\"effectiveIdentity\":\"agent://x\",\"deploymentSpec\":{\"keepAliveProbe\":{\"maxSeconds\":5}," + "\"agentServerMode\":\"STABLE\",\"minInstances\":2}}}"); + Engine e = Engine::from_json(doc); + ASSERT_EQ(e.id(), "e1"); + ASSERT_EQ(e.spec.effective_identity, "agent://x"); + Json out = e.spec.to_json(); + ASSERT_TRUE(out.find("futureField") != nullptr); + ASSERT_TRUE(out.find("effectiveIdentity") == nullptr); // output only + ASSERT_TRUE(out.find("deploymentSpec")->find("keepAliveProbe") != nullptr); + ASSERT_EQ(out.find("deploymentSpec")->find("agentServerMode")->as_string(), "STABLE"); +} + +TEST(runtime, update_mask_and_body) { + EngineUpdate u; + u.display_name = "New"; + EngineSpec s; + DeploymentSpec dep; + dep.max_instances = 20; + s.deployment = dep; + u.spec = s; + ASSERT_EQ(u.update_mask(), "displayName,spec.deploymentSpec"); + Json body = u.to_json(); + ASSERT_EQ(body.find("displayName")->as_string(), "New"); + ASSERT_TRUE(body.find("spec")->find("containerSpec") == nullptr); + EngineUpdate empty; + ASSERT_TRUE(invalid([&] { empty.to_json(); })); + EngineUpdate no_spec_fields; + no_spec_fields.spec = EngineSpec{}; + ASSERT_TRUE(invalid([&] { no_spec_fields.to_json(); })); +} + +TEST(runtime, query_body_shape) { + Json in = Json::object(); + in.set("message", Json("hi")); + Json b = AgentRuntime::query_body(in, "query"); + ASSERT_EQ(b.find("classMethod")->as_string(), "query"); + ASSERT_EQ(b.find("input")->find("message")->as_string(), "hi"); + ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(Json("str"), "query"); })); + ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(in, "bad method"); })); + ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(in, ""); })); +} + +TEST(runtime, ids_and_names_validated_before_network) { + Rig r; + Json in = Json::object(); + ASSERT_TRUE(invalid([&] { r.rt->get("../x"); })); + ASSERT_TRUE(invalid([&] { r.rt->get(""); })); + ASSERT_TRUE(invalid([&] { r.rt->get("a/b"); })); + ASSERT_TRUE(invalid([&] { r.rt->destroy("../x", false); })); + ASSERT_TRUE(invalid([&] { r.rt->get_revision("e1", "../r"); })); + ASSERT_TRUE(invalid([&] { r.rt->wait("../etc"); })); + ASSERT_TRUE(invalid([&] { r.rt->operation("operations/1"); })); + ASSERT_TRUE(invalid([&] { r.rt->cancel_operation("projects/p/../q"); })); + ASSERT_TRUE(invalid([&] { r.rt->cancel_async_query("e1", "x"); })); + ASSERT_TRUE(invalid([&] { r.rt->async_query("e1", "http://x", "gs://o"); })); + ASSERT_TRUE(invalid([&] { r.rt->async_query("e1", "gs://i", "gs://"); })); + ASSERT_TRUE(invalid([&] { r.rt->execute_code("e1", Json::array()); })); + ASSERT_TRUE(invalid([&] { r.rt->set_iam_policy("e1", Json("x")); })); + ASSERT_TRUE(invalid([&] { r.rt->get_iam_policy("e1", 9); })); + ASSERT_TRUE(invalid([&] { r.rt->test_iam_permissions("e1", {}); })); + ASSERT_TRUE(invalid([&] { r.rt->test_iam_permissions("e1", {"a b"}); })); + EngineDraft d = draft(); + d.display_name = ""; + ASSERT_TRUE(invalid([&] { r.rt->create_start(d); })); + ASSERT_EQ(r.mock->send_count(), 0u); +} + +TEST(runtime, spec_rules) { + EngineDraft d = draft(); + d.spec.service_account = "sa@p1.iam.gserviceaccount.com"; // with AGENT_IDENTITY + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d = draft(); + d.spec.identity = IdentityType::kServiceAccount; + d.spec.service_account = "not-an-email"; + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d.spec.service_account = "sa@p1.iam.gserviceaccount.com"; + d.to_json(); // valid + d = draft(); + d.spec.package = PackageSpec{}; // container and package together + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d = draft(); + d.spec.container = std::nullopt; + PackageSpec p; + p.python_version = "2.7"; + d.spec.package = p; + ASSERT_TRUE(invalid([&] { d.to_json(); })); + p.python_version = "3.12"; + p.requirements_gcs_uri = "https://x/r.txt"; + d.spec.package = p; + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d = draft(); + d.spec.agent_framework = "magic"; + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d = draft(); + d.spec.container->port = 70000; + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d = draft(); + d.spec.container->image_uri = ""; + ASSERT_TRUE(invalid([&] { d.to_json(); })); +} + +TEST(runtime, deployment_caps) { + auto bad = [](auto mutate) { + EngineDraft d = draft(); + mutate(*d.spec.deployment); + return invalid([&] { d.to_json(); }); + }; + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.max_instances = 1001; })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.max_instances = 0; })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.min_instances = 76; })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.min_instances = 11; })); // above max 10 + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.container_concurrency = 0; })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.cpu = "3"; })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.memory = "33Gi"; })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.memory = "8GB"; })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.env.push_back({"MODE", "dup"}); })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { s.env.push_back({"1BAD", "x"}); })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { + s.env.push_back({"BIG", std::string(RuntimeCaps::kMaxEnvValueChars + 1, 'a')}); + })); + ASSERT_TRUE(bad([](DeploymentSpec& s) { + for (std::size_t i = 0; i < RuntimeCaps::kMaxEnvVars; ++i) + s.env.push_back({"V" + std::to_string(i), "x"}); + })); + EngineDraft d = draft(); + d.description = std::string(RuntimeCaps::kMaxDescription + 1, 'a'); + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d = draft(); + d.display_name = std::string(RuntimeCaps::kMaxDisplayName + 1, 'a'); + ASSERT_TRUE(invalid([&] { d.to_json(); })); + d = draft(); + for (std::size_t i = 0; i < RuntimeCaps::kMaxLabels + 1; ++i) d.labels["k" + std::to_string(i)] = "v"; + ASSERT_TRUE(invalid([&] { d.to_json(); })); + Json big = Json::object(); + big.set("m", Json(std::string(RuntimeCaps::kMaxInputBytes + 1, 'a'))); + ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(big, "query"); })); + Rig r; + ASSERT_TRUE(invalid([&] { r.rt->list(std::string(RuntimeCaps::kMaxFilterChars + 1, 'f')); })); +} + +TEST(runtime, no_credential_is_loud_and_offline) { + Rig r; + try { + r.rt->get("e1"); + FAIL("must throw"); + } catch (const NotConfiguredError& e) { + ASSERT_EQ(e.http_status(), 503); + } + ASSERT_THROW(r.rt->list(), NotConfiguredError); + ASSERT_THROW(r.rt->destroy("e1", true), NotConfiguredError); + ASSERT_EQ(r.mock->send_count(), 0u); +} + +TEST(runtime, identity_and_secret_env_roundtrip) { + DeploymentSpec d; + d.secret_env.push_back({"API_KEY", "my-secret", "latest"}); + d.container_concurrency = 5; + d.validate(); + DeploymentSpec back = DeploymentSpec::from_json(d.to_json()); + ASSERT_EQ(back.secret_env.size(), 1u); + ASSERT_EQ(back.secret_env[0].secret, "my-secret"); + ASSERT_EQ(*back.container_concurrency, 5); + ASSERT_TRUE(identity_type_from("SERVICE_ACCOUNT") == IdentityType::kServiceAccount); + ASSERT_TRUE(identity_type_from("nonsense") == IdentityType::kUnspecified); +} + +// Live, read-only. Needs MOLO_LIVE_NET=1, GOOGLE_CLOUD_PROJECT and a +// credential (an express key AQ... is enough for these reads). Never creates, +// updates or deletes anything. +TEST(runtime_live, read_only_calls) { + CloudContext ctx = CloudContext::from_env(); + auto client = GoogleClient::from_env(); + if (!std::getenv("MOLO_LIVE_NET") || !client->configured() || ctx.project.empty()) { + std::cout << "SKIP runtime_live.read_only_calls (set MOLO_LIVE_NET=1, GOOGLE_CLOUD_PROJECT " + "and a Google credential)\n"; + return; + } + ctx.location = "us-central1"; + AgentRuntime rt(client, ctx); + auto engines = rt.list(); + std::cout << " engines in us-central1: " << engines.size() << "\n"; + // A missing engine must map to a typed NOT_FOUND-style error, not a crash. + try { + rt.get("1234567890123"); + FAIL("a missing engine must not be found"); + } catch (const GoogleError& e) { + std::cout << " get missing: " << e.http_status() << " " << e.status() << "\n"; + ASSERT_TRUE(e.http_status() == 404 || e.http_status() == 403 || e.http_status() == 400); + } + try { + rt.query("1234567890123", Json::object()); + FAIL("a missing engine must not answer a query"); + } catch (const GoogleError& e) { + std::cout << " query missing: " << e.http_status() << " " << e.status() << "\n"; + ASSERT_TRUE(e.http_status() >= 400 && e.http_status() < 500); + } + ctx.location = "europe-west4"; + AgentRuntime eu(client, ctx); + std::cout << " engines in europe-west4: " << eu.list().size() << "\n"; +}