feat(clients): google foundation for the agent platform: all-verb client, streaming, typed Gemini content, operations

GoogleClient gets every verb and stream_json (SSE and plain JSON), typed
Content/Part/Tool/GenerateRequest with the LanguageModel seam, CloudContext
resource names, long-running operation polling and pagination, OAuth bearer
tokens via GOOGLE_ACCESS_TOKEN. Example scaffold: one stub per agent module
under example/app/agent, wildcard builds, locust excludes /voice /google
/agent. plans/16-agent-platform.md splits the work into nine modules.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 04:12:52 +02:00
co-authored by Claude Sonnet 5.5
parent 837de58136
commit 6d744a433f
32 changed files with 1536 additions and 22 deletions
+3 -1
View File
@@ -50,7 +50,9 @@ client, credentials, errors, or caps.
below follow the same order.
The key travels in the `x-goog-api-key` header, never in the URL, so it
never reaches a span, log line, or proxy URL. Bearer tokens (OAuth, for
APIs that refuse keys) use the same seam: `Credentials::bearer`.
APIs that refuse keys) use the same seam: `Credentials::bearer`; a
`GOOGLE_ACCESS_TOKEN` (same lookup order) takes precedence over a key.
Tokens expire after about an hour; refresh is the caller's job (gap).
- No key: `configured()` is false and every call throws `NotConfiguredError`
(HTTP 503, status `NOT_CONFIGURED`) before any network traffic. Loud, not
silent.
+41 -6
View File
@@ -2,6 +2,7 @@
#include "clients/transports/http_transport.h"
#include "google/credentials.h"
#include "google/stream_decoder.h"
namespace molo::google {
@@ -25,13 +26,16 @@ std::shared_ptr<GoogleClient> GoogleClient::from_env() {
Credentials::from_env());
}
clients::body::Json GoogleClient::post_json(const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json& body) {
clients::body::Json GoogleClient::request(clients::Method method,
const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json* body) {
if (!configured_) throw NotConfiguredError(service.name);
try {
return finish(service, client_.post_json_blocking(
service.base_url + path, body));
clients::ClientRequest req(method,
clients::Url::parse(service.base_url + path));
if (body) req.json(*body);
return finish(service, client_.send_blocking(std::move(req)));
} catch (const GoogleError&) {
throw;
} catch (const std::exception& e) {
@@ -39,11 +43,42 @@ clients::body::Json GoogleClient::post_json(const ServiceEndpoint& service,
}
}
clients::body::Json GoogleClient::post_json(const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json& body) {
return request(clients::Method::kPost, service, path, &body);
}
clients::body::Json GoogleClient::patch_json(const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json& body) {
return request(clients::Method::kPatch, service, path, &body);
}
clients::body::Json GoogleClient::get_json(const ServiceEndpoint& service,
const std::string& path) {
return request(clients::Method::kGet, service, path, nullptr);
}
clients::body::Json GoogleClient::delete_json(const ServiceEndpoint& service,
const std::string& path) {
return request(clients::Method::kDelete, service, path, nullptr);
}
void GoogleClient::stream_json(const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json& body,
const EventSink& sink) {
if (!configured_) throw NotConfiguredError(service.name);
StreamDecoder decoder(service.name, sink);
try {
return finish(service, client_.get_blocking(service.base_url + path));
clients::ClientRequest req(
clients::Method::kPost, clients::Url::parse(service.base_url + path));
req.json(body);
client_.send_stream_blocking(
std::move(req),
[&](const std::string& chunk) { return decoder.feed(chunk); });
decoder.finish();
} catch (const GoogleError&) {
throw;
} catch (const std::exception& e) {
+19
View File
@@ -4,6 +4,7 @@
// sends JSON, maps failures to GoogleError. Runs over any clients::Transport
// (HttpTransport in production, MockTransport in tests).
#include <functional>
#include <memory>
#include <string>
@@ -26,11 +27,29 @@ class GoogleClient {
bool configured() const { return configured_; }
// One entry point for every verb; the helpers below delegate to it.
// body may be null (GET, DELETE).
clients::body::Json request(clients::Method method,
const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json* body = nullptr);
clients::body::Json post_json(const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json& body);
clients::body::Json patch_json(const ServiceEndpoint& service,
const std::string& path,
const clients::body::Json& body);
clients::body::Json get_json(const ServiceEndpoint& service,
const std::string& path);
clients::body::Json delete_json(const ServiceEndpoint& service,
const std::string& path);
// Streaming POST. Decodes SSE ("?alt=sse") and plain JSON bodies into
// events; sink returns false to stop early. An error body (Google's
// {"error":...}) throws GoogleError. Total streamed bytes are capped.
using EventSink = std::function<bool(const clients::body::Json&)>;
void stream_json(const ServiceEndpoint& service, const std::string& path,
const clients::body::Json& body, const EventSink& sink);
clients::ClientStatsSnapshot stats() const { return client_.stats(); }
+4
View File
@@ -47,6 +47,10 @@ std::string Credentials::env(const char* name) {
}
std::shared_ptr<clients::Auth> Credentials::from_env(const char* name) {
// An OAuth access token (GOOGLE_ACCESS_TOKEN, e.g. from
// `gcloud auth print-access-token`) wins: Agent Platform APIs need it.
std::string token = env("GOOGLE_ACCESS_TOKEN");
if (!token.empty()) return bearer(std::move(token));
std::string key = env(name);
if (key.empty()) return nullptr;
return api_key(std::move(key));
+284
View File
@@ -0,0 +1,284 @@
#include "google/gemini_types.h"
#include "security/crypto/Base64.h"
namespace molo::google {
using clients::body::Json;
using security::crypto::Base64;
namespace {
std::string str_of(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_string() ? v->as_string() : "";
}
int int_of(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_number() ? static_cast<int>(v->as_int()) : 0;
}
} // namespace
Part Part::of_text(std::string text) {
Part p;
p.text = std::move(text);
return p;
}
Part Part::of_inline(std::string mime, std::string bytes) {
Part p;
p.inline_data = InlineData{std::move(mime), std::move(bytes)};
return p;
}
Part Part::of_file(std::string mime, std::string uri) {
Part p;
p.file_data = FileData{std::move(mime), std::move(uri)};
return p;
}
Part Part::of_call(FunctionCall call) {
Part p;
p.function_call = std::move(call);
return p;
}
Part Part::of_response(FunctionResponse response) {
Part p;
p.function_response = std::move(response);
return p;
}
Json Part::to_json() const {
Json out = Json::object();
if (inline_data) {
Json d = Json::object();
d.set("mimeType", Json(inline_data->mime));
d.set("data", Json(Base64::encode(inline_data->data)));
out.set("inlineData", d);
} else if (file_data) {
Json d = Json::object();
d.set("mimeType", Json(file_data->mime));
d.set("fileUri", Json(file_data->uri));
out.set("fileData", d);
} else if (function_call) {
Json d = Json::object();
d.set("name", Json(function_call->name));
d.set("args", function_call->args);
if (!function_call->id.empty()) d.set("id", Json(function_call->id));
out.set("functionCall", d);
} else if (function_response) {
Json d = Json::object();
d.set("name", Json(function_response->name));
d.set("response", function_response->response);
if (!function_response->id.empty()) d.set("id", Json(function_response->id));
out.set("functionResponse", d);
} else {
out.set("text", Json(text));
}
if (thought) out.set("thought", Json(true));
return out;
}
Part Part::from_json(const Json& doc) {
Part p;
p.text = str_of(doc, "text");
if (const Json* t = doc.find("thought"); t && t->is_bool()) p.thought = t->as_bool();
if (const Json* d = doc.find("inlineData"); d && d->is_object()) {
std::string raw;
Base64::decode(str_of(*d, "data"), raw);
p.inline_data = InlineData{str_of(*d, "mimeType"), std::move(raw)};
}
if (const Json* d = doc.find("fileData"); d && d->is_object())
p.file_data = FileData{str_of(*d, "mimeType"), str_of(*d, "fileUri")};
if (const Json* d = doc.find("functionCall"); d && d->is_object()) {
FunctionCall c;
c.name = str_of(*d, "name");
c.id = str_of(*d, "id");
if (const Json* a = d->find("args"); a && a->is_object()) c.args = *a;
p.function_call = std::move(c);
}
if (const Json* d = doc.find("functionResponse"); d && d->is_object()) {
FunctionResponse r;
r.name = str_of(*d, "name");
r.id = str_of(*d, "id");
if (const Json* a = d->find("response"); a && a->is_object()) r.response = *a;
p.function_response = std::move(r);
}
return p;
}
Content Content::user(std::string text) {
Content c;
c.role = "user";
c.parts.push_back(Part::of_text(std::move(text)));
return c;
}
Content Content::model(std::string text) {
Content c;
c.role = "model";
c.parts.push_back(Part::of_text(std::move(text)));
return c;
}
std::string Content::text() const {
std::string out;
for (const Part& p : parts)
if (!p.thought && !p.inline_data && !p.file_data && !p.function_call &&
!p.function_response)
out += p.text;
return out;
}
Json Content::to_json() const {
Json out = Json::object();
if (!role.empty()) out.set("role", Json(role));
Json arr = Json::array();
for (const Part& p : parts) arr.push(p.to_json());
out.set("parts", arr);
return out;
}
Content Content::from_json(const Json& doc) {
Content c;
c.role = str_of(doc, "role");
if (const Json* parts = doc.find("parts"); parts && parts->is_array())
for (const Json& p : parts->as_array()) c.parts.push_back(Part::from_json(p));
return c;
}
Json FunctionDeclaration::to_json() const {
Json out = Json::object();
out.set("name", Json(name));
out.set("description", Json(description));
if (!parameters.is_null()) out.set("parameters", parameters);
return out;
}
Json Tool::to_json() const {
Json out = Json::object();
if (!functions.empty()) {
Json arr = Json::array();
for (const auto& f : functions) arr.push(f.to_json());
out.set("functionDeclarations", arr);
}
if (google_search) out.set("googleSearch", Json::object());
if (code_execution) out.set("codeExecution", Json::object());
if (extra.is_object())
for (const auto& [k, v] : extra.as_object()) out.set(k, v);
return out;
}
Json GenerateConfig::to_json() const {
Json out = Json::object();
if (temperature) out.set("temperature", Json(*temperature));
if (top_p) out.set("topP", Json(*top_p));
if (top_k) out.set("topK", Json(*top_k));
if (max_output_tokens) out.set("maxOutputTokens", Json(*max_output_tokens));
if (candidate_count) out.set("candidateCount", Json(*candidate_count));
if (thinking_budget) {
Json t = Json::object();
t.set("thinkingBudget", Json(*thinking_budget));
out.set("thinkingConfig", t);
}
if (!stop_sequences.empty()) {
Json a = Json::array();
for (const auto& s : stop_sequences) a.push(Json(s));
out.set("stopSequences", a);
}
if (!response_modalities.empty()) {
Json a = Json::array();
for (const auto& s : response_modalities) a.push(Json(s));
out.set("responseModalities", a);
}
if (!response_mime_type.empty()) out.set("responseMimeType", Json(response_mime_type));
if (!response_schema.is_null()) out.set("responseSchema", response_schema);
if (!voice_name.empty()) {
Json prebuilt = Json::object();
prebuilt.set("voiceName", Json(voice_name));
Json vc = Json::object();
vc.set("prebuiltVoiceConfig", prebuilt);
Json sc = Json::object();
sc.set("voiceConfig", vc);
out.set("speechConfig", sc);
}
return out;
}
Json GenerateRequest::to_json() const {
Json out = Json::object();
Json arr = Json::array();
for (const Content& c : contents) arr.push(c.to_json());
out.set("contents", arr);
if (system) {
Content s = *system;
s.role.clear();
out.set("systemInstruction", s.to_json());
}
if (!tools.empty()) {
Json t = Json::array();
for (const Tool& tool : tools) t.push(tool.to_json());
out.set("tools", t);
}
if (!tool_mode.empty()) {
Json fcc = Json::object();
fcc.set("mode", Json(tool_mode));
if (!allowed_functions.empty()) {
Json names = Json::array();
for (const auto& n : allowed_functions) names.push(Json(n));
fcc.set("allowedFunctionNames", names);
}
Json tc = Json::object();
tc.set("functionCallingConfig", fcc);
out.set("toolConfig", tc);
}
Json gc = config.to_json();
if (!gc.as_object().empty()) out.set("generationConfig", gc);
if (!safety.empty()) {
Json s = Json::array();
for (const auto& x : safety) {
Json one = Json::object();
one.set("category", Json(x.category));
one.set("threshold", Json(x.threshold));
s.push(one);
}
out.set("safetySettings", s);
}
return out;
}
UsageMetadata UsageMetadata::from_json(const Json& doc) {
UsageMetadata u;
u.prompt_tokens = int_of(doc, "promptTokenCount");
u.candidates_tokens = int_of(doc, "candidatesTokenCount");
u.total_tokens = int_of(doc, "totalTokenCount");
u.thoughts_tokens = int_of(doc, "thoughtsTokenCount");
return u;
}
std::string GenerateResponse::text() const {
return candidates.empty() ? "" : candidates.front().content.text();
}
std::vector<FunctionCall> GenerateResponse::function_calls() const {
std::vector<FunctionCall> out;
if (!candidates.empty())
for (const Part& p : candidates.front().content.parts)
if (p.function_call) out.push_back(*p.function_call);
return out;
}
GenerateResponse GenerateResponse::from_json(const Json& doc) {
GenerateResponse r;
if (const Json* cs = doc.find("candidates"); cs && cs->is_array())
for (const Json& c : cs->as_array()) {
Candidate cand;
if (const Json* content = c.find("content"); content && content->is_object())
cand.content = Content::from_json(*content);
cand.finish_reason = str_of(c, "finishReason");
if (const Json* g = c.find("groundingMetadata")) cand.grounding_metadata = *g;
if (const Json* g = c.find("safetyRatings")) cand.safety_ratings = *g;
r.candidates.push_back(std::move(cand));
}
if (const Json* u = doc.find("usageMetadata"); u && u->is_object())
r.usage = UsageMetadata::from_json(*u);
r.model_version = str_of(doc, "modelVersion");
if (const Json* f = doc.find("promptFeedback")) r.prompt_feedback = *f;
return r;
}
} // namespace molo::google
+152
View File
@@ -0,0 +1,152 @@
#pragma once
// Typed Gemini content model shared by every agent-platform module: Part,
// Content, tools, GenerateRequest/Response, and the LanguageModel seam that
// agents (ADK), the Live API, evaluation and sessions code against. Wire
// names follow the Vertex AI / Gemini REST schema (camelCase).
#include <functional>
#include <optional>
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::google {
struct InlineData {
std::string mime;
std::string data; // Raw bytes (base64 only on the wire).
};
struct FileData {
std::string mime;
std::string uri; // gs:// or https://
};
struct FunctionCall {
std::string name;
clients::body::Json args = clients::body::Json::object();
std::string id;
};
struct FunctionResponse {
std::string name;
clients::body::Json response = clients::body::Json::object();
std::string id;
};
struct Part {
std::string text;
bool thought = false;
std::optional<InlineData> inline_data;
std::optional<FileData> file_data;
std::optional<FunctionCall> function_call;
std::optional<FunctionResponse> function_response;
static Part of_text(std::string text);
static Part of_inline(std::string mime, std::string bytes);
static Part of_file(std::string mime, std::string uri);
static Part of_call(FunctionCall call);
static Part of_response(FunctionResponse response);
clients::body::Json to_json() const;
static Part from_json(const clients::body::Json& doc);
};
struct Content {
std::string role; // "user" | "model" | "" (system instruction)
std::vector<Part> parts;
static Content user(std::string text);
static Content model(std::string text);
std::string text() const; // Concatenated non-thought text parts.
clients::body::Json to_json() const;
static Content from_json(const clients::body::Json& doc);
};
struct FunctionDeclaration {
std::string name;
std::string description;
clients::body::Json parameters; // OpenAPI-subset schema; null: no params.
clients::body::Json to_json() const;
};
struct Tool {
std::vector<FunctionDeclaration> functions;
bool google_search = false;
bool code_execution = false;
clients::body::Json extra; // Raw extra tool fields (retrieval, urlContext...).
clients::body::Json to_json() const;
};
struct SafetySetting {
std::string category; // HARM_CATEGORY_*
std::string threshold; // BLOCK_*
};
struct GenerateConfig {
std::optional<double> temperature;
std::optional<double> top_p;
std::optional<int> top_k;
std::optional<int> max_output_tokens;
std::optional<int> candidate_count;
std::optional<int> thinking_budget; // 0: no thinking.
std::vector<std::string> stop_sequences;
std::vector<std::string> response_modalities; // "TEXT", "AUDIO", "IMAGE"
std::string response_mime_type; // e.g. application/json
clients::body::Json response_schema; // null: none
std::string voice_name; // speechConfig prebuilt voice
clients::body::Json to_json() const;
};
struct GenerateRequest {
std::string model; // Path component, not part of the body.
std::optional<Content> system;
std::vector<Content> contents;
std::vector<Tool> tools;
std::string tool_mode; // "", "AUTO", "ANY", "NONE"
std::vector<std::string> allowed_functions;
GenerateConfig config;
std::vector<SafetySetting> safety;
clients::body::Json to_json() const; // Body for :generateContent.
};
struct UsageMetadata {
int prompt_tokens = 0;
int candidates_tokens = 0;
int total_tokens = 0;
int thoughts_tokens = 0;
static UsageMetadata from_json(const clients::body::Json& doc);
};
struct Candidate {
Content content;
std::string finish_reason;
clients::body::Json grounding_metadata;
clients::body::Json safety_ratings;
};
struct GenerateResponse {
std::vector<Candidate> candidates;
UsageMetadata usage;
std::string model_version;
clients::body::Json prompt_feedback;
std::string text() const; // First candidate's text.
std::vector<FunctionCall> function_calls() const; // First candidate's calls.
static GenerateResponse from_json(const clients::body::Json& doc);
};
// The seam agents code against. Vertex/Gemini implement it; tests fake it.
class LanguageModel {
public:
virtual ~LanguageModel() = default;
virtual GenerateResponse generate(const GenerateRequest& request) = 0;
// Calls on_chunk per streamed response; return false to stop.
virtual void stream(const GenerateRequest& request,
const std::function<bool(const GenerateResponse&)>& on_chunk) = 0;
};
} // namespace molo::google
+4 -2
View File
@@ -11,9 +11,11 @@ CLIENTS_LIB ?= $(ROOT)/build/clients/libclients.a
OPERABILITY_LIB ?= build/liboperability.a
GOOGLE_INCS := -I$(ROOT)/src -I$(ROOT)/tests/src/clients
GOOGLE_SRCS := $(sort $(wildcard $(ROOT)/src/google/*.cpp)) \
# Recursive: every module under src/google/<module>/ builds without editing
# this file.
GOOGLE_SRCS := $(sort $(shell find $(ROOT)/src/google -name "*.cpp")) \
$(ROOT)/src/security/crypto/Base64.cpp
GOOGLE_TEST_SRCS := $(sort $(wildcard $(ROOT)/tests/src/google/*.cpp))
GOOGLE_TEST_SRCS := $(sort $(shell find $(ROOT)/tests/src/google -name "*.cpp"))
GOOGLE_BUILD := $(ROOT)/build/google
GOOGLE_OBJDIR := $(GOOGLE_BUILD)/objs
+71
View File
@@ -0,0 +1,71 @@
#include "google/operation.h"
#include <thread>
#include "google/errors.h"
namespace molo::google {
using clients::body::Json;
Operation Operation::from_json(const Json& doc) {
Operation op;
if (const Json* v = doc.find("name"); v && v->is_string()) op.name = v->as_string();
if (const Json* v = doc.find("done"); v && v->is_bool()) op.done = v->as_bool();
if (const Json* v = doc.find("response")) op.response = *v;
if (const Json* v = doc.find("metadata")) op.metadata = *v;
if (const Json* e = doc.find("error"); e && e->is_object()) {
const Json* c = e->find("code");
op.error_code = c && c->is_number() ? static_cast<int>(c->as_int()) : 2;
if (op.error_code == 0) op.error_code = 2;
const Json* m = e->find("message");
op.error_message = m && m->is_string() ? m->as_string() : "operation failed";
}
return op;
}
Operation wait_operation(GoogleClient& client, const ServiceEndpoint& endpoint,
const std::string& operation_name, const Sleeper& sleeper) {
if (operation_name.empty() || operation_name.find("..") != std::string::npos)
throw GoogleError::invalid("bad operation name");
Sleeper sleep = sleeper ? sleeper : [](std::chrono::milliseconds d) {
std::this_thread::sleep_for(d);
};
std::chrono::milliseconds waited{0};
for (std::size_t i = 0; i < OperationCaps::kMaxPolls; ++i) {
Operation op = Operation::from_json(client.get_json(endpoint, "/" + operation_name));
if (op.done) {
if (op.failed())
throw GoogleError(502, "OPERATION_FAILED", op.error_message, endpoint.name);
return op;
}
if (waited >= OperationCaps::kMaxWait) break;
sleep(OperationCaps::kInterval);
waited += OperationCaps::kInterval;
}
throw GoogleError(504, "DEADLINE_EXCEEDED",
"operation still running at the wait cap: " + operation_name,
endpoint.name);
}
Json list_all(GoogleClient& client, const ServiceEndpoint& endpoint,
const std::string& path, const std::string& items_key,
std::size_t max_pages) {
Json items = Json::array();
std::string token;
for (std::size_t page = 0; page < max_pages; ++page) {
std::string url = path;
if (!token.empty())
url += (path.find('?') == std::string::npos ? "?" : "&") +
std::string("pageToken=") + clients::Url::encode_component(token);
Json reply = client.get_json(endpoint, url);
if (const Json* arr = reply.find(items_key); arr && arr->is_array())
for (const Json& item : arr->as_array()) items.push(item);
const Json* next = reply.find("nextPageToken");
if (!next || !next->is_string() || next->as_string().empty()) break;
token = next->as_string();
}
return items;
}
} // namespace molo::google
+48
View File
@@ -0,0 +1,48 @@
#pragma once
// Long-running operations (google.longrunning) and pagination, shared by
// every module that creates, deletes or lists Cloud resources.
#include <chrono>
#include <functional>
#include <string>
#include <vector>
#include "google/client.h"
namespace molo::google {
struct Operation {
std::string name; // projects/.../operations/{id}
bool done = false;
clients::body::Json response; // Set when done and successful.
clients::body::Json metadata;
int error_code = 0; // google.rpc.Status, 0: no error
std::string error_message;
bool failed() const { return error_code != 0; }
static Operation from_json(const clients::body::Json& doc);
};
struct OperationCaps {
static constexpr std::chrono::seconds kMaxWait{600};
static constexpr std::chrono::milliseconds kInterval{2000};
static constexpr std::size_t kMaxPolls = 400;
};
using Sleeper = std::function<void(std::chrono::milliseconds)>;
// Polls GET {name} on the given endpoint until done. Throws GoogleError
// (status DEADLINE_EXCEEDED) at the cap and (status from the operation, or
// UNKNOWN) when the operation failed. `sleeper` is injectable for tests.
Operation wait_operation(GoogleClient& client, const ServiceEndpoint& endpoint,
const std::string& operation_name,
const Sleeper& sleeper = nullptr);
// Follows nextPageToken. `path` may already hold a query string. Collects
// `items_key` arrays into one Json array; stops at max_pages (default 100).
clients::body::Json list_all(GoogleClient& client, const ServiceEndpoint& endpoint,
const std::string& path, const std::string& items_key,
std::size_t max_pages = 100);
} // namespace molo::google
+83
View File
@@ -0,0 +1,83 @@
#include "google/resource.h"
#include "google/credentials.h"
#include "google/errors.h"
namespace molo::google {
namespace {
bool valid_project(const std::string& p) {
if (p.empty() || p.size() > 128) return false;
for (char c : p)
if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' ||
c == '.' || c == ':'))
return false;
return true;
}
bool valid_location(const std::string& l) {
if (l.empty() || l.size() > 64) return false;
for (char c : l)
if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-')) return false;
return true;
}
} // namespace
bool valid_segment(const std::string& id) {
if (id.empty() || id.size() > 128) return false;
for (char c : id)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
(c >= '0' && c <= '9') || c == '-' || c == '_' || c == '.'))
return false;
return id != "." && id != "..";
}
CloudContext CloudContext::from_env() {
CloudContext c;
c.project = Credentials::env("GOOGLE_CLOUD_PROJECT");
std::string loc = Credentials::env("GOOGLE_CLOUD_LOCATION");
if (!loc.empty()) c.location = loc;
return c;
}
bool CloudContext::valid() const {
return valid_project(project) && valid_location(location);
}
std::string CloudContext::parent() const {
if (!valid_project(project))
throw GoogleError::invalid("GOOGLE_CLOUD_PROJECT is missing or malformed");
if (!valid_location(location))
throw GoogleError::invalid("GOOGLE_CLOUD_LOCATION is malformed");
return "projects/" + project + "/locations/" + location;
}
std::string CloudContext::child(const std::string& collection,
const std::string& id) const {
if (!valid_segment(collection) || !valid_segment(id))
throw GoogleError::invalid("bad resource id");
return parent() + "/" + collection + "/" + id;
}
namespace endpoints {
ServiceEndpoint aiplatform(const std::string& location) {
if (location == "global" || location.empty())
return {"aiplatform", "https://aiplatform.googleapis.com/v1"};
if (!valid_location(location)) throw GoogleError::invalid("bad location");
return {"aiplatform", "https://" + location + "-aiplatform.googleapis.com/v1"};
}
ServiceEndpoint aiplatform_beta(const std::string& location) {
ServiceEndpoint e = aiplatform(location);
e.name = "aiplatform-beta";
e.base_url.replace(e.base_url.size() - 2, 2, "v1beta1");
return e;
}
ServiceEndpoint custom(std::string name, std::string base_url) {
return {std::move(name), std::move(base_url)};
}
} // namespace endpoints
} // namespace molo::google
+37
View File
@@ -0,0 +1,37 @@
#pragma once
// Cloud resource naming shared by every Vertex AI / Agent Platform module.
// Env: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION (default us-central1).
#include <string>
#include "google/endpoints.h"
namespace molo::google {
struct CloudContext {
std::string project;
std::string location = "us-central1";
static CloudContext from_env();
bool valid() const; // project set and both parts well formed
// "projects/{project}/locations/{location}"; throws GoogleError (invalid)
// when the project is empty or contains characters outside [a-z0-9.:-].
std::string parent() const;
// parent() + "/" + collection + "/" + id, id validated like a path segment.
std::string child(const std::string& collection, const std::string& id) const;
};
// True for a single URL path segment: 1..128 of [A-Za-z0-9._-].
bool valid_segment(const std::string& id);
namespace endpoints {
// https://{location}-aiplatform.googleapis.com/v1 ("global": no prefix).
ServiceEndpoint aiplatform(const std::string& location);
// Same host family, beta surface.
ServiceEndpoint aiplatform_beta(const std::string& location);
// Any other Google API host, e.g. custom("modelarmor", "https://modelarmor.us.rep.googleapis.com/v1").
ServiceEndpoint custom(std::string name, std::string base_url);
} // namespace endpoints
} // namespace molo::google
+14
View File
@@ -14,6 +14,20 @@ clients::body::Json Service::fetch(const std::string& path) const {
return client_->get_json(endpoint_, path);
}
clients::body::Json Service::patch(const std::string& path,
const clients::body::Json& body) const {
return client_->patch_json(endpoint_, path, body);
}
clients::body::Json Service::remove(const std::string& path) const {
return client_->delete_json(endpoint_, path);
}
void Service::stream(const std::string& path, const clients::body::Json& body,
const GoogleClient::EventSink& sink) const {
client_->stream_json(endpoint_, path, body, sink);
}
std::string Service::string_at(const clients::body::Json& doc,
const std::string& key,
const std::string& fallback) {
+5
View File
@@ -23,6 +23,11 @@ class Service {
clients::body::Json call(const std::string& path,
const clients::body::Json& body) const;
clients::body::Json fetch(const std::string& path) const;
clients::body::Json patch(const std::string& path,
const clients::body::Json& body) const;
clients::body::Json remove(const std::string& path) const;
void stream(const std::string& path, const clients::body::Json& body,
const GoogleClient::EventSink& sink) const;
// Tolerant readers for response documents.
static std::string string_at(const clients::body::Json& doc,
+109
View File
@@ -0,0 +1,109 @@
#include "google/stream_decoder.h"
#include "google/errors.h"
namespace molo::google {
using clients::body::Json;
StreamDecoder::StreamDecoder(std::string service, Sink sink)
: service_(std::move(service)), sink_(std::move(sink)) {}
bool StreamDecoder::emit(const Json& event) {
if (!sink_(event)) stopped_ = true;
return !stopped_;
}
bool StreamDecoder::dispatch_sse_block(const std::string& block) {
std::string data;
std::size_t pos = 0;
while (pos <= block.size()) {
std::size_t eol = block.find('\n', pos);
std::string line = block.substr(pos, eol == std::string::npos ? eol : eol - pos);
if (!line.empty() && line.back() == '\r') line.pop_back();
if (line.rfind("data:", 0) == 0) {
std::string v = line.substr(5);
if (!v.empty() && v.front() == ' ') v.erase(0, 1);
if (!data.empty()) data += "\n";
data += v;
}
if (eol == std::string::npos) break;
pos = eol + 1;
}
if (data.empty() || data == "[DONE]") return true;
Json event;
try {
event = Json::parse(data);
} catch (const std::exception& e) {
throw GoogleError(502, "BAD_RESPONSE", std::string("bad stream event: ") + e.what(), service_);
}
if (const Json* err = event.is_object() ? event.find("error") : nullptr; err)
throw GoogleError(502, "STREAM_ERROR", err->dump(), service_);
return emit(event);
}
bool StreamDecoder::feed(const std::string& chunk) {
if (stopped_) return false;
total_ += chunk.size();
if (total_ > kMaxBytes)
throw GoogleError(502, "BAD_RESPONSE", "stream over the byte cap", service_);
buffer_ += chunk;
if (!decided_) {
std::size_t first = buffer_.find_first_not_of(" \t\r\n");
if (first == std::string::npos) return true;
sse_ = buffer_[first] != '{' && buffer_[first] != '[';
decided_ = true;
}
if (!sse_) return true; // Plain JSON: parsed whole at finish().
for (;;) {
std::size_t end = buffer_.find("\n\n");
std::size_t sep = 2;
std::size_t crlf = buffer_.find("\r\n\r\n");
if (crlf != std::string::npos && (end == std::string::npos || crlf < end)) {
end = crlf;
sep = 4;
}
if (end == std::string::npos) break;
std::string block = buffer_.substr(0, end);
buffer_.erase(0, end + sep);
if (!dispatch_sse_block(block)) return false;
}
return true;
}
void StreamDecoder::finish() {
if (stopped_ || !decided_) return;
if (sse_) {
if (buffer_.find_first_not_of(" \t\r\n") != std::string::npos)
dispatch_sse_block(buffer_);
return;
}
Json doc;
try {
doc = Json::parse(buffer_);
} catch (const std::exception& e) {
throw GoogleError(502, "BAD_RESPONSE", e.what(), service_);
}
if (doc.is_object()) {
if (const Json* err = doc.find("error"))
throw GoogleError(err->is_object() && err->find("code") && err->find("code")->is_number()
? static_cast<int>(err->find("code")->as_int())
: 502,
err->is_object() && err->find("status") && err->find("status")->is_string()
? err->find("status")->as_string()
: "UNKNOWN",
err->is_object() && err->find("message") && err->find("message")->is_string()
? err->find("message")->as_string()
: err->dump(),
service_);
emit(doc);
} else if (doc.is_array()) {
for (const Json& item : doc.as_array()) {
if (item.is_object() && item.find("error"))
throw GoogleError(502, "STREAM_ERROR", item.find("error")->dump(), service_);
if (!emit(item)) break;
}
}
}
} // namespace molo::google
+40
View File
@@ -0,0 +1,40 @@
#pragma once
// Turns a streamed response body into JSON events. Understands SSE
// ("data: {...}" blocks, from ?alt=sse) and plain JSON bodies (an object is
// one event, an array is one event per element). A body that is Google's
// {"error":{...}} document throws GoogleError at finish().
#include <functional>
#include <string>
#include "clients/body/json.h"
namespace molo::google {
class StreamDecoder {
public:
static constexpr std::size_t kMaxBytes = 16u * 1024u * 1024u;
using Sink = std::function<bool(const clients::body::Json&)>;
StreamDecoder(std::string service, Sink sink);
// Returns false when the sink asked to stop (or the cap was hit): the
// caller should stop reading.
bool feed(const std::string& chunk);
void finish();
private:
bool emit(const clients::body::Json& event);
bool dispatch_sse_block(const std::string& data);
std::string service_;
Sink sink_;
std::string buffer_;
std::size_t total_ = 0;
bool decided_ = false;
bool sse_ = false;
bool stopped_ = false;
};
} // namespace molo::google