5.9 KiB
5.9 KiB
Google Cloud APIs - Specification
Owned directory: src/google/. Namespace molo::google. Depends on
molo::clients (HTTP client, JSON DOM, transports) and the Base64 codec in
src/security/crypto. No other part is included.
Purpose: one generic way to call any Google Cloud REST API, plus concrete
services built on it. Voice (text-to-speech, speech-to-text, Gemini reply and audio,
conversation pipeline) is the first set. Adding a service means one
ServiceEndpoint constant and one Service subclass; no change to the
client, credentials, errors, or caps.
1. Module map (one class or concern per file)
| File | Concern |
|---|---|
caps.h |
Static ceilings, never autotuned |
errors.h/.cpp |
GoogleError (http status, Google status, message), NotConfiguredError, parser for Google's {"error":{...}} body |
credentials.h/.cpp |
Credentials: API key and OAuth bearer providers, env loader |
service_account.h/.cpp |
ServiceAccountKey, JwtSigner (RS256), ServiceAccountAuth (self-refreshing bearer) |
endpoints.h/.cpp |
ServiceEndpoint plus the catalog of known services |
client.h/.cpp |
GoogleClient: auth, JSON in/out, error mapping, over any clients::Transport |
service.h/.cpp |
Service base class: holds client plus endpoint, one call() |
text_to_speech.h/.cpp |
TextToSpeech::synthesize, voices |
speech_to_text.h/.cpp |
SpeechToText::recognize |
generative.h/.cpp |
Generative::generate (Gemini generateContent) |
voice_io.h/.cpp |
Recognizer, Synthesizer seams plus request and audio types |
gemini_voice.h/.cpp |
Gemini-based Recognizer and Synthesizer |
voice_backend.h/.cpp |
cloud / gemini / vertex selection and wiring |
wav.h/.cpp |
PCM16 to WAV |
voice.h/.cpp |
Responder, GenerativeResponder, VoiceSessions, VoicePipeline |
2. Static caps (see caps.h)
| Knob | Value |
|---|---|
| TTS text characters per request | 5000 |
| STT audio bytes per request | 10 MiB (Google sync limit) |
| Generation output tokens | 300 default, 1024 max |
| Conversation history | 20 turns per conversation |
| Conversations held in memory | 1000, oldest evicted |
| Conversation id | [A-Za-z0-9_-], 1 to 64 chars |
| Message text per history entry | 4000 characters |
| Request timeout (total) | 60 s (client default) |
3. Contracts
- Two credentials per client: an API key and an OAuth credential (bearer
token or service account via
GOOGLE_APPLICATION_CREDENTIALS). OAuth is used for every endpoint except express ones (ServiceEndpoint::prefer_key, the Vertex express voice path), which only accept the key. - Credentials:
GOOGLE_API_KEYis read once byGoogleClient::from_env()from the process environment, else.env.json.local(git-ignored, put secrets here), else.env.json, in the working directory. All env knobs below follow the same order. The key travels in thex-goog-api-keyheader, never in the URL, so it never reaches a span, log line, or proxy URL. Bearer tokens (OAuth, for APIs that refuse keys) use the same seam:Credentials::bearer; aGOOGLE_ACCESS_TOKEN(same lookup order) takes precedence over a key. Tokens expire after about an hour; refresh is the caller's job (gap). - Test runs set
MOLO_ENV_FILES=off: config files are ignored so a developer's.env.json.localcannot change test outcomes.MOLO_LIVE_NET=1re-enables them for the opt-in live checks.make google-liveis the entry point: it mints a service-account token (build/google/sa-token), exports it asGOOGLE_ACCESS_TOKEN, and runs the full suite withMOLO_LIVE_NET=1. - No key:
configured()is false and every call throwsNotConfiguredError(HTTP 503, statusNOT_CONFIGURED) before any network traffic. Loud, not silent. - Upstream failure: any non-2xx becomes
GoogleErrorcarrying the HTTP status, Google'sstatusstring (PERMISSION_DENIED,RESOURCE_EXHAUSTED, ...) and message. Transport failures becomeGoogleErrorwith statusUNAVAILABLE. The key is never part of an error message. - Invalid input (empty text, text over cap, empty or oversized audio, bad
conversation id) throws
GoogleError400INVALID_ARGUMENTbefore any network traffic. - Transports are swappable: production uses
HttpTransport(HTTPS via wolfSSL), tests useMockTransport. Calling code does not change. - Voice replies disable model thinking (
thinkingBudget0): reasoning tokens count against the output cap and truncated spoken replies in practice. - Backends (
voice_backend.h):cloud(classic TTS/STT),gemini(generativelanguage audio in/out),vertex(aiplatform, express keys startingAQ.).GOOGLE_API_BACKENDoverrides the key-prefix guess. Gemini TTS returns raw PCM; the server wraps it as WAV. - Env knobs:
GOOGLE_API_KEY,GOOGLE_VOICE_LANG(defaultnl-NL),GOOGLE_VOICE_NAME(default empty: Google picks the language default),GOOGLE_GENAI_MODEL(defaultgemini-3.5-flash). VoicePipeline::turn= recognize, respond, synthesize. Silence (empty transcript) returns an empty result with no reply and no synthesis, so a quiet room costs one STT call and nothing else.- History is bounded per conversation and conversations are bounded in count; both evict oldest first.
4. Gaps
- Streaming recognition (gRPC/WebSocket) and the Gemini Live API are not implemented; turns are request/response over REST.
- Service-account OAuth is implemented (
service_account.h: RS256 JWT via wolfCrypt, token exchange, refresh 60 s before expiry) and its signing is tested with real RSA keys. The token exchange against Google itself is unverified until a key file is configured (GOOGLE_APPLICATION_CREDENTIALS). - Free-tier quota accounting is Google's;
RESOURCE_EXHAUSTEDis surfaced, not tracked. - Live behavior against Google needs a real
GOOGLE_API_KEY; the suite proves request shape and error mapping with scripted responses only.