feat(clients): registry: Agent Registry, Agent Gateway, Agent Identity from discovery call table

86-row call table checked against Google discovery documents, typed
services, local approval ledger, live read-only tests, /agent/registry demo.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 04:42:00 +02:00
co-authored by Claude Sonnet 5.5
parent 6d744a433f
commit cb70bb1116
55 changed files with 4629 additions and 3 deletions
+194
View File
@@ -0,0 +1,194 @@
# Google registry module - Specification
Owned directory: `src/google/registry/`. Namespace `molo::google::registry`.
Covers three Gemini Enterprise Agent Platform products: Agent Registry (central
index of agents, MCP servers and tools, endpoints, skills), Agent Gateway
(policy-enforcing connectivity between agents and tools) and Agent Identity
(per-agent SPIFFE identity, authorization policies, audit trail mapping).
Foundation used: `GoogleClient`, `Service`, `GoogleError`, `CloudContext`,
`valid_segment`, `wait_operation`, `list_all` (see `src/google/SPEC.md`).
## 1. Module map (one concern per file)
| File | Concern |
|---|---|
| `caps.h` | Static ceilings |
| `ids.h/.cpp` | `Ids`: validation of ids, asset names, template names, request ids, free text |
| `calls.h/.cpp` | `Calls` and THE call table (86 rows): method, path, discovery service/version, rpc id, request schema, query params, request fields |
| `call_runner.h/.cpp` | `CallRunner`: renders and validates a table call, paging, mutation + operation wait, `update_mask` |
| `operation_runner.h/.cpp` | `OperationRunner`: finish a long-running operation, 404 existence probe |
| `registry_service.h/.cpp` | `RegistryService : Service`: base of the four services |
| `service_record.h/.cpp` | `ServiceRecord`, `Interface`: body of `services.create/patch` |
| `skill_record.h/.cpp` | `SkillRecord`, `SkillRevisionRecord`, `SkillState` |
| `binding_record.h/.cpp` | `BindingRecord` |
| `agent_registry.h/.cpp` | `AgentRegistry`: every registry resource and method |
| `approvals.h/.cpp` | `ApprovalLedger`, `AuditTrail`: LOCAL approval state (see 3) |
| `agent_gateway.h/.cpp` | `AgentGateway`, `GatewaySpec` |
| `gateway_policy.h/.cpp` | `GatewayPolicies`, `AuthzPolicySpec`, `ModelArmorReference` |
| `agent_principal.h/.cpp` | `AgentPrincipal`: principal:// and principalSet:// strings |
| `agent_identity.h/.cpp` | `AgentIdentity`: effective identity, deny policies, access boundaries, audit query |
| `audit_mapper.h/.cpp` | `AuditMapper`: Cloud Audit Log entry to agent-aware event |
| `tools/check_discovery.py` | Fails when any table row is not in Google's discovery documents |
## 2. Static caps (see caps.h)
| Knob | Value |
|---|---|
| List page size / pages / items | 100 / 10 / 1000 per list call |
| displayName / skill displayName / description | 63 / 128 / 2048 (Google's limits) |
| Spec content | 10 KiB (Google's limit) |
| Service id | 4..63 of `[a-z0-9-]`, starts with a letter |
| Interfaces per service, URL length | 8, 2048 |
| Search text, filter text | 512 each |
| Labels, label length | 64, 128 |
| Gateway registries / resource URIs / DNS domains | 16 each |
| Policy rules / targets / body bytes | 5 (Google's limit) / 16 / 32 KiB |
| Deny principals / permissions per rule, rules per policy | 32 / 64, 5 |
| Inline skill archive (base64) | 4 MiB |
| Local ledger entries / audit records | 5000 / 500 (oldest dropped, counted) |
| Operation wait | foundation caps: 600 s, 2 s interval, 400 polls |
## 3. Contracts
- Every request is a row of the table in `calls.cpp`. `CallRunner` rejects,
before any network traffic: an unknown call id, a path variable that is
missing, extra, empty, contains `..`, `//` or characters outside resource
names, a query parameter the discovery document does not list for that
call, `pageSize` outside 1..100, a zero or malformed `requestId`, a body on
a bodiless call, a missing body, or a top-level body field not declared for
the call.
- Read before mutate: `register_service`, `create_skill`, `create_binding`,
`create` (gateway), `create_policy`, `create_deny_policy`, `create_boundary`
GET first and answer 409 `ALREADY_EXISTS` for an existing id. Update and
delete GET first, so a missing resource is a clear 404. `update_*` need a
non-empty `updateMask` whose root fields are declared for the call.
- Mutations wait for their long-running operation under the foundation caps
and return the resulting resource (delete: `{"operation": name}`).
- Destructive calls are explicit methods with no defaults that destroy:
`remove_service`, `delete_skill(force=false)`, `delete_revision`,
`delete_binding`, `remove_gateway`, `remove_policy`,
`delete_deny_policy`, `delete_boundary`, `delete_operation`.
`policyProfile` of an authz policy is immutable and refused in a mask.
- Approval. The registry REST API has NO approve or deprecate method for
agents, MCP servers or endpoints (verified: discovery lists only get, list,
search for them; the writable resource is `services`). Therefore
`ApprovalLedger` is a LOCAL abstraction, held in process memory, bounded,
audit-logged. It restricts what `list_approved` returns; it changes nothing
at Google and is lost on restart. Skills are different: `Skill.targetState`
(draft, active, disabled, deprecated, decommissioned) is a real field and
`AgentRegistry::set_skill_state` PATCHes it.
- Model Armor is a reference only: `ModelArmorReference` validates template
names and renders the authz extension metadata value. The armor module owns
Model Armor.
- Agent Identity is system attested and read-only: `identity()` reads
`reasoningEngines.spec.effectiveIdentity` and `identityType`. Requesting an
agent identity (`identityType = AGENT_IDENTITY`) is done at deploy time by
the runtime module, not here.
- No credential: every service call throws `NotConfiguredError` (503
`NOT_CONFIGURED`) before network traffic. Credentials are never logged.
- Hosts: `agentregistry`, `networkservices`, `networksecurity`, `iam`,
`logging` are global (`https://{service}.googleapis.com/{version}`);
`aiplatform` is regional (`{location}-aiplatform.googleapis.com/v1`).
Skills CRUD, skill search, revisions and publishers exist in `v1alpha`
only; everything else in `v1`.
## 4. Example routes (`/agent/registry`, see `example/app/agent/RegistryDemo.cpp`)
GET (no credential needed): `/agent/registry` page, `/status`, `/calls`,
`/approvals`, `/audit`. POST: `/list`, `/get`, `/search`, `/approve`,
`/deprecate`, `/reject`, `/skills/state`, `/gateways/list`, `/gateways/get`,
`/policies/list`, `/identity`, `/identity/audit` (503 `google_not_configured`
without a credential, 422 on bad input) and `/identity/principal` (local, no
credential). DELETE: `/services/{id}`, `/gateways/{id}`. `/approve` and
`/deprecate` read the asset from Google first.
## Sources
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/agent-registry
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/delegate-authorization
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents
- https://docs.cloud.google.com/agent-registry/reference/rest (and `/v1/projects.locations.services`, `.agents`, `.mcpServers`, `.endpoints`, `/v1alpha/projects.locations.skills`)
- https://docs.cloud.google.com/service-mesh/docs/reference/network-services/rest/v1/projects.locations.agentGateways
- https://docs.cloud.google.com/load-balancing/docs/reference/network-security/rest/v1/projects.locations.authzPolicies
- Discovery documents (machine readable, authoritative for this module):
`https://agentregistry.googleapis.com/$discovery/rest?version=v1` and `v1alpha`,
`networkservices` v1, `networksecurity` v1, `aiplatform` v1, `iam` v2 and v3,
`logging` v2.
## Verified against discovery
`python3 -I src/google/registry/tools/check_discovery.py`, run 2026-10-24:
`checked 86 calls across 8 discovery documents` / `OK`. For every row it
confirms: rpc method id exists, HTTP method, path (`version + path`), the
exact set of query parameters, the request schema name, and that every
declared request field is a property of that schema. Discovery findings that
corrected earlier assumptions: skills CRUD is v1alpha only; `agentGateways`
create/patch have no `requestId`, delete has `etag`; `aiplatform`
`reasoningEngines.getIamPolicy` is POST; `AuthzPolicy` create has `requestId`;
Skill has `targetState`; bindings exist in v1.
Not covered by the check: response field names (the list item keys used in
`list_all` calls were read from the response schemas by hand, same date), and
enum values beyond the ones the builders emit.
## Verified live
2026-10-24, project from `GOOGLE_CLOUD_PROJECT`, read-only GET/list/search, no
resource created, changed or deleted. Rerun: `MOLO_LIVE_NET=1` plus
`GOOGLE_CLOUD_PROJECT` and `GOOGLE_API_KEY` and/or `GOOGLE_ACCESS_TOKEN`, then
`make google-test` (tests `registry_live.*`; loud SKIP otherwise).
| Call | Express API key | Service-account OAuth token |
|---|---|---|
| aiplatform v1 `reasoningEngines` list | 200, empty list | 200, empty list |
| logging v2 `entries:list` | not tried | 200 (audit query path works) |
| agentregistry v1 locations/services/agents/mcpServers/endpoints/bindings/aiApplications/operations, `agents:search`, `mcpServers:search`; v1alpha skills/publishers/`skills:search` | 401 UNAUTHENTICATED "API keys are not supported by this API" | 403 PERMISSION_DENIED, reason `SERVICE_DISABLED`: "Agent Registry API has not been used in project ... before or it is disabled" |
| networkservices v1 `agentGateways` list | 401 UNAUTHENTICATED | 403 SERVICE_DISABLED: Network Services API not enabled |
| networksecurity v1 `authzPolicies` list | 401 UNAUTHENTICATED | 403 SERVICE_DISABLED: Network Security API not enabled |
What this proves: hosts, versions and collection paths exist (a wrong path
would be 404, not an auth or enablement error) and registry/gateway/policy APIs
need OAuth. What is NOT live-verified: any registry, gateway or policy
response body, any mutation, `effectiveIdentity` of a real agent (the project
has no reasoning engines), the IAM v2/v3 calls, `AuditMapper` against real
audit entries. Enabling the three APIs is a human decision; once enabled the
same live tests exercise the read paths.
## Unverified
Neither discovery nor the docs state these; each is a choice made here:
- Service id charset (the docs list for `serviceId` is garbled): `[a-z0-9-]`,
4..63, leading letter.
- Registry `filter` grammar outside `services` (AIP-160 is documented for
services only); `orderBy`, `searchType` values of `skills:search`.
- `ModelArmorReference.settings_value()` quoting: the docs show the extension
metadata `model_armor_settings` only as a YAML example.
- `AuditLog` fields (`protoPayload.authenticationInfo.principalSubject`,
`principalEmail`, `serviceAccountDelegationInfo[].principalSubject`,
`methodName`, `resourceName`, `serviceName`) come from the Cloud Audit Logs
proto, not from discovery (logging types `protoPayload` as a free map). The
delegated-user field is a best reading of "delegated actions log both
identities".
- Whether `%2F` inside IAM v2 resource names survives `clients::Url::parse`
unchanged (IAM v2 needs OAuth on an org or project; not run).
- That `mcpServers:search` and `agents:search` bodies behave identically
beyond the shared schema shape.
- The deny-policy permission and principal string checks are stricter than
Google's (shape checks only).
- 1000-item list ceiling: a larger registry is silently truncated at the cap.
## Gaps
- The three APIs above are not enabled on the test project, so no response
shape is seen live. Owner: a human enabling `agentregistry`,
`networkservices`, `networksecurity`; test: `test_registry_live.cpp`.
- The local approval ledger is in memory. Persistence belongs to a store in
`src/data` and is not wired here.
- Authz extension (`authzExtensions`, networkservices) and Service Extensions
CRUD are not implemented; policies reference extensions by name only.
- Allow bindings on target resources go through each target's own
`setIamPolicy`; only the registry, authz policy and reasoning engine reads
are present here.
- No token refresh (foundation gap).
+151
View File
@@ -0,0 +1,151 @@
#include "google/registry/agent_gateway.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
namespace molo::google::registry {
using clients::body::Json;
namespace {
void check_ref(const std::string& v, const char* what) {
if (v.empty()) throw GoogleError::invalid(std::string(what) + " must not be empty");
Ids::require_text(v, 512, what);
if (v.find("..") != std::string::npos || v.find(' ') != std::string::npos)
throw GoogleError::invalid(std::string(what) + " is malformed");
}
} // namespace
Json GatewaySpec::to_json() const {
Ids::require_text(description, RegistryCaps::kMaxDescription, "description");
if (labels.size() > RegistryCaps::kMaxLabels) throw GoogleError::invalid("too many labels");
if (registries.size() > RegistryCaps::kMaxRegistries)
throw GoogleError::invalid("too many registries");
if (resource_uris.size() > RegistryCaps::kMaxResourceUris)
throw GoogleError::invalid("too many resource uris");
if (dns_domains.size() > RegistryCaps::kMaxDnsDomains)
throw GoogleError::invalid("too many dns domains");
Json j = Json::object();
if (!description.empty()) j.set("description", Json(description));
if (!labels.empty()) {
Json l = Json::object();
for (const auto& kv : labels) {
if (kv.first.empty()) throw GoogleError::invalid("label key is empty");
Ids::require_text(kv.first, RegistryCaps::kMaxLabelChars, "label key");
Ids::require_text(kv.second, RegistryCaps::kMaxLabelChars, "label value");
l.set(kv.first, Json(kv.second));
}
j.set("labels", l);
}
if (!registries.empty()) {
Json a = Json::array();
for (const auto& r : registries) {
check_ref(r, "registry");
a.push(Json(r));
}
j.set("registries", a);
}
if (!agent_connectivity_template.empty()) {
check_ref(agent_connectivity_template, "agentConnectivityTemplate");
j.set("agentConnectivityTemplate", Json(agent_connectivity_template));
}
if (mode == GatewayMode::kGoogleManaged) {
if (!resource_uris.empty())
throw GoogleError::invalid("resource uris belong to selfManaged");
Json g = Json::object();
g.set("governedAccessPath",
Json(access_path == GovernedAccessPath::kAgentToAnywhere ? "AGENT_TO_ANYWHERE"
: "CLIENT_TO_AGENT"));
j.set("googleManaged", g);
} else {
Json s = Json::object();
Json a = Json::array();
for (const auto& u : resource_uris) {
check_ref(u, "resource uri");
a.push(Json(u));
}
s.set("resourceUris", a);
j.set("selfManaged", s);
}
if (!network_attachment.empty() || !dns_domains.empty()) {
Json n = Json::object();
if (!network_attachment.empty()) {
check_ref(network_attachment, "network attachment");
Json e = Json::object();
e.set("networkAttachment", Json(network_attachment));
n.set("egress", e);
}
if (!dns_domains.empty()) {
Json d = Json::object();
Json a = Json::array();
for (const auto& dom : dns_domains) {
check_ref(dom, "dns domain");
a.push(Json(dom));
}
d.set("domains", a);
if (!dns_target_project.empty()) d.set("targetProject", Json(dns_target_project));
if (!dns_target_network.empty()) d.set("targetNetwork", Json(dns_target_network));
n.set("dnsPeeringConfig", d);
}
j.set("networkConfig", n);
}
return j;
}
ServiceEndpoint AgentGateway::default_endpoint() {
return endpoints::custom("networkservices", "https://networkservices.googleapis.com/v1");
}
AgentGateway::AgentGateway(std::shared_ptr<GoogleClient> client, CloudContext context)
: RegistryService(std::move(client), default_endpoint(), std::move(context)) {}
Json AgentGateway::list() const {
return runner_.list("networkservices.v1.agentGateways.list", "agentGateways",
with("parent", context_.parent()));
}
Json AgentGateway::get(const std::string& id) const {
return runner_.invoke("networkservices.v1.agentGateways.get",
with("name", context_.child("agentGateways", id)));
}
Json AgentGateway::create(const std::string& id, const GatewaySpec& spec) const {
Ids::require_segment(id, "gateway id");
CallArgs a = with("parent", context_.parent());
a.body = spec.to_json();
a.query["agentGatewayId"] = id;
if (exists([&] { return get(id); }))
throw GoogleError(409, "ALREADY_EXISTS", "gateway " + id + " already exists");
runner_.mutate("networkservices.v1.agentGateways.create", a);
return get(id);
}
Json AgentGateway::update(const std::string& id, const GatewaySpec& spec,
const std::vector<std::string>& mask) const {
Ids::require_segment(id, "gateway id");
CallArgs a = with("name", context_.child("agentGateways", id));
a.body = spec.to_json();
a.query["updateMask"] = CallRunner::update_mask("networkservices.v1.agentGateways.patch", mask);
get(id);
runner_.mutate("networkservices.v1.agentGateways.patch", a);
return get(id);
}
Json AgentGateway::remove_gateway(const std::string& id, const std::string& etag) const {
Ids::require_segment(id, "gateway id");
Ids::require_text(etag, 256, "etag");
get(id);
CallArgs a = with("name", context_.child("agentGateways", id));
put_query(a, "etag", etag);
return runner_.mutate("networkservices.v1.agentGateways.delete", a);
}
Json AgentGateway::operation(const std::string& operation_id) const {
Ids::require_segment(operation_id, "operation id");
return runner_.invoke("networkservices.v1.operations.get",
with("name", context_.parent() + "/operations/" + operation_id));
}
} // namespace molo::google::registry
+62
View File
@@ -0,0 +1,62 @@
#pragma once
// Agent Gateway: policy-enforcing connectivity between agents and tools.
// REST: networkservices.googleapis.com/v1 projects.locations.agentGateways
// (list, get, create, patch, delete). Policies attach through authz
// policies (gateway_policy.h). Fields come from the discovery document.
#include <map>
#include <memory>
#include <string>
#include <vector>
#include "google/registry/registry_service.h"
namespace molo::google::registry {
enum class GatewayMode { kGoogleManaged, kSelfManaged };
enum class GovernedAccessPath { kAgentToAnywhere, kClientToAgent };
struct GatewaySpec {
std::string description;
std::map<std::string, std::string> labels;
std::vector<std::string> registries; // Agent Registry resources governed.
GatewayMode mode = GatewayMode::kGoogleManaged;
GovernedAccessPath access_path = GovernedAccessPath::kAgentToAnywhere;
std::vector<std::string> resource_uris; // selfManaged only.
std::string agent_connectivity_template;
std::string network_attachment; // networkConfig.egress.
std::vector<std::string> dns_domains; // networkConfig.dnsPeeringConfig.
std::string dns_target_project;
std::string dns_target_network;
// Validates against the caps, then builds the request body.
clients::body::Json to_json() const;
};
class AgentGateway : public RegistryService {
public:
AgentGateway(std::shared_ptr<GoogleClient> client, CloudContext context);
static ServiceEndpoint default_endpoint(); // networkservices .../v1
// Reads first.
clients::body::Json list() const;
clients::body::Json get(const std::string& id) const;
// Mutations are explicit and read first: create refuses an existing id,
// update and remove require the gateway to exist. All wait for the
// long-running operation (capped) and return the resulting gateway
// (remove: {"operation": name}).
clients::body::Json create(const std::string& id, const GatewaySpec& spec) const;
// mask: top-level AgentGateway fields (description, labels, registries,
// networkConfig, googleManaged, selfManaged, ...). Never empty.
clients::body::Json update(const std::string& id, const GatewaySpec& spec,
const std::vector<std::string>& mask) const;
// `etag` guards against a concurrent change; empty sends none.
clients::body::Json remove_gateway(const std::string& id, const std::string& etag = "") const;
clients::body::Json operation(const std::string& operation_id) const;
};
} // namespace molo::google::registry
+246
View File
@@ -0,0 +1,246 @@
#include "google/registry/agent_identity.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
namespace molo::google::registry {
using clients::body::Json;
namespace {
bool ends_with(const std::string& s, const std::string& suf) {
return s.size() >= suf.size() && s.compare(s.size() - suf.size(), suf.size(), suf) == 0;
}
void require_principal_ref(const std::string& p) {
bool ok = p.rfind("principal://", 0) == 0 || p.rfind("principalSet://", 0) == 0;
if (!ok || p.size() > RegistryCaps::kMaxPrincipalChars)
throw GoogleError::invalid("principal must be principal:// or principalSet://");
for (unsigned char c : p)
if (c <= 0x20 || c == '"' || c == '\\') throw GoogleError::invalid("principal has bad characters");
}
// service.googleapis.com/resource.verb, e.g. storage.googleapis.com/buckets.delete
void require_permission(const std::string& p) {
std::size_t slash = p.find('/');
if (slash == std::string::npos || slash == 0 || slash + 1 >= p.size() || p.size() > 256 ||
!ends_with(p.substr(0, slash), ".googleapis.com") || p.find('/', slash + 1) != std::string::npos)
throw GoogleError::invalid("permission must look like service.googleapis.com/resource.verb");
for (char c : p)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '.' ||
c == '/' || c == '-' || c == '_' || c == '*'))
throw GoogleError::invalid("permission has bad characters");
}
Json string_array(const std::vector<std::string>& v) {
Json a = Json::array();
for (const auto& s : v) a.push(Json(s));
return a;
}
void require_digits(const std::string& v, const char* what) {
if (v.empty() || v.size() > 20) throw GoogleError::invalid(std::string(what) + " must be numeric");
for (char c : v)
if (c < '0' || c > '9') throw GoogleError::invalid(std::string(what) + " must be numeric");
}
} // namespace
Json DenyRuleSpec::to_json() const {
Ids::require_text(description, RegistryCaps::kMaxDescription, "description");
if (denied_principals.empty() || denied_principals.size() > RegistryCaps::kMaxDenyPrincipals ||
exception_principals.size() > RegistryCaps::kMaxDenyPrincipals)
throw GoogleError::invalid("a deny rule needs 1..32 denied principals");
if (denied_permissions.empty() || denied_permissions.size() > RegistryCaps::kMaxDenyPermissions ||
exception_permissions.size() > RegistryCaps::kMaxDenyPermissions)
throw GoogleError::invalid("a deny rule needs 1..64 denied permissions");
for (const auto& p : denied_principals) require_principal_ref(p);
for (const auto& p : exception_principals) require_principal_ref(p);
for (const auto& p : denied_permissions) require_permission(p);
for (const auto& p : exception_permissions) require_permission(p);
Json deny = Json::object();
deny.set("deniedPrincipals", string_array(denied_principals));
deny.set("deniedPermissions", string_array(denied_permissions));
if (!exception_principals.empty()) deny.set("exceptionPrincipals", string_array(exception_principals));
if (!exception_permissions.empty())
deny.set("exceptionPermissions", string_array(exception_permissions));
Json rule = Json::object();
if (!description.empty()) rule.set("description", Json(description));
rule.set("denyRule", deny);
return rule;
}
Json DenyPolicySpec::to_json() const {
Ids::require_text(display_name, RegistryCaps::kMaxDisplayName, "displayName");
if (rules.empty() || rules.size() > RegistryCaps::kMaxPolicyRules)
throw GoogleError::invalid("a deny policy needs 1..5 rules");
Json j = Json::object();
if (!display_name.empty()) j.set("displayName", Json(display_name));
Json r = Json::array();
for (const auto& rule : rules) r.push(rule.to_json());
j.set("rules", r);
return j;
}
Json AccessBoundarySpec::to_json() const {
Ids::require_text(display_name, RegistryCaps::kMaxDisplayName, "displayName");
Ids::require_text(rule_description, RegistryCaps::kMaxDescription, "rule description");
if (resources.empty() || resources.size() > RegistryCaps::kMaxPolicyTargets)
throw GoogleError::invalid("a boundary needs 1..16 resources");
for (const auto& r : resources) {
Ids::require_text(r, 512, "resource");
if (r.empty() || r.find(' ') != std::string::npos)
throw GoogleError::invalid("boundary resource is malformed");
}
Json rule = Json::object();
rule.set("resources", string_array(resources));
rule.set("effect", Json("ALLOW"));
if (!rule_description.empty()) rule.set("description", Json(rule_description));
Json rules = Json::array();
rules.push(rule);
Json details = Json::object();
details.set("rules", rules);
Json j = Json::object();
if (!display_name.empty()) j.set("displayName", Json(display_name));
j.set("details", details);
return j;
}
ServiceEndpoint AgentIdentity::default_endpoint(const std::string& location) {
return endpoints::aiplatform(location);
}
AgentIdentity::AgentIdentity(std::shared_ptr<GoogleClient> client, CloudContext context)
: RegistryService(std::move(client), default_endpoint(context.location), context) {}
Json AgentIdentity::engines() const {
return runner_.list("aiplatform.v1.reasoningEngines.list", "reasoningEngines",
with("parent", context_.parent()));
}
IdentityInfo AgentIdentity::identity(const std::string& engine_id) const {
Json doc = runner_.invoke("aiplatform.v1.reasoningEngines.get",
with("name", context_.child("reasoningEngines", engine_id)));
IdentityInfo info;
info.engine = string_at(doc, "name");
if (const Json* spec = doc.find("spec"); spec && spec->is_object()) {
info.identity_type = string_at(*spec, "identityType");
info.effective = string_at(*spec, "effectiveIdentity");
}
info.agent_identity = info.identity_type == "AGENT_IDENTITY";
if (info.agent_identity && !info.effective.empty())
info.principal = info.effective.rfind("principal://", 0) == 0
? info.effective
: "principal://" + info.effective;
return info;
}
Json AgentIdentity::engine_iam_policy(const std::string& engine_id) const {
return runner_.invoke("aiplatform.v1.reasoningEngines.getIamPolicy",
with("resource", context_.child("reasoningEngines", engine_id)));
}
std::vector<AuditEvent> AgentIdentity::audit(const std::string& principal, int limit) const {
if (limit < 1 || limit > static_cast<int>(RegistryCaps::kMaxAuditEntries))
throw GoogleError::invalid("limit must be 1..500");
CallArgs a;
a.body = Json::object();
context_.parent(); // Validates the project.
a.body.set("resourceNames", [&] {
Json r = Json::array();
r.push(Json("projects/" + context_.project));
return r;
}());
a.body.set("filter", Json(AuditMapper::filter_for_agent(principal)));
a.body.set("orderBy", Json("timestamp desc"));
a.body.set("pageSize", Json(limit));
Json reply = runner_.invoke("logging.v2.entries.list", a);
const Json* entries = reply.find("entries");
return AuditMapper::map_all(entries ? *entries : Json::array());
}
std::string AgentIdentity::attachment_for_project(const std::string& n) {
require_digits(n, "project number");
return "cloudresourcemanager.googleapis.com%2Fprojects%2F" + n;
}
std::string AgentIdentity::attachment_for_organization(const std::string& org) {
require_digits(org, "organization id");
return "cloudresourcemanager.googleapis.com%2Forganizations%2F" + org;
}
std::string AgentIdentity::policy_parent(const std::string& attachment) {
if (attachment.find("%2F") == std::string::npos || attachment.size() > 256)
throw GoogleError::invalid("attachment point must be URL-encoded");
return "policies/" + attachment + "/denypolicies";
}
std::string AgentIdentity::policy_name(const std::string& attachment, const std::string& id) {
Ids::require_segment(id, "policy id");
return policy_parent(attachment) + "/" + id;
}
std::string AgentIdentity::boundary_parent(const std::string& org_id) {
require_digits(org_id, "organization id");
return "organizations/" + org_id + "/locations/global";
}
Json AgentIdentity::deny_policies(const std::string& attachment) const {
return runner_.list("iam.v2.policies.listPolicies", "policies",
with("parent", policy_parent(attachment)));
}
Json AgentIdentity::deny_policy(const std::string& attachment, const std::string& id) const {
return runner_.invoke("iam.v2.policies.get", with("name", policy_name(attachment, id)));
}
Json AgentIdentity::create_deny_policy(const std::string& attachment, const std::string& id,
const DenyPolicySpec& spec) const {
Ids::require_segment(id, "policy id");
CallArgs a = with("parent", policy_parent(attachment));
a.body = spec.to_json();
a.query["policyId"] = id;
if (exists([&] { return deny_policy(attachment, id); }))
throw GoogleError(409, "ALREADY_EXISTS", "deny policy " + id + " already exists");
runner_.mutate("iam.v2.policies.createPolicy", a);
return deny_policy(attachment, id);
}
Json AgentIdentity::delete_deny_policy(const std::string& attachment, const std::string& id,
const std::string& etag) const {
deny_policy(attachment, id);
CallArgs a = with("name", policy_name(attachment, id));
put_query(a, "etag", etag);
return runner_.mutate("iam.v2.policies.delete", a);
}
Json AgentIdentity::boundaries(const std::string& org_id) const {
return runner_.list("iam.v3.principalAccessBoundaryPolicies.list", "principalAccessBoundaryPolicies",
with("parent", boundary_parent(org_id)));
}
Json AgentIdentity::boundary(const std::string& org_id, const std::string& id) const {
Ids::require_segment(id, "policy id");
return runner_.invoke("iam.v3.principalAccessBoundaryPolicies.get",
with("name", boundary_parent(org_id) + "/principalAccessBoundaryPolicies/" + id));
}
Json AgentIdentity::create_boundary(const std::string& org_id, const std::string& id,
const AccessBoundarySpec& spec) const {
Ids::require_segment(id, "policy id");
CallArgs a = with("parent", boundary_parent(org_id));
a.body = spec.to_json();
a.query["principalAccessBoundaryPolicyId"] = id;
if (exists([&] { return boundary(org_id, id); }))
throw GoogleError(409, "ALREADY_EXISTS", "boundary " + id + " already exists");
runner_.mutate("iam.v3.principalAccessBoundaryPolicies.create", a);
return boundary(org_id, id);
}
Json AgentIdentity::delete_boundary(const std::string& org_id, const std::string& id) const {
boundary(org_id, id);
return runner_.mutate("iam.v3.principalAccessBoundaryPolicies.delete",
with("name", boundary_parent(org_id) + "/principalAccessBoundaryPolicies/" + id));
}
} // namespace molo::google::registry
+97
View File
@@ -0,0 +1,97 @@
#pragma once
// Agent Identity: the per-agent cryptographic (SPIFFE) identity of an Agent
// Runtime instance, the policies that authorise it, and its audit trail.
//
// - Identity itself is system attested and read-only: it appears as
// reasoningEngines.spec.effectiveIdentity (aiplatform v1) and is
// requested at deploy time with spec.identityType = AGENT_IDENTITY (that
// create call belongs to the runtime module).
// - Authorization: IAM deny policies (iam v2) and principal access
// boundary policies (iam v3) built here; allow bindings go through
// set-iam-policy on the target resource (engine_iam_policy reads it).
// - Audit: Cloud Logging entries.list filtered by principal, mapped by
// AuditMapper.
#include <memory>
#include <string>
#include <vector>
#include "google/registry/agent_principal.h"
#include "google/registry/audit_mapper.h"
#include "google/registry/registry_service.h"
namespace molo::google::registry {
struct IdentityInfo {
std::string engine; // Reasoning engine resource name.
std::string identity_type; // SERVICE_ACCOUNT | AGENT_IDENTITY | ""
std::string effective; // Raw spec.effectiveIdentity.
std::string principal; // principal:// form when it is an agent identity.
bool agent_identity = false;
};
struct DenyRuleSpec {
std::string description;
std::vector<std::string> denied_principals; // principalSet://... or principal://...
std::vector<std::string> denied_permissions; // service.googleapis.com/resource.verb
std::vector<std::string> exception_principals;
std::vector<std::string> exception_permissions;
clients::body::Json to_json() const;
};
struct DenyPolicySpec {
std::string display_name;
std::vector<DenyRuleSpec> rules; // At least one.
clients::body::Json to_json() const;
};
struct AccessBoundarySpec {
std::string display_name;
std::vector<std::string> resources; // One ALLOW rule over these resources.
std::string rule_description;
clients::body::Json to_json() const;
};
class AgentIdentity : public RegistryService {
public:
AgentIdentity(std::shared_ptr<GoogleClient> client, CloudContext context);
static ServiceEndpoint default_endpoint(const std::string& location);
// ---- Reading identities (aiplatform v1; an API key reaches these).
clients::body::Json engines() const;
IdentityInfo identity(const std::string& engine_id) const;
clients::body::Json engine_iam_policy(const std::string& engine_id) const;
// ---- Audit trail (logging v2). Needs OAuth.
std::vector<AuditEvent> audit(const std::string& principal, int limit = 50) const;
// ---- Deny policies (iam v2). attachment is the URL-encoded attachment
// point, e.g. attachment_for_project("123").
static std::string attachment_for_project(const std::string& project_number);
static std::string attachment_for_organization(const std::string& org_id);
clients::body::Json deny_policies(const std::string& attachment) const;
clients::body::Json deny_policy(const std::string& attachment, const std::string& id) const;
clients::body::Json create_deny_policy(const std::string& attachment, const std::string& id,
const DenyPolicySpec& spec) const;
clients::body::Json delete_deny_policy(const std::string& attachment, const std::string& id,
const std::string& etag = "") const;
// ---- Principal access boundary policies (iam v3, organization scope).
clients::body::Json boundaries(const std::string& org_id) const;
clients::body::Json boundary(const std::string& org_id, const std::string& id) const;
clients::body::Json create_boundary(const std::string& org_id, const std::string& id,
const AccessBoundarySpec& spec) const;
clients::body::Json delete_boundary(const std::string& org_id, const std::string& id) const;
private:
static std::string policy_parent(const std::string& attachment);
static std::string policy_name(const std::string& attachment, const std::string& id);
static std::string boundary_parent(const std::string& org_id);
};
} // namespace molo::google::registry
+85
View File
@@ -0,0 +1,85 @@
#include "google/registry/agent_principal.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/resource.h"
namespace molo::google::registry {
namespace {
const std::string kSuffix = ".system.id.goog";
void require_digits(const std::string& v, const char* what) {
if (v.empty() || v.size() > 20) throw GoogleError::invalid(std::string(what) + " must be numeric");
for (char c : v)
if (c < '0' || c > '9') throw GoogleError::invalid(std::string(what) + " must be numeric");
}
bool ends_with(const std::string& s, const std::string& suf) {
return s.size() >= suf.size() && s.compare(s.size() - suf.size(), suf.size(), suf) == 0;
}
bool valid_domain(const std::string& d) {
if (d.empty() || d.size() > 253) return false;
for (char c : d)
if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || c == '.')) return false;
return ends_with(d, kSuffix);
}
} // namespace
std::string AgentPrincipal::org_trust_domain(const std::string& org_id) {
require_digits(org_id, "organization id");
return "agents.global.org-" + org_id + kSuffix;
}
std::string AgentPrincipal::project_trust_domain(const std::string& n) {
require_digits(n, "project number");
return "agents.global.proj-" + n + kSuffix;
}
std::string AgentPrincipal::project_set(const std::string& org_id, const std::string& n) {
require_digits(n, "project number");
return "principalSet://" + org_trust_domain(org_id) +
"/attribute.platformContainer/aiplatform/projects/" + n;
}
std::string AgentPrincipal::orgless_project_set(const std::string& n) {
return "principalSet://" + project_trust_domain(n) +
"/attribute.platformContainer/aiplatform/projects/" + n;
}
std::string AgentPrincipal::org_set(const std::string& org_id) {
return "principalSet://" + org_trust_domain(org_id) + "/attribute.platform/aiplatform";
}
std::string AgentPrincipal::str() const {
if (!valid_domain(trust_domain)) throw GoogleError::invalid("bad trust domain");
if (!valid_segment(ns) || !valid_segment(agent_name))
throw GoogleError::invalid("bad namespace or agent name");
return "principal://" + trust_domain + "/" + ns + "/" + agent_name;
}
AgentPrincipal AgentPrincipal::parse(const std::string& p) {
const std::string scheme = "principal://";
if (p.size() > RegistryCaps::kMaxPrincipalChars || p.rfind(scheme, 0) != 0)
throw GoogleError::invalid("not a principal:// identity");
std::string rest = p.substr(scheme.size());
std::size_t a = rest.find('/');
std::size_t b = a == std::string::npos ? a : rest.find('/', a + 1);
if (a == std::string::npos || b == std::string::npos || rest.find('/', b + 1) != std::string::npos)
throw GoogleError::invalid("principal must be principal://domain/namespace/agent");
AgentPrincipal out{rest.substr(0, a), rest.substr(a + 1, b - a - 1), rest.substr(b + 1)};
out.str(); // Validates all three parts.
return out;
}
bool AgentPrincipal::is_agent_principal(const std::string& value) {
try {
parse(value);
return true;
} catch (const GoogleError&) {
return false;
}
}
} // namespace molo::google::registry
+37
View File
@@ -0,0 +1,37 @@
#pragma once
// Agent Identity principals (SPIFFE based). Formats from the Agent Identity
// documentation:
// principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME
// TRUST_DOMAIN = agents.global.org-{ORG_ID}.system.id.goog
// or agents.global.proj-{PROJECT_NUMBER}.system.id.goog
// This class only builds and parses strings; it makes no call.
#include <string>
namespace molo::google::registry {
struct AgentPrincipal {
std::string trust_domain;
std::string ns; // NAMESPACE
std::string agent_name; // Immutable reasoning engine id.
std::string str() const; // principal://...; throws GoogleError (invalid)
// Parses principal://domain/namespace/name; the domain must end in
// .system.id.goog. Throws GoogleError (invalid).
static AgentPrincipal parse(const std::string& principal);
static bool is_agent_principal(const std::string& value);
static std::string org_trust_domain(const std::string& org_id);
static std::string project_trust_domain(const std::string& project_number);
// principalSet://{org trust domain}/attribute.platformContainer/aiplatform/projects/{n}
static std::string project_set(const std::string& org_id, const std::string& project_number);
// Orgless: the project trust domain replaces the org one.
static std::string orgless_project_set(const std::string& project_number);
// principalSet://{org trust domain}/attribute.platform/aiplatform
static std::string org_set(const std::string& org_id);
};
} // namespace molo::google::registry
+356
View File
@@ -0,0 +1,356 @@
#include "google/registry/agent_registry.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
namespace molo::google::registry {
using clients::body::Json;
const char* asset_collection(AssetKind kind) {
switch (kind) {
case AssetKind::kAgents: return "agents";
case AssetKind::kMcpServers: return "mcpServers";
case AssetKind::kEndpoints: return "endpoints";
case AssetKind::kServices: return "services";
case AssetKind::kSkills: return "skills";
case AssetKind::kBindings: return "bindings";
case AssetKind::kPublishers: return "publishers";
case AssetKind::kAiApplications: return "aiApplications";
}
return "agents";
}
bool asset_kind_from(const std::string& c, AssetKind& out) {
for (AssetKind k : {AssetKind::kAgents, AssetKind::kMcpServers, AssetKind::kEndpoints,
AssetKind::kServices, AssetKind::kSkills, AssetKind::kBindings,
AssetKind::kPublishers, AssetKind::kAiApplications})
if (c == asset_collection(k)) {
out = k;
return true;
}
return false;
}
ServiceEndpoint AgentRegistry::default_endpoint() {
return endpoints::custom("agentregistry", "https://agentregistry.googleapis.com/v1");
}
AgentRegistry::AgentRegistry(std::shared_ptr<GoogleClient> client, CloudContext context)
: RegistryService(std::move(client), default_endpoint(), std::move(context)) {}
std::string AgentRegistry::call_id(AssetKind kind, const char* verb) const {
// Skills (CRUD, search, revisions) and publishers exist in v1alpha only.
bool alpha = kind == AssetKind::kSkills || kind == AssetKind::kPublishers;
return std::string("agentregistry.") + (alpha ? "v1alpha." : "v1.") + asset_collection(kind) +
"." + verb;
}
std::string AgentRegistry::name_of(AssetKind kind, const std::string& id) const {
return context_.child(asset_collection(kind), id);
}
CallArgs AgentRegistry::parent_args() const { return with("parent", context_.parent()); }
// ---- Reads
Json AgentRegistry::locations() const {
return runner_.list("agentregistry.v1.locations.list", "locations",
with("name", "projects/" + context_.project));
}
Json AgentRegistry::location(const std::string& id) const {
Ids::require_segment(id, "location id");
return runner_.invoke("agentregistry.v1.locations.get",
with("name", "projects/" + context_.project + "/locations/" + id));
}
Json AgentRegistry::list(AssetKind kind, const std::map<std::string, std::string>& query) const {
CallArgs a = parent_args();
for (const auto& kv : query) {
if (kv.first == "filter") Ids::require_text(kv.second, RegistryCaps::kMaxFilterChars, "filter");
a.query[kv.first] = kv.second;
}
return runner_.list(call_id(kind, "list"), asset_collection(kind), a);
}
Json AgentRegistry::get(AssetKind kind, const std::string& id) const {
return runner_.invoke(call_id(kind, "get"), with("name", name_of(kind, id)));
}
SearchPage AgentRegistry::search(AssetKind kind, const std::string& query, int page_size,
const std::string& page_token) const {
if (kind != AssetKind::kAgents && kind != AssetKind::kMcpServers)
throw GoogleError::invalid("POST search exists for agents and mcpServers only");
Ids::require_text(query, RegistryCaps::kMaxSearchChars, "query");
Ids::require_text(page_token, 2048, "page token");
if (page_size < 1 || page_size > RegistryCaps::kPageSize)
throw GoogleError::invalid("page size must be 1..100");
CallArgs a = parent_args();
a.body = Json::object();
if (!query.empty()) a.body.set("searchString", Json(query));
a.body.set("pageSize", Json(page_size));
if (!page_token.empty()) a.body.set("pageToken", Json(page_token));
Json reply = runner_.invoke(call_id(kind, "search"), a);
SearchPage page;
if (const Json* items = reply.find(asset_collection(kind)); items && items->is_array())
for (const Json& i : items->as_array()) page.items.push(i);
page.next_page_token = string_at(reply, "nextPageToken");
return page;
}
SearchPage AgentRegistry::search_skills(const std::string& query, const std::string& search_type,
int page_size, const std::string& page_token) const {
Ids::require_text(query, RegistryCaps::kMaxSearchChars, "query");
if (page_size < 1 || page_size > RegistryCaps::kPageSize)
throw GoogleError::invalid("page size must be 1..100");
CallArgs a = parent_args();
put_query(a, "searchString", query);
put_query(a, "searchType", search_type);
put_query(a, "pageToken", page_token);
a.query["pageSize"] = std::to_string(page_size);
Json reply = runner_.invoke("agentregistry.v1alpha.skills.search", a);
SearchPage page;
if (const Json* items = reply.find("skills"); items && items->is_array())
for (const Json& i : items->as_array()) page.items.push(i);
page.next_page_token = string_at(reply, "nextPageToken");
return page;
}
Json AgentRegistry::tools(const std::string& mcp_server_id) const {
Json server = get(AssetKind::kMcpServers, mcp_server_id);
const Json* t = server.find("tools");
return t && t->is_array() ? *t : Json::array();
}
Json AgentRegistry::list_approved(AssetKind kind, const ApprovalLedger& ledger) const {
return ledger.restrict_to_approved(list(kind));
}
// ---- Services
Json AgentRegistry::register_service(const std::string& id, const ServiceRecord& record,
const std::string& request_id) const {
Ids::require_service_id(id);
Ids::require_request_id(request_id);
CallArgs a = parent_args();
a.body = record.to_json(); // Validate before any traffic.
a.query["serviceId"] = id;
put_query(a, "requestId", request_id);
if (exists([&] { return get(AssetKind::kServices, id); }))
throw GoogleError(409, "ALREADY_EXISTS", "service " + id + " is already registered");
runner_.mutate("agentregistry.v1.services.create", a);
return get(AssetKind::kServices, id);
}
Json AgentRegistry::update_service(const std::string& id, const ServiceRecord& record,
const std::vector<std::string>& mask,
const std::string& request_id) const {
Ids::require_service_id(id);
CallArgs a = with("name", name_of(AssetKind::kServices, id));
a.body = record.to_json();
a.query["updateMask"] = CallRunner::update_mask("agentregistry.v1.services.patch", mask);
put_query(a, "requestId", request_id);
get(AssetKind::kServices, id); // Must exist.
runner_.mutate("agentregistry.v1.services.patch", a);
return get(AssetKind::kServices, id);
}
Json AgentRegistry::remove_service(const std::string& id) const {
Ids::require_service_id(id);
get(AssetKind::kServices, id);
return runner_.mutate("agentregistry.v1.services.delete",
with("name", name_of(AssetKind::kServices, id)));
}
// ---- Skills
Json AgentRegistry::create_skill(const std::string& id, const SkillRecord& skill,
const SkillRevisionRecord* initial) const {
Ids::require_segment(id, "skill id");
CallArgs a = parent_args();
a.body = skill.to_create_json(initial);
a.query["skillId"] = id;
if (exists([&] { return get(AssetKind::kSkills, id); }))
throw GoogleError(409, "ALREADY_EXISTS", "skill " + id + " already exists");
runner_.mutate("agentregistry.v1alpha.skills.create", a);
return get(AssetKind::kSkills, id);
}
Json AgentRegistry::set_skill_state(const std::string& id, SkillState state) const {
Ids::require_segment(id, "skill id");
get(AssetKind::kSkills, id); // Read first.
CallArgs a = with("name", name_of(AssetKind::kSkills, id));
a.body = Json::object();
a.body.set("targetState", Json(skill_target_state_name(state)));
a.query["updateMask"] = CallRunner::update_mask("agentregistry.v1alpha.skills.patch", {"targetState"});
runner_.mutate("agentregistry.v1alpha.skills.patch", a);
return get(AssetKind::kSkills, id);
}
Json AgentRegistry::delete_skill(const std::string& id, bool force) const {
Ids::require_segment(id, "skill id");
get(AssetKind::kSkills, id);
CallArgs a = with("name", name_of(AssetKind::kSkills, id));
if (force) a.query["force"] = "true";
return runner_.mutate("agentregistry.v1alpha.skills.delete", a);
}
Json AgentRegistry::list_revisions(const std::string& skill_id) const {
Ids::require_segment(skill_id, "skill id");
return runner_.list("agentregistry.v1alpha.skills.revisions.list", "skillRevisions",
with("parent", name_of(AssetKind::kSkills, skill_id)));
}
Json AgentRegistry::get_revision(const std::string& skill_id, const std::string& revision) const {
Ids::require_segment(skill_id, "skill id");
Ids::require_segment(revision, "revision id");
return runner_.invoke("agentregistry.v1alpha.skills.revisions.get",
with("name", name_of(AssetKind::kSkills, skill_id) + "/revisions/" + revision));
}
Json AgentRegistry::create_revision(const std::string& skill_id, const std::string& revision_id,
const SkillRevisionRecord& revision) const {
Ids::require_segment(skill_id, "skill id");
Ids::require_segment(revision_id, "revision id");
get(AssetKind::kSkills, skill_id);
CallArgs a = with("parent", name_of(AssetKind::kSkills, skill_id));
a.body = revision.to_json();
a.query["skillRevisionId"] = revision_id;
runner_.mutate("agentregistry.v1alpha.skills.revisions.create", a);
return get_revision(skill_id, revision_id);
}
Json AgentRegistry::delete_revision(const std::string& skill_id, const std::string& revision) const {
get_revision(skill_id, revision);
return runner_.mutate("agentregistry.v1alpha.skills.revisions.delete",
with("name", name_of(AssetKind::kSkills, skill_id) + "/revisions/" + revision));
}
// ---- Bindings
Json AgentRegistry::create_binding(const std::string& id, const BindingRecord& binding) const {
Ids::require_segment(id, "binding id");
CallArgs a = parent_args();
a.body = binding.to_json();
a.query["bindingId"] = id;
if (exists([&] { return get(AssetKind::kBindings, id); }))
throw GoogleError(409, "ALREADY_EXISTS", "binding " + id + " already exists");
runner_.mutate("agentregistry.v1.bindings.create", a);
return get(AssetKind::kBindings, id);
}
Json AgentRegistry::update_binding(const std::string& id, const BindingRecord& binding,
const std::vector<std::string>& mask) const {
Ids::require_segment(id, "binding id");
CallArgs a = with("name", name_of(AssetKind::kBindings, id));
a.body = binding.to_json();
a.query["updateMask"] = CallRunner::update_mask("agentregistry.v1.bindings.patch", mask);
get(AssetKind::kBindings, id);
runner_.mutate("agentregistry.v1.bindings.patch", a);
return get(AssetKind::kBindings, id);
}
Json AgentRegistry::delete_binding(const std::string& id) const {
Ids::require_segment(id, "binding id");
get(AssetKind::kBindings, id);
return runner_.mutate("agentregistry.v1.bindings.delete",
with("name", name_of(AssetKind::kBindings, id)));
}
Json AgentRegistry::fetch_available_bindings(const std::string& source_id,
const std::string& target_id) const {
if (!source_id.empty() && !BindingRecord::valid_identifier(source_id, true))
throw GoogleError::invalid("source id must be urn:agent:{publisher}:{namespace}:{name}");
if (!target_id.empty() && !BindingRecord::valid_identifier(target_id, false))
throw GoogleError::invalid("target id must be a urn:agent|mcp|endpoint identifier");
CallArgs a = parent_args();
put_query(a, "sourceIdentifier", source_id);
put_query(a, "targetIdentifier", target_id);
return runner_.list("agentregistry.v1.bindings.fetchAvailable", "bindings", a);
}
// ---- AI applications
Json AgentRegistry::application_assets(const std::string& application_id, AssetKind kind) const {
if (kind != AssetKind::kAgents && kind != AssetKind::kMcpServers && kind != AssetKind::kEndpoints)
throw GoogleError::invalid("applications hold agents, mcpServers and endpoints");
return runner_.list(std::string("agentregistry.v1.aiApplications.") + asset_collection(kind) + ".list",
asset_collection(kind),
with("parent", name_of(AssetKind::kAiApplications, application_id)));
}
// ---- Operations
Json AgentRegistry::operation(const std::string& id) const {
Ids::require_segment(id, "operation id");
return runner_.invoke("agentregistry.v1.operations.get",
with("name", context_.parent() + "/operations/" + id));
}
Json AgentRegistry::operations() const {
return runner_.list("agentregistry.v1.operations.list", "operations",
with("name", context_.parent()));
}
Json AgentRegistry::cancel_operation(const std::string& id) const {
operation(id);
CallArgs a = with("name", context_.parent() + "/operations/" + id);
a.body = Json::object();
return runner_.invoke("agentregistry.v1.operations.cancel", a);
}
Json AgentRegistry::delete_operation(const std::string& id) const {
operation(id);
return runner_.invoke("agentregistry.v1.operations.delete",
with("name", context_.parent() + "/operations/" + id));
}
// ---- IAM
namespace {
void require_iam_kind(AssetKind k) {
if (k != AssetKind::kSkills && k != AssetKind::kAiApplications)
throw GoogleError::invalid("IAM exists for skills and aiApplications only");
}
} // namespace
Json AgentRegistry::iam_policy(AssetKind kind, const std::string& id) const {
require_iam_kind(kind);
std::string cid = kind == AssetKind::kSkills ? "agentregistry.v1.skills.getIamPolicy"
: "agentregistry.v1.aiApplications.getIamPolicy";
return runner_.invoke(cid, with("resource", name_of(kind, id)));
}
Json AgentRegistry::set_iam_policy(AssetKind kind, const std::string& id, const Json& policy) const {
require_iam_kind(kind);
if (!policy.is_object()) throw GoogleError::invalid("policy must be a JSON object");
iam_policy(kind, id); // Read first.
std::string cid = kind == AssetKind::kSkills ? "agentregistry.v1.skills.setIamPolicy"
: "agentregistry.v1.aiApplications.setIamPolicy";
CallArgs a = with("resource", name_of(kind, id));
a.body = Json::object();
a.body.set("policy", policy);
return runner_.invoke(cid, a);
}
Json AgentRegistry::test_iam_permissions(AssetKind kind, const std::string& id,
const std::vector<std::string>& permissions) const {
require_iam_kind(kind);
if (permissions.empty() || permissions.size() > RegistryCaps::kMaxPermissions)
throw GoogleError::invalid("1..64 permissions");
std::string cid = kind == AssetKind::kSkills ? "agentregistry.v1.skills.testIamPermissions"
: "agentregistry.v1.aiApplications.testIamPermissions";
CallArgs a = with("resource", name_of(kind, id));
a.body = Json::object();
Json arr = Json::array();
for (const auto& p : permissions) {
Ids::require_text(p, 256, "permission");
arr.push(Json(p));
}
a.body.set("permissions", arr);
return runner_.invoke(cid, a);
}
} // namespace molo::google::registry
+114
View File
@@ -0,0 +1,114 @@
#pragma once
// Agent Registry: the central index of agents, MCP servers (and their
// tools), endpoints, skills, bindings and publishers. Host
// agentregistry.googleapis.com (v1; skills CRUD, revisions and publishers
// are v1alpha only). Every call comes from the call table (calls.cpp).
//
// What is real and what is local:
// - Services (register/update/delete) and bindings are Google mutations.
// - Skills have a real lifecycle (`targetState`): set_skill_state is a
// Google PATCH.
// - Agents, MCP servers and endpoints have no approval field in the API;
// their approve/deprecate lives in the local ApprovalLedger
// (approvals.h), which is not Google state.
#include <memory>
#include <string>
#include <vector>
#include "google/registry/approvals.h"
#include "google/registry/binding_record.h"
#include "google/registry/registry_service.h"
#include "google/registry/service_record.h"
#include "google/registry/skill_record.h"
namespace molo::google::registry {
enum class AssetKind { kAgents, kMcpServers, kEndpoints, kServices, kSkills, kBindings, kPublishers, kAiApplications };
const char* asset_collection(AssetKind kind); // "agents", "mcpServers", ...
bool asset_kind_from(const std::string& collection, AssetKind& out);
struct SearchPage {
clients::body::Json items = clients::body::Json::array();
std::string next_page_token;
};
class AgentRegistry : public RegistryService {
public:
AgentRegistry(std::shared_ptr<GoogleClient> client, CloudContext context);
static ServiceEndpoint default_endpoint(); // https://agentregistry.googleapis.com/v1
// ---- Reads (always available before any mutation).
clients::body::Json locations() const;
clients::body::Json location(const std::string& id) const;
// `query` holds optional filter / orderBy, accepted only where the
// discovery document lists them for that collection.
clients::body::Json list(AssetKind kind,
const std::map<std::string, std::string>& query = {}) const;
clients::body::Json get(AssetKind kind, const std::string& id) const;
// agents:search and mcpServers:search (POST body), one page per call.
SearchPage search(AssetKind kind, const std::string& query, int page_size = 20,
const std::string& page_token = "") const;
// skills:search (GET). search_type is passed through when non-empty.
SearchPage search_skills(const std::string& query, const std::string& search_type = "",
int page_size = 20, const std::string& page_token = "") const;
clients::body::Json tools(const std::string& mcp_server_id) const; // McpServer.tools
clients::body::Json list_approved(AssetKind kind, const ApprovalLedger& ledger) const;
// ---- Services (agents, MCP servers, endpoints are registered through
// these). Each mutation reads first and waits for the operation.
clients::body::Json register_service(const std::string& id, const ServiceRecord& record,
const std::string& request_id = "") const;
clients::body::Json update_service(const std::string& id, const ServiceRecord& record,
const std::vector<std::string>& mask,
const std::string& request_id = "") const;
clients::body::Json remove_service(const std::string& id) const;
// ---- Skills (v1alpha).
clients::body::Json create_skill(const std::string& id, const SkillRecord& skill,
const SkillRevisionRecord* initial = nullptr) const;
// The real approve/deprecate for skills: PATCH targetState.
clients::body::Json set_skill_state(const std::string& id, SkillState state) const;
// force=false unless the caller says otherwise; never defaulted to true.
clients::body::Json delete_skill(const std::string& id, bool force = false) const;
clients::body::Json list_revisions(const std::string& skill_id) const;
clients::body::Json get_revision(const std::string& skill_id, const std::string& revision) const;
clients::body::Json create_revision(const std::string& skill_id, const std::string& revision_id,
const SkillRevisionRecord& revision) const;
clients::body::Json delete_revision(const std::string& skill_id, const std::string& revision) const;
// ---- Bindings.
clients::body::Json create_binding(const std::string& id, const BindingRecord& binding) const;
clients::body::Json update_binding(const std::string& id, const BindingRecord& binding,
const std::vector<std::string>& mask) const;
clients::body::Json delete_binding(const std::string& id) const;
clients::body::Json fetch_available_bindings(const std::string& source_id,
const std::string& target_id) const;
// ---- AI applications (read only) and their agents, servers, endpoints.
clients::body::Json application_assets(const std::string& application_id,
AssetKind kind) const;
// ---- Operations (the registry's own long-running operations).
clients::body::Json operation(const std::string& operation_id) const;
clients::body::Json operations() const;
clients::body::Json cancel_operation(const std::string& operation_id) const;
clients::body::Json delete_operation(const std::string& operation_id) const;
// ---- IAM on skills and AI applications (get / set / test).
clients::body::Json iam_policy(AssetKind kind, const std::string& id) const;
clients::body::Json set_iam_policy(AssetKind kind, const std::string& id,
const clients::body::Json& policy) const;
clients::body::Json test_iam_permissions(AssetKind kind, const std::string& id,
const std::vector<std::string>& permissions) const;
private:
std::string call_id(AssetKind kind, const char* verb) const;
std::string name_of(AssetKind kind, const std::string& id) const;
CallArgs parent_args() const;
};
} // namespace molo::google::registry
+119
View File
@@ -0,0 +1,119 @@
#include "google/registry/approvals.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
namespace molo::google::registry {
using clients::body::Json;
const char* approval_state_name(ApprovalState s) {
switch (s) {
case ApprovalState::kUnreviewed: return "unreviewed";
case ApprovalState::kApproved: return "approved";
case ApprovalState::kDeprecated: return "deprecated";
case ApprovalState::kRejected: return "rejected";
}
return "unreviewed";
}
void AuditTrail::record(const std::string& actor, const std::string& action,
const std::string& target, const std::string& detail) {
std::lock_guard<std::mutex> lock(mutex_);
if (records_.size() >= RegistryCaps::kMaxAuditEntries) {
records_.erase(records_.begin());
++dropped_;
}
records_.push_back({next_seq_++, actor, action, target, detail});
}
std::vector<AuditRecord> AuditTrail::snapshot() const {
std::lock_guard<std::mutex> lock(mutex_);
return records_;
}
std::size_t AuditTrail::size() const {
std::lock_guard<std::mutex> lock(mutex_);
return records_.size();
}
std::size_t AuditTrail::dropped() const {
std::lock_guard<std::mutex> lock(mutex_);
return dropped_;
}
ApprovalEntry ApprovalLedger::set(const std::string& name, ApprovalState state,
const std::string& actor, const std::string& note,
const std::string& replaced_by, const char* action) {
Ids::require_asset_name(name);
if (actor.empty()) throw GoogleError::invalid("actor is required");
Ids::require_text(actor, RegistryCaps::kMaxActorChars, "actor");
Ids::require_text(note, RegistryCaps::kMaxNoteChars, "note");
if (!replaced_by.empty()) Ids::require_asset_name(replaced_by);
ApprovalEntry entry;
{
std::lock_guard<std::mutex> lock(mutex_);
auto it = entries_.find(name);
if (it == entries_.end() && entries_.size() >= RegistryCaps::kMaxLedgerEntries)
throw GoogleError(429, "RESOURCE_EXHAUSTED", "approval ledger is full");
if (state == ApprovalState::kDeprecated &&
(it == entries_.end() || it->second.state != ApprovalState::kApproved))
throw GoogleError(409, "FAILED_PRECONDITION",
"only an approved asset can be deprecated");
entry = {name, state, actor, note, replaced_by};
entries_[name] = entry;
}
audit_.record(actor, action, name, note);
return entry;
}
ApprovalEntry ApprovalLedger::approve(const std::string& name, const std::string& actor,
const std::string& note) {
return set(name, ApprovalState::kApproved, actor, note, "", "approve");
}
ApprovalEntry ApprovalLedger::deprecate(const std::string& name, const std::string& actor,
const std::string& note,
const std::string& replaced_by) {
return set(name, ApprovalState::kDeprecated, actor, note, replaced_by, "deprecate");
}
ApprovalEntry ApprovalLedger::reject(const std::string& name, const std::string& actor,
const std::string& note) {
return set(name, ApprovalState::kRejected, actor, note, "", "reject");
}
ApprovalState ApprovalLedger::state_of(const std::string& name) const {
std::lock_guard<std::mutex> lock(mutex_);
auto it = entries_.find(name);
return it == entries_.end() ? ApprovalState::kUnreviewed : it->second.state;
}
bool ApprovalLedger::is_approved(const std::string& name) const {
return state_of(name) == ApprovalState::kApproved;
}
std::vector<ApprovalEntry> ApprovalLedger::entries() const {
std::lock_guard<std::mutex> lock(mutex_);
std::vector<ApprovalEntry> out;
for (const auto& kv : entries_) out.push_back(kv.second);
return out;
}
std::size_t ApprovalLedger::size() const {
std::lock_guard<std::mutex> lock(mutex_);
return entries_.size();
}
Json ApprovalLedger::restrict_to_approved(const Json& items) const {
Json out = Json::array();
if (!items.is_array()) return out;
for (const Json& item : items.as_array()) {
const Json* n = item.is_object() ? item.find("name") : nullptr;
if (n && n->is_string() && is_approved(n->as_string())) out.push(item);
}
return out;
}
} // namespace molo::google::registry
+88
View File
@@ -0,0 +1,88 @@
#pragma once
// LOCAL approval state for registry assets. Agent Registry's REST API has no
// approve or deprecate method (see SPEC.md, Sources), so this ledger is a
// local abstraction held in this process. It restricts what callers see to
// approved assets; it does not change anything at Google.
#include <map>
#include <mutex>
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::google::registry {
enum class ApprovalState { kUnreviewed, kApproved, kDeprecated, kRejected };
const char* approval_state_name(ApprovalState s);
struct AuditRecord {
std::size_t seq = 0;
std::string actor;
std::string action; // approve | deprecate | reject
std::string target; // asset name
std::string detail;
};
// Bounded in-memory trail. At the cap the oldest record is dropped and
// `dropped()` counts it, loudly visible in status.
class AuditTrail {
public:
void record(const std::string& actor, const std::string& action,
const std::string& target, const std::string& detail);
std::vector<AuditRecord> snapshot() const;
std::size_t size() const;
std::size_t dropped() const;
private:
mutable std::mutex mutex_;
std::vector<AuditRecord> records_;
std::size_t next_seq_ = 1;
std::size_t dropped_ = 0;
};
struct ApprovalEntry {
std::string name;
ApprovalState state = ApprovalState::kUnreviewed;
std::string actor;
std::string note;
std::string replaced_by; // Deprecation pointer, may be empty.
};
class ApprovalLedger {
public:
// Explicit transitions. Every one validates the asset name and actor and
// appends an audit record. Throws GoogleError (invalid / 409 / 429).
ApprovalEntry approve(const std::string& name, const std::string& actor,
const std::string& note = "");
// Only an approved asset can be deprecated (409 FAILED_PRECONDITION else).
ApprovalEntry deprecate(const std::string& name, const std::string& actor,
const std::string& note = "",
const std::string& replaced_by = "");
ApprovalEntry reject(const std::string& name, const std::string& actor,
const std::string& note = "");
ApprovalState state_of(const std::string& name) const;
bool is_approved(const std::string& name) const;
std::vector<ApprovalEntry> entries() const;
std::size_t size() const;
// Keeps only the items (objects with a "name") that are approved.
clients::body::Json restrict_to_approved(const clients::body::Json& items) const;
AuditTrail& audit() { return audit_; }
const AuditTrail& audit() const { return audit_; }
private:
ApprovalEntry set(const std::string& name, ApprovalState state,
const std::string& actor, const std::string& note,
const std::string& replaced_by, const char* action);
mutable std::mutex mutex_;
std::map<std::string, ApprovalEntry> entries_;
AuditTrail audit_;
};
} // namespace molo::google::registry
+76
View File
@@ -0,0 +1,76 @@
#include "google/registry/audit_mapper.h"
#include "google/registry/agent_principal.h"
#include "google/registry/caps.h"
namespace molo::google::registry {
using clients::body::Json;
namespace {
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() : "";
}
} // namespace
AuditEvent AuditMapper::map(const Json& entry) {
AuditEvent e;
e.timestamp = str(entry, "timestamp");
const Json* p = entry.is_object() ? entry.find("protoPayload") : nullptr;
if (!p || !p->is_object()) return e;
e.service_name = str(*p, "serviceName");
e.method_name = str(*p, "methodName");
e.resource_name = str(*p, "resourceName");
if (const Json* a = p->find("authenticationInfo"); a && a->is_object()) {
e.caller = str(*a, "principalSubject");
if (e.caller.empty()) e.caller = str(*a, "principalEmail");
if (const Json* d = a->find("serviceAccountDelegationInfo"); d && d->is_array())
for (const Json& hop : d->as_array()) {
std::string who = str(hop, "principalSubject");
if (who.empty())
if (const Json* f = hop.find("firstPartyPrincipal"))
who = str(*f, "principalEmail");
if (!who.empty() && who != e.caller) e.delegated_by.push_back(who);
}
}
if (AgentPrincipal::is_agent_principal(e.caller)) {
e.by_agent = true;
e.agent_name = AgentPrincipal::parse(e.caller).agent_name;
e.autonomous = e.delegated_by.empty();
}
return e;
}
std::vector<AuditEvent> AuditMapper::map_all(const Json& entries) {
std::vector<AuditEvent> out;
if (!entries.is_array()) return out;
for (const Json& e : entries.as_array()) {
if (out.size() >= RegistryCaps::kMaxAuditEntries) break;
out.push_back(map(e));
}
return out;
}
std::string AuditMapper::filter_for_agent(const std::string& principal) {
AgentPrincipal::parse(principal); // Throws on anything but a clean identity.
return "protoPayload.authenticationInfo.principalSubject=\"" + principal + "\"";
}
Json AuditMapper::to_json(const AuditEvent& e) {
Json j = Json::object();
j.set("timestamp", Json(e.timestamp));
j.set("service", Json(e.service_name));
j.set("method", Json(e.method_name));
j.set("resource", Json(e.resource_name));
j.set("caller", Json(e.caller));
j.set("by_agent", Json(e.by_agent));
j.set("agent", Json(e.agent_name));
j.set("autonomous", Json(e.autonomous));
Json d = Json::array();
for (const auto& u : e.delegated_by) d.push(Json(u));
j.set("delegated_by", d);
return j;
}
} // namespace molo::google::registry
+42
View File
@@ -0,0 +1,42 @@
#pragma once
// Maps a Cloud Audit Log entry (logging v2 LogEntry whose protoPayload is a
// google.cloud.audit.AuditLog) to an agent-aware event: which agent acted,
// on which resource, and whether a user delegated the action. Pure local
// logic; the AuditLog field names come from the audit_log.proto, not from
// a discovery document (logging's discovery types protoPayload as a free
// map), and are listed as Unverified in SPEC.md.
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::google::registry {
struct AuditEvent {
std::string timestamp;
std::string service_name;
std::string method_name;
std::string resource_name;
std::string caller; // principalSubject, else principalEmail
bool by_agent = false; // caller is a principal:// agent identity
std::string agent_name; // reasoning engine id when by_agent
std::vector<std::string> delegated_by; // users the agent acted for
bool autonomous = false; // by_agent and nobody delegated
};
class AuditMapper {
public:
// Entry without a protoPayload object maps to an event with empty fields.
static AuditEvent map(const clients::body::Json& log_entry);
// Maps up to RegistryCaps::kMaxAuditEntries entries; extra are ignored.
static std::vector<AuditEvent> map_all(const clients::body::Json& entries);
// Cloud Logging filter selecting the audit entries of one agent identity.
// The principal is validated; quotes can never reach the filter.
static std::string filter_for_agent(const std::string& principal);
static clients::body::Json to_json(const AuditEvent& event);
};
} // namespace molo::google::registry
+74
View File
@@ -0,0 +1,74 @@
#include "google/registry/binding_record.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
#include "google/resource.h"
namespace molo::google::registry {
using clients::body::Json;
bool BindingRecord::valid_identifier(const std::string& id, bool agent_only) {
std::vector<std::string> parts;
std::string cur;
for (char c : id) {
if (c == ':') {
parts.push_back(cur);
cur.clear();
} else {
cur += c;
}
}
parts.push_back(cur);
if (parts.size() != 5 || parts[0] != "urn") return false;
bool kind_ok = parts[1] == "agent" || (!agent_only && (parts[1] == "mcp" || parts[1] == "endpoint"));
if (!kind_ok) return false;
for (std::size_t i = 2; i < 5; ++i)
if (!valid_segment(parts[i])) return false;
return true;
}
Json BindingRecord::to_json() const {
Ids::require_text(display_name, RegistryCaps::kMaxDisplayName, "displayName");
Ids::require_text(description, RegistryCaps::kMaxDescription, "description");
if (!target_id.empty() || !source_id.empty()) {
if (!source_id.empty() && !valid_identifier(source_id, true))
throw GoogleError::invalid("source id must be urn:agent:{publisher}:{namespace}:{name}");
if (!valid_identifier(target_id, false))
throw GoogleError::invalid("target id must be urn:{agent|mcp|endpoint}:{publisher}:{namespace}:{name}");
} else {
throw GoogleError::invalid("a binding needs a target id");
}
if (scopes.size() > RegistryCaps::kMaxScopes) throw GoogleError::invalid("too many scopes");
Json j = Json::object();
if (!display_name.empty()) j.set("displayName", Json(display_name));
if (!description.empty()) j.set("description", Json(description));
if (!source_id.empty()) {
Json s = Json::object();
s.set("identifier", Json(source_id));
j.set("source", s);
}
Json t = Json::object();
t.set("identifier", Json(target_id));
j.set("target", t);
if (!auth_provider.empty() || !scopes.empty() || !continue_uri.empty()) {
Ids::require_text(auth_provider, 512, "authProvider");
Ids::require_text(continue_uri, RegistryCaps::kMaxUrlChars, "continueUri");
Json a = Json::object();
if (!auth_provider.empty()) a.set("authProvider", Json(auth_provider));
if (!scopes.empty()) {
Json arr = Json::array();
for (const auto& s : scopes) {
Ids::require_text(s, 256, "scope");
arr.push(Json(s));
}
a.set("scopes", arr);
}
if (!continue_uri.empty()) a.set("continueUri", Json(continue_uri));
j.set("authProviderBinding", a);
}
return j;
}
} // namespace molo::google::registry
+28
View File
@@ -0,0 +1,28 @@
#pragma once
// Binding (agentregistry): connects a source agent to a target agent, MCP
// server or endpoint, optionally with an auth provider.
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::google::registry {
struct BindingRecord {
std::string display_name;
std::string description;
std::string source_id; // urn:agent:{publisher}:{namespace}:{name}, optional
std::string target_id; // urn:agent|mcp|endpoint:{publisher}:{namespace}:{name}
std::string auth_provider; // Optional authProviderBinding.authProvider
std::vector<std::string> scopes;
std::string continue_uri;
// Valid identifier: urn:{agent|mcp|endpoint}:a:b:c, each part a segment.
static bool valid_identifier(const std::string& id, bool agent_only);
clients::body::Json to_json() const;
};
} // namespace molo::google::registry
+108
View File
@@ -0,0 +1,108 @@
#include "google/registry/call_runner.h"
#include "clients/url.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
#include "google/registry/operation_runner.h"
namespace molo::google::registry {
using clients::body::Json;
CallRunner::CallRunner(std::shared_ptr<GoogleClient> client, std::string location)
: client_(std::move(client)), location_(std::move(location)) {}
std::string CallRunner::build_path(const CallSpec& call, const CallArgs& args,
bool default_page) const {
std::string path = Calls::render(call, args.vars);
std::map<std::string, std::string> query = args.query;
for (const auto& kv : query) {
if (!Calls::allows_query(call, kv.first))
throw GoogleError::invalid("query parameter " + kv.first + " is not in " + call.id);
Ids::require_text(kv.second, 2048, "query value");
if (kv.first == "pageSize") {
int n = 0;
for (char c : kv.second) {
if (c < '0' || c > '9') throw GoogleError::invalid("pageSize must be a number");
n = n * 10 + (c - '0');
if (n > RegistryCaps::kPageSize) break;
}
if (n < 1 || n > RegistryCaps::kPageSize)
throw GoogleError::invalid("pageSize must be 1..100");
}
if (kv.first == "requestId") Ids::require_request_id(kv.second);
}
if (default_page && Calls::allows_query(call, "pageSize") && !query.count("pageSize"))
query["pageSize"] = std::to_string(RegistryCaps::kPageSize);
char sep = '?';
for (const auto& kv : query) {
path += sep;
path += kv.first + "=" + clients::Url::encode_component(kv.second);
sep = '&';
}
return path;
}
void CallRunner::check_body(const CallSpec& call, const CallArgs& args) const {
bool wants = Calls::has_body(call);
if (wants && !args.body.is_object())
throw GoogleError::invalid(std::string(call.id) + " needs a JSON object body");
if (!wants && !args.body.is_null())
throw GoogleError::invalid(std::string(call.id) + " takes no body");
if (!wants) return;
for (const auto& kv : args.body.as_object())
if (!Calls::allows_field(call, kv.first))
throw GoogleError::invalid("field " + kv.first + " is not declared for " + call.id);
if (args.body.dump().size() > RegistryCaps::kMaxPolicyBytes)
throw GoogleError::invalid("request body is too large");
}
std::string CallRunner::update_mask(const std::string& call_id,
const std::vector<std::string>& fields) {
const CallSpec& call = Calls::get(call_id);
if (fields.empty()) throw GoogleError::invalid("update mask is required");
std::string joined;
for (const auto& f : fields) {
std::string root = f.substr(0, f.find('.'));
if (!Calls::allows_field(call, root))
throw GoogleError::invalid("update mask field not allowed: " + f);
Ids::require_text(f, 128, "update mask field");
joined += (joined.empty() ? "" : ",") + f;
}
return joined;
}
std::string CallRunner::describe(const std::string& call_id, const CallArgs& args) const {
const CallSpec& call = Calls::get(call_id);
check_body(call, args);
return std::string(call.method) + " " + Calls::endpoint(call, location_).base_url +
build_path(call, args, false);
}
Json CallRunner::invoke(const std::string& call_id, const CallArgs& args) const {
const CallSpec& call = Calls::get(call_id);
check_body(call, args);
std::string path = build_path(call, args, false);
ServiceEndpoint ep = Calls::endpoint(call, location_);
return client_->request(Calls::method_of(call), ep, path,
Calls::has_body(call) ? &args.body : nullptr);
}
Json CallRunner::list(const std::string& call_id, const std::string& items_key,
const CallArgs& args) const {
const CallSpec& call = Calls::get(call_id);
if (Calls::method_of(call) != clients::Method::kGet)
throw GoogleError::invalid("list needs a GET call");
std::string path = build_path(call, args, true);
return list_all(*client_, Calls::endpoint(call, location_), path, items_key,
RegistryCaps::kMaxPages);
}
Json CallRunner::mutate(const std::string& call_id, const CallArgs& args) const {
const CallSpec& call = Calls::get(call_id);
Json reply = invoke(call_id, args);
return OperationRunner::finish(*client_, Calls::endpoint(call, location_), reply, sleeper_);
}
} // namespace molo::google::registry
+62
View File
@@ -0,0 +1,62 @@
#pragma once
// Executes a call from the table. All validation happens before any network
// traffic: the call id, path variables, query parameters (only those the
// discovery document lists for the call), and the top-level request fields
// (only those declared in the table). Lists follow pages under the caps;
// mutations wait for their long-running operation (capped).
#include <map>
#include <memory>
#include <string>
#include <vector>
#include "google/operation.h"
#include "google/registry/calls.h"
namespace molo::google::registry {
struct CallArgs {
std::map<std::string, std::string> vars; // {+parent}, {+name}, ...
std::map<std::string, std::string> query; // updateMask, filter, ...
clients::body::Json body; // Null: no body.
};
class CallRunner {
public:
CallRunner(std::shared_ptr<GoogleClient> client, std::string location);
// One request, one reply.
clients::body::Json invoke(const std::string& call_id, const CallArgs& args) const;
// Follows nextPageToken (RegistryCaps::kMaxPages pages of kPageSize) and
// returns the concatenated `items_key` array.
clients::body::Json list(const std::string& call_id, const std::string& items_key,
const CallArgs& args) const;
// invoke + wait for the operation the reply describes; returns
// {"operation": name}.
clients::body::Json mutate(const std::string& call_id, const CallArgs& args) const;
// The exact request that invoke() would send: "METHOD path?query". Pure,
// no network. Used by tests to compare against the discovery paths.
std::string describe(const std::string& call_id, const CallArgs& args) const;
// Validated updateMask value: non-empty, every root segment is a request
// field declared for `call_id`. Throws GoogleError (invalid).
static std::string update_mask(const std::string& call_id,
const std::vector<std::string>& fields);
void set_sleeper(Sleeper sleeper) { sleeper_ = std::move(sleeper); }
bool configured() const { return client_->configured(); }
const std::shared_ptr<GoogleClient>& client() const { return client_; }
const std::string& location() const { return location_; }
private:
std::string build_path(const CallSpec& call, const CallArgs& args, bool default_page) const;
void check_body(const CallSpec& call, const CallArgs& args) const;
std::shared_ptr<GoogleClient> client_;
std::string location_;
Sleeper sleeper_;
};
} // namespace molo::google::registry
+198
View File
@@ -0,0 +1,198 @@
#include "google/registry/calls.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/resource.h"
namespace molo::google::registry {
namespace {
// THE call table. One row per line, derived from the Google discovery
// documents (see tools/check_discovery.py, which parses these lines).
// Column order: id, method, path, service, version, rpc, request schema,
// query parameters, request fields.
const std::vector<CallSpec> kCalls = {
{"agentregistry.v1.agents.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.agents.get", "-", "-", "-"},
{"agentregistry.v1.agents.list", "GET", "/{+parent}/agents", "agentregistry", "v1", "agentregistry.projects.locations.agents.list", "-", "filter,orderBy,pageSize,pageToken", "-"},
{"agentregistry.v1.agents.search", "POST", "/{+parent}/agents:search", "agentregistry", "v1", "agentregistry.projects.locations.agents.search", "SearchAgentsRequest", "-", "searchString,pageSize,pageToken"},
{"agentregistry.v1.aiApplications.agents.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.agents.get", "-", "-", "-"},
{"agentregistry.v1.aiApplications.agents.list", "GET", "/{+parent}/agents", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.agents.list", "-", "pageSize,pageToken", "-"},
{"agentregistry.v1.aiApplications.endpoints.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.endpoints.get", "-", "-", "-"},
{"agentregistry.v1.aiApplications.endpoints.list", "GET", "/{+parent}/endpoints", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.endpoints.list", "-", "pageSize,pageToken", "-"},
{"agentregistry.v1.aiApplications.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.get", "-", "-", "-"},
{"agentregistry.v1.aiApplications.getIamPolicy", "GET", "/{+resource}:getIamPolicy", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.getIamPolicy", "-", "options.requestedPolicyVersion", "-"},
{"agentregistry.v1.aiApplications.list", "GET", "/{+parent}/aiApplications", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.list", "-", "filter,orderBy,pageSize,pageToken", "-"},
{"agentregistry.v1.aiApplications.mcpServers.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.mcpServers.get", "-", "-", "-"},
{"agentregistry.v1.aiApplications.mcpServers.list", "GET", "/{+parent}/mcpServers", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.mcpServers.list", "-", "pageSize,pageToken", "-"},
{"agentregistry.v1.aiApplications.setIamPolicy", "POST", "/{+resource}:setIamPolicy", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.setIamPolicy", "GoogleIamV1SetIamPolicyRequest", "-", "policy,updateMask"},
{"agentregistry.v1.aiApplications.testIamPermissions", "POST", "/{+resource}:testIamPermissions", "agentregistry", "v1", "agentregistry.projects.locations.aiApplications.testIamPermissions", "GoogleIamV1TestIamPermissionsRequest", "-", "permissions"},
{"agentregistry.v1.bindings.create", "POST", "/{+parent}/bindings", "agentregistry", "v1", "agentregistry.projects.locations.bindings.create", "Binding", "bindingId,requestId", "displayName,description,source,target,authProviderBinding"},
{"agentregistry.v1.bindings.delete", "DELETE", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.bindings.delete", "-", "requestId", "-"},
{"agentregistry.v1.bindings.fetchAvailable", "GET", "/{+parent}/bindings:fetchAvailable", "agentregistry", "v1", "agentregistry.projects.locations.bindings.fetchAvailable", "-", "pageSize,pageToken,sourceIdentifier,targetIdentifier", "-"},
{"agentregistry.v1.bindings.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.bindings.get", "-", "-", "-"},
{"agentregistry.v1.bindings.list", "GET", "/{+parent}/bindings", "agentregistry", "v1", "agentregistry.projects.locations.bindings.list", "-", "filter,orderBy,pageSize,pageToken", "-"},
{"agentregistry.v1.bindings.patch", "PATCH", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.bindings.patch", "Binding", "requestId,updateMask", "displayName,description,source,target,authProviderBinding"},
{"agentregistry.v1.endpoints.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.endpoints.get", "-", "-", "-"},
{"agentregistry.v1.endpoints.list", "GET", "/{+parent}/endpoints", "agentregistry", "v1", "agentregistry.projects.locations.endpoints.list", "-", "filter,pageSize,pageToken", "-"},
{"agentregistry.v1.locations.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.get", "-", "-", "-"},
{"agentregistry.v1.locations.list", "GET", "/{+name}/locations", "agentregistry", "v1", "agentregistry.projects.locations.list", "-", "extraLocationTypes,filter,pageSize,pageToken", "-"},
{"agentregistry.v1.mcpServers.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.mcpServers.get", "-", "-", "-"},
{"agentregistry.v1.mcpServers.list", "GET", "/{+parent}/mcpServers", "agentregistry", "v1", "agentregistry.projects.locations.mcpServers.list", "-", "filter,orderBy,pageSize,pageToken", "-"},
{"agentregistry.v1.mcpServers.search", "POST", "/{+parent}/mcpServers:search", "agentregistry", "v1", "agentregistry.projects.locations.mcpServers.search", "SearchMcpServersRequest", "-", "searchString,pageSize,pageToken"},
{"agentregistry.v1.operations.cancel", "POST", "/{+name}:cancel", "agentregistry", "v1", "agentregistry.projects.locations.operations.cancel", "CancelOperationRequest", "-", "-"},
{"agentregistry.v1.operations.delete", "DELETE", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.operations.delete", "-", "-", "-"},
{"agentregistry.v1.operations.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.operations.get", "-", "-", "-"},
{"agentregistry.v1.operations.list", "GET", "/{+name}/operations", "agentregistry", "v1", "agentregistry.projects.locations.operations.list", "-", "filter,pageSize,pageToken,returnPartialSuccess", "-"},
{"agentregistry.v1.services.create", "POST", "/{+parent}/services", "agentregistry", "v1", "agentregistry.projects.locations.services.create", "Service", "requestId,serviceId", "displayName,description,interfaces,agentSpec,mcpServerSpec,endpointSpec"},
{"agentregistry.v1.services.delete", "DELETE", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.services.delete", "-", "requestId", "-"},
{"agentregistry.v1.services.get", "GET", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.services.get", "-", "-", "-"},
{"agentregistry.v1.services.list", "GET", "/{+parent}/services", "agentregistry", "v1", "agentregistry.projects.locations.services.list", "-", "filter,pageSize,pageToken", "-"},
{"agentregistry.v1.services.patch", "PATCH", "/{+name}", "agentregistry", "v1", "agentregistry.projects.locations.services.patch", "Service", "requestId,updateMask", "displayName,description,interfaces,agentSpec,mcpServerSpec,endpointSpec"},
{"agentregistry.v1.skills.getIamPolicy", "GET", "/{+resource}:getIamPolicy", "agentregistry", "v1", "agentregistry.projects.locations.skills.getIamPolicy", "-", "options.requestedPolicyVersion", "-"},
{"agentregistry.v1.skills.setIamPolicy", "POST", "/{+resource}:setIamPolicy", "agentregistry", "v1", "agentregistry.projects.locations.skills.setIamPolicy", "GoogleIamV1SetIamPolicyRequest", "-", "policy,updateMask"},
{"agentregistry.v1.skills.testIamPermissions", "POST", "/{+resource}:testIamPermissions", "agentregistry", "v1", "agentregistry.projects.locations.skills.testIamPermissions", "GoogleIamV1TestIamPermissionsRequest", "-", "permissions"},
{"agentregistry.v1alpha.publishers.get", "GET", "/{+name}", "agentregistry", "v1alpha", "agentregistry.projects.locations.publishers.get", "-", "-", "-"},
{"agentregistry.v1alpha.publishers.list", "GET", "/{+parent}/publishers", "agentregistry", "v1alpha", "agentregistry.projects.locations.publishers.list", "-", "pageSize,pageToken", "-"},
{"agentregistry.v1alpha.skills.create", "POST", "/{+parent}/skills", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.create", "Skill", "requestId,skillId", "displayName,description,type,targetState,publisher,defaultRevision,initialRevision"},
{"agentregistry.v1alpha.skills.delete", "DELETE", "/{+name}", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.delete", "-", "force,requestId", "-"},
{"agentregistry.v1alpha.skills.get", "GET", "/{+name}", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.get", "-", "-", "-"},
{"agentregistry.v1alpha.skills.getIamPolicy", "GET", "/{+resource}:getIamPolicy", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.getIamPolicy", "-", "options.requestedPolicyVersion", "-"},
{"agentregistry.v1alpha.skills.list", "GET", "/{+parent}/skills", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.list", "-", "filter,orderBy,pageSize,pageToken", "-"},
{"agentregistry.v1alpha.skills.patch", "PATCH", "/{+name}", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.patch", "Skill", "requestId,updateMask", "displayName,description,type,targetState,publisher,defaultRevision,initialRevision"},
{"agentregistry.v1alpha.skills.revisions.create", "POST", "/{+parent}/revisions", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.revisions.create", "SkillRevision", "requestId,skillRevisionId", "gcsSource,archiveUploadSource"},
{"agentregistry.v1alpha.skills.revisions.delete", "DELETE", "/{+name}", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.revisions.delete", "-", "requestId", "-"},
{"agentregistry.v1alpha.skills.revisions.get", "GET", "/{+name}", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.revisions.get", "-", "-", "-"},
{"agentregistry.v1alpha.skills.revisions.list", "GET", "/{+parent}/revisions", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.revisions.list", "-", "pageSize,pageToken", "-"},
{"agentregistry.v1alpha.skills.search", "GET", "/{+parent}/skills:search", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.search", "-", "filter,pageSize,pageToken,searchString,searchType", "-"},
{"agentregistry.v1alpha.skills.setIamPolicy", "POST", "/{+resource}:setIamPolicy", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.setIamPolicy", "GoogleIamV1SetIamPolicyRequest", "-", "policy,updateMask"},
{"agentregistry.v1alpha.skills.testIamPermissions", "POST", "/{+resource}:testIamPermissions", "agentregistry", "v1alpha", "agentregistry.projects.locations.skills.testIamPermissions", "GoogleIamV1TestIamPermissionsRequest", "-", "permissions"},
{"aiplatform.v1.operations.get", "GET", "/{+name}", "aiplatform", "v1", "aiplatform.projects.locations.operations.get", "-", "-", "-"},
{"aiplatform.v1.reasoningEngines.get", "GET", "/{+name}", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.get", "-", "-", "-"},
{"aiplatform.v1.reasoningEngines.getIamPolicy", "POST", "/{+resource}:getIamPolicy", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.getIamPolicy", "-", "options.requestedPolicyVersion", "-"},
{"aiplatform.v1.reasoningEngines.list", "GET", "/{+parent}/reasoningEngines", "aiplatform", "v1", "aiplatform.projects.locations.reasoningEngines.list", "-", "filter,pageSize,pageToken", "-"},
{"iam.v2.policies.createPolicy", "POST", "/{+parent}", "iam", "v2", "iam.policies.createPolicy", "GoogleIamV2Policy", "policyId", "displayName,rules,etag"},
{"iam.v2.policies.delete", "DELETE", "/{+name}", "iam", "v2", "iam.policies.delete", "-", "etag", "-"},
{"iam.v2.policies.get", "GET", "/{+name}", "iam", "v2", "iam.policies.get", "-", "-", "-"},
{"iam.v2.policies.listPolicies", "GET", "/{+parent}", "iam", "v2", "iam.policies.listPolicies", "-", "pageSize,pageToken", "-"},
{"iam.v2.policies.operations.get", "GET", "/{+name}", "iam", "v2", "iam.policies.operations.get", "-", "-", "-"},
{"iam.v2.policies.update", "PUT", "/{+name}", "iam", "v2", "iam.policies.update", "GoogleIamV2Policy", "-", "displayName,rules,etag"},
{"iam.v3.principalAccessBoundaryPolicies.create", "POST", "/{+parent}/principalAccessBoundaryPolicies", "iam", "v3", "iam.organizations.locations.principalAccessBoundaryPolicies.create", "GoogleIamV3PrincipalAccessBoundaryPolicy", "principalAccessBoundaryPolicyId,validateOnly", "displayName,annotations,details,etag"},
{"iam.v3.principalAccessBoundaryPolicies.delete", "DELETE", "/{+name}", "iam", "v3", "iam.organizations.locations.principalAccessBoundaryPolicies.delete", "-", "etag,force,validateOnly", "-"},
{"iam.v3.principalAccessBoundaryPolicies.get", "GET", "/{+name}", "iam", "v3", "iam.organizations.locations.principalAccessBoundaryPolicies.get", "-", "-", "-"},
{"iam.v3.principalAccessBoundaryPolicies.list", "GET", "/{+parent}/principalAccessBoundaryPolicies", "iam", "v3", "iam.organizations.locations.principalAccessBoundaryPolicies.list", "-", "filter,pageSize,pageToken", "-"},
{"iam.v3.principalAccessBoundaryPolicies.patch", "PATCH", "/{+name}", "iam", "v3", "iam.organizations.locations.principalAccessBoundaryPolicies.patch", "GoogleIamV3PrincipalAccessBoundaryPolicy", "updateMask,validateOnly", "displayName,annotations,details,etag"},
{"iam.v3.principalAccessBoundaryPolicies.searchPolicyBindings", "GET", "/{+name}:searchPolicyBindings", "iam", "v3", "iam.organizations.locations.principalAccessBoundaryPolicies.searchPolicyBindings", "-", "pageSize,pageToken", "-"},
{"logging.v2.entries.list", "POST", "/entries:list", "logging", "v2", "logging.entries.list", "ListLogEntriesRequest", "-", "resourceNames,filter,orderBy,pageSize,pageToken"},
{"networksecurity.v1.authzPolicies.create", "POST", "/{+parent}/authzPolicies", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.create", "AuthzPolicy", "authzPolicyId,requestId", "description,labels,target,httpRules,action,customProvider,policyProfile"},
{"networksecurity.v1.authzPolicies.delete", "DELETE", "/{+name}", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.delete", "-", "requestId", "-"},
{"networksecurity.v1.authzPolicies.get", "GET", "/{+name}", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.get", "-", "-", "-"},
{"networksecurity.v1.authzPolicies.getIamPolicy", "GET", "/{+resource}:getIamPolicy", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.getIamPolicy", "-", "options.requestedPolicyVersion", "-"},
{"networksecurity.v1.authzPolicies.list", "GET", "/{+parent}/authzPolicies", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.list", "-", "filter,orderBy,pageSize,pageToken", "-"},
{"networksecurity.v1.authzPolicies.patch", "PATCH", "/{+name}", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.patch", "AuthzPolicy", "requestId,updateMask", "description,labels,target,httpRules,action,customProvider,policyProfile"},
{"networksecurity.v1.authzPolicies.setIamPolicy", "POST", "/{+resource}:setIamPolicy", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.setIamPolicy", "GoogleIamV1SetIamPolicyRequest", "-", "policy,updateMask"},
{"networksecurity.v1.authzPolicies.testIamPermissions", "POST", "/{+resource}:testIamPermissions", "networksecurity", "v1", "networksecurity.projects.locations.authzPolicies.testIamPermissions", "GoogleIamV1TestIamPermissionsRequest", "-", "permissions"},
{"networksecurity.v1.operations.get", "GET", "/{+name}", "networksecurity", "v1", "networksecurity.projects.locations.operations.get", "-", "-", "-"},
{"networkservices.v1.agentGateways.create", "POST", "/{+parent}/agentGateways", "networkservices", "v1", "networkservices.projects.locations.agentGateways.create", "AgentGateway", "agentGatewayId", "description,labels,registries,networkConfig,googleManaged,selfManaged,agentConnectivityTemplate,etag"},
{"networkservices.v1.agentGateways.delete", "DELETE", "/{+name}", "networkservices", "v1", "networkservices.projects.locations.agentGateways.delete", "-", "etag", "-"},
{"networkservices.v1.agentGateways.get", "GET", "/{+name}", "networkservices", "v1", "networkservices.projects.locations.agentGateways.get", "-", "-", "-"},
{"networkservices.v1.agentGateways.list", "GET", "/{+parent}/agentGateways", "networkservices", "v1", "networkservices.projects.locations.agentGateways.list", "-", "filter,pageSize,pageToken,returnPartialSuccess", "-"},
{"networkservices.v1.agentGateways.patch", "PATCH", "/{+name}", "networkservices", "v1", "networkservices.projects.locations.agentGateways.patch", "AgentGateway", "updateMask", "description,labels,registries,networkConfig,googleManaged,selfManaged,agentConnectivityTemplate,etag"},
{"networkservices.v1.operations.get", "GET", "/{+name}", "networkservices", "v1", "networkservices.projects.locations.operations.get", "-", "-", "-"},
};
} // namespace
const std::vector<CallSpec>& Calls::all() { return kCalls; }
const CallSpec& Calls::get(const std::string& id) {
for (const CallSpec& c : kCalls)
if (id == c.id) return c;
throw GoogleError::invalid("unknown registry call: " + id);
}
std::vector<std::string> Calls::split(const char* list) {
std::vector<std::string> out;
std::string cur;
for (const char* p = list; *p; ++p) {
if (*p == ',') {
if (!cur.empty()) out.push_back(cur);
cur.clear();
} else {
cur += *p;
}
}
if (!cur.empty()) out.push_back(cur);
return out;
}
bool Calls::allows_query(const CallSpec& call, const std::string& name) {
if (std::string(call.query) == "-") return false;
for (const auto& q : split(call.query))
if (q == name) return true;
return false;
}
bool Calls::allows_field(const CallSpec& call, const std::string& name) {
if (std::string(call.fields) == "-") return false;
for (const auto& f : split(call.fields))
if (f == name) return true;
return false;
}
bool Calls::has_body(const CallSpec& call) { return std::string(call.request) != "-"; }
clients::Method Calls::method_of(const CallSpec& call) {
std::string m = call.method;
if (m == "GET") return clients::Method::kGet;
if (m == "POST") return clients::Method::kPost;
if (m == "PATCH") return clients::Method::kPatch;
if (m == "PUT") return clients::Method::kPut;
if (m == "DELETE") return clients::Method::kDelete;
throw GoogleError::invalid("bad method in call table");
}
namespace {
bool safe_resource_char(char c) {
return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '-' || c == '_' || c == '.' || c == '/' || c == '%' || c == ':';
}
} // namespace
std::string Calls::render(const CallSpec& call, const std::map<std::string, std::string>& vars) {
std::string tmpl = call.path;
std::string out;
std::size_t used = 0;
for (std::size_t i = 0; i < tmpl.size();) {
if (tmpl.compare(i, 2, "{+") == 0) {
std::size_t end = tmpl.find('}', i);
std::string name = tmpl.substr(i + 2, end - i - 2);
auto it = vars.find(name);
if (it == vars.end()) throw GoogleError::invalid("missing path variable " + name);
const std::string& v = it->second;
if (v.empty() || v.size() > 512 || v.front() == '/' || v.find("..") != std::string::npos ||
v.find("//") != std::string::npos)
throw GoogleError::invalid("bad value for " + name);
for (char c : v)
if (!safe_resource_char(c)) throw GoogleError::invalid("bad character in " + name);
out += v;
++used;
i = end + 1;
} else {
out += tmpl[i++];
}
}
if (used != vars.size()) throw GoogleError::invalid("unused path variable for " + std::string(call.id));
return out;
}
ServiceEndpoint Calls::endpoint(const CallSpec& call, const std::string& location) {
std::string service = call.service;
std::string version = call.version;
if (service == "aiplatform") {
ServiceEndpoint e = endpoints::aiplatform(location);
return e; // v1 only in the table.
}
return endpoints::custom(service + (version == "v1" ? "" : "-" + version),
"https://" + service + ".googleapis.com/" + version);
}
} // namespace molo::google::registry
+52
View File
@@ -0,0 +1,52 @@
#pragma once
// The one table of every REST call this module can make. Each row names the
// call, its HTTP method, path template (without version), the discovery
// service and version it was derived from, the rpc method id, the request
// schema, the allowed query parameters and the request fields our builders
// emit. tools/check_discovery.py fetches the discovery documents and fails
// when any row, query parameter or request field is absent there.
#include <map>
#include <string>
#include <vector>
#include "clients/request.h"
#include "google/endpoints.h"
namespace molo::google::registry {
struct CallSpec {
const char* id; // "<service>.<version>.<resource>.<method>"
const char* method; // GET POST PATCH PUT DELETE
const char* path; // "/{+parent}/agents"; {+x} is a full resource name
const char* service; // discovery service: agentregistry, iam, ...
const char* version; // v1, v1alpha, v2, v3
const char* rpc; // discovery method id
const char* request; // request schema name, "-" when no body
const char* query; // comma list of allowed query parameters, "-" none
const char* fields; // comma list of request fields we emit, "-" no body
};
class Calls {
public:
static const std::vector<CallSpec>& all();
// Throws GoogleError (invalid) for an id that is not in the table.
static const CallSpec& get(const std::string& id);
static std::vector<std::string> split(const char* comma_list);
static bool allows_query(const CallSpec& call, const std::string& name);
static bool allows_field(const CallSpec& call, const std::string& name);
static bool has_body(const CallSpec& call);
static clients::Method method_of(const CallSpec& call);
// Fills every {+var}. Values are validated (resource-name characters,
// no "..", bounded); every variable of the template must be supplied.
static std::string render(const CallSpec& call,
const std::map<std::string, std::string>& vars);
// Host for a call's discovery service. aiplatform is regional.
static ServiceEndpoint endpoint(const CallSpec& call, const std::string& location);
};
} // namespace molo::google::registry
+54
View File
@@ -0,0 +1,54 @@
#pragma once
// Static ceilings for the registry module (Agent Registry, Agent Gateway,
// Agent Identity). Never autotuned.
#include <cstddef>
namespace molo::google::registry {
struct RegistryCaps {
// Pagination: a list reads at most kMaxPages pages of kPageSize items.
static constexpr int kPageSize = 100; // Google's documented search cap.
static constexpr std::size_t kMaxPages = 10;
static constexpr std::size_t kMaxItems = kPageSize * kMaxPages;
// Service (registry entry) input limits; the first four are Google's.
static constexpr std::size_t kMaxDisplayName = 63;
static constexpr std::size_t kMaxDescription = 2048;
static constexpr std::size_t kMaxSpecBytes = 10 * 1024;
static constexpr std::size_t kMinServiceId = 4;
static constexpr std::size_t kMaxServiceId = 63;
static constexpr std::size_t kMaxInterfaces = 8;
static constexpr std::size_t kMaxUrlChars = 2048;
static constexpr std::size_t kMaxSearchChars = 512;
static constexpr std::size_t kMaxFilterChars = 512;
static constexpr std::size_t kMaxLabels = 64;
static constexpr std::size_t kMaxLabelChars = 128;
static constexpr std::size_t kMaxSkillDisplayName = 128; // Discovery: 128.
static constexpr std::size_t kMaxArchiveBase64 = 4 * 1024 * 1024;
static constexpr std::size_t kMaxScopes = 32;
static constexpr std::size_t kMaxPermissions = 64;
// Gateway and policy input limits.
static constexpr std::size_t kMaxRegistries = 16;
static constexpr std::size_t kMaxResourceUris = 16;
static constexpr std::size_t kMaxDnsDomains = 16;
static constexpr std::size_t kMaxPolicyRules = 5; // Google: 5 per policy.
static constexpr std::size_t kMaxPolicyTargets = 16;
static constexpr std::size_t kMaxPolicyBytes = 32 * 1024;
// Identity limits.
static constexpr std::size_t kMaxPrincipalChars = 512;
static constexpr std::size_t kMaxDenyPrincipals = 32;
static constexpr std::size_t kMaxDenyPermissions = 64;
// Local approval ledger and audit trail (not Google state).
static constexpr std::size_t kMaxLedgerEntries = 5000;
static constexpr std::size_t kMaxAuditEntries = 500;
static constexpr std::size_t kMaxNoteChars = 512;
static constexpr std::size_t kMaxActorChars = 128;
};
} // namespace molo::google::registry
+187
View File
@@ -0,0 +1,187 @@
#include "google/registry/gateway_policy.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
namespace molo::google::registry {
using clients::body::Json;
const char* policy_action_name(PolicyAction a) {
switch (a) {
case PolicyAction::kAllow: return "ALLOW";
case PolicyAction::kDeny: return "DENY";
case PolicyAction::kCustom: return "CUSTOM";
case PolicyAction::kDenyByDefault: return "DENY_BY_DEFAULT";
}
return "ALLOW";
}
const char* policy_profile_name(PolicyProfile p) {
return p == PolicyProfile::kContentAuthz ? "CONTENT_AUTHZ" : "REQUEST_AUTHZ";
}
void ModelArmorReference::validate() const {
if (request_template.empty() && response_template.empty())
throw GoogleError::invalid("a Model Armor reference needs a request or response template");
if (!request_template.empty()) Ids::require_template_name(request_template);
if (!response_template.empty()) Ids::require_template_name(response_template);
}
std::string ModelArmorReference::settings_value() const {
validate();
Json entry = Json::object();
if (!request_template.empty()) entry.set("request_template_id", Json(request_template));
if (!response_template.empty()) entry.set("response_template_id", Json(response_template));
Json list = Json::array();
list.push(entry);
return list.dump();
}
Json ModelArmorReference::extension_metadata() const {
Json m = Json::object();
m.set("model_armor_settings", Json(settings_value()));
return m;
}
Json AuthzPolicySpec::to_json(bool include_profile) const {
Ids::require_text(description, RegistryCaps::kMaxDescription, "description");
if (labels.size() > RegistryCaps::kMaxLabels) throw GoogleError::invalid("too many labels");
if (target_resources.empty() || target_resources.size() > RegistryCaps::kMaxPolicyTargets)
throw GoogleError::invalid("a policy needs 1..16 target resources");
if (!load_balancing_scheme.empty() && load_balancing_scheme != "INTERNAL_MANAGED" &&
load_balancing_scheme != "EXTERNAL_MANAGED" &&
load_balancing_scheme != "INTERNAL_SELF_MANAGED")
throw GoogleError::invalid("unknown load balancing scheme");
if (!http_rules.is_array()) throw GoogleError::invalid("httpRules must be an array");
if (http_rules.as_array().size() > RegistryCaps::kMaxPolicyRules)
throw GoogleError::invalid("at most 5 http rules per policy");
for (const Json& r : http_rules.as_array())
if (!r.is_object()) throw GoogleError::invalid("each http rule must be an object");
bool has_provider = cloud_iap || !extension_resources.empty();
if (action == PolicyAction::kCustom) {
if (!has_provider) throw GoogleError::invalid("CUSTOM needs a customProvider");
if (cloud_iap && !extension_resources.empty())
throw GoogleError::invalid("customProvider is either cloudIap or authzExtension");
} else if (has_provider) {
throw GoogleError::invalid("customProvider requires action CUSTOM");
}
Json j = Json::object();
if (!description.empty()) j.set("description", Json(description));
if (!labels.empty()) {
Json l = Json::object();
for (const auto& kv : labels) {
if (kv.first.empty()) throw GoogleError::invalid("label key is empty");
Ids::require_text(kv.first, RegistryCaps::kMaxLabelChars, "label key");
Ids::require_text(kv.second, RegistryCaps::kMaxLabelChars, "label value");
l.set(kv.first, Json(kv.second));
}
j.set("labels", l);
}
Json target = Json::object();
if (!load_balancing_scheme.empty())
target.set("loadBalancingScheme", Json(load_balancing_scheme));
Json res = Json::array();
for (const auto& r : target_resources) {
if (r.empty() || r.find("..") != std::string::npos || r.find(' ') != std::string::npos)
throw GoogleError::invalid("target resource is malformed");
Ids::require_text(r, 512, "target resource");
res.push(Json(r));
}
target.set("resources", res);
j.set("target", target);
if (!http_rules.as_array().empty()) j.set("httpRules", http_rules);
j.set("action", Json(policy_action_name(action)));
if (action == PolicyAction::kCustom) {
Json p = Json::object();
if (cloud_iap) {
p.set("cloudIap", Json::object());
} else {
Json ext = Json::object();
Json rs = Json::array();
for (const auto& e : extension_resources) {
if (e.empty() || e.find("..") != std::string::npos)
throw GoogleError::invalid("extension resource is malformed");
Ids::require_text(e, 512, "extension resource");
rs.push(Json(e));
}
ext.set("resources", rs);
p.set("authzExtension", ext);
}
j.set("customProvider", p);
}
if (include_profile) j.set("policyProfile", Json(policy_profile_name(profile)));
if (j.dump().size() > RegistryCaps::kMaxPolicyBytes)
throw GoogleError::invalid("policy is too large");
return j;
}
ServiceEndpoint GatewayPolicies::default_endpoint() {
return endpoints::custom("networksecurity", "https://networksecurity.googleapis.com/v1");
}
GatewayPolicies::GatewayPolicies(std::shared_ptr<GoogleClient> client, CloudContext context)
: RegistryService(std::move(client), default_endpoint(), std::move(context)) {}
Json GatewayPolicies::list() const {
return runner_.list("networksecurity.v1.authzPolicies.list", "authzPolicies",
with("parent", context_.parent()));
}
Json GatewayPolicies::get(const std::string& id) const {
return runner_.invoke("networksecurity.v1.authzPolicies.get",
with("name", context_.child("authzPolicies", id)));
}
Json GatewayPolicies::create_policy(const std::string& id, const AuthzPolicySpec& spec,
const std::string& request_id) const {
Ids::require_segment(id, "policy id");
CallArgs a = with("parent", context_.parent());
a.body = spec.to_json(true);
a.query["authzPolicyId"] = id;
put_query(a, "requestId", request_id);
if (exists([&] { return get(id); }))
throw GoogleError(409, "ALREADY_EXISTS", "policy " + id + " already exists");
runner_.mutate("networksecurity.v1.authzPolicies.create", a);
return get(id);
}
Json GatewayPolicies::update_policy(const std::string& id, const AuthzPolicySpec& spec,
const std::vector<std::string>& mask,
const std::string& request_id) const {
Ids::require_segment(id, "policy id");
for (const auto& f : mask)
if (f == "policyProfile")
throw GoogleError::invalid("policyProfile cannot be changed after creation");
CallArgs a = with("name", context_.child("authzPolicies", id));
a.body = spec.to_json(false);
a.query["updateMask"] = CallRunner::update_mask("networksecurity.v1.authzPolicies.patch", mask);
put_query(a, "requestId", request_id);
get(id);
runner_.mutate("networksecurity.v1.authzPolicies.patch", a);
return get(id);
}
Json GatewayPolicies::remove_policy(const std::string& id, const std::string& request_id) const {
Ids::require_segment(id, "policy id");
get(id);
CallArgs a = with("name", context_.child("authzPolicies", id));
put_query(a, "requestId", request_id);
return runner_.mutate("networksecurity.v1.authzPolicies.delete", a);
}
Json GatewayPolicies::iam_policy(const std::string& id) const {
return runner_.invoke("networksecurity.v1.authzPolicies.getIamPolicy",
with("resource", context_.child("authzPolicies", id)));
}
Json GatewayPolicies::operation(const std::string& operation_id) const {
Ids::require_segment(operation_id, "operation id");
return runner_.invoke("networksecurity.v1.operations.get",
with("name", context_.parent() + "/operations/" + operation_id));
}
} // namespace molo::google::registry
+74
View File
@@ -0,0 +1,74 @@
#pragma once
// Gateway policies: Cloud authz policies (networksecurity.googleapis.com/v1
// projects.locations.authzPolicies) that target an Agent Gateway, plus the
// Model Armor attachment as a REFERENCE only (template names validated and
// rendered into authz extension metadata; Model Armor itself belongs to the
// armor module).
#include <map>
#include <memory>
#include <string>
#include <vector>
#include "google/registry/registry_service.h"
namespace molo::google::registry {
enum class PolicyAction { kAllow, kDeny, kCustom, kDenyByDefault };
enum class PolicyProfile { kRequestAuthz, kContentAuthz };
const char* policy_action_name(PolicyAction a);
const char* policy_profile_name(PolicyProfile p);
// Names Model Armor templates to attach; does not call Model Armor.
struct ModelArmorReference {
std::string request_template; // projects/{p}/locations/{l}/templates/{t}
std::string response_template; // Same form; either may be empty, not both.
void validate() const;
// Value for the authz extension's metadata key "model_armor_settings".
std::string settings_value() const;
// {"model_armor_settings": settings_value()} for the extension metadata.
clients::body::Json extension_metadata() const;
};
struct AuthzPolicySpec {
std::string description;
std::map<std::string, std::string> labels;
std::vector<std::string> target_resources; // Gateways (full resource names).
std::string load_balancing_scheme; // INTERNAL_MANAGED, ... optional
PolicyAction action = PolicyAction::kAllow;
PolicyProfile profile = PolicyProfile::kRequestAuthz; // Immutable once created.
clients::body::Json http_rules = clients::body::Json::array(); // At most 5.
// action == kCustom: exactly one provider.
std::vector<std::string> extension_resources; // customProvider.authzExtension
bool cloud_iap = false; // customProvider.cloudIap
clients::body::Json to_json(bool include_profile = true) const;
};
class GatewayPolicies : public RegistryService {
public:
GatewayPolicies(std::shared_ptr<GoogleClient> client, CloudContext context);
static ServiceEndpoint default_endpoint(); // networksecurity .../v1
clients::body::Json list() const;
clients::body::Json get(const std::string& id) const;
// Explicit policy changes; each reads first and waits for the operation.
clients::body::Json create_policy(const std::string& id, const AuthzPolicySpec& spec,
const std::string& request_id = "") const;
// mask: description, labels, target, httpRules, action, customProvider.
// policyProfile cannot be changed and is refused.
clients::body::Json update_policy(const std::string& id, const AuthzPolicySpec& spec,
const std::vector<std::string>& mask,
const std::string& request_id = "") const;
clients::body::Json remove_policy(const std::string& id, const std::string& request_id = "") const;
clients::body::Json iam_policy(const std::string& id) const;
clients::body::Json operation(const std::string& operation_id) const;
};
} // namespace molo::google::registry
+101
View File
@@ -0,0 +1,101 @@
#include "google/registry/ids.h"
#include <vector>
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/resource.h"
namespace molo::google::registry {
namespace {
std::vector<std::string> split(const std::string& s) {
std::vector<std::string> out;
std::string cur;
for (char c : s) {
if (c == '/') {
out.push_back(cur);
cur.clear();
} else {
cur += c;
}
}
out.push_back(cur);
return out;
}
bool known_collection(const std::string& c) {
return c == "agents" || c == "mcpServers" || c == "endpoints" ||
c == "skills" || c == "services";
}
} // namespace
bool Ids::service_id(const std::string& id) {
if (id.size() < RegistryCaps::kMinServiceId || id.size() > RegistryCaps::kMaxServiceId)
return false;
if (!(id[0] >= 'a' && id[0] <= 'z')) return false;
for (char c : id)
if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-')) return false;
return true;
}
void Ids::require_service_id(const std::string& id) {
if (!service_id(id))
throw GoogleError::invalid("service id must be 4-63 of a-z 0-9 - and start with a letter");
}
void Ids::require_segment(const std::string& id, const char* what) {
if (!valid_segment(id)) throw GoogleError::invalid(std::string("bad ") + what);
}
bool Ids::asset_name(const std::string& name) {
if (name.size() > 512) return false;
auto p = split(name);
if (p.size() != 6) return false;
return p[0] == "projects" && p[2] == "locations" && known_collection(p[4]) &&
valid_segment(p[1]) && valid_segment(p[3]) && valid_segment(p[5]);
}
void Ids::require_asset_name(const std::string& name) {
if (!asset_name(name))
throw GoogleError::invalid(
"asset name must be projects/{p}/locations/{l}/{agents|mcpServers|endpoints|skills|services}/{id}");
}
std::string Ids::collection_of(const std::string& name) {
require_asset_name(name);
return split(name)[4];
}
void Ids::require_template_name(const std::string& name) {
auto p = split(name);
if (name.size() > 512 || p.size() != 6 || p[0] != "projects" || p[2] != "locations" ||
p[4] != "templates" || !valid_segment(p[1]) || !valid_segment(p[3]) ||
!valid_segment(p[5]))
throw GoogleError::invalid("template must be projects/{p}/locations/{l}/templates/{t}");
}
void Ids::require_request_id(const std::string& id) {
if (id.empty()) return;
bool nonzero = false;
bool ok = id.size() == 36;
for (std::size_t i = 0; ok && i < id.size(); ++i) {
char c = id[i];
if (i == 8 || i == 13 || i == 18 || i == 23) {
ok = c == '-';
} else {
ok = (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
if (ok && c != '0') nonzero = true;
}
}
if (!ok || !nonzero) throw GoogleError::invalid("request id must be a non-zero UUID");
}
void Ids::require_text(const std::string& text, std::size_t max, const char* what) {
if (text.size() > max)
throw GoogleError::invalid(std::string(what) + " is too long");
for (unsigned char c : text)
if (c < 0x20 || c == 0x7f)
throw GoogleError::invalid(std::string(what) + " has control characters");
}
} // namespace molo::google::registry
+39
View File
@@ -0,0 +1,39 @@
#pragma once
// Input validation for ids and resource names. Every id is checked here
// before any network traffic; a bad one throws GoogleError (invalid).
#include <string>
namespace molo::google::registry {
class Ids {
public:
// Registry service id: 4..63 of [a-z0-9-], starting with a letter.
static bool service_id(const std::string& id);
static void require_service_id(const std::string& id);
// Any single path segment (gateway id, policy id, engine id).
static void require_segment(const std::string& id, const char* what);
// "projects/{p}/locations/{l}/{collection}/{id}" for one of the registry
// collections (agents, mcpServers, endpoints, skills, services).
static bool asset_name(const std::string& name);
static void require_asset_name(const std::string& name);
// Collection segment of a valid asset name ("agents", ...).
static std::string collection_of(const std::string& name);
// Model Armor template: projects/{p}/locations/{l}/templates/{t}.
static void require_template_name(const std::string& name);
// Request id: a UUID, not the all-zero one. Empty is allowed (none).
static void require_request_id(const std::string& id);
// Free text placed in a query string or body: length cap, no control
// characters.
static void require_text(const std::string& text, std::size_t max,
const char* what);
};
} // namespace molo::google::registry
+34
View File
@@ -0,0 +1,34 @@
#include "google/registry/operation_runner.h"
#include "google/errors.h"
namespace molo::google::registry {
using clients::body::Json;
Json OperationRunner::finish(GoogleClient& client, const ServiceEndpoint& endpoint,
const Json& reply, const Sleeper& sleeper) {
Operation op = Operation::from_json(reply);
if (op.failed())
throw GoogleError(502, "OPERATION_FAILED", op.error_message, endpoint.name);
if (!op.done) {
if (op.name.empty())
throw GoogleError(502, "UNKNOWN", "operation reply has no name", endpoint.name);
op = wait_operation(client, endpoint, op.name, sleeper);
}
Json out = Json::object();
out.set("operation", Json(op.name));
return out;
}
bool OperationRunner::exists(const std::function<Json()>& probe) {
try {
probe();
return true;
} catch (const GoogleError& e) {
if (e.http_status() == 404) return false;
throw;
}
}
} // namespace molo::google::registry
+25
View File
@@ -0,0 +1,25 @@
#pragma once
// Shared by the registry, gateway and policy services: finish a mutation's
// long-running operation, and the read-before-mutate existence probe.
#include <functional>
#include <string>
#include "google/operation.h"
namespace molo::google::registry {
class OperationRunner {
public:
// Takes the reply of a create/patch/delete call. Returns {"operation":name}
// once done; polls through wait_operation (capped) when not yet done.
static clients::body::Json finish(GoogleClient& client, const ServiceEndpoint& endpoint,
const clients::body::Json& reply,
const Sleeper& sleeper);
// True when `probe` returns, false on HTTP 404, rethrows anything else.
static bool exists(const std::function<clients::body::Json()>& probe);
};
} // namespace molo::google::registry
+28
View File
@@ -0,0 +1,28 @@
#include "google/registry/registry_service.h"
#include "google/registry/operation_runner.h"
namespace molo::google::registry {
RegistryService::RegistryService(std::shared_ptr<GoogleClient> client, ServiceEndpoint primary,
CloudContext context)
: Service(client, std::move(primary)),
context_(std::move(context)),
runner_(std::move(client), context_.location) {}
CallArgs RegistryService::with(const std::string& var, const std::string& value) {
CallArgs a;
a.vars[var] = value;
return a;
}
void RegistryService::put_query(CallArgs& args, const std::string& key,
const std::string& value) {
if (!value.empty()) args.query[key] = value;
}
bool RegistryService::exists(const std::function<clients::body::Json()>& probe) {
return OperationRunner::exists(probe);
}
} // namespace molo::google::registry
+38
View File
@@ -0,0 +1,38 @@
#pragma once
// Base of the four services in this module. A Service whose requests all go
// through the call table (CallRunner), so path, method, query and body
// fields are the ones the discovery documents list.
#include <memory>
#include <string>
#include <vector>
#include "google/registry/call_runner.h"
#include "google/resource.h"
#include "google/service.h"
namespace molo::google::registry {
class RegistryService : public Service {
public:
RegistryService(std::shared_ptr<GoogleClient> client, ServiceEndpoint primary,
CloudContext context);
const CloudContext& context() const { return context_; }
CallRunner& runner() { return runner_; }
const CallRunner& runner() const { return runner_; }
void set_sleeper(Sleeper sleeper) { runner_.set_sleeper(std::move(sleeper)); }
protected:
// CallArgs preset with one path variable.
static CallArgs with(const std::string& var, const std::string& value);
static void put_query(CallArgs& args, const std::string& key, const std::string& value);
// Read-before-mutate probe: true when `probe` returns, false on 404.
static bool exists(const std::function<clients::body::Json()>& probe);
CloudContext context_;
CallRunner runner_;
};
} // namespace molo::google::registry
+106
View File
@@ -0,0 +1,106 @@
#include "google/registry/service_record.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
namespace molo::google::registry {
using clients::body::Json;
const char* protocol_binding_name(ProtocolBinding b) {
switch (b) {
case ProtocolBinding::kJsonRpc: return "JSONRPC";
case ProtocolBinding::kGrpc: return "GRPC";
case ProtocolBinding::kHttpJson: return "HTTP_JSON";
}
return "PROTOCOL_BINDING_UNSPECIFIED";
}
Json Interface::to_json() const {
if (url.empty() || url.size() > RegistryCaps::kMaxUrlChars)
throw GoogleError::invalid("interface url is empty or too long");
if (url.rfind("https://", 0) != 0 && url.rfind("http://", 0) != 0)
throw GoogleError::invalid("interface url must start with https:// or http://");
Ids::require_text(url, RegistryCaps::kMaxUrlChars, "interface url");
Json j = Json::object();
j.set("url", Json(url));
j.set("protocolBinding", Json(protocol_binding_name(binding)));
return j;
}
Interface Interface::from_json(const Json& doc) {
Interface i;
if (const Json* u = doc.find("url"); u && u->is_string()) i.url = u->as_string();
if (const Json* b = doc.find("protocolBinding"); b && b->is_string()) {
if (b->as_string() == "JSONRPC") i.binding = ProtocolBinding::kJsonRpc;
else if (b->as_string() == "GRPC") i.binding = ProtocolBinding::kGrpc;
}
return i;
}
const char* ServiceRecord::spec_field(SpecKind kind) {
switch (kind) {
case SpecKind::kAgent: return "agentSpec";
case SpecKind::kMcpServer: return "mcpServerSpec";
case SpecKind::kEndpoint: return "endpointSpec";
}
return "agentSpec";
}
Json ServiceRecord::to_json() const {
Ids::require_text(display_name, RegistryCaps::kMaxDisplayName, "displayName");
Ids::require_text(description, RegistryCaps::kMaxDescription, "description");
if (interfaces.size() > RegistryCaps::kMaxInterfaces)
throw GoogleError::invalid("too many interfaces");
bool has_content = !content.is_null();
if (has_content && !content.is_object())
throw GoogleError::invalid("spec content must be a JSON object");
if (has_content && content.dump().size() > RegistryCaps::kMaxSpecBytes)
throw GoogleError::invalid("spec content exceeds 10 KB");
if (spec_type == "NO_SPEC") {
if (has_content) throw GoogleError::invalid("NO_SPEC takes no content");
} else if (kind == SpecKind::kAgent && spec_type == "A2A_AGENT_CARD") {
if (!interfaces.empty())
throw GoogleError::invalid("A2A_AGENT_CARD: interfaces must be empty");
} else if (kind == SpecKind::kMcpServer && spec_type == "TOOL_SPEC") {
// Content is the tools/list response.
} else {
throw GoogleError::invalid("spec type " + spec_type + " is not valid for this kind");
}
Json j = Json::object();
if (!display_name.empty()) j.set("displayName", Json(display_name));
if (!description.empty()) j.set("description", Json(description));
if (!interfaces.empty()) {
Json arr = Json::array();
for (const auto& i : interfaces) arr.push(i.to_json());
j.set("interfaces", arr);
}
Json spec = Json::object();
spec.set("type", Json(spec_type));
if (has_content) spec.set("content", content);
j.set(spec_field(kind), spec);
return j;
}
ServiceRecord ServiceRecord::from_json(const Json& doc) {
ServiceRecord r;
if (const Json* v = doc.find("displayName"); v && v->is_string()) r.display_name = v->as_string();
if (const Json* v = doc.find("description"); v && v->is_string()) r.description = v->as_string();
if (const Json* a = doc.find("interfaces"); a && a->is_array())
for (const Json& i : a->as_array()) r.interfaces.push_back(Interface::from_json(i));
for (SpecKind k : {SpecKind::kAgent, SpecKind::kMcpServer, SpecKind::kEndpoint}) {
const Json* s = doc.find(spec_field(k));
if (!s || !s->is_object()) continue;
r.kind = k;
if (const Json* t = s->find("type"); t && t->is_string()) r.spec_type = t->as_string();
if (const Json* c = s->find("content")) r.content = *c;
break;
}
return r;
}
} // namespace molo::google::registry
+45
View File
@@ -0,0 +1,45 @@
#pragma once
// A registry Service (projects.locations.services): the writable entry that
// becomes an Agent, an MCP server or an Endpoint in the registry. Field
// names and enums come from the agentregistry discovery document.
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::google::registry {
enum class ProtocolBinding { kJsonRpc, kGrpc, kHttpJson };
const char* protocol_binding_name(ProtocolBinding b);
struct Interface {
std::string url;
ProtocolBinding binding = ProtocolBinding::kHttpJson;
clients::body::Json to_json() const;
static Interface from_json(const clients::body::Json& doc);
};
enum class SpecKind { kAgent, kMcpServer, kEndpoint };
struct ServiceRecord {
std::string display_name; // Max 63.
std::string description; // Max 2048.
std::vector<Interface> interfaces;
SpecKind kind = SpecKind::kAgent;
// Agent: NO_SPEC | A2A_AGENT_CARD. MCP server: NO_SPEC | TOOL_SPEC.
// Endpoint: NO_SPEC.
std::string spec_type = "NO_SPEC";
clients::body::Json content; // Null: none. Max 10 KB serialized.
// Validates every field against the caps and the documented spec rules,
// then builds the request body. Throws GoogleError (invalid).
clients::body::Json to_json() const;
static ServiceRecord from_json(const clients::body::Json& doc);
static const char* spec_field(SpecKind kind); // agentSpec, ...
};
} // namespace molo::google::registry
+64
View File
@@ -0,0 +1,64 @@
#include "google/registry/skill_record.h"
#include "google/errors.h"
#include "google/registry/caps.h"
#include "google/registry/ids.h"
namespace molo::google::registry {
using clients::body::Json;
const char* skill_target_state_name(SkillState s) {
switch (s) {
case SkillState::kDraft: return "TARGET_STATE_DRAFT";
case SkillState::kActive: return "TARGET_STATE_ACTIVE";
case SkillState::kDisabled: return "TARGET_STATE_DISABLED";
case SkillState::kDeprecated: return "TARGET_STATE_DEPRECATED";
case SkillState::kDecommissioned: return "TARGET_STATE_DECOMMISSIONED";
}
return "TARGET_STATE_UNSPECIFIED";
}
Json SkillRevisionRecord::to_json() const {
bool gcs = !gcs_uri.empty();
bool inline_archive = !archive_base64.empty();
if (gcs == inline_archive)
throw GoogleError::invalid("a revision needs exactly one of gcs uri or inline archive");
Json j = Json::object();
if (gcs) {
if (gcs_uri.rfind("gs://", 0) != 0 || gcs_uri.size() > 1024)
throw GoogleError::invalid("gcs uri must start with gs://");
Ids::require_text(gcs_uri, 1024, "gcs uri");
Ids::require_text(gcs_generation, 32, "gcs generation");
Json s = Json::object();
s.set("uri", Json(gcs_uri));
if (!gcs_generation.empty()) s.set("generation", Json(gcs_generation));
j.set("gcsSource", s);
} else {
if (archive_base64.size() > RegistryCaps::kMaxArchiveBase64)
throw GoogleError::invalid("inline archive is too large");
Json s = Json::object();
s.set("archiveContent", Json(archive_base64));
j.set("archiveUploadSource", s);
}
return j;
}
Json SkillRecord::to_create_json(const SkillRevisionRecord* initial) const {
if (display_name.empty()) throw GoogleError::invalid("skill displayName is required");
Ids::require_text(display_name, RegistryCaps::kMaxSkillDisplayName, "displayName");
Ids::require_text(description, RegistryCaps::kMaxDescription, "description");
Ids::require_text(publisher, 512, "publisher");
Ids::require_text(default_revision, 512, "defaultRevision");
Json j = Json::object();
j.set("displayName", Json(display_name));
if (!description.empty()) j.set("description", Json(description));
j.set("type", Json("SIMPLE"));
j.set("targetState", Json(skill_target_state_name(target_state)));
if (!publisher.empty()) j.set("publisher", Json(publisher));
if (!default_revision.empty()) j.set("defaultRevision", Json(default_revision));
if (initial) j.set("initialRevision", initial->to_json());
return j;
}
} // namespace molo::google::registry
+37
View File
@@ -0,0 +1,37 @@
#pragma once
// Skills (agentregistry v1alpha): Skill, SkillRevision. Unlike agents and
// MCP servers, a Skill has a real lifecycle field, `targetState`, so
// approve/deprecate on skills is a Google PATCH, not local state.
#include <string>
#include "clients/body/json.h"
namespace molo::google::registry {
// Skill.targetState values (discovery: TARGET_STATE_*).
enum class SkillState { kDraft, kActive, kDisabled, kDeprecated, kDecommissioned };
const char* skill_target_state_name(SkillState s);
struct SkillRevisionRecord {
// Exactly one source: a Cloud Storage archive, or inline archive bytes.
std::string gcs_uri; // gs://bucket/object
std::string gcs_generation; // Optional.
std::string archive_base64; // archiveUploadSource.archiveContent
clients::body::Json to_json() const;
};
struct SkillRecord {
std::string display_name; // Required, max 128.
std::string description; // Max 2048.
std::string publisher; // Optional publisher resource name.
SkillState target_state = SkillState::kDraft;
std::string default_revision; // Optional full revision name.
// Body for skills.create (type SIMPLE). `initial` is optional.
clients::body::Json to_create_json(const SkillRevisionRecord* initial = nullptr) const;
};
} // namespace molo::google::registry
@@ -0,0 +1,118 @@
#!/usr/bin/env python3
"""Verify the registry call table against Google's discovery documents.
Reads every row of the table in ../calls.cpp, fetches the discovery document
of its service and version (no credential needed), and fails when a row is
not backed by it: unknown rpc method id, different HTTP method or path,
query parameter the method does not list, request schema mismatch, or a
request field that the schema does not have.
python3 -I src/google/registry/tools/check_discovery.py [--cache DIR]
Standard library only. Exit status 0: every row verified.
"""
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")
ROW = re.compile(r'^\s*\{(".*")\},\s*$')
def rows():
out = []
for line in open(CALLS, encoding="utf-8"):
m = ROW.match(line)
if not m:
continue
cols = re.findall(r'"((?:[^"\\]|\\.)*)"', m.group(1))
if len(cols) != 9:
sys.exit("bad table row: " + line.strip())
out.append(dict(zip(
["id", "method", "path", "service", "version", "rpc", "request", "query", "fields"], cols)))
return out
def fetch(service, version, cache):
name = "%s_%s.json" % (service, version)
if cache:
path = os.path.join(cache, name)
if os.path.exists(path):
return json.load(open(path, encoding="utf-8"))
url = "https://%s.googleapis.com/$discovery/rest?version=%s" % (service, version)
with urllib.request.urlopen(url, timeout=60) as r:
data = r.read()
if cache:
os.makedirs(cache, exist_ok=True)
open(os.path.join(cache, name), "wb").write(data)
return json.loads(data)
def methods(doc):
found = {}
def walk(resources):
for r in resources.values():
for m in r.get("methods", {}).values():
found[m["id"]] = m
walk(r.get("resources", {}))
walk(doc.get("resources", {}))
return found
def main():
cache = None
if "--cache" in sys.argv:
cache = sys.argv[sys.argv.index("--cache") + 1]
table = rows()
if not table:
sys.exit("no rows found in calls.cpp")
docs, failures, ids = {}, [], set()
for row in table:
if row["id"] in ids:
failures.append("%s: duplicate id" % row["id"])
ids.add(row["id"])
key = (row["service"], row["version"])
if key not in docs:
doc = fetch(*key, cache)
docs[key] = (doc, methods(doc))
doc, found = docs[key]
m = found.get(row["rpc"])
if m is None:
failures.append("%s: rpc %s not in discovery" % (row["id"], row["rpc"]))
continue
if m["httpMethod"] != row["method"]:
failures.append("%s: method %s != discovery %s" % (row["id"], row["method"], m["httpMethod"]))
want = row["version"] + row["path"]
if m["path"] != want:
failures.append("%s: path %s != discovery %s" % (row["id"], want, m["path"]))
params = m.get("parameters", {})
queries = [] if row["query"] == "-" else row["query"].split(",")
listed = sorted(k for k, v in params.items() if v.get("location") == "query")
for q in queries:
if q not in listed:
failures.append("%s: query %s not listed" % (row["id"], q))
if sorted(queries) != listed:
failures.append("%s: query list differs from discovery %s" % (row["id"], listed))
req = m.get("request", {}).get("$ref", "-")
if req != row["request"]:
failures.append("%s: request %s != discovery %s" % (row["id"], row["request"], req))
if req != "-" and row["fields"] != "-":
props = doc["schemas"].get(req, {}).get("properties", {})
for f in row["fields"].split(","):
if f and f not in props:
failures.append("%s: field %s not in schema %s" % (row["id"], f, req))
print("checked %d calls across %d discovery documents" % (len(table), len(docs)))
for f in failures:
print("FAIL", f)
if failures:
sys.exit(1)
print("OK: every declared call, query parameter and request field is in discovery")
if __name__ == "__main__":
main()