Feature Request: Full HTTP/2 support (RFC 8441) for WebSocket connections via reverse proxy

[Githopp192]

Summary

When Collabora Online (built-in CODE server via Nextcloud's richdocumentscode app) is deployed behind a reverse proxy (HAProxy) with HTTP/2 enabled end-to-end, document loading fails due to WebSocket tunneling incompatibilities. HTTP/2 support for WebSocket connections (RFC 8441) would resolve this.

Environment

• Collabora Online: built-in CODE server (richdocumentscode Nextcloud app)
• Nextcloud version: latest (as of April 2026)
• Reverse proxy: HAProxy 3.2.14 (OPNsense)
• Web server: Apache + php-fpm
• Internal Collabora port: 9983 (HTTP, no TLS)
• OS: RHEL-based Linux

Current Behavior

When HAProxy has HTTP/2 enabled on the backend connection (HAProxy → Apache/Nextcloud), the WebSocket tunnel through Nextcloud's proxy.php fails with:

net::ERR_HTTP2_PROTOCOL_ERROR
net::ERR_CONTENT_LENGTH_MISMATCH
Document loading failed due to timeout: Please check for failing network requests

The coolwsd process runs correctly on port 9983 and responds to direct HTTP requests:

curl http://localhost:9983/
OK

The issue is not with coolwsd itself, but with the WebSocket tunneling layer when HTTP/2 is involved in the proxy chain.

Workaround

Force HTTP/1.1 on the HAProxy backend connection. This works but prevents end-to-end HTTP/2 optimization:

• Disable HTTP/2 on HAProxy backend pool
• Keep only HTTP/1.1 in ALPN for backend
• Add timeout tunnel 3600s to backend options

Expected Behavior

Collabora Online should work correctly in HTTP/2 reverse proxy environments. WebSocket over HTTP/2 has been standardized since RFC 8441 (September 2018) — nearly 8 years ago.

Feature Request

1. Ensure coolwsd fully supports RFC 8441 (WebSocket over HTTP/2)
2. Ensure the WebSocket handshake and tunneling work correctly when the proxy chain uses HTTP/2 (either end-to-end or partially)
3. Document the recommended HAProxy/nginx configuration for HTTP/2 deployments in the official docs

Why This Matters

HTTP/2 is now the standard for modern web deployments and brings significant performance improvements (multiplexing, header compression, reduced latency). Requiring a downgrade to HTTP/1.1 on the backend is a workaround that should not be necessary in 2026.

References

• RFC 8441: https://www.rfc-editor.org/rfc/rfc8441
• Related Nextcloud richdocuments issue: https://github.com/nextcloud/richdocuments/issues
• HAProxy WebSocket documentation: https://www.haproxy.com/blog/websockets-load-balancing-with-haproxy

[Githopp192]

proxy.php incompatible with HTTP/2 backend in HAProxy → ERR_CONTENT_LENGTH_MISMATCH

Summary

When HAProxy is used as a reverse proxy in front of Nextcloud with HTTP/2 enabled on the backend connection (HAProxy → Apache/Nextcloud), Collabora Online (built-in CODE server) fails to load documents. Disabling HTTP/2 on the HAProxy backend (falling back to HTTP/1.1) resolves the issue.

Environment

• Nextcloud version: latest (as of April 2026)
• Richdocuments / CODE Server: built-in (richdocumentscode app)
• Reverse proxy: HAProxy 3.2.14 (OPNsense)
• Web server: Apache with php-fpm
• OS: RHEL-based Linux

Steps to Reproduce

1. Set up Nextcloud behind HAProxy with SSL offloading
2. Enable HTTP/2 on the HAProxy backend pool (HAProxy ↔ Apache)
3. Try to open any document via Nextcloud Office / Collabora

Observed Behavior

Document loading fails with the following errors in the browser console:

First observed error:

net::ERR_HTTP2_PROTOCOL_ERROR  (POST proxy.php?req=/cool/.../write/3)  200 (OK)

After disabling HTTP/2 on HAProxy frontend (but keeping it on backend):

net::ERR_CONTENT_LENGTH_MISMATCH  (POST proxy.php?req=/cool/.../write/3)  200 (OK)

Final error in console:

Document loading failed due to timeout: Please check for failing network requests

Root Cause Analysis

proxy.php acts as a WebSocket tunnel between the browser and the internal coolwsd process (port 9983). When HAProxy uses HTTP/2 for the backend connection, the chunked/streaming responses from proxy.php produce a Content-Length mismatch, because HTTP/2 handles framing differently than HTTP/1.1.

WebSocket over HTTP/2 is standardized in RFC 8441 (since 2018), but the current proxy.php implementation does not appear to handle this correctly, causing the tunnel to break when the upstream connection uses HTTP/2.

Workaround

Disable HTTP/2 on the HAProxy backend pool (keep HTTP/1.1 only for HAProxy ↔ Apache communication). HTTP/2 can remain enabled on the frontend (Browser ↔ HAProxy).

HAProxy backend custom option that also helps:

timeout tunnel 3600s

Expected Behavior

proxy.php should correctly proxy WebSocket connections regardless of whether the HAProxy ↔ Apache connection uses HTTP/1.1 or HTTP/2.

Feature Request

Full HTTP/2 compatibility for proxy.php WebSocket tunneling, ideally with RFC 8441 (WebSocket over HTTP/2) support, so that end-to-end HTTP/2 deployments work without workarounds.

[joshtrichards]

Some Monday evening thoughts...

HTTP/2 enabled end-to-end, document loading fails due to WebSocket tunneling incompatibilities

Is there a specific problem you’re trying to solve by using HTTP/2 (H2) end-to-end?

I ask because... H2 all the way thru to the upstream/backend is still fairly uncommon (at least in my experience). It doesn't have exactly the same benefits there as it does on the client facing side.

Requiring a downgrade to HTTP/1.1 on the backend is a workaround that should not be necessary in 2026.

The performance benefits of H2 (like multiplexing) are less impactful on low-latency internal networks compared to high-latency client connections

And not using it there doesn't prevent its use on the frontend.

So it's more for client-to-proxy connections (currently) than proxy-to-upstream connections presently. In the latter, H1.1 is typically used (and connection management has different requirements there and thus handled differently generally).

Until a few months ago it wasn't even possible with, say, Nginx and remains unusual with, say, Apache.

And, yes, I know Haproxy technically supports it. Which is great. But it's still not commonplace at that point in the infrastructure.

That said, couple things:

• proxy.php is part of richdocumentscodenot richdocuments¹
• I do see some assumptions made in proxy.php that are effectively H1.x specific and where H2 headers being passed through could be... unpredictable or problematic
• Websockets via H1.1 are supported (essentially) via proxy.php, but RFC 8441 style Websockets are not; that would require H2 and a whole different wire format. And RFC 8441 upstream isn't even supported by Nginx currently.

Footnotes

1. https://github.com/CollaboraOnline/richdocumentscode ↩

[Githopp192]

Thanks Josh for the detailed Monday evening thoughts — really appreciated!

My original motivation: I didn't enable HTTP/2 on the HAProxy backend out of principle or for performance reasons. I enabled it because HAProxy supports it and it appeared to be a valid configuration. The problem was that proxy.php broke silently — no clear error on the server side, just a cryptic ERR_CONTENT_LENGTH_MISMATCH in the browser console after quite a bit of debugging.

So yes, I agree that H1.1 on the backend is the correct and stable choice right now. But the real issue is that this is not documented anywhere — and a user walking into this combination will lose a lot of time figuring out why documents simply won't load.

Given that you've confirmed there are H1.x-specific assumptions in proxy.php that make H2 headers unpredictable or problematic — which in practice means: Nextcloud Office simply fails to load any document, with no useful error message for the user or admin — would it be feasible to at least:

• Add a note to the documentation (or the app's admin settings) stating that HTTP/2 on the backend connection (proxy → Nextcloud) is not supported and should be disabled
• Optionally: log a warning server-side when H2 headers are detected in that context

The RFC 8441 / full H2 support request can stay as a long-term consideration — but the documentation gap feels like a low-hanging fix.

Happy to help draft that documentation note if useful.

Thanks again for the context, Josh

Best Mike