Enhance browser compatibility for ReadableStream in POST requests

[yilishan]

Issue Description

I've identified an issue where POST requests made with ky lose their payload in certain WebKit-based environments, particularly in iOS AlipayClient WebView and some Safari versions. The error message observed on the server side is "readablestream uploading is not supported".

Environment Information

• Browser/WebView: Safari, iOS WebView, particularly AlipayClient WebView
• Sample User Agent: Mozilla/5.0 (iPhone; CPU iPhone Os 18 3 2 like Mac Os X)AppleWebKit/605.1.15(KHTML.like Gecko) Mobile/22D82 Channelld(23) Ariver/1.1:0 AIAPD(AP/10.7.16.6000) Nebula WkRVKType(1)AlipayDefined(nt:WIFl,ws:440|8923.0)AlipayClient/10.7.16.6000 Alipay Language/zh-Hans Region/CNNebulax/1.0.0
• ky version: 1.8.0

Reproduction Steps

1. Create a POST request with a JSON payload using ky
2. Set headers including Content-Type: 'application/json'
3. Send the request from a WebKit-based environment (especially iOS WebView)
4. Observe that the server does not receive the payload

Root Cause Analysis

After thorough investigation, I believe this issue stems from the following:

1. Incomplete ReadableStream Support: While many WebKit-based browsers claim to support ReadableStream API, their implementation is incomplete or buggy when used as request bodies.

2. Feature Detection Limitations: The current feature detection in ky (supportsRequestStreams) only checks if duplex property is accessed, but doesn't verify if the browser can actually process stream requests correctly.

3. Lack of Graceful Degradation: When stream requests aren't fully supported, ky doesn't automatically fall back to a more compatible approach.

The key issue is that setting duplex: 'half' and using ReadableStream in these environments leads to request body serialization failures, even though basic feature detection suggests these features should work.

Proposed Solution

I propose enhancing the browser compatibility by implementing a more robust feature detection and graceful degradation approach:

1. Comprehensive Feature Testing: Test not just the presence of APIs but their actual working capability by creating a small test stream and attempt to use it.

2. Multi-level Safety Checks: Implement checks at multiple points (initial detection, constructor, stream creation, and request sending).

3. Automatic Fallback Mechanism: For POST requests in environments where streams aren't properly supported, automatically fall back to simpler request formats.

Code Suggestions

Below are some code snippets demonstrating the proposed approach:

1. Enhanced feature detection in constants.ts:

export const supportsRequestStreams = (() => {
    // Check basic API support
    if (typeof globalThis.ReadableStream !== 'function' || 
        typeof globalThis.Request !== 'function') {
        return false;
    }

    // Try creating a request with a stream and test browser support
    try {
        const stream = new globalThis.ReadableStream({
            start(controller) {
                controller.close();
            }
        });

        let duplexSupported = false;
        let requestBodyStreamSupported = true;

        try {
            const request = new globalThis.Request('https://example.com', {
                method: 'POST',
                body: stream,
                // @ts-expect-error - Types are outdated.
                get duplex() {
                    duplexSupported = true;
                    return 'half';
                }
            });

            // Further validation with a tiny stream
            if (duplexSupported) {
                // Additional validation logic...
            }
        } catch (error) {
            // Error handling logic...
            requestBodyStreamSupported = false;
        }

        return duplexSupported && requestBodyStreamSupported;
    } catch (error) {
        return false;
    }
})();

2. Self-contained feature testing in streamRequest function:

export const streamRequest = (request, onUploadProgress) => {
    // Internal feature detection
    const canUseStreams = (() => {
        try {
            // Feature testing logic...
            return true;
        } catch (error) {
            return false;
        }
    })();
    
    // Graceful degradation if streams not supported
    if (!canUseStreams) {
        // Fallback logic...
        return request;
    }

    // Stream handling logic...
};

3. Enhanced POST request handling in _fetch method:

if (!supportsRequestStreams && this.request.method.toLowerCase() === "post") {
    // Create a simple request object for compatibility
    const simpleOptions = {
        method: this.request.method,
        headers: this.request.headers,
        body: await this.request.clone().text(),
        // Other request properties...
    };

    return this._options.fetch(this.request.url, simpleOptions);
}

Benefits of This Approach

1. Broader Compatibility: Works across all browsers including those with partial ReadableStream support
2. Future-Proof: Relies on actual capability testing rather than user agent detection
3. Resilient Design: Multiple layers of checks and fallbacks ensure requests succeed even in edge cases
4. Maintainable Code: Self-contained testing reduces cross-module dependencies

I'd be happy to provide more information or assist with implementing these changes if needed.

[sholladay]

So basically, if ReadableStream is available, but sending them in body is not supported, then fallback to buffering the entire stream and sending it all at once?

I'm ok with that since duplex mode still isn't widely supported.

[yilishan]

@sholladay Thank you for your prompt response and understanding of the issue. Your interpretation is exactly right - when ReadableStream is available but not properly supported in request bodies, we should fall back to buffering and sending the data at once.

I appreciate you marking this with the "enhancement" and "help wanted" labels. This issue is causing significant problems in real-world applications, particularly in iOS WebView environments like Alipay where many users experience failed API calls. The fallback approach would greatly improve reliability across various browser environments.

Looking forward to seeing this compatibility enhancement in a future release. It would be a valuable improvement for many developers working with WebKit-based browsers and WebViews.

[yovanoc]

Hey! any improvements on this? sad to see uploadProgress not working on safari

[sholladay]

There's no way to make onUploadPfogress work in environments that lack support for streams in the fetch body option. Unless you just want us to report 0% and then 100%, which seems a bit pointless.

However, a meaningful improvement we could make is to convert the stream to a buffer before sending it, instead of throwing an error. I am in favor of doing that.

[yovanoc]

Yeah agree that it's a bit pointless, but will help for 'compatibility purposes' I would like to avoid having axios as a fallback for now..

[kadhirr]

hey @sholladay @yilishan , I could help with this issue.

Just a quick thought, can we just check if Request.prototype has a duplex property, if it does not, we can revert back to using "full" ? Would that work in this case?

[sholladay]

IIRC, detecting duplex support is not as simple as that. But we always have an internal utility for checking duplex support.

So, roughly speaking, you just need to add an else to the if condition where we detect duplex support.

[romansp]

I'm currently looking at the possibility to migrate from axios to ky and this issue is potentially a blocker as I'm seeing issue when uploading files with progress reporting in both Firefox 144.0.2 and Safari 26.0.1.

I totally understand that it will be impossible to have onUploadProgress work in environments that lack proper support. But immediately throwing Request streams are not supported in your environment. The "duplex" option for "Request" is not available. error is quite brutal. This forces to detect support myself which is already quite difficult before sending request with ky and making sure to omit those options.

I'm wondering if it's intentional that ky doesn't gracefully fallback to a non-streaming implementation?

In my case I will be totally fine with progressive enhancement: if not supported environment then onUploadProgress/onDownloadProgress is ignored and progress not reported or reported as indeterminate.