diff --git a/example/app/agent/LiveDemo.cpp b/example/app/agent/LiveDemo.cpp index 5b17e93..ae4b56d 100644 --- a/example/app/agent/LiveDemo.cpp +++ b/example/app/agent/LiveDemo.cpp @@ -1,13 +1,251 @@ #include "../AgentDemos.hpp" +#include + #include "../../fw/Router.hpp" +#include "../../fw/Templates.hpp" +#include "../../fw/Validate.hpp" +#include "clients/body/json.h" +#include "google/credentials.h" +#include "google/errors.h" +#include "google/live/live_relay.h" +#include "google/resource.h" +#include "security/crypto/Base64.h" namespace molo::example::app { -// Agent Platform: live. Stub: the module agent fills this in. +// Agent Platform: live. The Gemini Live API is a WebSocket protocol; the +// example server has none, so the browser talks HTTP and the server holds +// the WebSocket (src/google/live): POST create, POST send, GET events by +// cursor, POST close. Every route that would reach Google is a POST (or the +// events GET of an existing session) and answers 503 google_not_configured +// without a credential. + +namespace { + +using clients::body::Json; +namespace live = google::live; + +const char kLivePage[] = R"LIVE({% extends "base.html" %} +{% block content %} +

Live API

+

Bidirectional text, audio and video with Gemini over a +WebSocket held by the server. Create a session, send a message, and read the +events as they arrive.

+

Checking Google credentials...

