Web server gzip holds streamed /api responses until zlib's buffers fill

[qkmaosjtu]

Background

We are building Mobile Preview Plugin, an open-source DSH plugin for mobile developers. It shows and controls Android emulators and phones, iOS Simulators and USB-connected iPhones in the DSH side panel, so developers can watch and operate the app their agent is working on without leaving the conversation.

While qualifying the plugin on DSH Web and Desktop, we are running into host-side behavior that matters for plugins like ours. We will report these here one at a time, each with evidence and, where we can, a reference fix on our fork. This is the first one.

Where we hit this

The plugin streams the device screen as H.264 through a plugin fetch route (application/octet-stream) and decodes it in the panel with WebCodecs. With a USB iPhone in Desktop, the preview drew about 2 frames per second and updated in visible two-second jumps, although the phone produced about 27 frames per second and the host wrote every packet within 90 ms. A mostly static screen was the worst case: the encoder then sends one large keyframe every two seconds and very little else, so the buffered output was released about once per keyframe.

Summary

When the web server runs with compression: gzip (the default from @deepseek-ai/dsh-web-app), a streamed /api response is compressed but never flushed. The client receives it in large bursts instead of as it is produced.

We observed it on DSH Web 0.2.1-alpha.1 and Desktop 0.2.0-rc.2; Desktop 0.2.1-rc.2 ships the same gzip configuration and bridge code. Desktop proxies /api to the same host web server.

Cause

• createGzipMiddleware (packages/host/webserver) exempts only text/event-stream. Its config documents that unknown-length streams are eligible for gzip, and mime-db@1.54.0 marks application/octet-stream compressible.
• The HTTP bridge (packages/client/connection/src/http-bridge.ts) writes each response chunk with res.write(chunk) but never calls the res.flush() that compression adds. zlib therefore keeps the output until its internal buffers fill or the response ends.

Proposed fix

Flush after each chunk in the bridge, keeping compression and its streaming eligibility unchanged:

Commit on dsh-v0.2.1-rc.2: mobile-dev-harness/deepseek-harness@82438f0 (compare with master)

• BridgeServerResponse gains an optional flush(), documented as provided by a compressing middleware.
• The write loop calls res.flush?.() after each res.write(chunk), before the existing backpressure wait.
• The connection README (English and Chinese, translation pairing re-recorded) states that streamed bodies are flushed per chunk.

A new real-composition test in packages/client/connection/tests/http-bridge.host.spec.ts starts WebServer with compression: 'gzip' and has the handler produce its second chunk only after the client has decoded the first. Without the fix it fails after 5 seconds with "the first chunk was held by response compression"; with the fix it passes. The existing binary-rpc gzip test still passes, including its check that the compressed transfer stays under a tenth of the payload. build:artifacts, build:check and the commit hooks pass. doc-sync passes except verify-repository-references, which already fails at 687f282 on python/sdk/uv.lock:113 and is unrelated to this change.

Per-chunk Z_SYNC_FLUSH costs a few bytes per chunk, which is negligible for typical 16–64 KB chunks. If that matters for large bodies, coalescing flushes to one per event-loop turn is an alternative.

Measurements

Measured in a plugin route, stock DSH Web with an iOS Simulator stream (the same pattern appeared on a USB iPhone in Desktop):

	Longest wait in the browser's reader.read()	Bytes per read
gzip, no flush	~2000 ms	40–60 KB
response opted out with Cache-Control: no-transform	~65 ms	about one packet per read

On the host, the bridge pulled each chunk from the response stream within 1 ms of its enqueue in both cases, so the delay was entirely after the bridge's res.write.

Workaround for plugins

Cache-Control: no-transform on a streaming response disables compression for it; the Mobile Preview Plugin uses this on its media route.

The change is MIT-licensed like DSH. Please feel free to take the commit as-is or reimplement it in whatever form fits.

cc @tianyicui @imccyu

[PerryLink]

Confirmed on 687f282e86 (0.2.1-rc.2) — the middleware sets no flush policy, and your filter analysis is right about which responses escape.

The middleware

packages/host/webserver/src/index.ts:218-231:

const middleware = compressionMiddleware({
  level: config.compressionLevel,
  threshold: config.compressionThresholdBytes,
  filter(request, response) {
    if (response.getHeader('content-range') !== undefined) return false
    const contentType = response.getHeader('content-type')
    if (typeof contentType === 'string' && contentType.toLowerCase().startsWith('text/event-stream')) return false
    if (typeof contentType === 'string' && /^multipart\/form-data(?:;|$)/i.test(contentType)) return true
    return compressionMiddleware.filter(request, response)
  },
})

