Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(graphql): compress subscription WebSocket frames (#7997)
Sean Ayec2be6149dc42
diff --git a/Cargo.lock b/Cargo.lockindex fff26b46a2..ca4939bb51 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -6279,6 +6279,7 @@ dependencies = ["entity_registry","entity_registry_db_utils","favorites",+ "flate2","foreign_entity","forms","frecency",@@ -6293,6 +6294,8 @@ dependencies = ["harnesses","hex","http-body-util",+ "hyper 1.9.0",+ "hyper-util","import","initiative","initiative_description",@@ -6372,10 +6375,12 @@ dependencies = ["teams","thiserror 2.0.18","tokio",+ "tokio-tungstenite 0.27.0","tokio-util","tower 0.5.3","tower-http","tracing",+ "tungstenite 0.27.0","unicode-segmentation","urlencoding","user_api_key",@@ -7816,6 +7821,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"dependencies = ["crc32fast",+ "libz-sys","miniz_oxide","zlib-rs",]@@ -19490,6 +19496,18 @@ dependencies = ["tokio-stream",]+[[package]]+name = "tokio-tungstenite"+version = "0.27.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "489a59b6730eda1b0171fcfda8b121f4bee2b35cba8645ca35c5f7ba3eb736c1"+dependencies = [+ "futures-util",+ "log",+ "tokio",+ "tungstenite 0.27.0",+]+[[package]]name = "tokio-tungstenite"version = "0.28.0"@@ -19934,6 +19952,24 @@ dependencies = ["unicode-width 0.2.0",]+[[package]]+name = "tungstenite"+version = "0.27.0"+source = "git+https://github.com/signalapp/tungstenite-rs?rev=a1837ccfe96b6895a57352d7f0112e4557516c27#a1837ccfe96b6895a57352d7f0112e4557516c27"+dependencies = [+ "bytes",+ "data-encoding",+ "flate2",+ "headers",+ "http 1.4.0",+ "httparse",+ "log",+ "rand 0.9.4",+ "sha1 0.10.6",+ "thiserror 2.0.18",+ "utf-8",+]+[[package]]name = "tungstenite"version = "0.28.0"@@ -21803,6 +21839,7 @@ dependencies = ["itertools 0.13.0","lazy_static","libc",+ "libz-sys","linux-raw-sys 0.12.1","log","memchr",diff --git a/Cargo.toml b/Cargo.tomlindex 5bd6f1aa6e..288b4df39a 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -256,6 +256,8 @@ http = "1"http-body = "1.0.1"http-body-util = "0.1.2"httpdate = "1"+hyper = "1"+hyper-util = { version = "0.1", features = ["tokio"] }image = "0.25"image-webp = "0.2"indexmap = "2"@@ -377,6 +379,10 @@ tokio-tungstenite = { version = "0.28", default-features = false, features = ["connect","rustls-tls-webpki-roots",] }+# Signal's compression fork is based on tungstenite 0.27. Keep its Tokio+# adapter separate from the upstream sockets used elsewhere in the workspace.+tokio-tungstenite-signal = { package = "tokio-tungstenite", version = "0.27", default-features = false, features = ["handshake"] }+tungstenite-signal = { package = "tungstenite", version = "0.27", default-features = false, features = ["handshake", "deflate"] }tokio-util = "0.7.13"tower = { version = "0.5.1", features = ["util"] }tower-http = { version = "0.6.1", features = [@@ -444,6 +450,10 @@ ammonia = "4.1.7"html-escape = "0.2"subtle = "2.6.1"+[patch.crates-io]+# Only replaces tungstenite 0.27 (GraphQL subscriptions); 0.28/0.29 stay upstream.+tungstenite = { git = "https://github.com/signalapp/tungstenite-rs", rev = "a1837ccfe96b6895a57352d7f0112e4557516c27" }+# cache-turso's storage tests load thousands of rows into the embedded SQL engine# to assert VM step budgets. Unoptimized, the engine made them the slowest tests# in the Rust suite (34 s for the crate); at opt-level 2 the crate's tests takediff --git a/crates/agent_preview/Cargo.toml b/crates/agent_preview/Cargo.tomlindex a91afa6d97..9622cc6756 100644--- a/crates/agent_preview/Cargo.toml+++ b/crates/agent_preview/Cargo.toml@@ -17,8 +17,8 @@ entity_access = { path = "../entity_access", default-features = false, featuresmacro_authorization = { path = "../macro_authorization", default-features = false, features = ["axum"] }macro_user_id = { path = "../macro_user_id" }http-body-util = { workspace = true }-hyper = { version = "1", features = ["client", "http1"] }-hyper-util = { version = "0.1", features = ["tokio"] }+hyper = { workspace = true, features = ["client", "http1"] }+hyper-util = { workspace = true }rand = { workspace = true }rootcause = { workspace = true }russh = { version = "0.63.3", default-features = false, features = ["ring"] }diff --git a/crates/workspace-hack/Cargo.toml b/crates/workspace-hack/Cargo.tomlindex 4b86569ab1..a22487cbce 100644--- a/crates/workspace-hack/Cargo.toml+++ b/crates/workspace-hack/Cargo.toml@@ -58,7 +58,7 @@ either = { version = "1", features = ["serde", "use_std"] }elliptic-curve = { version = "0.13", default-features = false, features = ["ecdh", "hazmat", "pem", "std"] }event-listener = { version = "5" }fastrand = { version = "2" }-flate2 = { version = "1", features = ["zlib-rs"] }+flate2 = { version = "1", features = ["zlib", "zlib-rs"] }foldhash = { version = "0.2" }form_urlencoded = { version = "1" }futures-channel = { version = "0.3", features = ["sink"] }@@ -89,6 +89,7 @@ itertools-594e8ee84c453af0 = { package = "itertools", version = "0.13" }itertools-5ef9efb8ec2df382 = { package = "itertools", version = "0.12" }lazy_static = { version = "1", default-features = false, features = ["spin_no_std"] }libc = { version = "0.2", features = ["extra_traits"] }+libz-sys = { version = "1", features = ["static"] }log = { version = "0.4", default-features = false, features = ["std"] }memchr = { version = "2" }mime_guess = { version = "2" }@@ -211,7 +212,7 @@ either = { version = "1", features = ["serde", "use_std"] }elliptic-curve = { version = "0.13", default-features = false, features = ["ecdh", "hazmat", "pem", "std"] }event-listener = { version = "5" }fastrand = { version = "2" }-flate2 = { version = "1", features = ["zlib-rs"] }+flate2 = { version = "1", features = ["zlib", "zlib-rs"] }foldhash = { version = "0.2" }form_urlencoded = { version = "1" }futures-channel = { version = "0.3", features = ["sink"] }@@ -242,6 +243,7 @@ itertools-594e8ee84c453af0 = { package = "itertools", version = "0.13" }itertools-5ef9efb8ec2df382 = { package = "itertools", version = "0.12" }lazy_static = { version = "1", default-features = false, features = ["spin_no_std"] }libc = { version = "0.2", features = ["extra_traits"] }+libz-sys = { version = "1", features = ["static"] }log = { version = "0.4", default-features = false, features = ["std"] }memchr = { version = "2" }mime_guess = { version = "2" }diff --git a/docs/AGENT_GUIDE/browser-technique.md b/docs/AGENT_GUIDE/browser-technique.mdindex e843fd0c3a..d305851fd4 100644--- a/docs/AGENT_GUIDE/browser-technique.md+++ b/docs/AGENT_GUIDE/browser-technique.md@@ -62,6 +62,19 @@- Every backend request carries a `traceparent` header and returns `x-request-id` — grab themfrom `get_network_request` for backend correlation (see observability.md).+## GraphQL subscription compression++- For `/soup/graphql/ws`, check the **response** handshake header+ `Sec-WebSocket-Extensions` for `permessage-deflate`. The browser's request+ offering it is not proof the server accepted it. On a native `WebSocket`+ object, `socket.extensions` reports the negotiated extension after `open`.+- Both `graphql-transport-ws` and legacy `graphql-ws` support compression. The+ browser decompresses messages before delivering `message` events; keep using+ normal JSON parsing. DevTools' decoded message payloads do not show wire savings.+- No extension in the response means an uncompressed fallback, not a failed+ subscription. This change is specific to GraphQL; don't expect the connection+ gateway or agent sockets to negotiate compression.+## Hygiene- Work in the user-visible tab (no isolated contexts) when a human is watching via VNC.diff --git a/nix-support/root-cargo-output-hashes.nix b/nix-support/root-cargo-output-hashes.nixindex cf35d8a39f..8a10f609ab 100644--- a/nix-support/root-cargo-output-hashes.nix+++ b/nix-support/root-cargo-output-hashes.nix@@ -1,4 +1,6 @@{+ "git+https://github.com/signalapp/tungstenite-rs?rev=a1837ccfe96b6895a57352d7f0112e4557516c27#a1837ccfe96b6895a57352d7f0112e4557516c27" =+ "sha256-yGGTDdIpvW+skch46bHAa201WolofJC5KKwCcPfDTVs=";"git+https://github.com/tursodatabase/turso?rev=79163249538197d01dec5ea7f65519454ed792e2#79163249538197d01dec5ea7f65519454ed792e2" ="sha256-7Noz7RMN+4nhlU5BBLzxZZ53nNFGewrr8BFMO1adkCo=";"git+https://github.com/whutchinson98/jsonwebtoken#c8c0d19511a0e7ba9d456e21437a79d321e99f16" =diff --git a/services/document_storage_service/Cargo.toml b/services/document_storage_service/Cargo.tomlindex 30e5ff318a..e0a9228845 100644--- a/services/document_storage_service/Cargo.toml+++ b/services/document_storage_service/Cargo.toml@@ -151,6 +151,8 @@ graphql_scheduled_action = { path = "../../crates/graphql_scheduled_action" }harnesses = { path = "../../crates/harnesses" }hex = { workspace = true }http-body-util = { workspace = true }+hyper = { workspace = true }+hyper-util = { workspace = true }import = { path = "../../crates/import" }initiative = { path = "../../crates/initiative", features = ["inbound", "postgres", "resources"] }jsonwebtoken = { workspace = true }@@ -261,6 +263,8 @@ task_dedup = { path = "../../crates/task_dedup" }thiserror = { workspace = true }tokio = { workspace = true, features = ["signal"] }tokio-util = { workspace = true, features = ["rt"] }+tokio-tungstenite-signal = { workspace = true }+tungstenite-signal = { workspace = true }tower = { workspace = true }tower-http = { workspace = true, features = ["compression-gzip"] }tracing = { workspace = true }@@ -284,6 +288,7 @@ zip = { workspace = true }[dev-dependencies]cool_asserts = "2"+flate2 = "1"frecency = { path = "../../crates/frecency", features = ["mock"] }macro_auth = { path = "../../crates/macro_auth", features = ["testing"] }ordered-float = { workspace = true }diff --git a/services/document_storage_service/README.md b/services/document_storage_service/README.mdindex 32190a759f..ba7953f46e 100644--- a/services/document_storage_service/README.md+++ b/services/document_storage_service/README.md@@ -4,6 +4,59 @@You can use the **/docs** endpoint for a full swagger.+## GraphQL subscription compression++`GET /soup/graphql/ws` negotiates browser-native `permessage-deflate` for both+`graphql-transport-ws` and `graphql-ws`. Authentication and subscription context+are unchanged. Clients that omit compression or offer unsupported parameters+continue with uncompressed messages; no frontend decompressor is needed.++The transport in `src/api/graphql_soup/websocket.rs` uses Signal's tungstenite+fork pinned in the root `Cargo.toml`. The fork is based on 0.27, so it uses a+separate `tokio-tungstenite-signal` dependency (upstream Tokio adapter 0.27).+Other WebSocket endpoints retain their existing upstream dependencies.++Signal does not expose its handshake extension negotiation helpers publicly.+The Hyper adapter accepts known, unquoted RFC 7692 parameters with 9–15-bit+windows; quoted or unsupported offers fall back to uncompressed transport.+Both directions disable context takeover between messages. Existing default+frame/message size limits remain in place, including decompressed message limits.+The fork's `deflate` feature requires a zlib-compatible flate2 backend.++Transport regression tests (including wire-level compression and fallback):++```sh+cargo test -p document_storage_service --lib api::graphql_soup::websocket::test+```++### Measure payload savings locally++```sh+cargo test -p document_storage_service --lib measure_subscription_payload_sizes -- --nocapture+```++This starts a loopback Axum server using the production upgrade adapter and+subscribes twice to identical synthetic snapshots, with and without deflate.+The raw TCP reader counts actual WebSocket payload and frame bytes, checks RSV1,+and independently decompresses each message to verify identical JSON. No+recompression estimate, production data, or per-message production logging is+involved. The fixture is+`src/api/graphql_soup/websocket/measurement-entity.json`.++With the pinned dependencies, the local measurement is:++| Message | Plain payload | Deflate payload | Payload saved |+| --- | ---: | ---: | ---: |+| Connection acknowledgement | 25 B | 27 B | -8.00% |+| Synthetic 1-entity snapshot | 632 B | 360 B | 43.04% |+| Synthetic 25-entity snapshot | 13,120 B | 632 B | 95.18% |+| Synthetic 100-entity snapshot | 52,171 B | 1,349 B | 97.41% |+| Subscription completion | 34 B | 35 B | -2.94% |++These are controlled, repetitive fixtures, **not production traffic statistics**.+Small messages can grow. CSV `*_frame_bytes` columns also count the WebSocket+header; HTTP handshake, TCP/IP, and TLS overhead are excluded.+## PrerequisitesInstall and setup **Rust** ecosystem on your machine.diff --git a/services/document_storage_service/src/api/graphql_soup.rs b/services/document_storage_service/src/api/graphql_soup.rsindex 61848fa100..fe9acd23e7 100644--- a/services/document_storage_service/src/api/graphql_soup.rs+++ b/services/document_storage_service/src/api/graphql_soup.rs@@ -1,14 +1,11 @@use crate::api::context::{ApiContext, AuthorizationService};use crate::api::folders_query::DssFoldersQueryReader;use agent_session::outbound::postgres::PgAgentSessionRepo;-use async_graphql::{- Data,- http::{ALL_WEBSOCKET_PROTOCOLS, GraphiQLSource},-};-use async_graphql_axum::{GraphQLProtocol, GraphQLRequest, GraphQLResponse, GraphQLWebSocket};+use async_graphql::{Data, http::GraphiQLSource};+use async_graphql_axum::{GraphQLRequest, GraphQLResponse};use axum::{Router,- extract::{OriginalUri, State, WebSocketUpgrade},+ extract::{OriginalUri, State},http::{StatusCode, request::Parts},response::{Html, IntoResponse, Response},routing::get,@@ -24,6 +21,10 @@ use macro_authorization::{};use macro_user_id::user_id::MacroUserIdStr;+mod websocket;++use websocket::GraphqlWebSocketUpgrade;+const GRAPHQL_PATH: &str = "/soup/graphql";const GRAPHQL_SUBSCRIPTION_PATH: &str = "/soup/graphql/ws";@@ -76,8 +77,7 @@ async fn subscription_handler(Cached(auth): Cached<OptionalMacroAuthorizationExtractor<AuthorizationService, UserOrInternalService>,>,- protocol: GraphQLProtocol,- upgrade: WebSocketUpgrade,+ upgrade: GraphqlWebSocketUpgrade,) -> Response {let Some(acting_user) = auth.authorization@@ -95,15 +95,7 @@ async fn subscription_handler(let schema = state.graphql_soup_schema.clone();let data = graphql_subscription_context_data(&state, macro_user_id, organization_id);- upgrade- .protocols(ALL_WEBSOCKET_PROTOCOLS)- .on_upgrade(move |socket| async move {- GraphQLWebSocket::new(socket, schema, protocol)- .with_data(data)- .serve()- .await;- })- .into_response()+ upgrade.serve(schema, data)}fn graphql_subscription_context_data(diff --git a/services/document_storage_service/src/api/graphql_soup/websocket.rs b/services/document_storage_service/src/api/graphql_soup/websocket.rsnew file mode 100644index 0000000000..9f6c1618bc--- /dev/null+++ b/services/document_storage_service/src/api/graphql_soup/websocket.rs@@ -0,0 +1,214 @@+//! GraphQL-only WebSocket transport using Signal's compression-capable fork.++use async_graphql::{+ Data, Executor,+ http::{WebSocket, WebSocketProtocols, WsMessage},+};+use axum::{+ body::Body,+ extract::FromRequestParts,+ http::{HeaderMap, HeaderValue, StatusCode, header, request::Parts},+ response::{IntoResponse, Response},+};+use futures::{SinkExt, StreamExt, future};+use hyper::upgrade::{OnUpgrade, Upgraded};+use hyper_util::rt::TokioIo;+use tokio_tungstenite_signal::WebSocketStream;+use tungstenite_signal::{+ Message,+ extensions::compression::deflate::DeflateConfig,+ handshake::server::{Request, create_response},+ protocol::{CloseFrame, Role, WebSocketConfig},+};++#[cfg(test)]+mod test;++// Preserve the previous Axum receive limits without relying on fork defaults.+// The message limit also applies to decompressed input.+const MAX_GRAPHQL_MESSAGE_BYTES: usize = 64 << 20;+const MAX_GRAPHQL_FRAME_BYTES: usize = 16 << 20;++/// An authenticated handler must call `serve` to complete the upgrade.+/// Merely extracting this value never starts a socket or executes GraphQL.+pub(super) struct GraphqlWebSocketUpgrade {+ response: Response,+ on_upgrade: OnUpgrade,+ protocol: WebSocketProtocols,+ config: WebSocketConfig,+}++impl<S: Send + Sync> FromRequestParts<S> for GraphqlWebSocketUpgrade {+ type Rejection = Response;++ async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {+ let protocol: WebSocketProtocols = parts+ .headers+ .get(header::SEC_WEBSOCKET_PROTOCOL)+ .and_then(|value| value.to_str().ok())+ .and_then(|value| value.split(',').find_map(|p| p.trim().parse().ok()))+ .ok_or_else(|| StatusCode::BAD_REQUEST.into_response())?;++ // Use tungstenite's RFC 6455 handshake validation, including the method,+ // version, upgrade headers and accept key. This route uses HTTP/1.1 GET.+ let mut request = Request::new(());+ *request.method_mut() = parts.method.clone();+ *request.version_mut() = parts.version;+ *request.headers_mut() = parts.headers.clone();+ let mut response = create_response(&request)+ .map_err(|_| StatusCode::BAD_REQUEST.into_response())?+ .map(|()| Body::empty());+ response.headers_mut().insert(+ header::SEC_WEBSOCKET_PROTOCOL,+ HeaderValue::from_static(protocol.sec_websocket_protocol()),+ );++ let mut config = WebSocketConfig::default()+ .max_message_size(Some(MAX_GRAPHQL_MESSAGE_BYTES))+ .max_frame_size(Some(MAX_GRAPHQL_FRAME_BYTES));+ if let Some((deflate, agreed)) = negotiate_compression(&parts.headers) {+ config.extensions.permessage_deflate = Some(deflate);+ response+ .headers_mut()+ .insert(header::SEC_WEBSOCKET_EXTENSIONS, agreed);+ }+ let on_upgrade = parts+ .extensions+ .remove::<OnUpgrade>()+ .ok_or_else(|| StatusCode::UPGRADE_REQUIRED.into_response())?;++ Ok(Self {+ response,+ on_upgrade,+ protocol,+ config,+ })+ }+}++impl GraphqlWebSocketUpgrade {+ /// Start the subscription transport with the handler's authorized context.+ pub(super) fn serve(self, executor: impl Executor, data: Data) -> Response {+ tokio::spawn(async move {+ let upgraded = match self.on_upgrade.await {+ Ok(upgraded) => upgraded,+ Err(error) => {+ tracing::debug!(error = ?error, "GraphQL WebSocket upgrade failed");+ return;+ }+ };+ // Only the negotiated parameters are enabled on the raw socket;+ // clients that did not offer compression retain the default config.+ let socket = WebSocketStream::from_raw_socket(+ TokioIo::new(upgraded),+ Role::Server,+ Some(self.config),+ )+ .await;+ serve(socket, executor, data, self.protocol).await;+ });+ self.response+ }+}++async fn serve(+ socket: WebSocketStream<TokioIo<Upgraded>>,+ executor: impl Executor,+ data: Data,+ protocol: WebSocketProtocols,+) {+ let (mut sink, stream) = socket.split();+ // Match async-graphql-axum's transport behavior, without converting message+ // payloads through Axum's separate, uncompressed tungstenite dependency.+ let input = stream+ .take_while(|result| future::ready(result.is_ok()))+ .filter_map(|result| {+ future::ready(match result {+ Ok(message @ (Message::Text(_) | Message::Binary(_))) => Some(message.into_data()),+ _ => None,+ })+ });+ let output = WebSocket::new(executor, input, protocol).connection_data(data);+ futures::pin_mut!(output);+ while let Some(message) = output.next().await {+ let message = match message {+ WsMessage::Text(text) => Message::Text(text.into()),+ WsMessage::Close(code, reason) => Message::Close(Some(CloseFrame {+ code: code.into(),+ reason: reason.into(),+ })),+ };+ if sink.send(message).await.is_err() {+ break;+ }+ }+}++/// Signal's handshake negotiation helpers are private. For Hyper upgrades,+/// conservatively accept known, unquoted RFC 7692 parameters and decline other+/// offers. Declining compression still permits an ordinary WebSocket connection.+fn negotiate_compression(headers: &HeaderMap) -> Option<(DeflateConfig, HeaderValue)> {+ headers+ .get_all(header::SEC_WEBSOCKET_EXTENSIONS)+ .iter()+ .filter_map(|value| value.to_str().ok())+ // Do not split inside a quoted extension parameter. Browsers' standard+ // offers are unquoted; quoted offers can safely fall back to no deflate.+ .filter(|value| !value.contains('"'))+ .flat_map(|value| value.split(','))+ .find_map(accept_deflate_offer)+}++fn accept_deflate_offer(offer: &str) -> Option<(DeflateConfig, HeaderValue)> {+ let mut parameters = offer.split(';').map(str::trim);+ if parameters.next()? != "permessage-deflate" {+ return None;+ }++ // Do not share compression dictionaries between GraphQL messages. Besides+ // bounding retained state, this avoids cross-message compression side channels.+ let mut config = DeflateConfig::default()+ .set_no_context_takeover(Role::Server, true)+ .set_no_context_takeover(Role::Client, true);+ let mut seen = [false; 4];+ let mut response =+ String::from("permessage-deflate; server_no_context_takeover; client_no_context_takeover");+ for parameter in parameters {+ let (name, value) = parameter+ .split_once('=')+ .map_or((parameter, None), |(name, value)| {+ (name.trim(), Some(value.trim()))+ });+ let index = match name {+ "server_no_context_takeover" if value.is_none() => 0,+ "client_no_context_takeover" if value.is_none() => 1,+ "server_max_window_bits" | "client_max_window_bits" => {+ let role = if name == "server_max_window_bits" {+ Role::Server+ } else {+ Role::Client+ };+ let bits = match (role, value) {+ (Role::Client, None) => 15,+ (_, Some("9")) => 9,+ (_, Some("10")) => 10,+ (_, Some("11")) => 11,+ (_, Some("12")) => 12,+ (_, Some("13")) => 13,+ (_, Some("14")) => 14,+ (_, Some("15")) => 15,+ _ => return None,+ };+ // The fork's zlib backend cannot send with an 8-bit window.+ config = config.set_max_window_bits(role, bits).ok()?;+ response.push_str(&format!("; {name}={bits}"));+ if role == Role::Server { 2 } else { 3 }+ }+ _ => return None,+ };+ if std::mem::replace(&mut seen[index], true) {+ return None;+ }+ }+ Some((config, HeaderValue::from_str(&response).ok()?))+}diff --git a/services/document_storage_service/src/api/graphql_soup/websocket/handshake.txt b/services/document_storage_service/src/api/graphql_soup/websocket/handshake.txtnew file mode 100644index 0000000000..8986f76cb5--- /dev/null+++ b/services/document_storage_service/src/api/graphql_soup/websocket/handshake.txt@@ -0,0 +1,7 @@+GET /soup/graphql/ws HTTP/1.1+Host: {address}+Connection: Upgrade+Upgrade: websocket+Sec-WebSocket-Version: 13+Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==+Sec-WebSocket-Protocol: {protocol}diff --git a/services/document_storage_service/src/api/graphql_soup/websocket/measurement-entity.json b/services/document_storage_service/src/api/graphql_soup/websocket/measurement-entity.jsonnew file mode 100644index 0000000000..124ab74d2e--- /dev/null+++ b/services/document_storage_service/src/api/graphql_soup/websocket/measurement-entity.json@@ -0,0 +1,17 @@+{+ "__typename": "Document",+ "id": "018c8d80-0000-7000-8000-000000000000",+ "name": "Synthetic planning document",+ "fileType": "md",+ "createdAt": "2026-10-01T09:00:00Z",+ "updatedAt": "2026-10-13T12:00:00Z",+ "projectId": "018c8d80-0000-7000-8000-000000000100",+ "ownerId": "macro|[email protected]",+ "isDeleted": false,+ "isUnread": true,+ "preview": "Review the planned work, record the next steps, and share the updated document with the team.",+ "properties": [+ { "name": "Status", "value": "In progress" },+ { "name": "Priority", "value": "Medium" }+ ]+}diff --git a/services/document_storage_service/src/api/graphql_soup/websocket/test.rs b/services/document_storage_service/src/api/graphql_soup/websocket/test.rsnew file mode 100644index 0000000000..06a20b6bf5--- /dev/null+++ b/services/document_storage_service/src/api/graphql_soup/websocket/test.rs@@ -0,0 +1,511 @@+use super::*;+use async_graphql::{Context, EmptyMutation, Json, Object, Schema, Subscription};+use axum::{Router, routing::get};+use flate2::{Compress, Compression, Decompress, FlushCompress, FlushDecompress};+use futures::Stream;+use serde_json::{Value, json};+use std::{net::SocketAddr, time::Duration};+use tokio::{+ io::{AsyncReadExt, AsyncWrite, AsyncWriteExt},+ net::{TcpListener, TcpStream},+ task::JoinHandle,+ time::timeout,+};+use tungstenite_signal::client::IntoClientRequest;++const MAX_TEST_MESSAGE_BYTES: usize = 256 * 1024;++struct Query;++#[Object]+impl Query {+ async fn ready(&self) -> bool {+ true+ }+}++struct Subscriptions;++#[Subscription]+impl Subscriptions {+ async fn viewer(&self, context: &Context<'_>) -> impl Stream<Item = String> {+ let viewer = context.data_unchecked::<String>().clone();+ futures::stream::iter([viewer.clone(), viewer])+ }++ async fn snapshots(&self, context: &Context<'_>) -> impl Stream<Item = Json<Value>> {+ futures::stream::iter(+ context+ .data_unchecked::<Vec<Value>>()+ .clone()+ .into_iter()+ .map(Json),+ )+ }+}++struct TestServer {+ address: SocketAddr,+ task: JoinHandle<()>,+}++impl Drop for TestServer {+ fn drop(&mut self) {+ self.task.abort();+ }+}++async fn start_server() -> TestServer {+ start_server_with_payloads(Vec::new()).await+}++async fn start_server_with_payloads(payloads: Vec<Value>) -> TestServer {+ let app = Router::new().route(+ "/soup/graphql/ws",+ get(+ move |headers: HeaderMap, upgrade: GraphqlWebSocketUpgrade| {+ let payloads = payloads.clone();+ async move {+ // Mirror the production handler's requirement: extraction must not+ // upgrade the connection until the handler supplies authorized data.+ if headers.get(header::AUTHORIZATION).is_none() {+ return StatusCode::UNAUTHORIZED.into_response();+ }+ let schema = Schema::build(Query, EmptyMutation, Subscriptions).finish();+ let mut data = Data::default();+ data.insert(String::from("authorized-viewer"));+ data.insert(payloads);+ upgrade.serve(schema, data)+ }+ },+ ),+ );+ let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();+ let address = listener.local_addr().unwrap();+ let task = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });+ TestServer { address, task }+}++async fn handshake(+ address: SocketAddr,+ protocol: &str,+ extensions: Option<&str>,+ authorized: bool,+) -> (TcpStream, String) {+ let mut socket = TcpStream::connect(address).await.unwrap();+ let mut request = format!(+ include_str!("handshake.txt"),+ address = address,+ protocol = protocol+ )+ .replace('\n', "\r\n");+ if authorized {+ request.push_str("Authorization: test\r\n");+ }+ if let Some(extensions) = extensions {+ request.push_str(&format!("Sec-WebSocket-Extensions: {extensions}\r\n"));+ }+ request.push_str("\r\n");+ socket.write_all(request.as_bytes()).await.unwrap();+ let mut response = Vec::new();+ while !response.ends_with(b"\r\n\r\n") {+ response.push(socket.read_u8().await.unwrap());+ assert!(response.len() < 8192);+ }+ (+ socket,+ String::from_utf8(response).unwrap().to_ascii_lowercase(),+ )+}++// Use independent flate2 framing rather than the Signal client: assert RSV1+// and actual raw DEFLATE payloads on the wire, not just handshake advertising.+async fn send_json(socket: &mut (impl AsyncWrite + Unpin), message: Value, compressed: bool) {+ let payload = serde_json::to_vec(&message).unwrap();+ let payload = if compressed {+ let mut output = Vec::with_capacity(payload.len() + 128);+ Compress::new(Compression::fast(), false)+ .compress_vec(&payload, &mut output, FlushCompress::Sync)+ .unwrap();+ assert!(output.ends_with(&[0, 0, 255, 255]));+ output.truncate(output.len() - 4);+ output+ } else {+ payload+ };+ socket+ .write_u8(if compressed { 0xc1 } else { 0x81 })+ .await+ .unwrap();+ if payload.len() < 126 {+ socket.write_u8(0x80 | payload.len() as u8).await.unwrap();+ } else {+ socket.write_u8(0x80 | 126).await.unwrap();+ socket+ .write_u16(payload.len().try_into().unwrap())+ .await+ .unwrap();+ }+ let mask = [1, 2, 3, 4];+ socket.write_all(&mask).await.unwrap();+ let masked: Vec<_> = payload+ .iter()+ .enumerate()+ .map(|(index, byte)| byte ^ mask[index % 4])+ .collect();+ socket.write_all(&masked).await.unwrap();+}++struct MeasuredMessage {+ json: Value,+ payload_bytes: usize,+ frame_bytes: usize,+ decoded_bytes: usize,+}++async fn read_json(socket: &mut TcpStream, compressed: bool) -> Value {+ read_measured_message(socket, compressed).await.json+}++async fn read_measured_message(socket: &mut TcpStream, compressed: bool) -> MeasuredMessage {+ timeout(Duration::from_secs(5), async {+ let header = socket.read_u8().await.unwrap();+ assert_eq!(header, if compressed { 0xc1 } else { 0x81 });+ let length = socket.read_u8().await.unwrap();+ assert_eq!(length & 0x80, 0, "server frames must not be masked");+ let (length, header_bytes) = match length {+ 126 => (usize::from(socket.read_u16().await.unwrap()), 4),+ 127 => (socket.read_u64().await.unwrap().try_into().unwrap(), 10),+ length => (usize::from(length), 2),+ };+ assert!(length < MAX_TEST_MESSAGE_BYTES);+ let mut payload = vec![0; length];+ socket.read_exact(&mut payload).await.unwrap();+ if compressed {+ payload.extend_from_slice(&[0, 0, 255, 255]);+ let mut output = Vec::with_capacity(MAX_TEST_MESSAGE_BYTES);+ let mut decoder = Decompress::new(false);+ decoder+ .decompress_vec(&payload, &mut output, FlushDecompress::Sync)+ .unwrap();+ assert_eq!(decoder.total_in(), payload.len() as u64);+ payload = output;+ }+ MeasuredMessage {+ json: serde_json::from_slice(&payload).unwrap(),+ payload_bytes: length,+ frame_bytes: header_bytes + length,+ decoded_bytes: payload.len(),+ }+ })+ .await+ .expect("GraphQL response timed out")+}++async fn subscription_roundtrip(protocol: &str, offer: Option<&str>, compressed: bool) {+ let server = start_server().await;+ let (mut socket, response) = handshake(server.address, protocol, offer, true).await;+ assert!(response.starts_with("http/1.1 101"), "{response}");+ assert!(response.contains(&format!("sec-websocket-protocol: {protocol}\r\n")));+ assert_eq!(response.contains("sec-websocket-extensions:"), compressed);+ if compressed {+ assert!(response.contains("server_no_context_takeover"));+ assert!(response.contains("client_no_context_takeover"));+ }+ send_json(&mut socket, json!({"type": "connection_init"}), compressed).await;+ assert_eq!(+ read_json(&mut socket, compressed).await["type"],+ "connection_ack"+ );++ let modern = protocol == "graphql-transport-ws";+ send_json(+ &mut socket,+ json!({+ "id": "1",+ "type": if modern { "subscribe" } else { "start" },+ "payload": {"query": "subscription { viewer }"}+ }),+ compressed,+ )+ .await;+ // Both messages must decode with a fresh dictionary (no context takeover).+ for _ in 0..2 {+ let message = read_json(&mut socket, compressed).await;+ assert_eq!(message["id"], "1");+ assert_eq!(message["type"], if modern { "next" } else { "data" });+ assert_eq!(message["payload"]["data"]["viewer"], "authorized-viewer");+ }+ assert_eq!(read_json(&mut socket, compressed).await["type"], "complete");+ if modern {+ // Application-level ping/pong remains handled by async-graphql.+ send_json(&mut socket, json!({"type": "ping"}), compressed).await;+ assert_eq!(read_json(&mut socket, compressed).await["type"], "pong");+ }+}++fn measurement_snapshot(entity_count: usize) -> Value {+ let template: Value = serde_json::from_str(include_str!("measurement-entity.json")).unwrap();+ let entities: Vec<_> = (0..entity_count)+ .map(|index| {+ let mut entity = template.clone();+ entity["id"] = json!(format!("018c8d80-0000-7000-8000-{index:012x}"));+ entity["name"] = json!(format!("Planning document {index}"));+ entity["isUnread"] = json!(index % 3 == 0);+ entity+ })+ .collect();+ json!({"entities": entities, "totalCount": entity_count, "hasNextPage": false})+}++async fn measure_snapshot_connection(+ address: SocketAddr,+ compressed: bool,+ snapshot_count: usize,+) -> Vec<MeasuredMessage> {+ let offer = compressed.then_some("permessage-deflate; client_max_window_bits");+ let (mut socket, response) = handshake(address, "graphql-transport-ws", offer, true).await;+ assert!(response.starts_with("http/1.1 101"));+ assert_eq!(response.contains("sec-websocket-extensions:"), compressed);+ // Keep client requests identical. A negotiated connection can receive+ // uncompressed messages; only the server-to-client bytes are measured here.+ send_json(&mut socket, json!({"type": "connection_init"}), false).await;+ let mut messages = vec![read_measured_message(&mut socket, compressed).await];+ assert_eq!(messages[0].json["type"], "connection_ack");+ send_json(+ &mut socket,+ json!({+ "id": "measure",+ "type": "subscribe",+ "payload": {"query": "subscription { snapshots }"}+ }),+ false,+ )+ .await;+ for _ in 0..snapshot_count {+ let message = read_measured_message(&mut socket, compressed).await;+ assert_eq!(message.json["type"], "next");+ assert!(message.json["payload"].get("errors").is_none());+ messages.push(message);+ }+ let complete = read_measured_message(&mut socket, compressed).await;+ assert_eq!(complete.json["type"], "complete");+ messages.push(complete);+ messages+}++/// A local TCP measurement of this production upgrade adapter, not an estimate+/// from recompressing serialized JSON. The data is explicitly synthetic; it is+/// not a claim about production traffic. Run with `--nocapture` for the CSV.+#[tokio::test]+async fn measure_subscription_payload_sizes() {+ let sizes = [1, 25, 100];+ let server = start_server_with_payloads(sizes.map(measurement_snapshot).to_vec()).await;+ let plain = measure_snapshot_connection(server.address, false, sizes.len()).await;+ let deflate = measure_snapshot_connection(server.address, true, sizes.len()).await;+ let labels = [+ "connection_ack",+ "snapshot_1_entity",+ "snapshot_25_entities",+ "snapshot_100_entities",+ "complete",+ ];+ println!(+ "case,plain_payload_bytes,deflate_payload_bytes,plain_frame_bytes,deflate_frame_bytes,payload_saved_percent"+ );+ for ((label, plain), deflate) in labels.iter().zip(&plain).zip(&deflate) {+ assert_eq!(plain.json, deflate.json);+ assert_eq!(plain.decoded_bytes, deflate.decoded_bytes);+ assert_eq!(plain.payload_bytes, plain.decoded_bytes);+ let saved = 100.0 * (1.0 - deflate.payload_bytes as f64 / plain.payload_bytes as f64);+ println!(+ "{label},{},{},{},{},{saved:.2}",+ plain.payload_bytes, deflate.payload_bytes, plain.frame_bytes, deflate.frame_bytes+ );+ }+ for (plain, deflate) in plain[1..=sizes.len()].iter().zip(&deflate[1..=sizes.len()]) {+ assert!(deflate.payload_bytes < plain.payload_bytes);+ }+ // Tiny GraphQL control messages can grow under deflate; do not assert savings for+ // connection_ack/complete or hide their cost in the larger snapshots.+}++#[tokio::test]+async fn browser_compression_roundtrip_for_both_graphql_protocols() {+ for protocol in ["graphql-transport-ws", "graphql-ws"] {+ subscription_roundtrip(+ protocol,+ Some("permessage-deflate; client_max_window_bits"),+ true,+ )+ .await;+ }+}++#[tokio::test]+async fn uncompressed_clients_and_unsupported_offers_still_work() {+ for protocol in ["graphql-transport-ws", "graphql-ws"] {+ for offer in [None, Some("permessage-deflate; unknown=1")] {+ subscription_roundtrip(protocol, offer, false).await;+ }+ }+}++#[tokio::test]+async fn compressed_connections_can_receive_uncompressed_messages() {+ let server = start_server().await;+ let (mut socket, response) = handshake(+ server.address,+ "graphql-transport-ws",+ Some("permessage-deflate"),+ true,+ )+ .await;+ assert!(response.contains("sec-websocket-extensions:"));+ send_json(&mut socket, json!({"type": "connection_init"}), false).await;+ assert_eq!(read_json(&mut socket, true).await["type"], "connection_ack");+}++#[tokio::test]+async fn receive_limits_match_previous_axum_limits_for_every_negotiation_outcome() {+ for offer in [+ None,+ Some("permessage-deflate"),+ Some("permessage-deflate; unknown=1"),+ ] {+ let mut request = "ws://localhost/soup/graphql/ws"+ .into_client_request()+ .unwrap();+ request.headers_mut().insert(+ header::SEC_WEBSOCKET_PROTOCOL,+ HeaderValue::from_static("graphql-transport-ws"),+ );+ if let Some(offer) = offer {+ request.headers_mut().insert(+ header::SEC_WEBSOCKET_EXTENSIONS,+ HeaderValue::from_static(offer),+ );+ }+ // Extraction needs a Hyper upgrade handle, but this test never awaits it.+ let on_upgrade = hyper::upgrade::on(&mut request);+ request.extensions_mut().insert(on_upgrade);+ let (mut parts, ()) = request.into_parts();+ let upgrade = GraphqlWebSocketUpgrade::from_request_parts(&mut parts, &())+ .await+ .unwrap();++ assert_eq!(upgrade.config.max_message_size, Some(64 << 20));+ assert_eq!(upgrade.config.max_frame_size, Some(16 << 20));+ assert_eq!(+ upgrade.config.extensions.permessage_deflate.is_some(),+ offer == Some("permessage-deflate")+ );+ }+}++#[tokio::test]+async fn decompressed_messages_still_obey_size_limits() {+ let (mut client, server) = tokio::io::duplex(4096);+ let mut config = WebSocketConfig::default()+ .max_message_size(Some(64))+ .max_frame_size(Some(128));+ config.extensions.permessage_deflate = Some(DeflateConfig::default());+ let mut server = WebSocketStream::from_raw_socket(server, Role::Server, Some(config)).await;+ // The compressed frame fits, but its decoded contents exceed the limit.+ send_json(&mut client, json!({"payload": "x".repeat(1024)}), true).await;+ let result = timeout(Duration::from_secs(5), server.next())+ .await+ .unwrap();+ assert!(matches!(+ result,+ Some(Err(tungstenite_signal::Error::Capacity(+ tungstenite_signal::error::CapacityError::MessageTooLong { .. }+ )))+ ));+}++#[tokio::test]+async fn rejected_authorization_never_upgrades() {+ let server = start_server().await;+ let (_, response) = handshake(+ server.address,+ "graphql-transport-ws",+ Some("permessage-deflate"),+ false,+ )+ .await;+ assert!(response.starts_with("http/1.1 401"));+ assert!(!response.contains("sec-websocket-extensions:"));+}++#[tokio::test]+async fn unsupported_graphql_protocol_is_rejected() {+ let server = start_server().await;+ let (_, response) = handshake(server.address, "unsupported", None, true).await;+ assert!(response.starts_with("http/1.1 400"));+}++#[test]+fn negotiates_supported_window_sizes_and_context_limits() {+ for bits in 9..=15 {+ let offer = format!(+ "permessage-deflate; server_max_window_bits={bits}; client_max_window_bits={bits}; server_no_context_takeover; client_no_context_takeover"+ );+ let (config, response) = accept_deflate_offer(&offer).unwrap();+ assert_eq!(config.server_max_window_bits().get(), bits);+ assert_eq!(config.client_max_window_bits().get(), bits);+ assert!(config.server_no_context_takeover);+ assert!(config.client_no_context_takeover);+ let response = response.to_str().unwrap();+ assert!(response.contains(&format!("server_max_window_bits={bits}")));+ assert!(response.contains(&format!("client_max_window_bits={bits}")));+ }+}++#[test]+fn declines_invalid_or_unsupported_parameters() {+ for offer in [+ "other-extension",+ "permessage-deflate; unknown",+ "permessage-deflate; server_no_context_takeover=1",+ "permessage-deflate; client_no_context_takeover=1",+ "permessage-deflate; server_no_context_takeover; server_no_context_takeover",+ "permessage-deflate; client_max_window_bits; client_max_window_bits=12",+ "permessage-deflate; server_max_window_bits",+ "permessage-deflate; server_max_window_bits=8",+ "permessage-deflate; client_max_window_bits=16",+ "permessage-deflate; client_max_window_bits=+12",+ "permessage-deflate; client_max_window_bits=012",+ "permessage-deflate; client_max_window_bits=",+ "permessage-deflate;",+ ] {+ assert!(accept_deflate_offer(offer).is_none(), "accepted {offer}");+ }+}++#[test]+fn picks_first_supported_offer_across_multiple_headers() {+ let mut headers = HeaderMap::new();+ headers.append(+ header::SEC_WEBSOCKET_EXTENSIONS,+ HeaderValue::from_static("unknown, permessage-deflate; server_max_window_bits=8"),+ );+ headers.append(+ header::SEC_WEBSOCKET_EXTENSIONS,+ HeaderValue::from_static(+ "permessage-deflate; server_max_window_bits=10, permessage-deflate",+ ),+ );+ let (config, _) = negotiate_compression(&headers).unwrap();+ assert_eq!(config.server_max_window_bits().get(), 10);+}++#[test]+fn does_not_mistake_quoted_values_for_extension_offers() {+ let mut headers = HeaderMap::new();+ headers.insert(+ header::SEC_WEBSOCKET_EXTENSIONS,+ HeaderValue::from_static("unknown; value=\"ignored,permessage-deflate\""),+ );+ assert!(negotiate_compression(&headers).is_none());+}