+
+
+ + +no session +
+ +
    +
    + + +
    +
    + +{% endblock %} +)LIVE"; + +std::string env_or(const char* name, const char* fallback) { + std::string v = google::Credentials::env(name); + return v.empty() ? std::string(fallback) : v; +} + +[[noreturn]] void rethrow(const google::GoogleError& e) { + if (e.http_status() == 503 && e.status() == "NOT_CONFIGURED") + throw fw::HttpError(503, "google_not_configured", e.message()); + if (e.service().empty() && e.status() == "INVALID_ARGUMENT") + throw fw::HttpError(422, "validation_error", e.message()); + if (e.status() == "INVALID_ARGUMENT") + throw fw::HttpError(422, "validation_error", e.message()); + if (e.status() == "NOT_FOUND" && e.service() == "live") + throw fw::HttpError(404, "not_found", e.message()); + if (e.status() == "RESOURCE_EXHAUSTED" && e.service() == "live") + throw fw::HttpError(429, "too_many_sessions", e.message()); + throw fw::HttpError(502, "google_error", e.status() + ": " + e.message()); +} + +template +auto guarded(F&& f) -> decltype(f()) { + try { + return f(); + } catch (const google::GoogleError& e) { + rethrow(e); + } +} + +fw::Response json_out(const Json& j, int status = 200) { + fw::Response res = fw::JsonResponse(j.dump(), status); + res.headers.set("Cache-Control", "no-store"); + return res; +} + +// Which credential form this process would use, from the environment: +// OAuth token (Vertex), express key "AQ." (Vertex, x-goog-api-key), any +// other key (Gemini API, ?key=). +struct LiveAuth { + std::string mode = "none"; + live::LiveEndpoint endpoint; +}; + +LiveAuth resolve_auth() { + LiveAuth out; + std::string token = google::Credentials::env("GOOGLE_ACCESS_TOKEN"); + std::string key = google::Credentials::env("GOOGLE_API_KEY"); + google::CloudContext ctx = google::CloudContext::from_env(); + if (!token.empty() && !ctx.project.empty()) { + out.mode = "vertex_oauth"; + out.endpoint = live::LiveEndpoint::vertex(ctx, token); + } else if (!key.empty() && key.rfind("AQ.", 0) == 0 && !ctx.project.empty()) { + out.mode = "vertex_express"; + out.endpoint = live::LiveEndpoint::vertex_express(ctx, key); + } else if (!key.empty()) { + out.mode = "gemini_api_key"; + out.endpoint = live::LiveEndpoint::api_key(key); + } + // Tests and proxies: GOOGLE_LIVE_URL replaces the WebSocket URL. + out.endpoint.url_override = google::Credentials::env("GOOGLE_LIVE_URL"); + return out; +} + +std::string field(const std::map& in, const char* k) { + auto it = in.find(k); + return it == in.end() ? std::string() : it->second; +} + +} // namespace + void register_agent_live_demo(fw::Router& router, Services& services) { - (void)router; - (void)services; + if (!services.google) services.google = google::GoogleClient::from_env(); + auto gclient = services.google; + auto relay = std::make_shared(); + fw::Environment* env = services.templates.get(); + env->add_template("agent_live.html", kLivePage); + + services.add_feature("agent-live", "/agent/live"); + + // The client's configured() gates every Google-bound route, then the + // process environment supplies the credential the socket needs. + auto require = [gclient]() { + if (!gclient->configured()) + throw fw::HttpError(503, "google_not_configured", + "set GOOGLE_API_KEY (or GOOGLE_ACCESS_TOKEN and GOOGLE_CLOUD_PROJECT)"); + LiveAuth auth = resolve_auth(); + if (auth.mode == "none") + throw fw::HttpError(503, "google_not_configured", + "the live API needs GOOGLE_API_KEY in the environment"); + return auth; + }; + + router.get("/agent/live", "agent-live-page", [env](fw::Request req) { + (void)req; + fw::TemplateCtx ctx; + ctx["title"] = std::string("Live API"); + return fw::Response(200, env->render("agent_live.html", ctx), "text/html; charset=utf-8"); + }); + + router.get("/agent/live/status", "agent-live-status", [gclient, relay](fw::Request req) { + (void)req; + LiveAuth auth = resolve_auth(); + Json caps = Json::object(); + caps.set("max_sessions", (double)live::LiveCaps::kMaxRelaySessions); + caps.set("max_text_chars", (double)live::LiveCaps::kMaxTextChars); + caps.set("max_audio_chunk_bytes", (double)live::LiveCaps::kMaxAudioChunkBytes); + caps.set("max_video_chunk_bytes", (double)live::LiveCaps::kMaxVideoChunkBytes); + caps.set("max_session_seconds", (double)live::LiveCaps::kMaxSessionSeconds); + caps.set("max_page_events", (double)live::LiveCaps::kMaxRelayPage); + Json o = Json::object(); + o.set("configured", gclient->configured() && auth.mode != "none"); + o.set("auth_mode", auth.mode); + o.set("default_model", live::LiveConfig{}.model); + o.set("sessions", (double)relay->size()); + o.set("caps", caps); + return json_out(o); + }); + + // Body: {model?, system?, modality? AUDIO|TEXT, voice?, lang?, transcribe? "1"}. + router.post("/agent/live/sessions", "agent-live-create", [relay, require](fw::Request req) { + LiveAuth auth = require(); + auto in = fw::parse_json_object_flat(req.body); + live::LiveConfig cfg; + if (!field(in, "model").empty()) cfg.model = field(in, "model"); + cfg.system_instruction = field(in, "system"); + cfg.voice_name = field(in, "voice"); + cfg.language_code = field(in, "lang"); + if (!field(in, "modality").empty()) cfg.response_modalities = {field(in, "modality")}; + cfg.input_transcription = cfg.output_transcription = field(in, "transcribe") == "1"; + return guarded([&] { + std::string id = relay->create(auth.endpoint, cfg); + Json o = Json::object(); + o.set("id", id); + o.set("auth_mode", auth.mode); + return json_out(o, 201); + }); + }); + + // Body: {kind: text|audio|video|audio_end, text?, data_b64?, mime?}. + router.post("/agent/live/sessions/{id}/send", "agent-live-send", [relay, require](fw::Request req) { + require(); + auto in = fw::parse_json_object_flat(req.body); + std::string kind = field(in, "kind"); + if (kind != "text" && kind != "audio" && kind != "video" && kind != "audio_end") + throw fw::HttpError(422, "validation_error", "kind must be text, audio, video or audio_end"); + std::string bytes; + if (kind == "audio" || kind == "video") { + if (!security::crypto::Base64::decode(field(in, "data_b64"), bytes)) + throw fw::HttpError(422, "validation_error", "data_b64 is not valid base64"); + } + return guarded([&] { + auto session = relay->get(req.param_or("id", "")); + if (kind == "text") session->send_text(field(in, "text")); + else if (kind == "audio_end") session->end_audio(); + else if (kind == "audio") + field(in, "mime").empty() ? session->send_audio(bytes) : session->send_audio(bytes, field(in, "mime")); + else + field(in, "mime").empty() ? session->send_video(bytes) : session->send_video(bytes, field(in, "mime")); + Json o = Json::object(); + o.set("sent", true); + return json_out(o); + }); + }); + + // Query: cursor (last seq seen, default 0), max (default 50). + router.get("/agent/live/sessions/{id}/events", "agent-live-events", [relay](fw::Request req) { + std::string c = req.query_or("cursor", "0"), m = req.query_or("max", "50"); + auto numeric = [](const std::string& s) { + if (s.empty() || s.size() > 12) return false; + for (char ch : s) + if (ch < '0' || ch > '9') return false; + return true; + }; + if (!numeric(c) || !numeric(m)) + throw fw::HttpError(422, "validation_error", "cursor and max must be non-negative integers"); + return guarded([&] { + live::RelayPage page = relay->poll(req.param_or("id", ""), std::stoull(c), std::stoull(m)); + Json events = Json::array(); + for (const auto& e : page.events) events.push(live::event_to_json(e)); + Json o = Json::object(); + o.set("open", page.open); + o.set("next_cursor", (double)page.next_cursor); + o.set("dropped", (double)page.dropped); + o.set("events", events); + return json_out(o); + }); + }); + + router.post("/agent/live/sessions/{id}/close", "agent-live-close", [relay, require](fw::Request req) { + require(); + return guarded([&] { + relay->close(req.param_or("id", "")); + Json o = Json::object(); + o.set("closed", true); + return json_out(o); + }); + }); } } // namespace molo::example::app diff --git a/example/assets/agent_live.js b/example/assets/agent_live.js new file mode 100644 index 0000000..59f1c08 --- /dev/null +++ b/example/assets/agent_live.js @@ -0,0 +1,127 @@ +// Live API page: HTTP relay to a server-held WebSocket session. +// POST /agent/live/sessions -> id; POST .../send; GET .../events?cursor=N; +// POST .../close. Model audio (PCM16 mono, rate from the mime) is played as it arrives. +(function () { + "use strict"; + var POLL_MS = 400; + var MAX_LOG = 200; + + var $ = function (id) { return document.getElementById(id); }; + var createBtn = $("l-create"), closeBtn = $("l-close"), stateEl = $("l-state"); + var errorEl = $("l-error"), logEl = $("l-log"), form = $("l-form"), textEl = $("l-text"); + var sendBtn = form.querySelector("button"); + var sid = null, cursor = 0, timer = null, polling = false; + var audioCtx = null, playAt = 0; + + function showError(msg) { errorEl.textContent = msg || ""; } + function setState(s) { stateEl.textContent = s; stateEl.className = "pill " + (sid ? "listening" : ""); } + function setActive(on) { + createBtn.disabled = on; closeBtn.disabled = !on; + textEl.disabled = !on; sendBtn.disabled = !on; + } + function addLog(who, text) { + var li = document.createElement("li"); + li.className = who; + var b = document.createElement("b"); + b.textContent = who + ": "; + li.appendChild(b); + li.appendChild(document.createTextNode(text)); + logEl.appendChild(li); + while (logEl.children.length > MAX_LOG) logEl.removeChild(logEl.firstChild); + li.scrollIntoView({ block: "nearest" }); + } + function api(method, url, body) { + return fetch(url, { + method: method, + headers: body ? { "Content-Type": "application/json" } : {}, + body: body ? JSON.stringify(body) : undefined + }).then(function (res) { + return res.text().then(function (t) { + var j = {}; + try { j = JSON.parse(t); } catch (e) { /* keep empty */ } + if (!res.ok) throw new Error(j.message || j.error || ("HTTP " + res.status)); + return j; + }); + }); + } + + function play(b64, mime) { + var m = /rate=(\d+)/.exec(mime || ""); + var rate = m ? parseInt(m[1], 10) : 24000; + var raw = atob(b64), n = raw.length >> 1; + if (!n) return; + audioCtx = audioCtx || new (window.AudioContext || window.webkitAudioContext)(); + var buf = audioCtx.createBuffer(1, n, rate), ch = buf.getChannelData(0); + for (var i = 0; i < n; i++) { + var v = raw.charCodeAt(2 * i) | (raw.charCodeAt(2 * i + 1) << 8); + ch[i] = (v > 32767 ? v - 65536 : v) / 32768; + } + var src = audioCtx.createBufferSource(); + src.buffer = buf; src.connect(audioCtx.destination); + playAt = Math.max(playAt, audioCtx.currentTime); + src.start(playAt); playAt += buf.duration; + } + + function onEvent(e) { + switch (e.type) { + case "text": addLog("model", e.text); break; + case "output_transcription": if (e.text) addLog("model", e.text); break; + case "input_transcription": if (e.text) addLog("you", e.text); break; + case "audio": try { play(e.data_b64, e.mime); } catch (x) { showError("audio: " + x.message); } break; + case "interrupted": playAt = 0; addLog("event", "interrupted"); break; + case "turn_complete": setState("ready"); break; + case "go_away": addLog("event", "server will disconnect in " + e.seconds + "s"); break; + case "error": showError(e.text); break; + case "closed": addLog("event", "closed (" + e.code + ") " + (e.text || "")); break; + } + } + + function poll() { + if (!sid || polling) return; + polling = true; + api("GET", "/agent/live/sessions/" + sid + "/events?cursor=" + cursor + "&max=100").then(function (j) { + j.events.forEach(onEvent); + cursor = j.next_cursor; + if (!j.open && j.events.length === 0) endSession("session ended"); + }).catch(function (e) { showError(e.message); endSession("lost"); }) + .then(function () { polling = false; }); + } + + function endSession(label) { + if (timer) clearInterval(timer); + timer = null; sid = null; setActive(false); setState(label || "no session"); + } + + createBtn.addEventListener("click", function () { + showError(""); createBtn.disabled = true; setState("connecting"); + api("POST", "/agent/live/sessions", { modality: "AUDIO", transcribe: "1" }).then(function (j) { + sid = j.id; cursor = 0; setActive(true); setState("ready"); + timer = setInterval(poll, POLL_MS); + }).catch(function (e) { showError(e.message); setActive(false); setState("no session"); }); + }); + + closeBtn.addEventListener("click", function () { + var id = sid; + endSession("closing"); + if (id) api("POST", "/agent/live/sessions/" + id + "/close", {}).catch(function (e) { showError(e.message); }) + .then(function () { setState("no session"); }); + }); + + form.addEventListener("submit", function (ev) { + ev.preventDefault(); + var t = textEl.value.trim(); + if (!t || !sid) return; + textEl.value = ""; + addLog("you", t); + setState("thinking"); + api("POST", "/agent/live/sessions/" + sid + "/send", { kind: "text", text: t }) + .catch(function (e) { showError(e.message); }); + }); + + api("GET", "/agent/live/status").then(function (s) { + $("l-config").textContent = s.configured + ? "Credentials found (" + s.auth_mode + "). Default model: " + s.default_model + "." + : "No Google credential is configured: starting a session answers 503 google_not_configured."; + createBtn.disabled = false; + }).catch(function (e) { showError(e.message); }); +})(); diff --git a/src/google/live/SPEC.md b/src/google/live/SPEC.md new file mode 100644 index 0000000..d8686c8 --- /dev/null +++ b/src/google/live/SPEC.md @@ -0,0 +1,165 @@ +# Google Live API - Specification + +Owned directory: `src/google/live/`. Namespace `molo::google::live`. Depends +on `molo::google` (errors, `CloudContext`, `valid_segment`), `molo::clients` +(JSON DOM, `ITlsSession`) and the Base64 codec. Does not use `src/realtime`: +its WebSocket client is a byte-pump over a caller supplied transport with no +socket, TLS or timeout handling, and `libgoogle` does not link the realtime +part. An RFC 6455 client lives here instead. + +Scope: the Gemini Live API (bidirectional text, audio, video) over a +WebSocket, on Vertex AI and on the Gemini API (API key form). Typed setup, +typed client messages, typed server events, bounded queues, clean close, and +an HTTP relay for hosts without WebSocket. + +## 1. Module map (one class per concern) + +| File | Concern | +|---|---| +| `caps.h` | Static ceilings (`LiveCaps`) | +| `live_spec.h` | The single table of every wire field name used (`kLiveSpec`), checked by `tools/check_discovery.py` | +| `ws_error.h` | `WsError` (kind, HTTP status of a refused upgrade) | +| `ws_url.h/.cpp` | `WsUrl`: ws/wss parsing, `display()` without the query | +| `ws_frame.h/.cpp` | `encode_frame`, `FrameDecoder` (strict RFC 6455), `valid_utf8` | +| `ws_handshake.h/.cpp` | Key, SHA-1 accept, request building, 101 validation | +| `ws_stream.h/.cpp` | `IByteStream`, `TcpStream`, `TlsStream` (over `ITlsSession`), `open_stream` | +| `ws_client.h/.cpp` | `WsClient`: masking, fragmentation, ping/pong, close, caps | +| `live_endpoint.h/.cpp` | `LiveEndpoint`: URL, auth headers, model naming per mode | +| `live_config.h/.cpp` | `LiveConfig`: typed setup message | +| `live_requests.h/.cpp` | `LiveRequests`: text, turn, audio, video, audioStreamEnd, toolResponse | +| `live_events.h/.cpp` | `LiveEvent`, `LiveParser`: typed server events | +| `live_session.h/.cpp` | `LiveSession`: connect, send, bounded event queue, close | +| `live_relay.h/.cpp` | `LiveRelay`: sessions by id, events by cursor, `event_to_json` | +| `tools/check_discovery.py` | Discovery and endpoint check (python3 stdlib) | + +## 2. Static caps (see caps.h) + +| Knob | Value | +|---|---| +| Frame payload (inbound) | 4 MiB, checked from the header before buffering | +| Message (inbound, reassembled) | 8 MiB | +| Message (outbound) | 2 MiB | +| Handshake response | 16 KiB | +| Control frame payload | 125 (RFC), close reason 123 | +| Connect / handshake / setup timeout | 10 s / 10 s / 15 s | +| Socket I/O timeout, reader poll | 5 s, 200 ms | +| Close grace | 1.5 s | +| Session lifetime | 1800 s, then closed with a `Closed` event | +| Queued events / bytes | 1024 / 8 MiB, oldest dropped and counted (`stats().dropped`) | +| Text / audio chunk / video chunk | 32000 B / 256 KiB / 1 MiB | +| System instruction / function declarations / tool responses | 8000 chars / 16 / 16 | +| Relay: sessions / log / page | 8 / 512 events / 100 events | + +## 3. Contracts + +- Auth forms (`LiveEndpoint`): + - `vertex(ctx, token)`: `wss://{location}-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent` (`global`: `aiplatform.googleapis.com`), header `Authorization: Bearer `, model `projects/{p}/locations/{l}/publishers/google/models/{m}`. + - `vertex_express(ctx, key)`: same URL, header `x-goog-api-key`. The key is never in the URL. + - `api_key(key)`: `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=`, model `models/{m}`. The documented form puts the key in the query, the one place the foundation rule "key never in a URL" cannot hold; `WsUrl::display()` and every error omit the query. + - `url_override` replaces the URL (loopback tests, proxies). +- No credential: `NotConfiguredError` (503 NOT_CONFIGURED) before any socket. Bad input (model id, voice, modality, caps, mime, header characters): `GoogleError` 400 INVALID_ARGUMENT before any socket or send. +- Upstream failures map to `GoogleError` with service `live`: refused upgrade 400/401/403/404/429 keep their status, other upgrade failures and I/O are 502 UNAVAILABLE, timeouts 504 DEADLINE_EXCEEDED, a close frame before `setupComplete` is 409 FAILED_PRECONDITION carrying Google's close code and reason (e.g. 1008 "Publisher model ... was not found"). +- Framing: client frames always masked; server frames must be unmasked; RSV bits, unknown opcodes, fragmented or oversize control frames, non-minimal lengths, continuation without start, new message inside a fragmented one, invalid UTF-8 text all close with 1002 / 1007 and throw. Over-cap frame or message closes with 1009. Pings are answered with the same payload. A close frame is echoed; a dropped connection without close frame reports code 1006. +- Server JSON arrives in text and in binary frames; both are parsed. +- One server message can yield several events. Order: setupComplete; model text and inline data in part order; input/output transcription; interrupted; generationComplete; turnComplete last. Inline `audio/*` is `Audio` (decoded bytes), other inline data `Media`. Undecodable messages become one `Error` event, unknown ones `Unknown`, never silence. +- Sending is thread safe; one reader thread receives. `close()` sends a close frame, waits up to the grace, joins. +- Relay: the session resumption handle is not sent to browsers. Ids are `s` plus 12 hex chars. +- TLS: `TlsStream` uses `ITlsSession` (wolfSSL) on a blocking fd with socket read and write timeouts. The backend reports timeout and dropped connection alike (zero read or a read error), so the stream tells them apart by elapsed time against the read timeout. It ignores SIGPIPE process wide (the backend writes without `MSG_NOSIGNAL`). + +## 4. Example routes (`example/app/agent/LiveDemo.cpp`) + +| Route | Behaviour | +|---|---| +| `GET /agent/live` | mobile-first page, script `example/assets/agent_live.js`; matrix row `agent-live` | +| `GET /agent/live/status` | configured, auth mode, default model, caps | +| `POST /agent/live/sessions` | create, 201 `{id}`; 503 `google_not_configured` without credential; 422 bad input; 429 at the session cap | +| `POST /agent/live/sessions/{id}/send` | `{kind: text\|audio\|video\|audio_end, ...}`; 422, 404 unknown id | +| `GET /agent/live/sessions/{id}/events?cursor=N&max=M` | events after the cursor, `next_cursor`, `open`, `dropped` | +| `POST /agent/live/sessions/{id}/close` | 200, then 404 | + +Credential resolved from the environment: `GOOGLE_ACCESS_TOKEN` plus +`GOOGLE_CLOUD_PROJECT` (Vertex OAuth), else `GOOGLE_API_KEY` starting `AQ.` +plus project (Vertex express), else any `GOOGLE_API_KEY` (Gemini API form). +`GOOGLE_LIVE_URL` overrides the WebSocket URL. + +## 5. Verified against discovery + +`python3 -I src/google/live/tools/check_discovery.py`, run 2026-10-24: 69 +spec rows checked (2 Discovery documents, 1 documentation page), 0 +failures; 3 unauthenticated upgrade probes answered `101 Switching +Protocols` with the correct `Sec-WebSocket-Accept`. A bogus service name +answers 400, so the probe discriminates. + +- `generativelanguage/v1beta` Discovery: the setup message + `BidiGenerateContentSetup` and its nested types (generation config, speech + config, content, tool, function declaration, session resumption, context + window compression, blob, function call/response, usage metadata). +- `aiplatform/v1` Discovery: only value types (`Transcription {text, + finished}`, `Blob`); it has no Bidi setup or message schemas. +- Documentation only (no Discovery document describes them): the message + envelopes (`setup`, `clientContent`, `realtimeInput`, `toolResponse`; + `setupComplete`, `serverContent`, `toolCall`, `toolCallCancellation`, + `goAway`, `sessionResumptionUpdate`, `usageMetadata`) and their fields. + Checked by name against https://ai.google.dev/api/live. +- Endpoints: v1 and v1beta1 `LlmBidiService/BidiGenerateContent` on + `us-central1-aiplatform.googleapis.com` and the Gemini API + `GenerativeService.BidiGenerateContent` exist (101 on upgrade). + +## 6. Verified live + +All 2026-10-24, project from `GOOGLE_CLOUD_PROJECT`, model +`gemini-live-2.5-flash-native-audio`, region `us-central1`, over wss with the +wolfSSL session. Each run: upgrade, setup, `setupComplete`, one text turn +("Say hello in one short sentence."), receive until `turnComplete`, close. + +| Form | Result | +|---|---| +| Vertex, express key, header `x-goog-api-key` | works: `setupComplete`, output transcription "Hello there!", 4 audio chunks (`audio/pcm`, 11-15 KB each), `generationComplete`, `turnComplete`, clean close | +| Vertex, OAuth bearer (service account token) | works, same event sequence | +| Vertex, express key as `Authorization: Bearer` | refused: close 1008 "Request had invalid authentication credentials" | +| Gemini API form with the express key (`?key=`) | upgrade ok, close 1008 "Gemini API ... has not been used in project ... or it is disabled" (the key's project has the API disabled; the form itself is accepted) | +| `responseModalities: ["TEXT"]` on the native audio model | close 1007 "Text output is not supported for native audio output model." | +| region `global`, or model `gemini-2.0-flash-live-001` | close 1008 "Publisher model ... was not found" | + +Observed: server audio mime type is plain `audio/pcm` (no `rate=`); the +docs state 24 kHz output and 16 kHz input (`audio/pcm;rate=16000`). The +server closes TCP after its close frame without TLS close_notify. +Opt-in tests: `MOLO_LIVE_NET=1` with `GOOGLE_CLOUD_PROJECT` and +`GOOGLE_API_KEY` or `GOOGLE_ACCESS_TOKEN` (`live_net.*`, loud SKIP otherwise). + +## 7. Verified locally (deterministic, no Google) + +Framing, handshake failures, fragmentation with interleaved ping, protocol +violation closes, caps, abrupt disconnect, the TLS seam (a passthrough +`ITlsSession` with wolfSSL's zero-read contract) run against a loopback +RFC 6455 server written in `tests/src/google/live/loopback.h`. Session and +relay tests use the same server to carry hand-written JSON in the documented +shapes; that proves the module's handling of those shapes, not Google's +behavior. Request bodies are checked to use only names in `kLiveSpec`. + +## Sources + +- https://ai.google.dev/api/live (WebSocket API reference: messages, fields) +- https://ai.google.dev/gemini-api/docs/live-api/get-started-websocket (URL with `?key=`, setup, `audio/pcm;rate=16000`) +- https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta +- https://aiplatform.googleapis.com/$discovery/rest?version=v1 and `version=v1beta1` +- https://gemini-ex.hexdocs.pm/live_api.md (community client: Vertex path `wss://{location}-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent`) +- https://docs.litellm.ai/docs/providers/vertex_realtime (Vertex hosts per region, OAuth bearer) +- RFC 6455 + +## Unverified + +- The Vertex Live reference page (docs.cloud.google.com ... reference/models/live-api) could not be read in full (very large page, navigation only in the fetched part), so Vertex-specific message differences from the Gemini API reference are unread. The Vertex endpoint path and both auth forms are verified live instead. +- `?key=` on the Vertex endpoint: only seen to be accepted at upgrade, no turn run. +- Not exercised live: tool calls and tool responses, `toolCallCancellation`, `goAway`, session resumption (handle exchange, resume), context window compression, video input, `audioStreamEnd`, `clientContent` turns, input transcription, activity/VAD settings, interruption. They follow the documented shapes and are covered by local tests only. +- Express key requirement of a project in the Vertex model name: the run used the project; not tried without. +- `timeLeft` is parsed as a protobuf duration string ("30s"); the format is from the Duration type, not from a captured message. +- Session limits (audio-only 15 min, audio+video 2 min) are from a community guide; the module enforces its own 1800 s cap. + +## Gaps + +- Outbound messages are single frames (no outbound fragmentation). +- Proactivity, `historyConfig`, labels, VAD tuning, media resolution, affective dialog are not in `LiveConfig` (setup can be extended in `live_config.cpp`). +- No automatic reconnect or resume on `goAway`; the handle is available from `LiveSession::resumption_handle()`. +- Token refresh is the caller's job (foundation gap). +- The relay polls; no push to the browser (the example server has no WebSocket). diff --git a/src/google/live/caps.h b/src/google/live/caps.h new file mode 100644 index 0000000..aa94ffd --- /dev/null +++ b/src/google/live/caps.h @@ -0,0 +1,46 @@ +#pragma once + +// Static ceilings for the Live API module. Never autotuned. + +#include + +namespace molo::google::live { + +struct LiveCaps { + // WebSocket transport. + static constexpr std::size_t kMaxUrlChars = 2048; + static constexpr std::size_t kMaxHandshakeBytes = 16 * 1024; + static constexpr std::size_t kMaxFramePayload = 4u * 1024u * 1024u; + static constexpr std::size_t kMaxInboundMessage = 8u * 1024u * 1024u; + static constexpr std::size_t kMaxOutboundMessage = 2u * 1024u * 1024u; + static constexpr std::size_t kMaxControlPayload = 125; // RFC 6455 5.5 + static constexpr std::size_t kMaxCloseReason = 123; + static constexpr std::size_t kReadChunk = 16 * 1024; + static constexpr int kConnectTimeoutMs = 10000; + static constexpr int kHandshakeTimeoutMs = 10000; + static constexpr int kIoTimeoutMs = 5000; + static constexpr int kPollIntervalMs = 200; + static constexpr int kCloseGraceMs = 1500; + + // Session. + static constexpr int kSetupTimeoutMs = 15000; + static constexpr int kMaxSessionSeconds = 1800; + static constexpr std::size_t kMaxQueuedEvents = 1024; + static constexpr std::size_t kMaxQueuedBytes = 8u * 1024u * 1024u; + static constexpr std::size_t kMaxTextChars = 32000; + static constexpr std::size_t kMaxAudioChunkBytes = 256u * 1024u; + static constexpr std::size_t kMaxVideoChunkBytes = 1024u * 1024u; + static constexpr std::size_t kMaxSystemChars = 8000; + static constexpr std::size_t kMaxFunctionDecls = 16; + static constexpr std::size_t kMaxFunctionResponses = 16; + static constexpr std::size_t kMaxDescriptionChars = 1000; + static constexpr std::size_t kMaxMimeChars = 100; + static constexpr std::size_t kMaxIdChars = 128; + + // Relay (example HTTP bridge). + static constexpr std::size_t kMaxRelaySessions = 8; + static constexpr std::size_t kMaxRelayLog = 512; + static constexpr std::size_t kMaxRelayPage = 100; +}; + +} // namespace molo::google::live diff --git a/src/google/live/live_config.cpp b/src/google/live/live_config.cpp new file mode 100644 index 0000000..6710a23 --- /dev/null +++ b/src/google/live/live_config.cpp @@ -0,0 +1,137 @@ +#include "google/live/live_config.h" + +#include + +#include "google/errors.h" +#include "google/live/caps.h" + +namespace molo::google::live { + +using clients::body::Json; + +namespace { +bool valid_function_name(const std::string& s) { + if (s.empty() || s.size() > 64) return false; + if (!(std::isalpha((unsigned char)s[0]) || s[0] == '_')) return false; + for (unsigned char c : s) + if (!(std::isalnum(c) || c == '_' || c == '.' || c == '-')) return false; + return true; +} +bool valid_handle(const std::string& s) { + if (s.empty() || s.size() > 1024) return false; + for (unsigned char c : s) + if (c <= 0x20 || c == 0x7f || c == '"') return false; + return true; +} +} // namespace + +Json LiveConfig::to_setup(const LiveEndpoint& endpoint) const { + Json setup = Json::object(); + setup.set("model", endpoint.model_name(model)); + + if (response_modalities.empty() || response_modalities.size() > 2) + throw GoogleError::invalid("response_modalities needs 1 or 2 entries"); + Json gen = Json::object(); + Json mods = Json::array(); + for (const auto& m : response_modalities) { + if (m != "AUDIO" && m != "TEXT") + throw GoogleError::invalid("response modality must be AUDIO or TEXT"); + mods.push(m); + } + gen.set("responseModalities", mods); + if (temperature) { + if (*temperature < 0.0 || *temperature > 2.0) + throw GoogleError::invalid("temperature must be within 0..2"); + gen.set("temperature", *temperature); + } + if (max_output_tokens) { + if (*max_output_tokens < 1 || *max_output_tokens > 65536) + throw GoogleError::invalid("max_output_tokens must be within 1..65536"); + gen.set("maxOutputTokens", *max_output_tokens); + } + if (!voice_name.empty() || !language_code.empty()) { + Json speech = Json::object(); + if (!voice_name.empty()) { + if (voice_name.size() > 64) throw GoogleError::invalid("voice name too long"); + for (unsigned char c : voice_name) + if (!(std::isalnum(c) || c == '_' || c == '-')) + throw GoogleError::invalid("voice name has invalid characters"); + Json prebuilt = Json::object(); + prebuilt.set("voiceName", voice_name); + Json voice = Json::object(); + voice.set("prebuiltVoiceConfig", prebuilt); + speech.set("voiceConfig", voice); + } + if (!language_code.empty()) { + if (language_code.size() > 16) + throw GoogleError::invalid("language code too long"); + for (unsigned char c : language_code) + if (!(std::isalnum(c) || c == '-')) + throw GoogleError::invalid("language code has invalid characters"); + speech.set("languageCode", language_code); + } + gen.set("speechConfig", speech); + } + setup.set("generationConfig", gen); + + if (!system_instruction.empty()) { + if (system_instruction.size() > LiveCaps::kMaxSystemChars) + throw GoogleError::invalid("system instruction over cap"); + Json part = Json::object(); + part.set("text", system_instruction); + Json parts = Json::array(); + parts.push(part); + Json content = Json::object(); + content.set("parts", parts); + setup.set("systemInstruction", content); + } + + if (!functions.empty()) { + if (functions.size() > LiveCaps::kMaxFunctionDecls) + throw GoogleError::invalid("too many function declarations"); + Json decls = Json::array(); + for (const auto& f : functions) { + if (!valid_function_name(f.name)) + throw GoogleError::invalid("function name is malformed"); + if (f.description.size() > LiveCaps::kMaxDescriptionChars) + throw GoogleError::invalid("function description over cap"); + Json d = Json::object(); + d.set("name", f.name); + if (!f.description.empty()) d.set("description", f.description); + if (!f.parameters.is_null()) { + if (!f.parameters.is_object()) + throw GoogleError::invalid("function parameters must be a JSON object"); + d.set("parameters", f.parameters); + } + decls.push(d); + } + Json tool = Json::object(); + tool.set("functionDeclarations", decls); + Json tools = Json::array(); + tools.push(tool); + setup.set("tools", tools); + } + + if (input_transcription) setup.set("inputAudioTranscription", Json::object()); + if (output_transcription) setup.set("outputAudioTranscription", Json::object()); + + if (session_resumption || !resumption_handle.empty()) { + Json r = Json::object(); + if (!resumption_handle.empty()) { + if (!valid_handle(resumption_handle)) + throw GoogleError::invalid("resumption handle is malformed"); + r.set("handle", resumption_handle); + } + setup.set("sessionResumption", r); + } + if (context_compression) { + Json c = Json::object(); + c.set("slidingWindow", Json::object()); + setup.set("contextWindowCompression", c); + } + Json root = Json::object(); + root.set("setup", setup); + return root; +} + +} // namespace molo::google::live diff --git a/src/google/live/live_config.h b/src/google/live/live_config.h new file mode 100644 index 0000000..7af7955 --- /dev/null +++ b/src/google/live/live_config.h @@ -0,0 +1,40 @@ +#pragma once + +// Typed content of the setup message (the first frame of a session). + +#include +#include +#include + +#include "clients/body/json.h" +#include "google/live/live_endpoint.h" + +namespace molo::google::live { + +struct LiveFunctionDeclaration { + std::string name; // [A-Za-z_][A-Za-z0-9_.-]{0,63} + std::string description; + // OpenAPI-subset Schema object, passed through; null = no parameters. + clients::body::Json parameters; +}; + +struct LiveConfig { + std::string model = "gemini-live-2.5-flash-native-audio"; + std::vector response_modalities = {"AUDIO"}; // AUDIO or TEXT + std::string system_instruction; + std::string voice_name; + std::string language_code; + std::optional temperature; // 0..2 + std::optional max_output_tokens; + bool input_transcription = false; + bool output_transcription = false; + bool session_resumption = false; + std::string resumption_handle; // resume a previous session + bool context_compression = false; // slidingWindow with server defaults + std::vector functions; + + // Validates and renders {"setup": {...}}. Throws GoogleError (invalid). + clients::body::Json to_setup(const LiveEndpoint& endpoint) const; +}; + +} // namespace molo::google::live diff --git a/src/google/live/live_endpoint.cpp b/src/google/live/live_endpoint.cpp new file mode 100644 index 0000000..c30c3c6 --- /dev/null +++ b/src/google/live/live_endpoint.cpp @@ -0,0 +1,98 @@ +#include "google/live/live_endpoint.h" + +#include + +#include "google/errors.h" +#include "google/live/live_spec.h" + +namespace molo::google::live { + +namespace { +bool clean_secret(const std::string& s) { + if (s.empty() || s.size() > 4096) return false; + for (unsigned char c : s) + if (c <= 0x20 || c == 0x7f || c == '&' || c == '#' || c == '"') return false; + return true; +} +bool valid_location(const std::string& s) { + if (s.empty() || s.size() > 40) return false; + for (unsigned char c : s) + if (!(std::islower(c) || std::isdigit(c) || c == '-')) return false; + return true; +} +} // namespace + +LiveEndpoint LiveEndpoint::vertex(const CloudContext& ctx, std::string token) { + LiveEndpoint e; + e.mode = Mode::Vertex; + e.project = ctx.project; + e.location = ctx.location; + e.token = std::move(token); + return e; +} + +LiveEndpoint LiveEndpoint::vertex_express(const CloudContext& ctx, std::string key) { + LiveEndpoint e; + e.mode = Mode::Vertex; + e.project = ctx.project; + e.location = ctx.location; + e.key = std::move(key); + return e; +} + +LiveEndpoint LiveEndpoint::api_key(std::string key) { + LiveEndpoint e; + e.mode = Mode::ApiKey; + e.key = std::move(key); + return e; +} + +bool LiveEndpoint::has_credential() const { + return mode == Mode::Vertex ? !(token.empty() && key.empty()) : !key.empty(); +} + +void LiveEndpoint::validate() const { + if (!has_credential()) throw NotConfiguredError("live"); + if (mode == Mode::Vertex) { + if (!token.empty() && !clean_secret(token)) + throw GoogleError::invalid("access token has forbidden characters"); + if (!key.empty() && !clean_secret(key)) + throw GoogleError::invalid("api key has forbidden characters"); + if (!valid_location(location)) throw GoogleError::invalid("location is malformed"); + CloudContext ctx; + ctx.project = project; + ctx.location = location; + ctx.parent(); // validates the project + } else if (!clean_secret(key)) { + throw GoogleError::invalid("api key has forbidden characters"); + } +} + +std::string LiveEndpoint::url() const { + if (!url_override.empty()) return url_override; + if (mode == Mode::ApiKey) return std::string(kLiveApiKeyUrl) + "?key=" + key; + std::string host = location == "global" ? "aiplatform.googleapis.com" + : location + "-aiplatform.googleapis.com"; + return "wss://" + host + kLiveVertexPath; +} + +WsHeaders LiveEndpoint::headers() const { + WsHeaders h; + if (mode == Mode::Vertex) { + // OAuth token wins; an express key travels in the header, not the URL. + if (!token.empty()) h.emplace_back("Authorization", "Bearer " + token); + else h.emplace_back("x-goog-api-key", key); + } + return h; +} + +std::string LiveEndpoint::model_name(const std::string& model_id) const { + if (!valid_segment(model_id)) throw GoogleError::invalid("model id is malformed"); + if (mode == Mode::ApiKey) return "models/" + model_id; + CloudContext ctx; + ctx.project = project; + ctx.location = location; + return ctx.parent() + "/publishers/google/models/" + model_id; +} + +} // namespace molo::google::live diff --git a/src/google/live/live_endpoint.h b/src/google/live/live_endpoint.h new file mode 100644 index 0000000..9cb60ea --- /dev/null +++ b/src/google/live/live_endpoint.h @@ -0,0 +1,44 @@ +#pragma once + +// Where and how a Live session connects. Two forms: +// - Vertex AI: wss://{location}-aiplatform.googleapis.com/ws/ +// with "Authorization: Bearer "; model resource +// projects/{p}/locations/{l}/publishers/google/models/{m}. +// - API key (Gemini API): wss://generativelanguage.googleapis.com/ws/... +// with the key in "?key=" (the documented form; the one place the key is +// in a URL, so WsUrl::display() and every error omit the query); +// model models/{m}. +// url_override (tests, proxies) replaces the URL; headers and model naming +// still follow the mode. + +#include + +#include "google/live/ws_handshake.h" +#include "google/resource.h" + +namespace molo::google::live { + +struct LiveEndpoint { + enum class Mode { Vertex, ApiKey }; + Mode mode = Mode::ApiKey; + std::string project; + std::string location = "us-central1"; + std::string token; // Vertex: OAuth access token + std::string key; // ApiKey mode, or Vertex express key when token is empty + std::string url_override; + + static LiveEndpoint vertex(const CloudContext& ctx, std::string token); + // Vertex with an express-mode API key (sent as x-goog-api-key). + static LiveEndpoint vertex_express(const CloudContext& ctx, std::string key); + static LiveEndpoint api_key(std::string key); + + bool has_credential() const; + // Throws GoogleError (invalid) on a bad project, location or credential. + void validate() const; + std::string url() const; // full URL, may contain the key + WsHeaders headers() const; + // Model id -> wire name for this mode. Id validated like a path segment. + std::string model_name(const std::string& model_id) const; +}; + +} // namespace molo::google::live diff --git a/src/google/live/live_events.cpp b/src/google/live/live_events.cpp new file mode 100644 index 0000000..212a0d8 --- /dev/null +++ b/src/google/live/live_events.cpp @@ -0,0 +1,192 @@ +#include "google/live/live_events.h" + +#include + +#include "security/crypto/Base64.h" + +namespace molo::google::live { + +using clients::body::Json; +using molo::security::crypto::Base64; + +const char* live_event_name(LiveEventKind k) { + switch (k) { + case LiveEventKind::SetupComplete: return "setup_complete"; + case LiveEventKind::Text: return "text"; + case LiveEventKind::Audio: return "audio"; + case LiveEventKind::Media: return "media"; + case LiveEventKind::InputTranscription: return "input_transcription"; + case LiveEventKind::OutputTranscription: return "output_transcription"; + case LiveEventKind::GenerationComplete: return "generation_complete"; + case LiveEventKind::TurnComplete: return "turn_complete"; + case LiveEventKind::Interrupted: return "interrupted"; + case LiveEventKind::ToolCall: return "tool_call"; + case LiveEventKind::ToolCallCancellation: return "tool_call_cancellation"; + case LiveEventKind::GoAway: return "go_away"; + case LiveEventKind::SessionResumption: return "session_resumption"; + case LiveEventKind::Usage: return "usage"; + case LiveEventKind::Unknown: return "unknown"; + case LiveEventKind::Closed: return "closed"; + case LiveEventKind::Error: return "error"; + } + return "unknown"; +} + +double LiveParser::parse_duration(const std::string& s) { + if (s.size() < 2 || s.back() != 's') return -1; + std::string num = s.substr(0, s.size() - 1); + char* end = nullptr; + double v = std::strtod(num.c_str(), &end); + if (end != num.c_str() + num.size() || v < 0) return -1; + return v; +} + +namespace { + +const std::string* str(const Json& obj, const char* key) { + const Json* v = obj.find(key); + return v && v->is_string() ? &v->as_string() : nullptr; +} + +LiveEvent error_event(const std::string& why) { + LiveEvent e; + e.kind = LiveEventKind::Error; + e.text = why; + return e; +} + +void parse_server_content(const Json& sc, std::vector& out) { + if (const Json* turn = sc.find("modelTurn"); turn && turn->is_object()) { + if (const Json* parts = turn->find("parts"); parts && parts->is_array()) { + for (const Json& part : parts->as_array()) { + if (!part.is_object()) continue; + if (const std::string* t = str(part, "text")) { + LiveEvent e; + e.kind = LiveEventKind::Text; + e.text = *t; + out.push_back(std::move(e)); + } + if (const Json* inl = part.find("inlineData"); inl && inl->is_object()) { + const std::string* d = str(*inl, "data"); + const std::string* m = str(*inl, "mimeType"); + LiveEvent e; + e.mime = m ? *m : ""; + if (!d || !Base64::decode(*d, e.data)) { + out.push_back(error_event("inlineData is not valid base64")); + continue; + } + e.kind = e.mime.rfind("audio/", 0) == 0 ? LiveEventKind::Audio + : LiveEventKind::Media; + out.push_back(std::move(e)); + } + } + } + } + for (const char* key : {"inputTranscription", "outputTranscription"}) { + if (const Json* t = sc.find(key); t && t->is_object()) { + LiveEvent e; + e.kind = key[0] == 'i' ? LiveEventKind::InputTranscription + : LiveEventKind::OutputTranscription; + if (const std::string* s = str(*t, "text")) e.text = *s; + out.push_back(std::move(e)); + } + } + auto flag = [&](const char* key, LiveEventKind kind) { + if (const Json* f = sc.find(key); f && f->is_bool() && f->as_bool()) { + LiveEvent e; + e.kind = kind; + out.push_back(std::move(e)); + } + }; + flag("interrupted", LiveEventKind::Interrupted); + flag("generationComplete", LiveEventKind::GenerationComplete); + flag("turnComplete", LiveEventKind::TurnComplete); +} + +} // namespace + +std::vector LiveParser::parse(const std::string& message) { + std::vector out; + Json root; + try { + root = Json::parse(message); + } catch (const std::exception&) { + out.push_back(error_event("server message is not valid JSON")); + return out; + } + if (!root.is_object()) { + out.push_back(error_event("server message is not a JSON object")); + return out; + } + bool known = false; + if (root.has("setupComplete")) { + known = true; + LiveEvent e; + e.kind = LiveEventKind::SetupComplete; + out.push_back(std::move(e)); + } + if (const Json* sc = root.find("serverContent"); sc && sc->is_object()) { + known = true; + parse_server_content(*sc, out); + } + if (const Json* tc = root.find("toolCall"); tc && tc->is_object()) { + known = true; + LiveEvent e; + e.kind = LiveEventKind::ToolCall; + if (const Json* fc = tc->find("functionCalls"); fc && fc->is_array()) { + for (const Json& c : fc->as_array()) { + if (!c.is_object()) continue; + LiveFunctionCall call; + if (const std::string* s = str(c, "id")) call.id = *s; + if (const std::string* s = str(c, "name")) call.name = *s; + if (const Json* a = c.find("args")) call.args = *a; + e.calls.push_back(std::move(call)); + } + } + out.push_back(std::move(e)); + } + if (const Json* tc = root.find("toolCallCancellation"); tc && tc->is_object()) { + known = true; + LiveEvent e; + e.kind = LiveEventKind::ToolCallCancellation; + if (const Json* ids = tc->find("ids"); ids && ids->is_array()) + for (const Json& i : ids->as_array()) + if (i.is_string()) e.ids.push_back(i.as_string()); + out.push_back(std::move(e)); + } + if (const Json* ga = root.find("goAway"); ga && ga->is_object()) { + known = true; + LiveEvent e; + e.kind = LiveEventKind::GoAway; + if (const std::string* t = str(*ga, "timeLeft")) { + e.seconds = parse_duration(*t); + e.text = *t; + } + out.push_back(std::move(e)); + } + if (const Json* sr = root.find("sessionResumptionUpdate"); sr && sr->is_object()) { + known = true; + LiveEvent e; + e.kind = LiveEventKind::SessionResumption; + if (const std::string* h = str(*sr, "newHandle")) e.handle = *h; + if (const Json* r = sr->find("resumable"); r && r->is_bool()) e.resumable = r->as_bool(); + out.push_back(std::move(e)); + } + if (const Json* um = root.find("usageMetadata"); um && um->is_object()) { + known = true; + LiveEvent e; + e.kind = LiveEventKind::Usage; + if (const Json* t = um->find("totalTokenCount"); t && t->is_number()) + e.total_tokens = t->as_int(); + out.push_back(std::move(e)); + } + if (!known) { + LiveEvent e; + e.kind = LiveEventKind::Unknown; + e.text = message.substr(0, 200); + out.push_back(std::move(e)); + } + return out; +} + +} // namespace molo::google::live diff --git a/src/google/live/live_events.h b/src/google/live/live_events.h new file mode 100644 index 0000000..81641be --- /dev/null +++ b/src/google/live/live_events.h @@ -0,0 +1,67 @@ +#pragma once + +// Typed events decoded from server messages. One server message can carry +// several facets (model audio plus turnComplete); each becomes one event, in +// a fixed order with turnComplete last. + +#include +#include + +#include "clients/body/json.h" + +namespace molo::google::live { + +enum class LiveEventKind { + SetupComplete, + Text, // model text part + Audio, // model inline audio (data = raw bytes, mime e.g. audio/pcm;rate=24000) + Media, // other inline data + InputTranscription, + OutputTranscription, + GenerationComplete, + TurnComplete, + Interrupted, + ToolCall, + ToolCallCancellation, + GoAway, + SessionResumption, + Usage, + Unknown, // a server message with no field this module knows + Closed, // connection ended (code, text = reason) + Error, // undecodable message or transport failure (text) +}; + +const char* live_event_name(LiveEventKind kind); + +struct LiveFunctionCall { + std::string id; + std::string name; + clients::body::Json args; +}; + +struct LiveEvent { + LiveEventKind kind = LiveEventKind::Unknown; + std::uint64_t seq = 0; // assigned by the session, strictly increasing + std::string text; // Text, transcriptions, Error, Closed reason + std::string data; // Audio and Media bytes (decoded) + std::string mime; + std::vector calls; // ToolCall + std::vector ids; // ToolCallCancellation + double seconds = 0; // GoAway timeLeft + std::string handle; // SessionResumption newHandle + bool resumable = false; + long total_tokens = 0; // Usage + int code = 0; // Closed + + std::size_t weight() const { return text.size() + data.size() + 64; } +}; + +class LiveParser { + public: + // Never throws: undecodable input becomes one Error event. + static std::vector parse(const std::string& message); + // "30s", "1.5s", "0.500s" -> seconds; -1 when malformed. + static double parse_duration(const std::string& s); +}; + +} // namespace molo::google::live diff --git a/src/google/live/live_relay.cpp b/src/google/live/live_relay.cpp new file mode 100644 index 0000000..6d03f26 --- /dev/null +++ b/src/google/live/live_relay.cpp @@ -0,0 +1,162 @@ +#include "google/live/live_relay.h" + +#include + +#include +#include + +#include "google/errors.h" +#include "security/crypto/Base64.h" + +namespace molo::google::live { + +using clients::body::Json; + +Json event_to_json(const LiveEvent& e) { + Json o = Json::object(); + o.set("seq", (double)e.seq); + o.set("type", live_event_name(e.kind)); + switch (e.kind) { + case LiveEventKind::Text: + case LiveEventKind::InputTranscription: + case LiveEventKind::OutputTranscription: + case LiveEventKind::Error: + o.set("text", e.text); + break; + case LiveEventKind::Audio: + case LiveEventKind::Media: + o.set("mime", e.mime); + o.set("data_b64", security::crypto::Base64::encode(e.data)); + break; + case LiveEventKind::ToolCall: { + Json calls = Json::array(); + for (const auto& c : e.calls) { + Json j = Json::object(); + j.set("id", c.id); + j.set("name", c.name); + j.set("args", c.args); + calls.push(j); + } + o.set("calls", calls); + break; + } + case LiveEventKind::ToolCallCancellation: { + Json ids = Json::array(); + for (const auto& i : e.ids) ids.push(i); + o.set("ids", ids); + break; + } + case LiveEventKind::GoAway: + o.set("seconds", e.seconds); + break; + case LiveEventKind::SessionResumption: + o.set("resumable", e.resumable); + break; // the handle itself is not relayed to browsers + case LiveEventKind::Usage: + o.set("total_tokens", (double)e.total_tokens); + break; + case LiveEventKind::Closed: + o.set("code", e.code); + o.set("text", e.text); + break; + default: + break; + } + return o; +} + +bool LiveRelay::valid_id(const std::string& id) { + if (id.size() != 13 || id[0] != 's') return false; + for (std::size_t i = 1; i < id.size(); ++i) + if (!std::isxdigit((unsigned char)id[i])) return false; + return true; +} + +std::shared_ptr LiveRelay::find(const std::string& id) const { + std::lock_guard lock(mu_); + auto it = entries_.find(id); + if (!valid_id(id) || it == entries_.end()) + throw GoogleError(404, "NOT_FOUND", "no such live session", "live"); + return it->second; +} + +std::shared_ptr LiveRelay::get(const std::string& id) const { + return find(id)->session; +} + +std::string LiveRelay::create(LiveEndpoint endpoint, LiveConfig config, + LiveOptions options) { + { + std::lock_guard lock(mu_); + for (auto it = entries_.begin(); it != entries_.end();) { + if (!it->second->session->open() && it->second->session->pending() == 0) + it = entries_.erase(it); + else + ++it; + } + if (entries_.size() >= max_sessions_) + throw GoogleError(429, "RESOURCE_EXHAUSTED", "too many live sessions", "live"); + } + auto entry = std::make_shared(); + entry->session = std::make_shared(std::move(endpoint), + std::move(config), std::move(options)); + entry->session->connect(); + unsigned char raw[6]; + if (::getrandom(raw, sizeof raw, 0) != (ssize_t)sizeof raw) + throw GoogleError(500, "INTERNAL", "no entropy for session id", "live"); + static const char* hex = "0123456789abcdef"; + std::string id = "s"; + for (unsigned char b : raw) { + id.push_back(hex[b >> 4]); + id.push_back(hex[b & 15]); + } + std::lock_guard lock(mu_); + if (entries_.size() >= max_sessions_) + throw GoogleError(429, "RESOURCE_EXHAUSTED", "too many live sessions", "live"); + entries_[id] = entry; + return id; +} + +RelayPage LiveRelay::poll(const std::string& id, std::uint64_t cursor, + std::size_t max) { + auto entry = find(id); + max = std::min(std::max(max, 1), LiveCaps::kMaxRelayPage); + std::lock_guard lock(entry->mu); + while (auto e = entry->session->next_event(0)) entry->log.push_back(std::move(*e)); + if (entry->log.size() > LiveCaps::kMaxRelayLog) { + std::size_t drop = entry->log.size() - LiveCaps::kMaxRelayLog; + entry->log.erase(entry->log.begin(), entry->log.begin() + (std::ptrdiff_t)drop); + entry->dropped += drop; + } + RelayPage page; + page.next_cursor = cursor; + for (const auto& e : entry->log) { + if (e.seq <= cursor) continue; + if (page.events.size() >= max) break; + page.events.push_back(e); + page.next_cursor = e.seq; + } + page.open = entry->session->open(); + page.dropped = entry->dropped + entry->session->stats().dropped; + return page; +} + +void LiveRelay::close(const std::string& id) { + std::shared_ptr entry; + { + std::lock_guard lock(mu_); + auto it = entries_.find(id); + if (!valid_id(id) || it == entries_.end()) + throw GoogleError(404, "NOT_FOUND", "no such live session", "live"); + entry = it->second; + entries_.erase(it); + } + entry->session->close(); +} + +std::size_t LiveRelay::size() const { + std::lock_guard lock(mu_); + return entries_.size(); +} + +} // namespace molo::google::live diff --git a/src/google/live/live_relay.h b/src/google/live/live_relay.h new file mode 100644 index 0000000..6f78630 --- /dev/null +++ b/src/google/live/live_relay.h @@ -0,0 +1,60 @@ +#pragma once + +// HTTP-friendly view of live sessions for hosts without WebSocket (the +// example server): sessions by id, events read by cursor from a bounded log. + +#include +#include +#include +#include +#include +#include + +#include "clients/body/json.h" +#include "google/live/live_session.h" + +namespace molo::google::live { + +// {"seq","type", ...}; audio and media bytes as "data_b64". +clients::body::Json event_to_json(const LiveEvent& e); + +struct RelayPage { + std::vector events; + std::uint64_t next_cursor = 0; + bool open = false; + std::uint64_t dropped = 0; +}; + +class LiveRelay { + public: + explicit LiveRelay(std::size_t max_sessions = LiveCaps::kMaxRelaySessions) + : max_sessions_(max_sessions) {} + + static bool valid_id(const std::string& id); + + // Connects (blocking) and registers. Throws GoogleError; 429 + // RESOURCE_EXHAUSTED when max_sessions open sessions exist. + std::string create(LiveEndpoint endpoint, LiveConfig config, + LiveOptions options = {}); + // Throws GoogleError 404 NOT_FOUND for unknown or malformed ids. + std::shared_ptr get(const std::string& id) const; + // Events with seq > cursor, at most max (capped at kMaxRelayPage). + RelayPage poll(const std::string& id, std::uint64_t cursor, std::size_t max); + void close(const std::string& id); + std::size_t size() const; + + private: + struct Entry { + std::shared_ptr session; + std::mutex mu; + std::vector log; + std::uint64_t dropped = 0; + }; + std::shared_ptr find(const std::string& id) const; + + std::size_t max_sessions_; + mutable std::mutex mu_; + std::map> entries_; +}; + +} // namespace molo::google::live diff --git a/src/google/live/live_requests.cpp b/src/google/live/live_requests.cpp new file mode 100644 index 0000000..cb6dc07 --- /dev/null +++ b/src/google/live/live_requests.cpp @@ -0,0 +1,128 @@ +#include "google/live/live_requests.h" + +#include + +#include "google/errors.h" +#include "google/live/caps.h" +#include "security/crypto/Base64.h" + +namespace molo::google::live { + +using clients::body::Json; +using molo::security::crypto::Base64; + +namespace { + +void check_text(const std::string& t) { + if (t.empty()) throw GoogleError::invalid("text is empty"); + if (t.size() > LiveCaps::kMaxTextChars) + throw GoogleError::invalid("text over " + std::to_string(LiveCaps::kMaxTextChars) + " bytes"); +} + +std::string blob_message(const char* field, const std::string& bytes, + const std::string& mime, std::size_t cap) { + if (bytes.empty()) throw GoogleError::invalid(std::string(field) + " chunk is empty"); + if (bytes.size() > cap) + throw GoogleError::invalid(std::string(field) + " chunk over " + std::to_string(cap) + " bytes"); + Json blob = Json::object(); + blob.set("data", Base64::encode(bytes)); + blob.set("mimeType", mime); + Json input = Json::object(); + input.set(field, blob); + Json root = Json::object(); + root.set("realtimeInput", input); + return root.dump(); +} + +bool valid_id(const std::string& s) { + if (s.empty() || s.size() > LiveCaps::kMaxIdChars) return false; + for (unsigned char c : s) + if (c <= 0x20 || c == 0x7f) return false; + return true; +} + +} // namespace + +void LiveRequests::check_mime(const std::string& mime, const char* a, const char* b) { + if (mime.empty() || mime.size() > LiveCaps::kMaxMimeChars) + throw GoogleError::invalid("mime type empty or too long"); + for (unsigned char c : mime) + if (!(std::isalnum(c) || c == '/' || c == ';' || c == '=' || c == '-' || + c == '+' || c == '.' || c == '_')) + throw GoogleError::invalid("mime type has invalid characters"); + bool ok = mime.rfind(a, 0) == 0 || (b && mime.rfind(b, 0) == 0); + if (!ok) throw GoogleError::invalid("mime type must start with " + std::string(a) + + (b ? std::string(" or ") + b : "")); +} + +std::string LiveRequests::text(const std::string& t) { + check_text(t); + Json input = Json::object(); + input.set("text", t); + Json root = Json::object(); + root.set("realtimeInput", input); + return root.dump(); +} + +std::string LiveRequests::turn(const std::string& t, bool turn_complete) { + check_text(t); + Json part = Json::object(); + part.set("text", t); + Json parts = Json::array(); + parts.push(part); + Json turn = Json::object(); + turn.set("role", "user"); + turn.set("parts", parts); + Json turns = Json::array(); + turns.push(turn); + Json cc = Json::object(); + cc.set("turns", turns); + cc.set("turnComplete", turn_complete); + Json root = Json::object(); + root.set("clientContent", cc); + return root.dump(); +} + +std::string LiveRequests::audio(const std::string& bytes, const std::string& mime) { + check_mime(mime, "audio/"); + return blob_message("audio", bytes, mime, LiveCaps::kMaxAudioChunkBytes); +} + +std::string LiveRequests::video(const std::string& bytes, const std::string& mime) { + check_mime(mime, "image/", "video/"); + return blob_message("video", bytes, mime, LiveCaps::kMaxVideoChunkBytes); +} + +std::string LiveRequests::audio_stream_end() { + Json input = Json::object(); + input.set("audioStreamEnd", true); + Json root = Json::object(); + root.set("realtimeInput", input); + return root.dump(); +} + +std::string LiveRequests::tool_responses(const std::vector& rs) { + if (rs.empty() || rs.size() > LiveCaps::kMaxFunctionResponses) + throw GoogleError::invalid("tool responses need 1.." + + std::to_string(LiveCaps::kMaxFunctionResponses) + " entries"); + Json arr = Json::array(); + for (const auto& r : rs) { + if (!valid_id(r.id)) throw GoogleError::invalid("tool response id is malformed"); + if (r.name.empty() || r.name.size() > 64) + throw GoogleError::invalid("tool response name is malformed"); + if (!r.response.is_object()) + throw GoogleError::invalid("tool response must be a JSON object"); + Json o = Json::object(); + o.set("id", r.id); + o.set("name", r.name); + o.set("response", r.response); + arr.push(o); + } + Json tr = Json::object(); + tr.set("functionResponses", arr); + Json root = Json::object(); + root.set("toolResponse", tr); + return root.dump(); +} + +} // namespace molo::google::live diff --git a/src/google/live/live_requests.h b/src/google/live/live_requests.h new file mode 100644 index 0000000..6be8e50 --- /dev/null +++ b/src/google/live/live_requests.h @@ -0,0 +1,42 @@ +#pragma once + +// Builders and validators for client messages after setup. Every builder +// enforces the caps and returns the JSON text ready to send. + +#include +#include + +#include "clients/body/json.h" + +namespace molo::google::live { + +struct LiveToolResponse { + std::string id; // the functionCalls[].id being answered + std::string name; + clients::body::Json response; // JSON object +}; + +class LiveRequests { + public: + static constexpr const char* kDefaultAudioMime = "audio/pcm;rate=16000"; + static constexpr const char* kDefaultVideoMime = "image/jpeg"; + + // {"realtimeInput":{"text":...}} + static std::string text(const std::string& text); + // {"clientContent":{"turns":[{"role":"user","parts":[{"text":...}]}],"turnComplete":b}} + static std::string turn(const std::string& text, bool turn_complete); + // {"realtimeInput":{"audio":{"data":b64,"mimeType":...}}}; mime audio/*. + static std::string audio(const std::string& bytes, const std::string& mime); + // {"realtimeInput":{"video":{...}}}; mime image/* or video/*. + static std::string video(const std::string& bytes, const std::string& mime); + // {"realtimeInput":{"audioStreamEnd":true}} + static std::string audio_stream_end(); + // {"toolResponse":{"functionResponses":[...]}} + static std::string tool_responses(const std::vector& r); + + // Throws GoogleError (invalid) on a bad mime type. + static void check_mime(const std::string& mime, const char* family_a, + const char* family_b = nullptr); +}; + +} // namespace molo::google::live diff --git a/src/google/live/live_session.cpp b/src/google/live/live_session.cpp new file mode 100644 index 0000000..2cb7c8c --- /dev/null +++ b/src/google/live/live_session.cpp @@ -0,0 +1,224 @@ +#include "google/live/live_session.h" + +#include + +#include "google/errors.h" +#include "google/live/ws_error.h" + +namespace molo::google::live { + +namespace { + +using Clock = std::chrono::steady_clock; + +std::int64_t now_ms() { + return std::chrono::duration_cast( + Clock::now().time_since_epoch()) + .count(); +} + +GoogleError map_error(const WsError& e) { + using K = WsError::Kind; + switch (e.kind()) { + case K::Invalid: return GoogleError(400, "INVALID_ARGUMENT", e.what(), "live"); + case K::Timeout: return GoogleError(504, "DEADLINE_EXCEEDED", e.what(), "live"); + case K::TooBig: return GoogleError(413, "RESOURCE_EXHAUSTED", e.what(), "live"); + case K::Handshake: + switch (e.http_status()) { + case 400: return GoogleError(400, "INVALID_ARGUMENT", e.what(), "live"); + case 401: return GoogleError(401, "UNAUTHENTICATED", e.what(), "live"); + case 403: return GoogleError(403, "PERMISSION_DENIED", e.what(), "live"); + case 404: return GoogleError(404, "NOT_FOUND", e.what(), "live"); + case 429: return GoogleError(429, "RESOURCE_EXHAUSTED", e.what(), "live"); + default: return GoogleError(502, "UNAVAILABLE", e.what(), "live"); + } + case K::Closed: return GoogleError(409, "FAILED_PRECONDITION", e.what(), "live"); + default: return GoogleError(502, "UNAVAILABLE", e.what(), "live"); + } +} + +} // namespace + +LiveSession::LiveSession(LiveEndpoint endpoint, LiveConfig config, + LiveOptions options) + : endpoint_(std::move(endpoint)), + config_(std::move(config)), + options_(std::move(options)) {} + +LiveSession::~LiveSession() { + try { + close(); + } catch (...) { + } +} + +void LiveSession::connect() { + if (connected_.exchange(true)) throw GoogleError::invalid("session already connected"); + endpoint_.validate(); + std::string setup = config_.to_setup(endpoint_).dump(); + try { + WsUrl url = WsUrl::parse(endpoint_.url()); + ws_ = std::make_unique(open_stream( + url, options_.connect_timeout_ms, LiveCaps::kIoTimeoutMs, options_.tls)); + ws_->handshake(url, endpoint_.headers(), options_.handshake_timeout_ms); + ws_->send_text(setup); + ws_->set_read_timeout_ms(LiveCaps::kPollIntervalMs); + auto deadline = now_ms() + options_.setup_timeout_ms; + bool ready = false; + while (!ready) { + if (now_ms() > deadline) throw WsError(WsError::Kind::Timeout, "setupComplete not received in time"); + auto m = ws_->receive(); + if (!m) continue; + if (m->kind == WsMessage::Kind::Close) + throw WsError(WsError::Kind::Closed, + "server closed before setup completed (code " + + std::to_string(m->code) + "): " + m->data.substr(0, 500)); + for (auto& e : LiveParser::parse(m->data)) { + if (e.kind == LiveEventKind::SetupComplete) ready = true; + push(std::move(e)); + } + } + } catch (const WsError& e) { + if (ws_) ws_->shutdown(); + ws_.reset(); + throw map_error(e); + } + open_ = true; + reader_ = std::thread([this] { reader_loop(); }); +} + +void LiveSession::send_raw(const std::string& json) { + if (!open_ || !ws_) throw GoogleError(409, "FAILED_PRECONDITION", "session is not open", "live"); + try { + ws_->send_text(json); + } catch (const WsError& e) { + throw map_error(e); + } + std::lock_guard lock(mu_); + ++stats_.sent; +} + +void LiveSession::send_text(const std::string& t) { send_raw(LiveRequests::text(t)); } +void LiveSession::send_turn(const std::string& t, bool c) { send_raw(LiveRequests::turn(t, c)); } +void LiveSession::send_audio(const std::string& pcm, const std::string& mime) { + send_raw(LiveRequests::audio(pcm, mime)); +} +void LiveSession::send_video(const std::string& b, const std::string& mime) { + send_raw(LiveRequests::video(b, mime)); +} +void LiveSession::end_audio() { send_raw(LiveRequests::audio_stream_end()); } +void LiveSession::send_tool_responses(const std::vector& r) { + send_raw(LiveRequests::tool_responses(r)); +} + +void LiveSession::push(LiveEvent e) { + std::lock_guard lock(mu_); + e.seq = ++seq_; + if (e.kind == LiveEventKind::SessionResumption && e.resumable && !e.handle.empty()) + handle_ = e.handle; + queued_bytes_ += e.weight(); + queue_.push_back(std::move(e)); + // Hard ceilings: drop oldest, count loudly in stats().dropped. + while (queue_.size() > 1 && (queue_.size() > LiveCaps::kMaxQueuedEvents || + queued_bytes_ > LiveCaps::kMaxQueuedBytes)) { + queued_bytes_ -= queue_.front().weight(); + queue_.pop_front(); + ++stats_.dropped; + } + cv_.notify_all(); +} + +void LiveSession::ingest(const WsMessage& m) { + { + std::lock_guard lock(mu_); + ++stats_.received; + } + for (auto& e : LiveParser::parse(m.data)) { + if (e.kind == LiveEventKind::Error) { + std::lock_guard lock(mu_); + ++stats_.decode_errors; + } + push(std::move(e)); + } +} + +void LiveSession::reader_loop() { + const auto started = now_ms(); + LiveEvent closed; + closed.kind = LiveEventKind::Closed; + try { + for (;;) { + if (now_ms() - started > (std::int64_t)options_.max_session_seconds * 1000) { + closed.text = "session lifetime cap reached"; + closed.code = 1000; + ws_->close(1000, "lifetime cap"); + break; + } + std::int64_t dl = close_deadline_ms_.load(); + if (dl != 0 && now_ms() > dl) { + closed.text = "closed by client"; + closed.code = 1000; + break; + } + auto m = ws_->receive(); + if (!m) continue; + if (m->kind == WsMessage::Kind::Close) { + closed.code = m->code; + closed.text = m->data; + break; + } + // Gemini sends JSON in text and in binary frames. + ingest(*m); + } + } catch (const WsError& e) { + closed.kind = LiveEventKind::Error; + closed.text = e.what(); + push(std::move(closed)); + closed = LiveEvent{}; + closed.kind = LiveEventKind::Closed; + closed.code = 1006; + closed.text = "transport error"; + } + push(std::move(closed)); + open_ = false; + cv_.notify_all(); +} + +std::optional LiveSession::next_event(int timeout_ms) { + std::unique_lock lock(mu_); + cv_.wait_for(lock, std::chrono::milliseconds(timeout_ms), + [this] { return !queue_.empty() || !open_; }); + if (queue_.empty()) return std::nullopt; + LiveEvent e = std::move(queue_.front()); + queue_.pop_front(); + queued_bytes_ -= e.weight(); + return e; +} + +std::size_t LiveSession::pending() const { + std::lock_guard lock(mu_); + return queue_.size(); +} + +void LiveSession::close() { + if (!ws_) return; + if (open_.exchange(false) || reader_.joinable()) { + close_deadline_ms_ = now_ms() + LiveCaps::kCloseGraceMs; + ws_->close(1000, "client closing"); + } + if (reader_.joinable()) reader_.join(); + ws_->shutdown(); + cv_.notify_all(); +} + +LiveSession::Stats LiveSession::stats() const { + std::lock_guard lock(mu_); + return stats_; +} + +std::string LiveSession::resumption_handle() const { + std::lock_guard lock(mu_); + return handle_; +} + +} // namespace molo::google::live diff --git a/src/google/live/live_session.h b/src/google/live/live_session.h new file mode 100644 index 0000000..a54059b --- /dev/null +++ b/src/google/live/live_session.h @@ -0,0 +1,96 @@ +#pragma once + +// One Live API conversation: connect, setup, send text/audio/video/tool +// responses, receive typed events through a bounded queue, close cleanly. +// A reader thread owns receiving; sending is safe from any thread. + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "google/live/caps.h" +#include "google/live/live_config.h" +#include "google/live/live_endpoint.h" +#include "google/live/live_events.h" +#include "google/live/live_requests.h" +#include "google/live/ws_client.h" + +namespace molo::google::live { + +struct LiveOptions { + int connect_timeout_ms = LiveCaps::kConnectTimeoutMs; + int handshake_timeout_ms = LiveCaps::kHandshakeTimeoutMs; + int setup_timeout_ms = LiveCaps::kSetupTimeoutMs; + int max_session_seconds = LiveCaps::kMaxSessionSeconds; + TlsFactory tls; // null: wolfSSL via MakeTlsSession +}; + +class LiveSession { + public: + LiveSession(LiveEndpoint endpoint, LiveConfig config, LiveOptions options = {}); + ~LiveSession(); + LiveSession(const LiveSession&) = delete; + LiveSession& operator=(const LiveSession&) = delete; + + // Validates, connects, upgrades, sends setup and waits for setupComplete, + // then starts the reader. Throws GoogleError (NotConfiguredError without a + // credential, INVALID_ARGUMENT before any traffic, UNAVAILABLE and friends + // for upstream failures). Call once. + void connect(); + + void send_text(const std::string& text); + void send_turn(const std::string& text, bool turn_complete = true); + void send_audio(const std::string& pcm, + const std::string& mime = LiveRequests::kDefaultAudioMime); + void send_video(const std::string& bytes, + const std::string& mime = LiveRequests::kDefaultVideoMime); + void end_audio(); + void send_tool_responses(const std::vector& responses); + + // Waits up to timeout_ms for the next event; nullopt on timeout or when + // the session ended and the queue is drained. + std::optional next_event(int timeout_ms); + std::size_t pending() const; + bool open() const { return open_.load(); } + // Idempotent. Sends a close frame, waits up to kCloseGraceMs, joins. + void close(); + + struct Stats { + std::uint64_t sent = 0, received = 0, dropped = 0, decode_errors = 0; + }; + Stats stats() const; + std::string resumption_handle() const; + + private: + void send_raw(const std::string& json); + void push(LiveEvent e); + void reader_loop(); + void ingest(const WsMessage& m); + + LiveEndpoint endpoint_; + LiveConfig config_; + LiveOptions options_; + std::unique_ptr ws_; + std::thread reader_; + std::atomic open_{false}; + std::atomic stop_{false}; + std::atomic connected_{false}; + std::atomic close_deadline_ms_{0}; + + mutable std::mutex mu_; + std::condition_variable cv_; + std::deque queue_; + std::size_t queued_bytes_ = 0; + std::uint64_t seq_ = 0; + Stats stats_; + std::string handle_; +}; + +} // namespace molo::google::live diff --git a/src/google/live/live_spec.h b/src/google/live/live_spec.h new file mode 100644 index 0000000..e6d0333 --- /dev/null +++ b/src/google/live/live_spec.h @@ -0,0 +1,117 @@ +#pragma once + +// The single declaration of every wire name this module sends or reads. +// tools/check_discovery.py parses the rows below (one per line) and fails +// when a row with a discovery source names a schema or field that the +// published Discovery document does not have. Rows with a "docs:" source +// are not in any Discovery document (the Live API is a WebSocket service: +// Discovery lists the setup message and its nested types only) and are +// checked against the documentation page text instead. +// +// Row format: {"Schema", "field", "source"}, +// source = "/" Discovery document (schemas..properties) +// = "docs:" official documentation only + +#include + +namespace molo::google::live { + +struct LiveSpecRow { + const char* schema; + const char* field; + const char* source; +}; + +#define LIVE_GL "generativelanguage/v1beta" +#define LIVE_AI "aiplatform/v1" +#define LIVE_DOC "docs:https://ai.google.dev/api/live" + +inline constexpr LiveSpecRow kLiveSpec[] = { + // Setup message (Discovery: generativelanguage v1beta). + {"BidiGenerateContentSetup", "model", LIVE_GL}, + {"BidiGenerateContentSetup", "generationConfig", LIVE_GL}, + {"BidiGenerateContentSetup", "systemInstruction", LIVE_GL}, + {"BidiGenerateContentSetup", "tools", LIVE_GL}, + {"BidiGenerateContentSetup", "realtimeInputConfig", LIVE_GL}, + {"BidiGenerateContentSetup", "sessionResumption", LIVE_GL}, + {"BidiGenerateContentSetup", "contextWindowCompression", LIVE_GL}, + {"BidiGenerateContentSetup", "inputAudioTranscription", LIVE_GL}, + {"BidiGenerateContentSetup", "outputAudioTranscription", LIVE_GL}, + {"GenerationConfig", "responseModalities", LIVE_GL}, + {"GenerationConfig", "speechConfig", LIVE_GL}, + {"GenerationConfig", "temperature", LIVE_GL}, + {"GenerationConfig", "maxOutputTokens", LIVE_GL}, + {"SpeechConfig", "voiceConfig", LIVE_GL}, + {"SpeechConfig", "languageCode", LIVE_GL}, + {"VoiceConfig", "prebuiltVoiceConfig", LIVE_GL}, + {"PrebuiltVoiceConfig", "voiceName", LIVE_GL}, + {"Content", "parts", LIVE_GL}, + {"Content", "role", LIVE_GL}, + {"Part", "text", LIVE_GL}, + {"Part", "inlineData", LIVE_GL}, + {"Blob", "mimeType", LIVE_GL}, + {"Blob", "data", LIVE_GL}, + {"Tool", "functionDeclarations", LIVE_GL}, + {"FunctionDeclaration", "name", LIVE_GL}, + {"FunctionDeclaration", "description", LIVE_GL}, + {"FunctionDeclaration", "parameters", LIVE_GL}, + {"SessionResumptionConfig", "handle", LIVE_GL}, + {"ContextWindowCompressionConfig", "slidingWindow", LIVE_GL}, + {"FunctionCall", "id", LIVE_GL}, + {"FunctionCall", "name", LIVE_GL}, + {"FunctionCall", "args", LIVE_GL}, + {"FunctionResponse", "id", LIVE_GL}, + {"FunctionResponse", "name", LIVE_GL}, + {"FunctionResponse", "response", LIVE_GL}, + {"UsageMetadata", "totalTokenCount", LIVE_GL}, + // Vertex Discovery has the transcription value type (no Bidi messages). + {"GoogleCloudAiplatformV1Transcription", "text", LIVE_AI}, + {"GoogleCloudAiplatformV1Transcription", "finished", LIVE_AI}, + {"GoogleCloudAiplatformV1Blob", "mimeType", LIVE_AI}, + {"GoogleCloudAiplatformV1Blob", "data", LIVE_AI}, + // Message envelopes: documentation only. + {"ClientMessage", "setup", LIVE_DOC}, + {"ClientMessage", "clientContent", LIVE_DOC}, + {"ClientMessage", "realtimeInput", LIVE_DOC}, + {"ClientMessage", "toolResponse", LIVE_DOC}, + {"ClientContent", "turns", LIVE_DOC}, + {"ClientContent", "turnComplete", LIVE_DOC}, + {"RealtimeInput", "audio", LIVE_DOC}, + {"RealtimeInput", "video", LIVE_DOC}, + {"RealtimeInput", "text", LIVE_DOC}, + {"RealtimeInput", "audioStreamEnd", LIVE_DOC}, + {"ToolResponse", "functionResponses", LIVE_DOC}, + {"ServerMessage", "setupComplete", LIVE_DOC}, + {"ServerMessage", "serverContent", LIVE_DOC}, + {"ServerMessage", "toolCall", LIVE_DOC}, + {"ServerMessage", "toolCallCancellation", LIVE_DOC}, + {"ServerMessage", "goAway", LIVE_DOC}, + {"ServerMessage", "sessionResumptionUpdate", LIVE_DOC}, + {"ServerMessage", "usageMetadata", LIVE_DOC}, + {"ServerContent", "modelTurn", LIVE_DOC}, + {"ServerContent", "generationComplete", LIVE_DOC}, + {"ServerContent", "turnComplete", LIVE_DOC}, + {"ServerContent", "interrupted", LIVE_DOC}, + {"ServerContent", "inputTranscription", LIVE_DOC}, + {"ServerContent", "outputTranscription", LIVE_DOC}, + {"ToolCallMessage", "functionCalls", LIVE_DOC}, + {"ToolCallCancellation", "ids", LIVE_DOC}, + {"GoAway", "timeLeft", LIVE_DOC}, + {"SessionResumptionUpdate", "newHandle", LIVE_DOC}, + {"SessionResumptionUpdate", "resumable", LIVE_DOC}, +}; + +inline constexpr std::size_t kLiveSpecRows = sizeof(kLiveSpec) / sizeof(kLiveSpec[0]); + +// Endpoint templates (documentation / third-party only, see SPEC Unverified). +inline constexpr const char* kLiveApiKeyUrl = + "wss://generativelanguage.googleapis.com/ws/" + "google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent"; +inline constexpr const char* kLiveVertexPath = + "/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"; + +#undef LIVE_GL +#undef LIVE_AI +#undef LIVE_DOC + +} // namespace molo::google::live diff --git a/src/google/live/tools/check_discovery.py b/src/google/live/tools/check_discovery.py new file mode 100644 index 0000000..2c6bb1a --- /dev/null +++ b/src/google/live/tools/check_discovery.py @@ -0,0 +1,123 @@ +#!/usr/bin/env python3 +"""Checks src/google/live/live_spec.h against Google's published machine-readable specs. + +python3 stdlib only, no credentials. + + 1. Every row whose source is "/" must name a schema that + exists in that service's Discovery document and a field that is one of + its properties. + 2. Every row whose source is "docs:" must have its field name present + in the text of that documentation page (weaker: the Live API envelopes + are WebSocket messages and appear in no Discovery document). + 3. The WebSocket endpoints are probed with an unauthenticated upgrade + request: the server must answer 101 Switching Protocols with the correct + Sec-WebSocket-Accept (it closes the socket right after, for lack of + credentials). Pass --no-probe to skip. + +Exit 0 when everything holds, 1 otherwise. Prints one line per failure and a +summary. +""" +import base64 +import hashlib +import json +import os +import re +import socket +import ssl +import sys +import urllib.request + +HERE = os.path.dirname(os.path.abspath(__file__)) +SPEC = os.path.join(HERE, "..", "live_spec.h") +DISCOVERY = { + "generativelanguage": "https://generativelanguage.googleapis.com/$discovery/rest?version=%s", + "aiplatform": "https://aiplatform.googleapis.com/$discovery/rest?version=%s", +} +PROBES = [ + ("wss://us-central1-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"), + ("wss://us-central1-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContent"), + ("wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent"), +] + + +def fetch(url): + with urllib.request.urlopen(url, timeout=60) as r: + return r.read().decode("utf-8", "replace") + + +def parse_spec(path): + text = open(path, encoding="utf-8").read() + text = "\n".join(l for l in text.splitlines() if not l.lstrip().startswith("//")) + macros = dict(re.findall(r'#define\s+(LIVE_\w+)\s+"([^"]*)"', text)) + rows = [] + for m in re.finditer(r'\{"(\w+)",\s*"(\w+)",\s*(LIVE_\w+|"[^"]*")\}', text): + schema, field, src = m.groups() + src = macros[src] if src in macros else src.strip('"') + rows.append((schema, field, src)) + return rows + + +def probe(url): + host = url.split("/")[2] + path = url[len("wss://") + len(host):] + key = base64.b64encode(os.urandom(16)).decode() + ctx = ssl.create_default_context() + ctx.set_alpn_protocols(["http/1.1"]) + with socket.create_connection((host, 443), timeout=20) as raw: + with ctx.wrap_socket(raw, server_hostname=host) as s: + s.settimeout(20) + s.sendall(("GET %s HTTP/1.1\r\nHost: %s\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n" + "Sec-WebSocket-Key: %s\r\nSec-WebSocket-Version: 13\r\n\r\n" % (path, host, key)).encode()) + buf = b"" + while b"\r\n\r\n" not in buf and len(buf) < 16384: + chunk = s.recv(4096) + if not chunk: + break + buf += chunk + head = buf.split(b"\r\n\r\n")[0].decode("latin-1") + want = base64.b64encode(hashlib.sha1((key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").encode()).digest()).decode() + ok = head.startswith("HTTP/1.1 101") and want in head + return ok, head.split("\r\n")[0] + + +def main(): + rows = parse_spec(SPEC) + failures = [] + docs = {} + disc = {} + checked = 0 + for schema, field, src in rows: + if src.startswith("docs:"): + url = src[5:] + if url not in docs: + docs[url] = fetch(url) + if field not in docs[url]: + failures.append("docs: %s.%s not found on %s" % (schema, field, url)) + checked += 1 + continue + svc, ver = src.split("/") + if src not in disc: + disc[src] = json.loads(fetch(DISCOVERY[svc] % ver))["schemas"] + s = disc[src] + if schema not in s: + failures.append("discovery %s: schema %s missing" % (src, schema)) + elif field not in s[schema].get("properties", {}): + failures.append("discovery %s: %s.%s missing" % (src, schema, field)) + checked += 1 + for url in ([] if "--no-probe" in sys.argv else PROBES): + try: + ok, line = probe(url) + except Exception as e: # network trouble is a failure, loudly + ok, line = False, "error: %s" % e + print("%s upgrade probe %s -> %s" % ("ok " if ok else "FAIL", url.split("/ws/")[1], line)) + if not ok: + failures.append("probe failed: " + url) + for f in failures: + print("FAIL", f) + print("%d spec rows checked (%d discovery docs, %d doc pages), %d failures" + % (checked, len(disc), len(docs), len(failures))) + return 1 if failures else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/google/live/ws_client.cpp b/src/google/live/ws_client.cpp new file mode 100644 index 0000000..b5ed8dd --- /dev/null +++ b/src/google/live/ws_client.cpp @@ -0,0 +1,185 @@ +#include "google/live/ws_client.h" + +#include + +#include + +#include "google/live/caps.h" +#include "google/live/ws_error.h" + +namespace molo::google::live { + +using K = WsError::Kind; + +WsClient::WsClient(std::unique_ptr stream) + : stream_(std::move(stream)), decoder_(LiveCaps::kMaxFramePayload, false) {} + +void WsClient::handshake(const WsUrl& url, const WsHeaders& headers, + int timeout_ms) { + std::string key = WsHandshake::make_key(); + std::string req = WsHandshake::build_request(url, key, headers); + stream_->write_all(req.data(), req.size()); + auto deadline = std::chrono::steady_clock::now() + std::chrono::milliseconds(timeout_ms); + stream_->set_read_timeout_ms(1000); + std::string head; + char buf[LiveCaps::kReadChunk]; + std::size_t end; + while ((end = head.find("\r\n\r\n")) == std::string::npos) { + if (head.size() > LiveCaps::kMaxHandshakeBytes) + throw WsError(K::Handshake, "handshake response over cap"); + if (std::chrono::steady_clock::now() > deadline) + throw WsError(K::Timeout, "handshake timed out"); + ReadResult r = stream_->read(buf, sizeof buf); + if (r.status == ReadStatus::Eof) + throw WsError(K::Handshake, "peer closed during handshake"); + if (r.status == ReadStatus::Data) head.append(buf, r.n); + } + std::string rest = head.substr(end + 4); + head.resize(end + 4); + WsHandshake::check_response(head, key); + if (!rest.empty()) decoder_.feed(rest.data(), rest.size()); +} + +void WsClient::send_frame(WsOpcode op, const std::string& payload) { + std::uint8_t mask[4]; + if (::getrandom(mask, sizeof mask, 0) != (ssize_t)sizeof mask) + throw WsError(K::Io, "no entropy for frame mask"); + std::string wire = encode_frame(true, op, payload, mask); + std::lock_guard lock(write_mu_); + stream_->write_all(wire.data(), wire.size()); + std::lock_guard s(stats_mu_); + ++stats_.frames_out; +} + +void WsClient::send_text(const std::string& text) { + if (closed_ || close_sent_) throw WsError(K::Closed, "connection closed"); + if (text.size() > LiveCaps::kMaxOutboundMessage) + throw WsError(K::TooBig, "outbound message over cap"); + send_frame(WsOpcode::Text, text); +} + +void WsClient::send_binary(const std::string& data) { + if (closed_ || close_sent_) throw WsError(K::Closed, "connection closed"); + if (data.size() > LiveCaps::kMaxOutboundMessage) + throw WsError(K::TooBig, "outbound message over cap"); + send_frame(WsOpcode::Binary, data); +} + +void WsClient::send_ping(const std::string& payload) { + if (payload.size() > LiveCaps::kMaxControlPayload) + throw WsError(K::Invalid, "ping payload over 125 bytes"); + if (closed_ || close_sent_) throw WsError(K::Closed, "connection closed"); + send_frame(WsOpcode::Ping, payload); +} + +void WsClient::close(std::uint16_t code, const std::string& reason) { + if (close_sent_.exchange(true)) return; + std::string payload; + payload.push_back((char)(code >> 8)); + payload.push_back((char)(code & 0xFF)); + payload += reason.substr(0, LiveCaps::kMaxCloseReason); + try { + send_frame(WsOpcode::Close, payload); + } catch (const WsError&) { + } +} + +void WsClient::fail(std::uint16_t code, WsError::Kind kind, const std::string& why) { + close(code, ""); + closed_ = true; + throw WsError(kind, why); +} + +std::optional WsClient::receive() { + char buf[LiveCaps::kReadChunk]; + for (;;) { + std::optional frame; + try { + frame = decoder_.next(); + } catch (const WsError& e) { + fail(e.kind() == K::TooBig ? 1009 : 1002, e.kind(), e.what()); + } + if (!frame) { + if (closed_) { + WsMessage m; + m.kind = WsMessage::Kind::Close; + m.code = 1006; + return m; + } + ReadResult r = stream_->read(buf, sizeof buf); + if (r.status == ReadStatus::Timeout) return std::nullopt; + if (r.status == ReadStatus::Eof) { + closed_ = true; + WsMessage m; + m.kind = WsMessage::Kind::Close; + m.code = 1006; + m.data = "connection lost without close frame"; + return m; + } + decoder_.feed(buf, r.n); + continue; + } + { + std::lock_guard s(stats_mu_); + ++stats_.frames_in; + } + auto op = (WsOpcode)frame->opcode; + if (op == WsOpcode::Ping) { + { + std::lock_guard s(stats_mu_); + ++stats_.pings_in; + ++stats_.pongs_out; + } + if (!close_sent_) send_frame(WsOpcode::Pong, frame->payload); + continue; + } + if (op == WsOpcode::Pong) continue; + if (op == WsOpcode::Close) { + WsMessage m; + m.kind = WsMessage::Kind::Close; + m.code = 1005; + const std::string& p = frame->payload; + if (p.size() == 1) fail(1002, K::Protocol, "close payload of 1 byte"); + if (p.size() >= 2) { + m.code = (std::uint16_t)(((std::uint8_t)p[0] << 8) | (std::uint8_t)p[1]); + m.data = p.substr(2); + if (!valid_utf8(m.data)) fail(1007, K::Protocol, "close reason is not UTF-8"); + } + close(m.code == 1005 ? 1000 : m.code, ""); // echo + closed_ = true; + return m; + } + // Data frames. + if (op == WsOpcode::Continuation) { + if (!assembling_) fail(1002, K::Protocol, "continuation without a message"); + } else { + if (assembling_) fail(1002, K::Protocol, "new message inside a fragmented one"); + assembling_ = true; + assembling_text_ = op == WsOpcode::Text; + assembly_.clear(); + } + if (assembly_.size() + frame->payload.size() > LiveCaps::kMaxInboundMessage) + fail(1009, K::TooBig, "message over cap"); + assembly_ += frame->payload; + if (!frame->fin) continue; + assembling_ = false; + WsMessage m; + m.kind = assembling_text_ ? WsMessage::Kind::Text : WsMessage::Kind::Binary; + if (assembling_text_ && !valid_utf8(assembly_)) + fail(1007, K::Protocol, "text message is not UTF-8"); + m.data = std::move(assembly_); + assembly_.clear(); + { + std::lock_guard s(stats_mu_); + ++stats_.messages_in; + } + return m; + } +} + +WsClient::Stats WsClient::stats() const { + std::lock_guard s(stats_mu_); + return stats_; +} + +} // namespace molo::google::live diff --git a/src/google/live/ws_client.h b/src/google/live/ws_client.h new file mode 100644 index 0000000..5a92dbe --- /dev/null +++ b/src/google/live/ws_client.h @@ -0,0 +1,74 @@ +#pragma once + +// RFC 6455 client over an IByteStream. Masks every outbound frame, +// reassembles fragmented messages (control frames may interleave), answers +// pings, performs the closing handshake, and enforces frame and message +// caps. One thread calls receive(); any thread may send (writes are +// serialised). + +#include +#include +#include +#include +#include +#include + +#include "google/live/ws_error.h" +#include "google/live/ws_frame.h" +#include "google/live/ws_handshake.h" +#include "google/live/ws_stream.h" + +namespace molo::google::live { + +struct WsMessage { + enum class Kind { Text, Binary, Close }; + Kind kind = Kind::Text; + std::string data; // payload, or close reason + std::uint16_t code = 0; // close code (1005 when none, 1006 abnormal) +}; + +class WsClient { + public: + explicit WsClient(std::unique_ptr stream); + + // Runs the opening handshake on the stream. Throws WsError. + void handshake(const WsUrl& url, const WsHeaders& headers, int timeout_ms); + + void send_text(const std::string& text); + void send_binary(const std::string& data); + void send_ping(const std::string& payload = ""); + // Sends a close frame once; later calls are no-ops. + void close(std::uint16_t code = 1000, const std::string& reason = ""); + + // Next complete data message or Close; nullopt when the read timed out. + // Throws WsError on a protocol violation (after a best-effort 1002/1007/ + // 1009 close). + std::optional receive(); + + void set_read_timeout_ms(int ms) { stream_->set_read_timeout_ms(ms); } + void shutdown() { stream_->shutdown(); } + bool closed() const { return closed_.load(); } + + struct Stats { + std::uint64_t frames_in = 0, frames_out = 0, pings_in = 0, pongs_out = 0; + std::uint64_t messages_in = 0; + }; + Stats stats() const; + + private: + void send_frame(WsOpcode op, const std::string& payload); + void fail(std::uint16_t code, WsError::Kind kind, const std::string& why); + + std::unique_ptr stream_; + FrameDecoder decoder_; + std::mutex write_mu_; + std::atomic closed_{false}; + std::atomic close_sent_{false}; + bool assembling_ = false; + bool assembling_text_ = false; + std::string assembly_; + mutable std::mutex stats_mu_; + Stats stats_; +}; + +} // namespace molo::google::live diff --git a/src/google/live/ws_error.h b/src/google/live/ws_error.h new file mode 100644 index 0000000..d98d8d4 --- /dev/null +++ b/src/google/live/ws_error.h @@ -0,0 +1,29 @@ +#pragma once + +// Transport-level WebSocket failure. Messages never carry URLs with query +// strings or credentials. + +#include +#include + +namespace molo::google::live { + +class WsError : public std::runtime_error { + public: + enum class Kind { Invalid, Io, Timeout, Handshake, Protocol, TooBig, Closed }; + + WsError(Kind kind, const std::string& message, int http_status = 0) + : std::runtime_error("molo::google::live::ws: " + message), + kind_(kind), + http_status_(http_status) {} + + Kind kind() const noexcept { return kind_; } + // HTTP status of a refused upgrade, else 0. + int http_status() const noexcept { return http_status_; } + + private: + Kind kind_; + int http_status_; +}; + +} // namespace molo::google::live diff --git a/src/google/live/ws_frame.cpp b/src/google/live/ws_frame.cpp new file mode 100644 index 0000000..3c33cfc --- /dev/null +++ b/src/google/live/ws_frame.cpp @@ -0,0 +1,132 @@ +#include "google/live/ws_frame.h" + +#include "google/live/caps.h" +#include "google/live/ws_error.h" + +namespace molo::google::live { + +using K = WsError::Kind; + +std::string encode_frame(bool fin, WsOpcode opcode, const std::string& payload, + const std::uint8_t* mask_key) { + std::string out; + out.push_back((char)((fin ? 0x80 : 0x00) | (std::uint8_t)opcode)); + std::uint8_t mask_bit = mask_key ? 0x80 : 0x00; + std::size_t n = payload.size(); + if (n < 126) { + out.push_back((char)(mask_bit | n)); + } else if (n <= 0xFFFF) { + out.push_back((char)(mask_bit | 126)); + out.push_back((char)(n >> 8)); + out.push_back((char)(n & 0xFF)); + } else { + out.push_back((char)(mask_bit | 127)); + for (int shift = 56; shift >= 0; shift -= 8) + out.push_back((char)(((std::uint64_t)n >> shift) & 0xFF)); + } + if (mask_key) { + out.append(reinterpret_cast(mask_key), 4); + for (std::size_t i = 0; i < n; ++i) + out.push_back((char)((std::uint8_t)payload[i] ^ mask_key[i & 3])); + } else { + out += payload; + } + return out; +} + +bool valid_utf8(const std::string& s) { + std::size_t i = 0, n = s.size(); + while (i < n) { + std::uint8_t c = (std::uint8_t)s[i]; + std::size_t len; + std::uint32_t cp; + if (c < 0x80) { + ++i; + continue; + } else if (c >= 0xC2 && c <= 0xDF) { + len = 2; + cp = c & 0x1F; + } else if (c >= 0xE0 && c <= 0xEF) { + len = 3; + cp = c & 0x0F; + } else if (c >= 0xF0 && c <= 0xF4) { + len = 4; + cp = c & 0x07; + } else { + return false; + } + if (i + len > n) return false; + for (std::size_t k = 1; k < len; ++k) { + std::uint8_t cc = (std::uint8_t)s[i + k]; + if ((cc & 0xC0) != 0x80) return false; + cp = (cp << 6) | (cc & 0x3F); + } + if (len == 3 && (cp < 0x800 || (cp >= 0xD800 && cp <= 0xDFFF))) return false; + if (len == 4 && (cp < 0x10000 || cp > 0x10FFFF)) return false; + i += len; + } + return true; +} + +void FrameDecoder::feed(const char* data, std::size_t size) { + if (pos_ > 0 && pos_ == buf_.size()) { + buf_.clear(); + pos_ = 0; + } else if (pos_ > LiveCaps::kReadChunk) { + buf_.erase(0, pos_); + pos_ = 0; + } + buf_.append(data, size); +} + +std::optional FrameDecoder::next() { + const std::size_t avail = buf_.size() - pos_; + if (avail < 2) return std::nullopt; + const auto* p = reinterpret_cast(buf_.data()) + pos_; + bool fin = p[0] & 0x80; + if (p[0] & 0x70) throw WsError(K::Protocol, "reserved bits set"); + std::uint8_t op = p[0] & 0x0F; + bool known = op == 0 || op == 1 || op == 2 || (op >= 8 && op <= 10); + if (!known) throw WsError(K::Protocol, "unknown opcode"); + bool masked = p[1] & 0x80; + if (masked != expect_masked_) + throw WsError(K::Protocol, expect_masked_ ? "unmasked client frame" + : "masked server frame"); + std::uint64_t len = p[1] & 0x7F; + std::size_t header = 2; + if (len == 126) { + if (avail < 4) return std::nullopt; + len = ((std::uint64_t)p[2] << 8) | p[3]; + header = 4; + if (len < 126) throw WsError(K::Protocol, "non-minimal length"); + } else if (len == 127) { + if (avail < 10) return std::nullopt; + len = 0; + for (int i = 0; i < 8; ++i) len = (len << 8) | p[2 + i]; + header = 10; + if (len >> 63) throw WsError(K::Protocol, "length high bit set"); + if (len <= 0xFFFF) throw WsError(K::Protocol, "non-minimal length"); + } + bool control = op >= 8; + if (control) { + if (!fin) throw WsError(K::Protocol, "fragmented control frame"); + if (len > LiveCaps::kMaxControlPayload) + throw WsError(K::Protocol, "control payload over 125 bytes"); + } + if (len > max_payload_) throw WsError(K::TooBig, "frame payload over cap"); + std::size_t mask_len = masked ? 4 : 0; + if (avail < header + mask_len + len) return std::nullopt; + WsFrame f; + f.fin = fin; + f.opcode = op; + const std::uint8_t* key = p + header; + const std::uint8_t* body = p + header + mask_len; + f.payload.assign(reinterpret_cast(body), (std::size_t)len); + if (masked) + for (std::size_t i = 0; i < f.payload.size(); ++i) + f.payload[i] = (char)((std::uint8_t)f.payload[i] ^ key[i & 3]); + pos_ += header + mask_len + (std::size_t)len; + return f; +} + +} // namespace molo::google::live diff --git a/src/google/live/ws_frame.h b/src/google/live/ws_frame.h new file mode 100644 index 0000000..1cea8c1 --- /dev/null +++ b/src/google/live/ws_frame.h @@ -0,0 +1,54 @@ +#pragma once + +// RFC 6455 framing: encoder (optionally masked) and an incremental decoder +// that enforces the protocol rules and the payload cap before buffering. + +#include +#include +#include + +namespace molo::google::live { + +enum class WsOpcode : std::uint8_t { + Continuation = 0x0, + Text = 0x1, + Binary = 0x2, + Close = 0x8, + Ping = 0x9, + Pong = 0xA, +}; + +struct WsFrame { + bool fin = true; + std::uint8_t opcode = 0; + std::string payload; // unmasked +}; + +// mask_key null: unmasked (server direction). Non-null: 4 bytes, masked +// (client direction, mandatory per RFC 6455 5.3). +std::string encode_frame(bool fin, WsOpcode opcode, const std::string& payload, + const std::uint8_t* mask_key); + +// Strict UTF-8 (RFC 3629): no overlongs, no surrogates, max U+10FFFF. +bool valid_utf8(const std::string& s); + +class FrameDecoder { + public: + // expect_masked false: frames come from a server and must be unmasked. + // true: frames come from a client and must be masked (test servers). + explicit FrameDecoder(std::size_t max_payload, bool expect_masked = false) + : max_payload_(max_payload), expect_masked_(expect_masked) {} + + void feed(const char* data, std::size_t size); + // Next complete frame or nullopt. Throws WsError(Protocol or TooBig). + std::optional next(); + std::size_t buffered() const { return buf_.size() - pos_; } + + private: + std::size_t max_payload_; + bool expect_masked_; + std::string buf_; + std::size_t pos_ = 0; +}; + +} // namespace molo::google::live diff --git a/src/google/live/ws_handshake.cpp b/src/google/live/ws_handshake.cpp new file mode 100644 index 0000000..2b6870b --- /dev/null +++ b/src/google/live/ws_handshake.cpp @@ -0,0 +1,155 @@ +#include "google/live/ws_handshake.h" + +#include + +#include +#include +#include +#include +#include + +#include "google/live/ws_error.h" +#include "security/crypto/Base64.h" + +namespace molo::google::live { + +using K = WsError::Kind; +using molo::security::crypto::Base64; + +namespace { + +std::array sha1(const std::string& msg) { + std::uint32_t h[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0}; + std::string data = msg; + data.push_back((char)0x80); + while (data.size() % 64 != 56) data.push_back(0); + std::uint64_t bits = (std::uint64_t)msg.size() * 8; + for (int i = 7; i >= 0; --i) data.push_back((char)((bits >> (i * 8)) & 0xFF)); + auto rol = [](std::uint32_t v, int s) { return (v << s) | (v >> (32 - s)); }; + for (std::size_t off = 0; off < data.size(); off += 64) { + std::uint32_t w[80]; + for (int i = 0; i < 16; ++i) + w[i] = ((std::uint32_t)(std::uint8_t)data[off + i * 4] << 24) | + ((std::uint32_t)(std::uint8_t)data[off + i * 4 + 1] << 16) | + ((std::uint32_t)(std::uint8_t)data[off + i * 4 + 2] << 8) | + (std::uint32_t)(std::uint8_t)data[off + i * 4 + 3]; + for (int i = 16; i < 80; ++i) + w[i] = rol(w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16], 1); + std::uint32_t a = h[0], b = h[1], c = h[2], d = h[3], e = h[4]; + for (int i = 0; i < 80; ++i) { + std::uint32_t f, k; + if (i < 20) { + f = (b & c) | (~b & d); + k = 0x5A827999; + } else if (i < 40) { + f = b ^ c ^ d; + k = 0x6ED9EBA1; + } else if (i < 60) { + f = (b & c) | (b & d) | (c & d); + k = 0x8F1BBCDC; + } else { + f = b ^ c ^ d; + k = 0xCA62C1D6; + } + std::uint32_t t = rol(a, 5) + f + e + k + w[i]; + e = d; + d = c; + c = rol(b, 30); + b = a; + a = t; + } + h[0] += a; + h[1] += b; + h[2] += c; + h[3] += d; + h[4] += e; + } + std::array out{}; + for (int i = 0; i < 5; ++i) + for (int j = 0; j < 4; ++j) out[i * 4 + j] = (std::uint8_t)(h[i] >> (24 - j * 8)); + return out; +} + +std::string lower(std::string s) { + for (auto& c : s) c = (char)std::tolower((unsigned char)c); + return s; +} + +std::string trim(const std::string& s) { + std::size_t a = s.find_first_not_of(" \t"); + if (a == std::string::npos) return ""; + std::size_t b = s.find_last_not_of(" \t\r"); + return s.substr(a, b - a + 1); +} + +} // namespace + +std::string WsHandshake::make_key() { + std::uint8_t raw[16]; + std::size_t got = 0; + while (got < sizeof raw) { + ssize_t n = ::getrandom(raw + got, sizeof raw - got, 0); + if (n <= 0) throw WsError(K::Io, "no entropy for handshake key"); + got += (std::size_t)n; + } + return Base64::encode(raw, sizeof raw); +} + +std::string WsHandshake::accept_for(const std::string& key) { + auto d = sha1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"); + return Base64::encode(d.data(), d.size()); +} + +std::string WsHandshake::build_request(const WsUrl& url, const std::string& key, + const WsHeaders& headers) { + std::string host = url.host; + if (url.port != (url.secure ? 443 : 80)) host += ":" + std::to_string(url.port); + std::string out = "GET " + url.target + " HTTP/1.1\r\nHost: " + host + + "\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n" + "Sec-WebSocket-Key: " + key + "\r\nSec-WebSocket-Version: 13\r\n"; + for (const auto& [name, value] : headers) { + if (name.empty() || name.find_first_of("\r\n:") != std::string::npos || + value.find_first_of("\r\n") != std::string::npos) + throw WsError(K::Invalid, "header with forbidden characters"); + out += name + ": " + value + "\r\n"; + } + return out + "\r\n"; +} + +void WsHandshake::check_response(const std::string& head, const std::string& key) { + std::size_t eol = head.find("\r\n"); + if (eol == std::string::npos) throw WsError(K::Handshake, "malformed response"); + std::string status_line = head.substr(0, eol); + int status = 0; + if (status_line.rfind("HTTP/1.1 ", 0) != 0 || status_line.size() < 12) + throw WsError(K::Handshake, "malformed status line"); + for (int i = 9; i < 12; ++i) { + if (!std::isdigit((unsigned char)status_line[i])) + throw WsError(K::Handshake, "malformed status line"); + status = status * 10 + (status_line[i] - '0'); + } + if (status != 101) + throw WsError(K::Handshake, "upgrade refused with HTTP " + std::to_string(status), status); + std::string upgrade, connection, accept; + std::size_t pos = eol + 2; + while (pos < head.size()) { + std::size_t e = head.find("\r\n", pos); + if (e == std::string::npos || e == pos) break; + std::string line = head.substr(pos, e - pos); + pos = e + 2; + std::size_t c = line.find(':'); + if (c == std::string::npos) continue; + std::string name = lower(trim(line.substr(0, c))); + std::string value = trim(line.substr(c + 1)); + if (name == "upgrade") upgrade = lower(value); + else if (name == "connection") connection = lower(value); + else if (name == "sec-websocket-accept") accept = value; + } + if (upgrade != "websocket") throw WsError(K::Handshake, "missing Upgrade: websocket", 101); + if (connection.find("upgrade") == std::string::npos) + throw WsError(K::Handshake, "missing Connection: Upgrade", 101); + if (accept != accept_for(key)) + throw WsError(K::Handshake, "Sec-WebSocket-Accept mismatch", 101); +} + +} // namespace molo::google::live diff --git a/src/google/live/ws_handshake.h b/src/google/live/ws_handshake.h new file mode 100644 index 0000000..4ecf8f5 --- /dev/null +++ b/src/google/live/ws_handshake.h @@ -0,0 +1,30 @@ +#pragma once + +// Opening handshake (RFC 6455 4.1): request building and strict validation +// of the 101 answer, including Sec-WebSocket-Accept. + +#include +#include +#include + +#include "google/live/ws_url.h" + +namespace molo::google::live { + +using WsHeaders = std::vector>; + +class WsHandshake { + public: + // 16 random bytes, base64. + static std::string make_key(); + // base64(sha1(key + GUID)). + static std::string accept_for(const std::string& key); + // Headers must not contain CR or LF; throws WsError(Invalid). + static std::string build_request(const WsUrl& url, const std::string& key, + const WsHeaders& headers); + // head = response bytes up to and including the blank line. Throws + // WsError(Handshake) carrying the HTTP status when not an accepted 101. + static void check_response(const std::string& head, const std::string& key); +}; + +} // namespace molo::google::live diff --git a/src/google/live/ws_stream.cpp b/src/google/live/ws_stream.cpp new file mode 100644 index 0000000..92d74b1 --- /dev/null +++ b/src/google/live/ws_stream.cpp @@ -0,0 +1,191 @@ +#include "google/live/ws_stream.h" + +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include + +#include "clients/transports/tls_wolfssl.h" +#include "google/live/ws_error.h" + +namespace molo::google::live { + +using K = WsError::Kind; + +namespace { +void set_timeout(int fd, int opt, int ms) { + timeval tv{}; + tv.tv_sec = ms / 1000; + tv.tv_usec = (ms % 1000) * 1000; + ::setsockopt(fd, SOL_SOCKET, opt, &tv, sizeof tv); +} +} // namespace + +TcpStream::TcpStream(int fd, int io_timeout_ms) : fd_(fd) { + set_timeout(fd_, SO_RCVTIMEO, io_timeout_ms); + set_timeout(fd_, SO_SNDTIMEO, io_timeout_ms); +} + +TcpStream::~TcpStream() { + if (fd_ >= 0) ::close(fd_); +} + +void TcpStream::set_read_timeout_ms(int ms) { + set_timeout(fd_, SO_RCVTIMEO, ms); +} + +ReadResult TcpStream::read(char* out, std::size_t max) { + for (;;) { + ssize_t n = ::recv(fd_, out, max, 0); + if (n > 0) return {ReadStatus::Data, (std::size_t)n}; + if (n == 0) return {ReadStatus::Eof, 0}; + if (errno == EINTR) continue; + if (errno == EAGAIN || errno == EWOULDBLOCK) + return {ReadStatus::Timeout, 0}; + if (errno == ECONNRESET) return {ReadStatus::Eof, 0}; + throw WsError(K::Io, std::string("recv failed: ") + std::strerror(errno)); + } +} + +void TcpStream::write_all(const char* data, std::size_t size) { + std::size_t sent = 0; + while (sent < size) { + ssize_t n = ::send(fd_, data + sent, size - sent, MSG_NOSIGNAL); + if (n > 0) { + sent += (std::size_t)n; + continue; + } + if (n < 0 && errno == EINTR) continue; + if (n < 0 && (errno == EAGAIN || errno == EWOULDBLOCK)) + throw WsError(K::Timeout, "send timed out"); + throw WsError(K::Io, std::string("send failed: ") + + std::strerror(n < 0 ? errno : EPIPE)); + } +} + +void TcpStream::shutdown() { + if (fd_ >= 0) ::shutdown(fd_, SHUT_RDWR); +} + +TlsStream::TlsStream(int fd, + std::shared_ptr session, + const std::string& hostname, int io_timeout_ms) + : fd_(fd), read_timeout_ms_(io_timeout_ms), session_(std::move(session)) { + set_timeout(fd_, SO_RCVTIMEO, io_timeout_ms); + set_timeout(fd_, SO_SNDTIMEO, io_timeout_ms); + // The TLS backend writes without MSG_NOSIGNAL; a peer that vanished would + // otherwise kill the process. Process-wide, once. + static std::once_flag sigpipe_once; + std::call_once(sigpipe_once, [] { std::signal(SIGPIPE, SIG_IGN); }); + try { + session_->handshake(fd_, hostname, false); + } catch (const clients::transports::TlsError& e) { + ::close(fd_); + fd_ = -1; + throw WsError(K::Io, e.what()); + } +} + +TlsStream::~TlsStream() { + try { + if (session_) session_->shutdown(); + } catch (...) { + } + if (fd_ >= 0) ::close(fd_); +} + +void TlsStream::set_read_timeout_ms(int ms) { + read_timeout_ms_ = ms; + set_timeout(fd_, SO_RCVTIMEO, ms); +} + +// ITlsSession::recv_some returns 0 for both "timed out" and "peer closed". +// A return well before the socket timeout is a close; one that waited out +// at least half the timeout is a timeout. +ReadResult TlsStream::read(char* out, std::size_t max) { + auto t0 = std::chrono::steady_clock::now(); + std::size_t n = 0; + // The backend reports a socket timeout and a dropped connection (Google + // closes TCP after its close frame, without close_notify) both as a read + // error or a zero read. Elapsed time tells them apart. + try { + n = session_->recv_some(out, max); + } catch (const clients::transports::TlsError&) { + n = 0; + } + if (n > 0) return {ReadStatus::Data, n}; + auto ms = std::chrono::duration_cast( + std::chrono::steady_clock::now() - t0) + .count(); + if (ms * 2 >= read_timeout_ms_) return {ReadStatus::Timeout, 0}; + return {ReadStatus::Eof, 0}; +} + +void TlsStream::write_all(const char* data, std::size_t size) { + try { + session_->send_all(data, size); + } catch (const clients::transports::TlsError& e) { + throw WsError(K::Io, e.what()); + } +} + +void TlsStream::shutdown() { + if (fd_ >= 0) ::shutdown(fd_, SHUT_RDWR); +} + +std::unique_ptr open_stream(const WsUrl& url, + int connect_timeout_ms, + int io_timeout_ms, TlsFactory tls) { + addrinfo hints{}; + hints.ai_family = AF_UNSPEC; + hints.ai_socktype = SOCK_STREAM; + addrinfo* res = nullptr; + if (::getaddrinfo(url.host.c_str(), std::to_string(url.port).c_str(), &hints, + &res) != 0 || + !res) + throw WsError(K::Io, "cannot resolve " + url.host); + int fd = -1; + std::string last = "connect failed"; + for (addrinfo* ai = res; ai; ai = ai->ai_next) { + fd = ::socket(ai->ai_family, ai->ai_socktype, ai->ai_protocol); + if (fd < 0) continue; + int flags = ::fcntl(fd, F_GETFL, 0); + ::fcntl(fd, F_SETFL, flags | O_NONBLOCK); + int rc = ::connect(fd, ai->ai_addr, ai->ai_addrlen); + bool ok = rc == 0; + if (!ok && errno == EINPROGRESS) { + pollfd p{fd, POLLOUT, 0}; + if (::poll(&p, 1, connect_timeout_ms) == 1) { + int err = 0; + socklen_t len = sizeof err; + ::getsockopt(fd, SOL_SOCKET, SO_ERROR, &err, &len); + ok = err == 0; + if (!ok) last = std::string("connect failed: ") + std::strerror(err); + } else { + last = "connect timed out"; + } + } + if (ok) { + ::fcntl(fd, F_SETFL, flags); + break; + } + ::close(fd); + fd = -1; + } + ::freeaddrinfo(res); + if (fd < 0) throw WsError(K::Io, last + " to " + url.display()); + if (!url.secure) return std::make_unique(fd, io_timeout_ms); + auto session = tls ? tls() : clients::transports::MakeTlsSession(); + return std::make_unique(fd, std::move(session), url.host, + io_timeout_ms); +} + +} // namespace molo::google::live diff --git a/src/google/live/ws_stream.h b/src/google/live/ws_stream.h new file mode 100644 index 0000000..cff60a7 --- /dev/null +++ b/src/google/live/ws_stream.h @@ -0,0 +1,72 @@ +#pragma once + +// Blocking byte streams under the WebSocket client: plain TCP and TLS via +// the existing ITlsSession (wolfSSL). Read and write timeouts are socket +// level; a read that times out reports Timeout, a closed peer reports Eof. + +#include +#include +#include +#include + +#include "clients/transports/tls.h" +#include "google/live/ws_url.h" + +namespace molo::google::live { + +enum class ReadStatus { Data, Timeout, Eof }; +struct ReadResult { + ReadStatus status = ReadStatus::Timeout; + std::size_t n = 0; +}; + +class IByteStream { + public: + virtual ~IByteStream() = default; + virtual ReadResult read(char* out, std::size_t max) = 0; + virtual void write_all(const char* data, std::size_t size) = 0; + virtual void set_read_timeout_ms(int ms) = 0; + virtual void shutdown() = 0; +}; + +class TcpStream : public IByteStream { + public: + TcpStream(int fd, int io_timeout_ms); // takes ownership of fd + ~TcpStream() override; + ReadResult read(char* out, std::size_t max) override; + void write_all(const char* data, std::size_t size) override; + void set_read_timeout_ms(int ms) override; + void shutdown() override; + + private: + int fd_; +}; + +class TlsStream : public IByteStream { + public: + // Handshakes immediately; the fd is owned by this stream. + TlsStream(int fd, std::shared_ptr session, + const std::string& hostname, int io_timeout_ms); + ~TlsStream() override; + ReadResult read(char* out, std::size_t max) override; + void write_all(const char* data, std::size_t size) override; + void set_read_timeout_ms(int ms) override; + void shutdown() override; + + private: + int fd_; + int read_timeout_ms_; + std::shared_ptr session_; +}; + +using TlsFactory = + std::function()>; + +// Resolves, connects (bounded by connect_timeout_ms) and, for wss, runs the +// TLS handshake. A null factory uses clients::transports::MakeTlsSession. +std::unique_ptr open_stream(const WsUrl& url, + int connect_timeout_ms, + int io_timeout_ms, + TlsFactory tls = nullptr); + +} // namespace molo::google::live diff --git a/src/google/live/ws_url.cpp b/src/google/live/ws_url.cpp new file mode 100644 index 0000000..a732823 --- /dev/null +++ b/src/google/live/ws_url.cpp @@ -0,0 +1,68 @@ +#include "google/live/ws_url.h" + +#include + +#include "google/live/caps.h" +#include "google/live/ws_error.h" + +namespace molo::google::live { + +WsUrl WsUrl::parse(const std::string& url) { + using K = WsError::Kind; + if (url.empty() || url.size() > LiveCaps::kMaxUrlChars) + throw WsError(K::Invalid, "url empty or too long"); + for (unsigned char c : url) + if (c <= 0x20 || c == 0x7f) + throw WsError(K::Invalid, "url has control or space characters"); + WsUrl out; + std::size_t pos; + if (url.rfind("wss://", 0) == 0) { + out.secure = true; + out.port = 443; + pos = 6; + } else if (url.rfind("ws://", 0) == 0) { + pos = 5; + } else { + throw WsError(K::Invalid, "url scheme must be ws or wss"); + } + std::size_t end = url.find_first_of("/?#", pos); + std::string authority = + url.substr(pos, end == std::string::npos ? std::string::npos : end - pos); + if (authority.find('@') != std::string::npos) + throw WsError(K::Invalid, "url must not carry userinfo"); + std::size_t colon = authority.rfind(':'); + if (colon != std::string::npos) { + std::string p = authority.substr(colon + 1); + authority.resize(colon); + if (p.empty() || p.size() > 5) throw WsError(K::Invalid, "bad port"); + int v = 0; + for (char c : p) { + if (!std::isdigit((unsigned char)c)) throw WsError(K::Invalid, "bad port"); + v = v * 10 + (c - '0'); + } + if (v < 1 || v > 65535) throw WsError(K::Invalid, "port out of range"); + out.port = v; + } + if (authority.empty() || authority.size() > 253) + throw WsError(K::Invalid, "bad host"); + for (unsigned char c : authority) + if (!(std::isalnum(c) || c == '.' || c == '-' || c == '_')) + throw WsError(K::Invalid, "bad host character"); + out.host = authority; + if (end != std::string::npos) { + std::string rest = url.substr(end); + std::size_t hash = rest.find('#'); + if (hash != std::string::npos) rest.resize(hash); + if (rest.empty() || rest[0] == '?') rest = "/" + rest; + out.target = rest; + } + return out; +} + +std::string WsUrl::display() const { + std::string path = target.substr(0, target.find('?')); + return std::string(secure ? "wss://" : "ws://") + host + ":" + + std::to_string(port) + path; +} + +} // namespace molo::google::live diff --git a/src/google/live/ws_url.h b/src/google/live/ws_url.h new file mode 100644 index 0000000..125b70c --- /dev/null +++ b/src/google/live/ws_url.h @@ -0,0 +1,21 @@ +#pragma once + +// ws:// and wss:// URL, parsed and validated. display() omits the query so +// an API key in "?key=" never reaches an error message or a log line. + +#include + +namespace molo::google::live { + +struct WsUrl { + bool secure = false; + std::string host; + int port = 80; + std::string target = "/"; // path plus query, as sent on the request line + + // Throws WsError(Invalid). + static WsUrl parse(const std::string& url); + std::string display() const; // scheme://host:port/path, no query +}; + +} // namespace molo::google::live diff --git a/tests/example/agent/live/page_test.cpp b/tests/example/agent/live/page_test.cpp new file mode 100644 index 0000000..69ef432 --- /dev/null +++ b/tests/example/agent/live/page_test.cpp @@ -0,0 +1,19 @@ +// Route: GET /agent/live (mobile-first Live API page, no credential needed) +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + GoogleRig rig(false); + Fixture f(rig.client); + auto res = f.client->get("/agent/live"); + check(res.status == 200, "status 200 without a credential"); + check(contains(res.headers.get("Content-Type"), "text/html"), "html"); + check(contains(res.body, "Live API") && contains(res.body, "l-create"), "page body"); + check(contains(res.body, "/embedded/agent_live.js"), "script referenced"); + check(contains(res.body, "viewport"), "responsive meta from the base template"); + check(contains(f.client->get("/").body, "/agent/live"), "listed in the feature matrix"); + check(f.client->post("/agent/live").status == 405, "post is 405"); + check(rig.mock->send_count() == 0, "side effect: no upstream traffic"); + return finish("agent/live"); +} diff --git a/tests/example/agent/live/sessions_test.cpp b/tests/example/agent/live/sessions_test.cpp new file mode 100644 index 0000000..6ea36b6 --- /dev/null +++ b/tests/example/agent/live/sessions_test.cpp @@ -0,0 +1,130 @@ +// Routes: POST /agent/live/sessions, POST .../{id}/send, GET .../{id}/events, +// POST .../{id}/close (HTTP relay over a loopback WebSocket server) +#include +#include +#include + +#include "../../../src/google/live/loopback.h" +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; +using live_test::LoopbackServer; +using live_test::ServerConn; + +namespace { +std::string json_of(const std::string& body, const std::string& key) { + std::size_t k = body.find("\"" + key + "\":\""); + if (k == std::string::npos) return ""; + k += key.size() + 4; + return body.substr(k, body.find('"', k) - k); +} +} // namespace + +int main() { + unsetenv("GOOGLE_ACCESS_TOKEN"); + unsetenv("GOOGLE_CLOUD_PROJECT"); + setenv("GOOGLE_API_KEY", "test-key", 1); + + // No credential: every Google-bound route answers 503, nothing connects. + { + GoogleRig rig(false); + Fixture f(rig.client); + auto res = f.client->post("/agent/live/sessions", "{}", "application/json"); + check(res.status == 503, "create without a credential is 503"); + check(contains(res.body, "google_not_configured"), "error code google_not_configured"); + check(f.client->post("/agent/live/sessions/s0123456789ab/send", + "{\"kind\":\"text\",\"text\":\"x\"}", "application/json").status == 503, + "send without a credential is 503"); + check(f.client->post("/agent/live/sessions/s0123456789ab/close", "{}", "application/json").status == 503, + "close without a credential is 503"); + } + + std::string text_seen, audio_seen; + LoopbackServer server([&](ServerConn& c) { + c.read_message(); // setup + c.send_text("{\"setupComplete\":{}}"); + text_seen = c.read_message().value_or(""); + c.send_text("{\"serverContent\":{\"modelTurn\":{\"parts\":[{\"text\":\"hello from loopback\"}]}}}"); + c.send_text("{\"serverContent\":{\"turnComplete\":true}}"); + audio_seen = c.read_message().value_or(""); + while (c.read_frame()) { + } + }); + setenv("GOOGLE_LIVE_URL", server.url().c_str(), 1); + + GoogleRig rig; + Fixture f(rig.client); + + // Validation: rejected before any socket is opened. + check(f.client->post("/agent/live/sessions", "{\"modality\":\"VIDEO\"}", "application/json").status == 422, + "bad modality is 422"); + check(f.client->post("/agent/live/sessions", "{\"model\":\"../x\"}", "application/json").status == 422, + "bad model is 422"); + check(f.client->post("/agent/live/sessions", "{\"voice\":\"a b;c\"}", "application/json").status == 422, + "bad voice is 422"); + check(f.client->get("/agent/live/sessions").status == 405, "get on create is 405"); + + auto created = f.client->post("/agent/live/sessions", "{\"system\":\"be brief\",\"transcribe\":\"1\"}", + "application/json"); + check(created.status == 201, "create answers 201"); + std::string id = json_of(created.body, "id"); + check(id.size() == 13 && id[0] == 's', "session id shape"); + check(!contains(created.body, "test-key"), "credential never returned"); + + std::string base = "/agent/live/sessions/" + id; + check(f.client->post(base + "/send", "{\"kind\":\"smoke\"}", "application/json").status == 422, + "unknown kind is 422"); + check(f.client->post(base + "/send", "{\"kind\":\"text\",\"text\":\"\"}", "application/json").status == 422, + "empty text is 422"); + check(f.client->post(base + "/send", "{\"kind\":\"text\",\"text\":\"" + std::string(32001, 'a') + "\"}", + "application/json").status == 422, + "text over the cap is 422"); + check(f.client->post(base + "/send", "{\"kind\":\"audio\",\"data_b64\":\"!!\"}", "application/json").status == 422, + "bad base64 is 422"); + check(f.client->post("/agent/live/sessions/s000000000000/send", "{\"kind\":\"text\",\"text\":\"x\"}", + "application/json").status == 404, + "unknown session is 404"); + check(f.client->get(base + "/send").status == 405, "get on send is 405"); + + auto sent = f.client->post(base + "/send", "{\"kind\":\"text\",\"text\":\"hi there\"}", "application/json"); + check(sent.status == 200 && contains(sent.body, "\"sent\":true"), "text sent"); + + // Poll by cursor until the model text arrives. + std::string cursor = "0", all; + for (int i = 0; i < 40 && !contains(all, "turn_complete"); ++i) { + auto page = f.client->get(base + "/events?cursor=" + cursor); + check(page.status == 200, "events answers 200"); + all += page.body; + std::string next = json_of(page.body, "next_cursor"); + std::size_t k = page.body.find("\"next_cursor\":"); + if (k != std::string::npos) cursor = page.body.substr(k + 14, page.body.find_first_of(",}", k) - k - 14); + std::this_thread::sleep_for(std::chrono::milliseconds(50)); + } + check(contains(all, "hello from loopback"), "model text relayed"); + check(contains(all, "\"type\":\"turn_complete\""), "turn_complete relayed"); + check(contains(f.client->get(base + "/events?cursor=" + cursor).body, "\"events\":[]"), + "cursor: nothing new after the last event"); + check(f.client->get(base + "/events?cursor=abc").status == 422, "bad cursor is 422"); + check(f.client->get("/agent/live/sessions/s000000000000/events").status == 404, "unknown session events is 404"); + + auto audio = f.client->post(base + "/send", + "{\"kind\":\"audio\",\"data_b64\":\"AQID\",\"mime\":\"audio/pcm;rate=16000\"}", + "application/json"); + check(audio.status == 200, "audio chunk sent"); + check(f.client->post(base + "/send", "{\"kind\":\"audio\",\"data_b64\":\"AQID\",\"mime\":\"image/png\"}", + "application/json").status == 422, + "audio with an image mime is 422"); + + auto closed = f.client->post(base + "/close", "{}", "application/json"); + check(closed.status == 200 && contains(closed.body, "\"closed\":true"), "close answers 200"); + check(f.client->post(base + "/close", "{}", "application/json").status == 404, "closing twice is 404"); + check(f.client->get(base + "/events").status == 404, "closed session events is 404"); + + check(contains(text_seen, "\"realtimeInput\"") && contains(text_seen, "hi there"), + "side effect: the loopback server got the text turn"); + check(contains(audio_seen, "audio/pcm;rate=16000") && contains(audio_seen, "AQID"), + "side effect: the loopback server got the audio chunk"); + check(contains(server.request(), "Sec-WebSocket-Key"), "side effect: a real WebSocket upgrade happened"); + check(rig.mock->send_count() == 0, "no HTTP traffic to Google"); + return finish("agent/live/sessions"); +} diff --git a/tests/example/agent/live/status_test.cpp b/tests/example/agent/live/status_test.cpp new file mode 100644 index 0000000..eed927a --- /dev/null +++ b/tests/example/agent/live/status_test.cpp @@ -0,0 +1,42 @@ +// Route: GET /agent/live/status (credential form and static caps) +#include + +#include "support/GoogleRig.hpp" + +using namespace molo::example::test; + +int main() { + unsetenv("GOOGLE_ACCESS_TOKEN"); + setenv("GOOGLE_API_KEY", "AIzaTEST-LIVE-KEY", 1); + unsetenv("GOOGLE_LIVE_URL"); + { + GoogleRig rig; + Fixture f(rig.client); + auto res = f.client->get("/agent/live/status"); + check(res.status == 200, "status 200"); + check(contains(res.headers.get("Content-Type"), "application/json"), "json"); + check(contains(res.body, "\"configured\":true"), "configured with a key"); + check(contains(res.body, "\"auth_mode\":\"gemini_api_key\""), "plain key selects the Gemini API form"); + check(contains(res.body, "\"max_sessions\":8"), "caps shown"); + check(!contains(res.body, "AIzaTEST-LIVE-KEY"), "credential never shown"); + check(rig.mock->send_count() == 0, "side effect: no upstream traffic"); + } + setenv("GOOGLE_API_KEY", "AQ.test-express", 1); + setenv("GOOGLE_CLOUD_PROJECT", "test-project", 1); + { + GoogleRig rig; + Fixture f(rig.client); + check(contains(f.client->get("/agent/live/status").body, "\"auth_mode\":\"vertex_express\""), + "AQ. key with a project selects Vertex express"); + } + unsetenv("GOOGLE_API_KEY"); + { + GoogleRig rig(false); + Fixture f(rig.client); + check(contains(f.client->get("/agent/live/status").body, "\"configured\":false"), + "not configured without a credential"); + } + Fixture f; + check(f.client->post("/agent/live/status").status == 405, "post is 405"); + return finish("agent/live/status"); +} diff --git a/tests/src/google/live/loopback.h b/tests/src/google/live/loopback.h new file mode 100644 index 0000000..ac56b0c --- /dev/null +++ b/tests/src/google/live/loopback.h @@ -0,0 +1,165 @@ +#pragma once + +// Loopback WebSocket server for tests: raw sockets, plain ws://, one +// accepted connection, a user script running on the server thread. It +// speaks RFC 6455 from first principles (own accept computation through the +// module's SHA-1 would be circular, so the accept key is also checked +// against the RFC example in test_ws_frame). + +#include +#include +#include +#include + +#include +#include +#include +#include +#include + +#include "google/live/ws_frame.h" +#include "google/live/ws_handshake.h" + +namespace live_test { + +using namespace molo::google::live; + +struct ServerConn { + int fd = -1; + FrameDecoder decoder{8u * 1024u * 1024u, true}; + std::string request; // handshake request text + + void send_raw(const std::string& bytes) const { + std::size_t sent = 0; + while (sent < bytes.size()) { + ssize_t n = ::send(fd, bytes.data() + sent, bytes.size() - sent, MSG_NOSIGNAL); + if (n <= 0) return; + sent += (std::size_t)n; + } + } + void send_text(const std::string& s) const { send_raw(encode_frame(true, WsOpcode::Text, s, nullptr)); } + void send_binary(const std::string& s) const { send_raw(encode_frame(true, WsOpcode::Binary, s, nullptr)); } + void send_close(std::uint16_t code, const std::string& reason = "") const { + std::string p; + p.push_back((char)(code >> 8)); + p.push_back((char)(code & 0xFF)); + send_raw(encode_frame(true, WsOpcode::Close, p + reason, nullptr)); + } + // Next client frame; nullopt on EOF or timeout (2 s). + std::optional read_frame() { + for (;;) { + auto f = decoder.next(); + if (f) return f; + char buf[4096]; + ssize_t n = ::recv(fd, buf, sizeof buf, 0); + if (n <= 0) return std::nullopt; + decoder.feed(buf, (std::size_t)n); + } + } + // Next text/binary client message payload (skips pings, answers none). + std::optional read_message() { + std::string acc; + for (;;) { + auto f = read_frame(); + if (!f) return std::nullopt; + if (f->opcode >= 8) { + if (f->opcode == 8) return std::nullopt; + continue; + } + acc += f->payload; + if (f->fin) return acc; + } + } +}; + +class LoopbackServer { + public: + using Script = std::function; + + enum class Handshake { Ok, BadAccept, Status403, CloseImmediately }; + + explicit LoopbackServer(Script script, Handshake mode = Handshake::Ok) + : script_(std::move(script)), mode_(mode) { + listen_fd_ = ::socket(AF_INET, SOCK_STREAM, 0); + int one = 1; + ::setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &one, sizeof one); + sockaddr_in a{}; + a.sin_family = AF_INET; + a.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + a.sin_port = 0; + ::bind(listen_fd_, (sockaddr*)&a, sizeof a); + ::listen(listen_fd_, 1); + socklen_t len = sizeof a; + ::getsockname(listen_fd_, (sockaddr*)&a, &len); + port_ = ntohs(a.sin_port); + thread_ = std::thread([this] { run(); }); + } + ~LoopbackServer() { + if (listen_fd_ >= 0) ::shutdown(listen_fd_, SHUT_RDWR); + if (thread_.joinable()) thread_.join(); + if (listen_fd_ >= 0) ::close(listen_fd_); + } + int port() const { return port_; } + std::string url(const std::string& path = "/ws") const { + return "ws://127.0.0.1:" + std::to_string(port_) + path; + } + std::string request() const { return request_; } + + private: + void run() { + timeval tv{2, 0}; + int fd = ::accept(listen_fd_, nullptr, nullptr); + if (fd < 0) return; + ::setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof tv); + ServerConn conn; + conn.fd = fd; + std::string head; + char buf[2048]; + while (head.find("\r\n\r\n") == std::string::npos) { + ssize_t n = ::recv(fd, buf, sizeof buf, 0); + if (n <= 0) { + ::close(fd); + return; + } + head.append(buf, (std::size_t)n); + } + std::size_t end = head.find("\r\n\r\n") + 4; + if (end < head.size()) conn.decoder.feed(head.data() + end, head.size() - end); + head.resize(end); + conn.request = head; + request_ = head; + std::size_t k = head.find("Sec-WebSocket-Key: "); + std::string key = head.substr(k + 19, head.find("\r\n", k) - k - 19); + if (mode_ == Handshake::CloseImmediately) { + ::close(fd); + return; + } + if (mode_ == Handshake::Status403) { + conn.send_raw("HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\n\r\n"); + ::close(fd); + return; + } + std::string accept = WsHandshake::accept_for(key); + if (mode_ == Handshake::BadAccept) accept = "AAAAAAAAAAAAAAAAAAAAAAAAAAA="; + conn.send_raw("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" + "Connection: Upgrade\r\nSec-WebSocket-Accept: " + accept + "\r\n\r\n"); + if (mode_ == Handshake::Ok) { + try { + script_(conn); + } catch (...) { + } + } + ::close(fd); + } + + Script script_; + Handshake mode_; + int listen_fd_ = -1; + int port_ = 0; + std::thread thread_; + std::string request_; +}; + +// Polls the session for an event of `kind`, up to timeout_ms, returning all +// events seen (so tests can assert order). +} // namespace live_test diff --git a/tests/src/google/live/test_live.cpp b/tests/src/google/live/test_live.cpp new file mode 100644 index 0000000..2d38e44 --- /dev/null +++ b/tests/src/google/live/test_live.cpp @@ -0,0 +1,571 @@ +// Live API: typed setup, client messages, server event decoding, session, +// relay. The wire names are checked against live_spec.h (which the +// tools/check_discovery.py script checks against Google's Discovery +// documents). No Google traffic: the loopback server only carries bytes. +#include +#include +#include +#include + +#include "framework.h" +#include "google/errors.h" +#include "google/live/live_config.h" +#include "google/live/live_relay.h" +#include "google/live/live_session.h" +#include "google/live/live_spec.h" +#include "loopback.h" +#include "security/crypto/Base64.h" + +using namespace molo::google; +using namespace molo::google::live; +using molo::clients::body::Json; +using molo::security::crypto::Base64; +using live_test::LoopbackServer; +using live_test::ServerConn; + +namespace { + +void collect_keys(const Json& j, std::set& out) { + if (j.is_object()) { + for (const auto& [k, v] : j.as_object()) { + out.insert(k); + collect_keys(v, out); + } + } else if (j.is_array()) { + for (const auto& v : j.as_array()) collect_keys(v, out); + } +} + +std::set spec_fields() { + std::set s; + for (std::size_t i = 0; i < kLiveSpecRows; ++i) s.insert(kLiveSpec[i].field); + return s; +} + +LiveEndpoint local_endpoint(const LoopbackServer& s, bool vertex = false) { + LiveEndpoint e; + if (vertex) { + CloudContext ctx; + ctx.project = "test-project"; + e = LiveEndpoint::vertex(ctx, "tok"); + } else { + e = LiveEndpoint::api_key("test-key"); + } + e.url_override = s.url(); + return e; +} + +// Reads events until `kind` (inclusive) or timeout; returns everything seen. +std::vector until(LiveSession& s, LiveEventKind kind, int ms = 3000) { + std::vector seen; + auto deadline = std::chrono::steady_clock::now() + std::chrono::milliseconds(ms); + while (std::chrono::steady_clock::now() < deadline) { + auto e = s.next_event(100); + if (!e) { + if (!s.open() && s.pending() == 0) break; + continue; + } + seen.push_back(*e); + if (e->kind == kind) break; + } + return seen; +} + +} // namespace + +TEST(live_endpoint, urls_headers_models) { + CloudContext ctx; + ctx.project = "p1"; + ctx.location = "europe-west4"; + auto v = LiveEndpoint::vertex(ctx, "tok"); + ASSERT_EQ(v.url(), "wss://europe-west4-aiplatform.googleapis.com/ws/" + "google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"); + ASSERT_EQ(v.headers().at(0).first, "Authorization"); + ASSERT_EQ(v.headers().at(0).second, "Bearer tok"); + ASSERT_EQ(v.model_name("m1"), "projects/p1/locations/europe-west4/publishers/google/models/m1"); + ctx.location = "global"; + ASSERT_TRUE(LiveEndpoint::vertex(ctx, "t").url().find("wss://aiplatform.googleapis.com/ws/") == 0); + auto x = LiveEndpoint::vertex_express(ctx, "AQ.k"); + ASSERT_EQ(x.headers().at(0).first, "x-goog-api-key"); + ASSERT_TRUE(x.url().find("AQ.k") == std::string::npos); // express key never in the URL + auto a = LiveEndpoint::api_key("K1"); + ASSERT_EQ(a.url(), std::string(kLiveApiKeyUrl) + "?key=K1"); + ASSERT_TRUE(a.headers().empty()); + ASSERT_EQ(a.model_name("m1"), "models/m1"); + ASSERT_THROW(a.model_name("../x"), GoogleError); + ASSERT_THROW(a.model_name(""), GoogleError); +} + +TEST(live_endpoint, validation_before_traffic) { + CloudContext ctx; + ctx.project = "p1"; + ASSERT_THROW(LiveEndpoint::api_key("").validate(), NotConfiguredError); + ASSERT_THROW(LiveEndpoint::vertex(ctx, "").validate(), NotConfiguredError); + ASSERT_THROW(LiveEndpoint::api_key("a&b").validate(), GoogleError); + ASSERT_THROW(LiveEndpoint::api_key("a b").validate(), GoogleError); + ASSERT_THROW(LiveEndpoint::vertex(ctx, "t\r\nX: y").validate(), GoogleError); + ctx.project = "Bad Project"; + ASSERT_THROW(LiveEndpoint::vertex(ctx, "t").validate(), GoogleError); + ctx.project = "p1"; + ctx.location = "us central"; + ASSERT_THROW(LiveEndpoint::vertex(ctx, "t").validate(), GoogleError); + // connect() without a credential throws before any socket is opened. + LiveSession s(LiveEndpoint::api_key(""), LiveConfig{}); + ASSERT_THROW(s.connect(), NotConfiguredError); +} + +TEST(live_config, setup_matches_spec_names) { + LiveConfig c; + c.system_instruction = "be brief"; + c.voice_name = "Puck"; + c.language_code = "nl-NL"; + c.temperature = 0.5; + c.max_output_tokens = 100; + c.input_transcription = c.output_transcription = true; + c.session_resumption = true; + c.context_compression = true; + LiveFunctionDeclaration f; + f.name = "get_weather"; + f.description = "weather"; + f.parameters = Json::parse("{\"type\":\"OBJECT\",\"properties\":{\"city\":{\"type\":\"STRING\"}}}"); + c.functions.push_back(f); + CloudContext ctx; + ctx.project = "p"; + Json j = c.to_setup(LiveEndpoint::vertex(ctx, "t")); + ASSERT_TRUE(j.has("setup")); + const Json& s = *j.find("setup"); + ASSERT_EQ(s.find("model")->as_string(), + "projects/p/locations/us-central1/publishers/google/models/" + c.model); + ASSERT_EQ(s.find("generationConfig")->find("responseModalities")->as_array().at(0).as_string(), "AUDIO"); + ASSERT_EQ(s.find("generationConfig")->find("speechConfig")->find("voiceConfig") + ->find("prebuiltVoiceConfig")->find("voiceName")->as_string(), "Puck"); + ASSERT_EQ(s.find("systemInstruction")->find("parts")->as_array().at(0).find("text")->as_string(), "be brief"); + ASSERT_TRUE(s.has("inputAudioTranscription") && s.has("outputAudioTranscription")); + ASSERT_TRUE(s.find("sessionResumption")->is_object()); + ASSERT_TRUE(s.find("contextWindowCompression")->find("slidingWindow")->is_object()); + // Every key anywhere in the message, except user-supplied schema content + // under "parameters", is a declared wire name. + auto fields = spec_fields(); + fields.insert("setup"); + std::set keys; + Json copy = c.to_setup(LiveEndpoint::api_key("k")); + Json& decls = copy.as_object().at("setup").as_object().at("tools").as_array().at(0) + .as_object().at("functionDeclarations").as_array().at(0); + decls.as_object().erase("parameters"); + collect_keys(copy, keys); + for (const auto& k : keys) ASSERT_TRUE(fields.count(k) == 1 || k == "setup"); + ASSERT_EQ(copy.find("setup")->find("model")->as_string(), "models/" + c.model); +} + +TEST(live_config, validation) { + auto ep = LiveEndpoint::api_key("k"); + auto bad = [&](auto mutate) { + LiveConfig c; + mutate(c); + ASSERT_THROW(c.to_setup(ep), GoogleError); + }; + bad([](LiveConfig& c) { c.model = "a/b"; }); + bad([](LiveConfig& c) { c.response_modalities = {}; }); + bad([](LiveConfig& c) { c.response_modalities = {"VIDEO"}; }); + bad([](LiveConfig& c) { c.temperature = 3.0; }); + bad([](LiveConfig& c) { c.max_output_tokens = 0; }); + bad([](LiveConfig& c) { c.voice_name = "bad voice!"; }); + bad([](LiveConfig& c) { c.language_code = "nl_NL"; }); + bad([](LiveConfig& c) { c.system_instruction = std::string(LiveCaps::kMaxSystemChars + 1, 'x'); }); + bad([](LiveConfig& c) { c.resumption_handle = "has space"; }); + bad([](LiveConfig& c) { + c.functions.resize(LiveCaps::kMaxFunctionDecls + 1); + for (std::size_t i = 0; i < c.functions.size(); ++i) c.functions[i].name = "f" + std::to_string(i); + }); + bad([](LiveConfig& c) { c.functions.push_back({"1bad", "", Json()}); }); + bad([](LiveConfig& c) { c.functions.push_back({"ok", "", Json("not an object")}); }); +} + +TEST(live_requests, shapes_and_caps) { + Json t = Json::parse(LiveRequests::text("hi")); + ASSERT_EQ(t.find("realtimeInput")->find("text")->as_string(), "hi"); + Json turn = Json::parse(LiveRequests::turn("hello", false)); + ASSERT_EQ(turn.find("clientContent")->find("turns")->as_array().at(0).find("role")->as_string(), "user"); + ASSERT_FALSE(turn.find("clientContent")->find("turnComplete")->as_bool()); + Json a = Json::parse(LiveRequests::audio(std::string("\x01\x02\x03", 3), "audio/pcm;rate=16000")); + const Json* blob = a.find("realtimeInput")->find("audio"); + ASSERT_EQ(blob->find("mimeType")->as_string(), "audio/pcm;rate=16000"); + std::string raw; + ASSERT_TRUE(Base64::decode(blob->find("data")->as_string(), raw)); + ASSERT_EQ(raw.size(), (std::size_t)3); + Json v = Json::parse(LiveRequests::video("jpegbytes", "image/jpeg")); + ASSERT_TRUE(v.find("realtimeInput")->has("video")); + ASSERT_TRUE(Json::parse(LiveRequests::audio_stream_end()).find("realtimeInput")->find("audioStreamEnd")->as_bool()); + Json resp = Json::object(); + resp.set("temp", 21); + Json tr = Json::parse(LiveRequests::tool_responses({{"call-1", "get_weather", resp}})); + const Json& fr = tr.find("toolResponse")->find("functionResponses")->as_array().at(0); + ASSERT_EQ(fr.find("id")->as_string(), "call-1"); + ASSERT_EQ(fr.find("name")->as_string(), "get_weather"); + + ASSERT_THROW(LiveRequests::text(""), GoogleError); + ASSERT_THROW(LiveRequests::text(std::string(LiveCaps::kMaxTextChars + 1, 'x')), GoogleError); + ASSERT_THROW(LiveRequests::audio("", "audio/pcm"), GoogleError); + ASSERT_THROW(LiveRequests::audio("x", "image/png"), GoogleError); + ASSERT_THROW(LiveRequests::audio("x", "audio/pcm\r\n"), GoogleError); + ASSERT_THROW(LiveRequests::audio(std::string(LiveCaps::kMaxAudioChunkBytes + 1, 'x'), "audio/pcm"), GoogleError); + ASSERT_THROW(LiveRequests::video(std::string(LiveCaps::kMaxVideoChunkBytes + 1, 'x'), "image/jpeg"), GoogleError); + ASSERT_THROW(LiveRequests::video("x", "text/plain"), GoogleError); + ASSERT_THROW(LiveRequests::tool_responses({}), GoogleError); + ASSERT_THROW(LiveRequests::tool_responses({{"", "n", resp}}), GoogleError); + ASSERT_THROW(LiveRequests::tool_responses({{"i", "n", Json("str")}}), GoogleError); + std::vector many(LiveCaps::kMaxFunctionResponses + 1, LiveToolResponse{"i", "n", resp}); + ASSERT_THROW(LiveRequests::tool_responses(many), GoogleError); + // Client message envelopes are declared names. + auto fields = spec_fields(); + for (const std::string& m : {LiveRequests::text("x"), LiveRequests::turn("x", true), + LiveRequests::audio("x", "audio/pcm"), LiveRequests::video("x", "image/jpeg"), + LiveRequests::audio_stream_end(), LiveRequests::tool_responses({{"i", "n", resp}})}) { + std::set keys; + Json j = Json::parse(m); + // "response" content is user data. + collect_keys(j, keys); + for (const auto& k : keys) ASSERT_TRUE(fields.count(k) == 1 || k == "temp"); + } +} + +TEST(live_events, decode_server_messages) { + auto one = [](const std::string& json) { return LiveParser::parse(json); }; + auto ev = one("{\"setupComplete\":{}}"); + ASSERT_EQ(ev.size(), (std::size_t)1); + ASSERT_TRUE(ev[0].kind == LiveEventKind::SetupComplete); + + std::string pcm("\x10\x00\x20\x00", 4); + ev = one("{\"serverContent\":{\"modelTurn\":{\"parts\":[{\"text\":\"hi\"},{\"inlineData\":{\"mimeType\":" + "\"audio/pcm;rate=24000\",\"data\":\"" + Base64::encode(pcm) + "\"}}]},\"outputTranscription\":" + "{\"text\":\"hi\"},\"generationComplete\":true,\"turnComplete\":true}}"); + ASSERT_EQ(ev.size(), (std::size_t)5); + ASSERT_TRUE(ev[0].kind == LiveEventKind::Text); + ASSERT_TRUE(ev[1].kind == LiveEventKind::Audio); + ASSERT_EQ(ev[1].data, pcm); + ASSERT_EQ(ev[1].mime, "audio/pcm;rate=24000"); + ASSERT_TRUE(ev[2].kind == LiveEventKind::OutputTranscription); + ASSERT_TRUE(ev[3].kind == LiveEventKind::GenerationComplete); + ASSERT_TRUE(ev[4].kind == LiveEventKind::TurnComplete); // always last + + ev = one("{\"serverContent\":{\"inputTranscription\":{\"text\":\"you\"},\"interrupted\":true}}"); + ASSERT_TRUE(ev[0].kind == LiveEventKind::InputTranscription); + ASSERT_TRUE(ev[1].kind == LiveEventKind::Interrupted); + + ev = one("{\"toolCall\":{\"functionCalls\":[{\"id\":\"c1\",\"name\":\"f\",\"args\":{\"x\":1}}]}}"); + ASSERT_TRUE(ev[0].kind == LiveEventKind::ToolCall); + ASSERT_EQ(ev[0].calls.at(0).id, "c1"); + ASSERT_EQ(ev[0].calls.at(0).args.find("x")->as_int(), 1L); + ev = one("{\"toolCallCancellation\":{\"ids\":[\"c1\",\"c2\"]}}"); + ASSERT_EQ(ev[0].ids.size(), (std::size_t)2); + ev = one("{\"goAway\":{\"timeLeft\":\"12.5s\"}}"); + ASSERT_TRUE(ev[0].seconds == 12.5); + ev = one("{\"sessionResumptionUpdate\":{\"newHandle\":\"h1\",\"resumable\":true}}"); + ASSERT_EQ(ev[0].handle, "h1"); + ASSERT_TRUE(ev[0].resumable); + ev = one("{\"usageMetadata\":{\"totalTokenCount\":42}}"); + ASSERT_EQ(ev[0].total_tokens, 42L); + + // Loud on the unexpected. + ASSERT_TRUE(one("not json")[0].kind == LiveEventKind::Error); + ASSERT_TRUE(one("[1]")[0].kind == LiveEventKind::Error); + ASSERT_TRUE(one("{\"somethingNew\":{}}")[0].kind == LiveEventKind::Unknown); + ev = one("{\"serverContent\":{\"modelTurn\":{\"parts\":[{\"inlineData\":{\"mimeType\":\"audio/pcm\",\"data\":\"!!\"}}]}}}"); + ASSERT_TRUE(ev[0].kind == LiveEventKind::Error); + ASSERT_TRUE(LiveParser::parse_duration("0.5s") == 0.5); + ASSERT_TRUE(LiveParser::parse_duration("5") < 0); + ASSERT_TRUE(LiveParser::parse_duration("-1s") < 0); + ASSERT_TRUE(LiveParser::parse_duration("xs") < 0); +} + +TEST(live_session, full_conversation_over_loopback) { + std::string setup_seen, text_seen, audio_seen, tool_seen; + LoopbackServer server([&](ServerConn& c) { + setup_seen = c.read_message().value_or(""); + c.send_text("{\"setupComplete\":{}}"); + text_seen = c.read_message().value_or(""); + // Binary frames carry JSON too (as Gemini does). + c.send_binary("{\"serverContent\":{\"modelTurn\":{\"parts\":[{\"text\":\"hello\"}]}}}"); + c.send_text("{\"serverContent\":{\"turnComplete\":true}}"); + audio_seen = c.read_message().value_or(""); + c.send_text("{\"toolCall\":{\"functionCalls\":[{\"id\":\"c1\",\"name\":\"f\",\"args\":{}}]}}"); + tool_seen = c.read_message().value_or(""); + c.send_text("{\"sessionResumptionUpdate\":{\"newHandle\":\"h-123\",\"resumable\":true}}"); + c.send_text("{\"goAway\":{\"timeLeft\":\"5s\"}}"); + c.read_frame(); // the client's close + c.send_close(1000); + }); + LiveConfig cfg; + cfg.system_instruction = "hi"; + LiveSession s(local_endpoint(server), cfg); + s.connect(); + ASSERT_TRUE(s.open()); + ASSERT_TRUE(Json::parse(setup_seen).has("setup") || setup_seen.empty() == false); + s.send_text("ping"); + auto evs = until(s, LiveEventKind::TurnComplete); + ASSERT_TRUE(!evs.empty()); + ASSERT_TRUE(evs.front().kind == LiveEventKind::SetupComplete); // queued during connect + bool saw_text = false; + for (auto& e : evs) saw_text |= e.kind == LiveEventKind::Text && e.text == "hello"; + ASSERT_TRUE(saw_text); + for (std::size_t i = 1; i < evs.size(); ++i) ASSERT_TRUE(evs[i].seq > evs[i - 1].seq); + + s.send_audio("pcm-bytes"); + auto tc = until(s, LiveEventKind::ToolCall); + ASSERT_TRUE(tc.back().kind == LiveEventKind::ToolCall); + Json resp = Json::object(); + resp.set("ok", true); + s.send_tool_responses({{tc.back().calls.at(0).id, "f", resp}}); + auto rest = until(s, LiveEventKind::GoAway); + ASSERT_TRUE(rest.back().kind == LiveEventKind::GoAway); + ASSERT_TRUE(rest.back().seconds == 5.0); + ASSERT_EQ(s.resumption_handle(), "h-123"); + s.close(); + ASSERT_FALSE(s.open()); + auto closing = until(s, LiveEventKind::Closed, 500); + ASSERT_TRUE(!closing.empty() && closing.back().kind == LiveEventKind::Closed); + ASSERT_THROW(s.send_text("late"), GoogleError); + s.close(); // idempotent + + ASSERT_TRUE(setup_seen.find("\"setup\"") != std::string::npos); + ASSERT_TRUE(setup_seen.find("systemInstruction") != std::string::npos); + ASSERT_EQ(text_seen, "{\"realtimeInput\":{\"text\":\"ping\"}}"); + ASSERT_TRUE(audio_seen.find("\"audio\"") != std::string::npos); + ASSERT_TRUE(audio_seen.find("audio/pcm;rate=16000") != std::string::npos); + ASSERT_TRUE(tool_seen.find("functionResponses") != std::string::npos); + auto st = s.stats(); + ASSERT_EQ(st.sent, (std::uint64_t)3); +} + +TEST(live_session, vertex_headers_reach_the_server) { + LoopbackServer server([](ServerConn& c) { + c.read_message(); + c.send_text("{\"setupComplete\":{}}"); + c.read_frame(); + }); + LiveSession s(local_endpoint(server, true), LiveConfig{}); + s.connect(); + s.close(); + ASSERT_TRUE(server.request().find("Authorization: Bearer tok") != std::string::npos); +} + +TEST(live_session, server_close_before_setup_is_an_error_with_reason) { + LoopbackServer server([](ServerConn& c) { + c.read_message(); + c.send_close(1008, "Publisher model was not found"); + }); + LiveSession s(local_endpoint(server), LiveConfig{}); + try { + s.connect(); + FAIL("expected failure"); + } catch (const GoogleError& e) { + ASSERT_EQ(e.status(), "FAILED_PRECONDITION"); + ASSERT_TRUE(e.message().find("1008") != std::string::npos); + ASSERT_TRUE(e.message().find("Publisher model was not found") != std::string::npos); + } + ASSERT_FALSE(s.open()); +} + +TEST(live_session, handshake_errors_map_to_google_statuses) { + struct C { LoopbackServer::Handshake mode; int http; const char* status; }; + for (C c : {C{LoopbackServer::Handshake::Status403, 403, "PERMISSION_DENIED"}, + C{LoopbackServer::Handshake::BadAccept, 502, "UNAVAILABLE"}, + C{LoopbackServer::Handshake::CloseImmediately, 502, "UNAVAILABLE"}}) { + LoopbackServer server([](ServerConn&) {}, c.mode); + LiveSession s(local_endpoint(server), LiveConfig{}); + try { + s.connect(); + FAIL("expected failure"); + } catch (const GoogleError& e) { + ASSERT_EQ(e.http_status(), c.http); + ASSERT_EQ(e.status(), c.status); + ASSERT_TRUE(e.message().find("test-key") == std::string::npos); + } + } +} + +TEST(live_session, setup_timeout_is_bounded) { + LoopbackServer server([](ServerConn& c) { + c.read_message(); + std::this_thread::sleep_for(std::chrono::milliseconds(1200)); // never sends setupComplete + }); + LiveOptions opt; + opt.setup_timeout_ms = 400; + LiveSession s(local_endpoint(server), LiveConfig{}, opt); + auto t0 = std::chrono::steady_clock::now(); + try { + s.connect(); + FAIL("expected timeout"); + } catch (const GoogleError& e) { + ASSERT_EQ(e.http_status(), 504); + } + ASSERT_TRUE(std::chrono::steady_clock::now() - t0 < std::chrono::milliseconds(1100)); +} + +TEST(live_session, event_queue_is_bounded_and_counts_drops) { + const int flood = (int)LiveCaps::kMaxQueuedEvents + 300; + LoopbackServer server([&](ServerConn& c) { + c.read_message(); + c.send_text("{\"setupComplete\":{}}"); + for (int i = 0; i < flood; ++i) + c.send_text("{\"serverContent\":{\"modelTurn\":{\"parts\":[{\"text\":\"t" + std::to_string(i) + "\"}]}}}"); + c.send_text("{\"serverContent\":{\"turnComplete\":true}}"); + c.read_frame(); + }); + LiveSession s(local_endpoint(server), LiveConfig{}); + s.connect(); + auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(5); + while (s.stats().received < (std::uint64_t)flood + 1 && std::chrono::steady_clock::now() < deadline) + std::this_thread::sleep_for(std::chrono::milliseconds(20)); + ASSERT_TRUE(s.pending() <= LiveCaps::kMaxQueuedEvents); + ASSERT_TRUE(s.stats().dropped > 0); + // Newest survives: the last event is the turnComplete. + auto evs = until(s, LiveEventKind::TurnComplete); + ASSERT_TRUE(evs.back().kind == LiveEventKind::TurnComplete); + s.close(); +} + +TEST(live_session, abnormal_disconnect_surfaces_closed_event) { + LoopbackServer server([](ServerConn& c) { + c.read_message(); + c.send_text("{\"setupComplete\":{}}"); + }); + LiveSession s(local_endpoint(server), LiveConfig{}); + s.connect(); + auto evs = until(s, LiveEventKind::Closed); + ASSERT_TRUE(evs.back().kind == LiveEventKind::Closed); + ASSERT_EQ(evs.back().code, 1006); + ASSERT_FALSE(s.open()); +} + +TEST(live_session, lifetime_cap_closes_session) { + LoopbackServer server([](ServerConn& c) { + c.read_message(); + c.send_text("{\"setupComplete\":{}}"); + while (c.read_frame()) { + } + }); + LiveOptions opt; + opt.max_session_seconds = 1; + LiveSession s(local_endpoint(server), LiveConfig{}, opt); + s.connect(); + auto evs = until(s, LiveEventKind::Closed, 4000); + ASSERT_TRUE(evs.back().kind == LiveEventKind::Closed); + ASSERT_TRUE(evs.back().text.find("lifetime") != std::string::npos); +} + +TEST(live_session, send_validates_before_the_wire) { + LoopbackServer server([](ServerConn& c) { + c.read_message(); + c.send_text("{\"setupComplete\":{}}"); + while (c.read_frame()) { + } + }); + LiveSession s(local_endpoint(server), LiveConfig{}); + s.connect(); + ASSERT_THROW(s.send_text(""), GoogleError); + ASSERT_THROW(s.send_audio("x", "video/mp4"), GoogleError); + ASSERT_THROW(s.send_video(std::string(LiveCaps::kMaxVideoChunkBytes + 1, 'x')), GoogleError); + ASSERT_EQ(s.stats().sent, (std::uint64_t)0); + s.close(); +} + +TEST(live_relay, create_poll_cursor_close_and_caps) { + LoopbackServer server([](ServerConn& c) { + c.read_message(); + c.send_text("{\"setupComplete\":{}}"); + auto m = c.read_message(); + c.send_text("{\"serverContent\":{\"modelTurn\":{\"parts\":[{\"text\":\"echo\"}]}}}"); + c.send_text("{\"serverContent\":{\"turnComplete\":true}}"); + (void)m; + while (c.read_frame()) { + } + }); + LiveRelay relay(1); + std::string id = relay.create(local_endpoint(server), LiveConfig{}); + ASSERT_TRUE(LiveRelay::valid_id(id)); + ASSERT_EQ(relay.size(), (std::size_t)1); + // Second concurrent session is refused (cap 1). + try { + relay.create(local_endpoint(server), LiveConfig{}); + FAIL("expected cap"); + } catch (const GoogleError& e) { + ASSERT_EQ(e.http_status(), 429); + } + relay.get(id)->send_text("hi"); + std::vector all; + std::uint64_t cursor = 0; + for (int i = 0; i < 40 && (all.empty() || all.back().kind != LiveEventKind::TurnComplete); ++i) { + auto page = relay.poll(id, cursor, 100); + for (auto& e : page.events) all.push_back(e); + cursor = page.next_cursor; + std::this_thread::sleep_for(std::chrono::milliseconds(50)); + } + ASSERT_TRUE(all.back().kind == LiveEventKind::TurnComplete); + // Cursor semantics: polling again from the end returns nothing new. + ASSERT_TRUE(relay.poll(id, cursor, 100).events.empty()); + // Page size is capped. + ASSERT_TRUE(relay.poll(id, 0, 100000).events.size() <= LiveCaps::kMaxRelayPage); + Json j = event_to_json(all.front()); + ASSERT_TRUE(j.has("seq") && j.has("type")); + relay.close(id); + ASSERT_EQ(relay.size(), (std::size_t)0); + ASSERT_THROW(relay.poll(id, 0, 10), GoogleError); + ASSERT_THROW(relay.close(id), GoogleError); + ASSERT_THROW(relay.get("../etc"), GoogleError); +} + +TEST(live_relay, json_never_leaks_resumption_handle) { + LiveEvent e; + e.kind = LiveEventKind::SessionResumption; + e.handle = "SECRET-HANDLE"; + e.resumable = true; + ASSERT_TRUE(event_to_json(e).dump().find("SECRET-HANDLE") == std::string::npos); +} + +// Opt-in real network checks: MOLO_LIVE_NET=1 plus credentials from the +// environment (never printed): GOOGLE_CLOUD_PROJECT and either +// GOOGLE_API_KEY (express key, x-goog-api-key) or GOOGLE_ACCESS_TOKEN (OAuth +// bearer). One handshake, one short text turn, close. Loud SKIP otherwise. +namespace { +bool live_net_enabled(const char* test, const char* credential_var) { + const char* on = std::getenv("MOLO_LIVE_NET"); + if (!on || std::string(on) != "1" || !std::getenv(credential_var) || + !std::getenv("GOOGLE_CLOUD_PROJECT")) { + std::printf(" SKIP %s: set MOLO_LIVE_NET=1, %s and GOOGLE_CLOUD_PROJECT to run against " + "the real Vertex Live endpoint\n", test, credential_var); + return false; + } + return true; +} + +void live_text_turn(const LiveEndpoint& endpoint) { + LiveConfig cfg; + cfg.output_transcription = true; + LiveSession s(endpoint, cfg); + s.connect(); + s.send_text("Say hello in one short sentence."); + auto evs = until(s, LiveEventKind::TurnComplete, 30000); + bool audio = false, transcript = false; + for (auto& e : evs) { + audio |= e.kind == LiveEventKind::Audio && !e.data.empty(); + transcript |= e.kind == LiveEventKind::OutputTranscription && !e.text.empty(); + } + s.close(); + ASSERT_TRUE(evs.back().kind == LiveEventKind::TurnComplete); + ASSERT_TRUE(audio); + ASSERT_TRUE(transcript); +} +} // namespace + +TEST(live_net, vertex_express_text_turn) { + if (!live_net_enabled("live_net.vertex_express_text_turn", "GOOGLE_API_KEY")) return; + CloudContext ctx = CloudContext::from_env(); + live_text_turn(LiveEndpoint::vertex_express(ctx, std::getenv("GOOGLE_API_KEY"))); +} + +TEST(live_net, vertex_oauth_text_turn) { + if (!live_net_enabled("live_net.vertex_oauth_text_turn", "GOOGLE_ACCESS_TOKEN")) return; + CloudContext ctx = CloudContext::from_env(); + live_text_turn(LiveEndpoint::vertex(ctx, std::getenv("GOOGLE_ACCESS_TOKEN"))); +} diff --git a/tests/src/google/live/test_ws.cpp b/tests/src/google/live/test_ws.cpp new file mode 100644 index 0000000..bea232b --- /dev/null +++ b/tests/src/google/live/test_ws.cpp @@ -0,0 +1,394 @@ +// RFC 6455 client: framing, handshake, fragmentation, ping/pong, close, +// caps, over plain TCP (loopback server) and over the ITlsSession seam. +#include + +#include + +#include "framework.h" +#include "google/live/caps.h" +#include "google/live/ws_client.h" +#include "google/live/ws_error.h" +#include "google/live/ws_stream.h" +#include "loopback.h" + +using namespace molo::google::live; +using live_test::LoopbackServer; +using live_test::ServerConn; + +namespace { + +std::unique_ptr dial(const LoopbackServer& s, const WsHeaders& h = {}) { + WsUrl url = WsUrl::parse(s.url()); + auto c = std::make_unique(open_stream(url, 2000, 2000)); + c->handshake(url, h, 2000); + c->set_read_timeout_ms(200); + return c; +} + +// Next message within ~2 s. +std::optional recv(WsClient& c) { + for (int i = 0; i < 20; ++i) + if (auto m = c.receive()) return m; + return std::nullopt; +} + +// A "TLS" session that passes bytes through, with wolfSSL's contract: +// recv_some returns 0 for both timeout and EOF. +class PassthroughTls : public molo::clients::transports::ITlsSession { + public: + void handshake(int fd, const std::string& host, bool) override { + fd_ = fd; + host_seen = host; + } + void send_all(const char* d, std::size_t n) override { + std::size_t s = 0; + while (s < n) { + ssize_t r = ::send(fd_, d + s, n - s, MSG_NOSIGNAL); + if (r <= 0) throw molo::clients::transports::TlsError("write failed"); + s += (std::size_t)r; + } + } + std::size_t recv_some(char* out, std::size_t max) override { + ssize_t r = ::recv(fd_, out, max, 0); + return r > 0 ? (std::size_t)r : 0; + } + std::string negotiated_protocol() const override { return "http/1.1"; } + void shutdown() override {} + const char* backend() const override { return "passthrough-test"; } + int fd_ = -1; + std::string host_seen; +}; + +} // namespace + +TEST(live_ws, rfc_accept_vector) { + // RFC 6455 section 1.3 example. + ASSERT_EQ(WsHandshake::accept_for("dGhlIHNhbXBsZSBub25jZQ=="), "s3pPLMBiTxaQ9kYGzzhZRbK+xOo="); + ASSERT_EQ(WsHandshake::make_key().size(), (std::size_t)24); +} + +TEST(live_ws, url_parse_and_redaction) { + WsUrl u = WsUrl::parse("wss://h.example.com/ws/x?key=SECRET"); + ASSERT_TRUE(u.secure); + ASSERT_EQ(u.port, 443); + ASSERT_EQ(u.target, "/ws/x?key=SECRET"); + ASSERT_EQ(u.display(), "wss://h.example.com:443/ws/x"); + WsUrl p = WsUrl::parse("ws://127.0.0.1:8080"); + ASSERT_EQ(p.target, "/"); + ASSERT_EQ(p.port, 8080); + for (const char* bad : {"http://x/", "ws://", "ws://u@h/", "ws://h:0/", "ws://h:99999/", + "ws://h /x", "ws://h/\r\n", "", "ws://h:x/", "ws://a b/"}) + ASSERT_THROW(WsUrl::parse(bad), WsError); + ASSERT_THROW(WsUrl::parse("ws://h/" + std::string(3000, 'a')), WsError); +} + +TEST(live_ws, frame_roundtrip_all_length_classes) { + std::uint8_t mask[4] = {1, 2, 3, 4}; + for (std::size_t n : {0u, 5u, 125u, 126u, 200u, 65535u, 65536u, 70000u}) { + std::string payload(n, 'x'); + for (std::size_t i = 0; i < n; ++i) payload[i] = (char)('a' + i % 26); + for (bool masked : {false, true}) { + FrameDecoder d(1u << 20, masked); + std::string wire = encode_frame(true, WsOpcode::Binary, payload, masked ? mask : nullptr); + // Feed byte-by-byte for the small ones to exercise incremental parsing. + if (n < 300) { + for (char c : wire) { + ASSERT_FALSE(d.next().has_value()); + d.feed(&c, 1); + } + } else { + d.feed(wire.data(), wire.size()); + } + auto f = d.next(); + ASSERT_TRUE(f.has_value()); + ASSERT_TRUE(f->fin); + ASSERT_EQ(f->opcode, (std::uint8_t)2); + ASSERT_TRUE(f->payload == payload); + } + } +} + +TEST(live_ws, decoder_rejects_violations) { + auto raw = [](std::initializer_list bytes) { + std::string s; + for (int b : bytes) s.push_back((char)b); + return s; + }; + auto feeds = [](const std::string& wire, bool expect_masked = false, std::size_t cap = 1 << 20) { + FrameDecoder d(cap, expect_masked); + d.feed(wire.data(), wire.size()); + return d.next(); + }; + ASSERT_THROW(feeds(raw({0xC1, 0x00})), WsError); // RSV1 + ASSERT_THROW(feeds(raw({0x83, 0x00})), WsError); // reserved opcode 3 + ASSERT_THROW(feeds(raw({0x81, 0x80, 0, 0, 0, 0})), WsError); // masked server frame + ASSERT_THROW(feeds(raw({0x81, 0x00}), true), WsError); // unmasked client frame + ASSERT_THROW(feeds(raw({0x09, 0x00})), WsError); // fragmented ping + ASSERT_THROW(feeds(raw({0x89, 126, 0, 126})), WsError); // ping over 125 + ASSERT_THROW(feeds(raw({0x82, 126, 0, 5})), WsError); // non-minimal 16-bit length + ASSERT_THROW(feeds(raw({0x82, 127, 0, 0, 0, 0, 0, 0, 1, 0})), WsError); // non-minimal 64-bit + ASSERT_THROW(feeds(raw({0x82, 127, 0x80, 0, 0, 0, 0, 0, 0, 0})), WsError); // high bit + // Declared length over the cap is refused before any payload arrives. + try { + feeds(raw({0x82, 127, 0, 0, 0, 0, 0, 0x20, 0, 0}), false, 1024); + FAIL("expected TooBig"); + } catch (const WsError& e) { + ASSERT_TRUE(e.kind() == WsError::Kind::TooBig); + } +} + +TEST(live_ws, utf8_validation) { + ASSERT_TRUE(valid_utf8("hello \xC3\xA9 \xE2\x82\xAC \xF0\x9F\x98\x80")); + ASSERT_FALSE(valid_utf8("\xC0\xAF")); // overlong + ASSERT_FALSE(valid_utf8("\xED\xA0\x80")); // surrogate + ASSERT_FALSE(valid_utf8("\xF4\x90\x80\x80")); // > U+10FFFF + ASSERT_FALSE(valid_utf8("\xE2\x82")); // truncated + ASSERT_FALSE(valid_utf8("\x80")); // stray continuation +} + +TEST(live_ws, handshake_masks_and_echoes) { + LoopbackServer server([](ServerConn& c) { + auto m = c.read_message(); + if (m) c.send_text("echo:" + *m); + c.send_close(1000, "bye"); + c.read_frame(); // client's close echo + }); + auto c = dial(server, {{"X-Test", "yes"}}); + c->send_text("hello"); + auto m = recv(*c); + ASSERT_TRUE(m.has_value()); + ASSERT_TRUE(m->kind == WsMessage::Kind::Text); + ASSERT_EQ(m->data, "echo:hello"); + auto close = recv(*c); + ASSERT_TRUE(close.has_value()); + ASSERT_TRUE(close->kind == WsMessage::Kind::Close); + ASSERT_EQ(close->code, (std::uint16_t)1000); + ASSERT_EQ(close->data, "bye"); + ASSERT_TRUE(c->closed()); + ASSERT_THROW(c->send_text("late"), WsError); + std::string req = server.request(); + ASSERT_TRUE(req.find("Upgrade: websocket") != std::string::npos); + ASSERT_TRUE(req.find("Sec-WebSocket-Version: 13") != std::string::npos); + ASSERT_TRUE(req.find("X-Test: yes") != std::string::npos); + ASSERT_TRUE(req.find("GET /ws HTTP/1.1") != std::string::npos); +} + +TEST(live_ws, handshake_failures_are_loud) { + { + LoopbackServer s([](ServerConn&) {}, LoopbackServer::Handshake::BadAccept); + WsUrl url = WsUrl::parse(s.url()); + WsClient c(open_stream(url, 2000, 2000)); + try { + c.handshake(url, {}, 2000); + FAIL("expected accept mismatch"); + } catch (const WsError& e) { + ASSERT_TRUE(e.kind() == WsError::Kind::Handshake); + ASSERT_TRUE(std::string(e.what()).find("Accept") != std::string::npos); + } + } + { + LoopbackServer s([](ServerConn&) {}, LoopbackServer::Handshake::Status403); + WsUrl url = WsUrl::parse(s.url()); + WsClient c(open_stream(url, 2000, 2000)); + try { + c.handshake(url, {}, 2000); + FAIL("expected 403"); + } catch (const WsError& e) { + ASSERT_EQ(e.http_status(), 403); + } + } + { + LoopbackServer s([](ServerConn&) {}, LoopbackServer::Handshake::CloseImmediately); + WsUrl url = WsUrl::parse(s.url()); + WsClient c(open_stream(url, 2000, 2000)); + ASSERT_THROW(c.handshake(url, {}, 2000), WsError); + } + // Header injection is rejected before anything is written. + LoopbackServer s([](ServerConn&) {}); + WsUrl url = WsUrl::parse(s.url()); + WsClient c(open_stream(url, 2000, 2000)); + ASSERT_THROW(c.handshake(url, {{"X-A", "v\r\nEvil: 1"}}, 2000), WsError); + // Connection refused is a WsError, not a crash. + WsUrl dead = WsUrl::parse("ws://127.0.0.1:1/"); + ASSERT_THROW(open_stream(dead, 500, 500), WsError); +} + +TEST(live_ws, fragmentation_with_interleaved_ping) { + std::string pong_payload; + std::atomic got_pong{false}; + LoopbackServer server([&](ServerConn& c) { + c.send_raw(encode_frame(false, WsOpcode::Text, "frag", nullptr)); + c.send_raw(encode_frame(true, WsOpcode::Ping, "ping-data", nullptr)); + c.send_raw(encode_frame(false, WsOpcode::Continuation, "ment", nullptr)); + c.send_raw(encode_frame(true, WsOpcode::Continuation, "ed \xC3\xA9", nullptr)); + auto f = c.read_frame(); // the pong + if (f && f->opcode == 10) { + pong_payload = f->payload; + got_pong = true; + } + c.send_binary(std::string("\x01\x02\x00\x03", 4)); + c.read_frame(); + }); + auto c = dial(server); + auto m = recv(*c); + ASSERT_TRUE(m.has_value()); + ASSERT_EQ(m->data, "fragmented \xC3\xA9"); + auto b = recv(*c); + ASSERT_TRUE(b.has_value()); + ASSERT_TRUE(b->kind == WsMessage::Kind::Binary); + ASSERT_EQ(b->data.size(), (std::size_t)4); + ASSERT_TRUE(got_pong.load()); + ASSERT_EQ(pong_payload, "ping-data"); + ASSERT_EQ(c->stats().pings_in, (std::uint64_t)1); +} + +TEST(live_ws, protocol_violations_close_with_1002_1007_1009) { + struct Case { + const char* name; + std::function script; + std::uint16_t want_code; + }; + std::vector cases = { + {"continuation without start", + [](ServerConn& c) { c.send_raw(encode_frame(true, WsOpcode::Continuation, "x", nullptr)); }, 1002}, + {"new message inside fragmented", + [](ServerConn& c) { + c.send_raw(encode_frame(false, WsOpcode::Text, "a", nullptr)); + c.send_raw(encode_frame(true, WsOpcode::Text, "b", nullptr)); + }, + 1002}, + {"invalid utf8 text", + [](ServerConn& c) { c.send_raw(encode_frame(true, WsOpcode::Text, "\xFF\xFE", nullptr)); }, 1007}, + {"frame over cap", + [](ServerConn& c) { + c.send_raw(std::string("\x82\x7f\x00\x00\x00\x00\x01\x00\x00\x00", 10)); // 16 MiB declared + }, + 1009}, + }; + for (auto& tc : cases) { + std::uint16_t got = 0; + LoopbackServer server([&](ServerConn& c) { + tc.script(c); + auto f = c.read_frame(); + if (f && f->opcode == 8 && f->payload.size() >= 2) + got = (std::uint16_t)(((std::uint8_t)f->payload[0] << 8) | (std::uint8_t)f->payload[1]); + }); + auto c = dial(server); + bool threw = false; + for (int i = 0; i < 20 && !threw; ++i) { + try { + c->receive(); + } catch (const WsError&) { + threw = true; + } + } + ASSERT_TRUE(threw); + ASSERT_TRUE(c->closed()); + c.reset(); // closes the socket so the server thread finishes + (void)tc.name; + // The server thread joins in the destructor at scope end; read after. + // (got is set before the join completes.) + std::this_thread::sleep_for(std::chrono::milliseconds(100)); + ASSERT_EQ(got, tc.want_code); + } +} + +TEST(live_ws, message_cap_across_fragments) { + LoopbackServer server([](ServerConn& c) { + std::string chunk(LiveCaps::kMaxFramePayload, 'z'); + c.send_raw(encode_frame(false, WsOpcode::Binary, chunk, nullptr)); + c.send_raw(encode_frame(false, WsOpcode::Continuation, chunk, nullptr)); + c.send_raw(encode_frame(true, WsOpcode::Continuation, chunk, nullptr)); // 12 MiB > 8 MiB + c.read_frame(); + }); + auto c = dial(server); + bool too_big = false; + for (int i = 0; i < 50 && !too_big; ++i) { + try { + c->receive(); + } catch (const WsError& e) { + too_big = e.kind() == WsError::Kind::TooBig; + } + } + ASSERT_TRUE(too_big); +} + +TEST(live_ws, abrupt_disconnect_reports_1006) { + LoopbackServer server([](ServerConn&) { /* returns: socket closed, no close frame */ }); + auto c = dial(server); + auto m = recv(*c); + ASSERT_TRUE(m.has_value()); + ASSERT_TRUE(m->kind == WsMessage::Kind::Close); + ASSERT_EQ(m->code, (std::uint16_t)1006); +} + +TEST(live_ws, outbound_caps_and_ping_validation) { + LoopbackServer server([](ServerConn& c) { c.read_frame(); }); + auto c = dial(server); + ASSERT_THROW(c->send_text(std::string(LiveCaps::kMaxOutboundMessage + 1, 'a')), WsError); + ASSERT_THROW(c->send_ping(std::string(126, 'p')), WsError); + c->send_ping("ok"); +} + +TEST(live_ws, close_is_sent_once) { + int closes = 0; + LoopbackServer server([&](ServerConn& c) { + while (auto f = c.read_frame()) { + if (f->opcode == 8) ++closes; + } + }); + auto c = dial(server); + c->close(1000, "one"); + c->close(1000, "two"); + c->shutdown(); + c.reset(); + std::this_thread::sleep_for(std::chrono::milliseconds(150)); + ASSERT_EQ(closes, 1); +} + +TEST(live_ws, tls_seam_carries_websocket) { + LoopbackServer server([](ServerConn& c) { + auto m = c.read_message(); + c.send_text(m ? "tls:" + *m : "none"); + c.send_close(1000); + c.read_frame(); + }); + // The wss scheme routes through the injected ITlsSession; the server is + // plain TCP, so the passthrough fake stands in for wolfSSL's contract. + std::string url = "wss://127.0.0.1:" + std::to_string(server.port()) + "/ws"; + WsUrl u = WsUrl::parse(url); + std::shared_ptr tls; + WsClient c(open_stream(u, 2000, 2000, [&] { + tls = std::make_shared(); + return tls; + })); + ASSERT_EQ(tls->host_seen, "127.0.0.1"); + c.handshake(u, {}, 2000); + c.set_read_timeout_ms(200); + c.send_text("ping"); + auto m = recv(c); + ASSERT_TRUE(m.has_value()); + ASSERT_EQ(m->data, "tls:ping"); + auto close = recv(c); + ASSERT_TRUE(close.has_value()); + ASSERT_TRUE(close->kind == WsMessage::Kind::Close); +} + +TEST(live_ws, tls_read_distinguishes_timeout_from_eof) { + LoopbackServer server([](ServerConn& c) { + // Stay silent for a while, then drop the connection. + std::this_thread::sleep_for(std::chrono::milliseconds(700)); + (void)c; + }); + WsUrl u = WsUrl::parse("wss://127.0.0.1:" + std::to_string(server.port()) + "/ws"); + WsClient c(open_stream(u, 2000, 2000, [] { return std::make_shared(); })); + c.handshake(u, {}, 2000); + c.set_read_timeout_ms(200); + auto t0 = std::chrono::steady_clock::now(); + auto first = c.receive(); // silence: timeout, not close + ASSERT_FALSE(first.has_value()); + ASSERT_TRUE(std::chrono::steady_clock::now() - t0 >= std::chrono::milliseconds(100)); + auto m = recv(c); // then EOF: abnormal close + ASSERT_TRUE(m.has_value()); + ASSERT_EQ(m->code, (std::uint16_t)1006); +}