Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(graphql): compress subscription WebSocket frames (#7997)

Sean Ayec2be6149dc42
diff --git a/Cargo.lock b/Cargo.lock
index 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.toml
index 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 take
diff --git a/crates/agent_preview/Cargo.toml b/crates/agent_preview/Cargo.toml
index 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, features
macro_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.toml
index 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.md
index 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 them
from `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.nix
index 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.toml
index 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.md
index 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.
+
## Prerequisites
Install 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.rs
index 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.rs
new file mode 100644
index 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.txt
new file mode 100644
index 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.json
new file mode 100644
index 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.rs
new file mode 100644
index 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());
+}