level and threshold only. No flush option, and no res.flush() call anywhere in the wrapper — so the zlib stream runs in its default mode, which emits only when its internal buffers fill or the writable ends. An application/octet-stream plugin route matches neither of the two exclusions, so it is compressed, and your H.264 case is exactly the pathological input: a large keyframe every couple of seconds and almost nothing in between. The buffered output is released on the keyframe, hence "about 2 fps, in two-second jumps".

One supporting detail from the surrounding config: :102 documents the threshold as "Minimum known response length eligible for gzip; unknown-length streams are eligible" — streams are deliberately included, which is the right call for the common case and the reason a streaming route has no protection here.

Also worth noting for the write-up

compression: 'gzip' is not the webserver default — :106 is DEFAULT_COMPRESSION = 'none'. So this only bites deployments where the bundle turns gzip on, which is why it presents as "on some installs". Naming that in the report helps anyone reproducing it.

On the reference fix

There are two shapes, and they differ in who has to change:

1. Flush per chunk. compression accepts a flush option, so flush: zlib.constants.Z_SYNC_FLUSH inside that object literal would make every write reachable output immediately. One line in the host, benefits every streaming plugin route, costs some compression ratio on streamed bodies (each flush closes the current deflate block). For your payload the ratio loss is irrelevant — it is already compressed.
2. Exclude the route. Extend the filter to skip compression for responses that declare a streaming content type, or for a route marked no-compress by the plugin. This is the cleaner contract but needs a way for a plugin to opt out, which is a new surface.

I would push for (1): it fixes the class without new API, and a per-response flush is the standard answer for "gzip + server-sent chunks over a non-SSE content type".

A related symptom worth checking before you file

Worth noting in the report which framing the response uses. If the route sets Content-Length rather than chunked encoding, the buffering story is different again (the body length is known up front, so the compressor has no reason to hold bytes for it, but it also has no reason to flush early), and that decides whether the flush option alone is enough for your case. Your H.264 route is almost certainly chunked, but saying so explicitly saves the next reader a round trip.

[qkmaosjtu]

Thanks, @PerryLink. We measured both fixes against stock 687f282, using a real WebServer with compression: 'gzip' at level 1 (the @deepseek-ai/dsh-web-app setting) on loopback:

	Stock (no flush)	Our bridge res.flush() (82438f0)	Your flush: zlib.constants.Z_SYNC_FLUSH
Delay from enqueue to decoded bytes, 200 × 2 KB chunks at 10 ms intervals (median / p95)	54 / 89 ms	0.6 / 0.9 ms	0.7 / 1.0 ms
2 MB of JavaScript in 64 KB chunks through the /api bridge	470,777 B	482,377 B (+2.5%)	471,138 B (+0.08%)
512 KB of JavaScript through the bridge, 16 KB chunks	120,844 B	+6.5%	+0.4%
4 KB chunks	120,844 B	+19%	+3.4%
1 KB chunks	120,844 B	+50%	+13%
256 B chunks	120,844 B	+132%	+31%

The sizes were identical across repeated runs, and the 2 MB transfer took about 10 ms in every variant.

Same idea, better code

We reached the same conclusion, flushing every chunk, but your version is the better implementation. Our post said per-chunk Z_SYNC_FLUSH costs only a few bytes; that holds for your option, not for our commit. compression's res.flush() calls zlib's flush() without a kind, which defaults to Z_FULL_FLUSH and resets the deflate dictionary at every chunk, hence the extra 2.5% to 132% above. Your option keeps the dictionary, is one line in the package that owns compression, and also covers routes that do not go through the bridge.

Its wider effect is that every gzip response flushes on each write. In DSH today that costs a few bytes per response: the filter already excludes SSE, and the static frontend and plugin bundles are written with a single res.end(body). A direct route writing 2 MB in 64 KB writes grew by 0.08%.

Your other two points

• Default: right, the webserver default is 'none'. @deepseek-ai/dsh-web-app sets compression: gzip (packages/bundle/web-app/cordis.patch.yml:186), and the Desktop runtime loads that bundle, so stock Web and Desktop installs both compress.
• Framing: our media route sets no Content-Length, so it is chunked. compression also removes Content-Length from every response it compresses, so a compressed response is always chunked and the flush option alone covers both cases.

We have switched our fork to your approach: mobile-dev-harness/deepseek-harness@f971321. The bridge change is reverted and the regression test now lives in the webserver package, so the compare link in the post shows only the webserver change. In a Chromium browser, a gzip response written every 100 ms now arrives as 30 reads of 2 KB at most 103 ms apart, instead of five reads of about 16 KB roughly 815 ms apart.

Thanks for the careful review. This is exactly the kind of discussion we hoped these reports would start, and we look forward to helping make DSH better together.