Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(server): stop compression from holding live streams until they end

nirholasb08c00a3c0b9
diff --git a/server/compression-filter.mjs b/server/compression-filter.mjs
new file mode 100644
index 000000000..f34a0728f
--- /dev/null
+++ b/server/compression-filter.mjs
@@ -0,0 +1,33 @@
+// Which responses the gzip/brotli middleware may compress.
+//
+// `compression` buffers its output until the encoder has a block worth
+// emitting, so a response written incrementally reaches a client that accepts
+// an encoding only when the handler ends it. The library's default filter
+// exempts text/event-stream, but every other live stream on this server wears
+// an ordinary type: /api/tty writes ANSI frames as text/plain for 8 seconds,
+// and the LLM and agent streams write NDJSON. Measured 2026-10-08 against
+// production: `curl https://three.ws/tty` animated from 0.15 s, while the same
+// request with `Accept-Encoding: br` (Node fetch, browsers' fetch, curl
+// --compressed) got its first byte at 9.8 s, the whole animation delivered as
+// one wall of text after it had finished.
+//
+// The handlers already say so: `x-accel-buffering: no` is the header each
+// streaming route sets to tell proxies not to hold its body. Honoring the same
+// signal here covers every current stream and the next one without a list of
+// paths or content types to keep in sync.
+
+import compression from 'compression';
+
+/** @param {import('node:http').ServerResponse} res */
+export function isUnbufferedStream(res) {
+ return String(res.getHeader('x-accel-buffering') ?? '').trim().toLowerCase() === 'no';
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ */
+export function shouldCompress(req, res) {
+ if (isUnbufferedStream(res)) return false;
+ return compression.filter(req, res);
+}
diff --git a/server/index.mjs b/server/index.mjs
index 9541886dd..c7c63d981 100644
--- a/server/index.mjs
+++ b/server/index.mjs
@@ -25,13 +25,15 @@
// - req.body is pre-parsed for JSON / urlencoded / text / octet-stream at
// an 8 MB limit (Cloud Run's ceiling is 32 MB); multipart and other types
// stay unconsumed so upload handlers can read the raw stream.
-// - SSE works: compression skips text/event-stream, and the HTTP server's
+// - SSE and other live streams work: compression skips text/event-stream and
+// any response marked `x-accel-buffering: no`, and the HTTP server's
// idle timeouts are lifted (Cloud Run enforces the real deadline).
//
// Run locally: node server/index.mjs (PORT defaults to 8080)
import express from 'express';
import compression from 'compression';
+import { shouldCompress } from './compression-filter.mjs';
import { statSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { pathToFileURL, fileURLToPath } from 'node:url';
@@ -347,9 +349,10 @@ const app = express();
app.set('trust proxy', true); // Cloud Run sits behind Google front ends
app.disable('x-powered-by');
-// Default filter already skips non-compressible types (text/event-stream,
-// images, GLB), so SSE and binary assets pass through untouched.
-app.use(compression());
+// The default filter skips non-compressible types (text/event-stream, images,
+// GLB); shouldCompress also passes through any response that marked itself
+// `x-accel-buffering: no`, so a live text stream is not held until it ends.
+app.use(compression({ filter: shouldCompress }));
// Canonical host. `www.three.ws` resolves to the same load balancer as the apex
// and serves the identical app, but the apex is the only origin the platform
diff --git a/tests/server-compression-streams.test.js b/tests/server-compression-streams.test.js
new file mode 100644
index 000000000..e3dcfca08
--- /dev/null
+++ b/tests/server-compression-streams.test.js
@@ -0,0 +1,87 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import http from 'node:http';
+import express from 'express';
+import compression from 'compression';
+import { shouldCompress, isUnbufferedStream } from '../server/compression-filter.mjs';
+
+// A live stream must reach a client that accepts an encoding while it is still
+// being written. /api/tty sends ANSI frames as text/plain for seconds, and with
+// the default compression filter a `br`/`gzip` client got the first byte only
+// after the last frame (9.8 s on production, 2026-10-08).
+
+const servers = [];
+afterEach(() => {
+ while (servers.length) servers.pop().close();
+});
+
+function boot(filter) {
+ const app = express();
+ app.use(filter ? compression({ filter }) : compression());
+ app.get('/stream', (req, res) => {
+ res.setHeader('content-type', 'text/plain; charset=utf-8');
+ res.setHeader('x-accel-buffering', 'no');
+ res.flushHeaders();
+ res.write('frame-1\n'.repeat(200));
+ setTimeout(() => res.end('frame-2\n'), 600);
+ });
+ app.get('/json', (req, res) => {
+ res.json({ rows: Array.from({ length: 400 }, (_, i) => ({ i, label: 'compress me' })) });
+ });
+ return new Promise((resolve) => {
+ const server = app.listen(0, '127.0.0.1', () => {
+ servers.push(server);
+ resolve(`http://127.0.0.1:${server.address().port}`);
+ });
+ });
+}
+
+// Milliseconds from request to the first body byte, plus the response headers.
+function firstByte(url) {
+ return new Promise((resolve, reject) => {
+ const started = Date.now();
+ const req = http.get(url, { headers: { 'accept-encoding': 'br, gzip' } }, (res) => {
+ res.once('data', () => {
+ resolve({ ms: Date.now() - started, headers: res.headers });
+ res.resume();
+ });
+ res.on('error', reject);
+ });
+ req.on('error', reject);
+ });
+}
+
+describe('compression and live streams', () => {
+ it('the default filter holds an unbuffered text stream until it ends (the bug)', async () => {
+ const base = await boot(null);
+ const { ms } = await firstByte(`${base}/stream`);
+ expect(ms).toBeGreaterThanOrEqual(500);
+ });
+
+ it('shouldCompress lets an x-accel-buffering: no stream through as it is written', async () => {
+ const base = await boot(shouldCompress);
+ const { ms, headers } = await firstByte(`${base}/stream`);
+ expect(ms).toBeLessThan(400);
+ expect(headers['content-encoding']).toBeUndefined();
+ });
+
+ it('shouldCompress still compresses an ordinary response', async () => {
+ const base = await boot(shouldCompress);
+ const { headers } = await firstByte(`${base}/json`);
+ expect(headers['content-encoding']).toMatch(/br|gzip/);
+ });
+
+ it('reads the header case- and space-insensitively', () => {
+ const res = (value) => ({ getHeader: () => value });
+ expect(isUnbufferedStream(res(' No '))).toBe(true);
+ expect(isUnbufferedStream(res('yes'))).toBe(false);
+ expect(isUnbufferedStream(res(undefined))).toBe(false);
+ });
+});
+
+describe('the production server uses the stream-aware filter', () => {
+ it('server/index.mjs mounts compression with shouldCompress', async () => {
+ const { readFileSync } = await import('node:fs');
+ const src = readFileSync(new URL('../server/index.mjs', import.meta.url), 'utf8');
+ expect(src).toMatch(/app\.use\(compression\(\{\s*filter:\s*shouldCompress\s*\}\)\)/);
+ });
+});