fix(openai_compat): clarify HTML response parse errors

[qs3c]

Description

Improve the error message when an OpenAI-compatible endpoint returns HTML instead of JSON with 200 OK.

Previously this surfaced only as a JSON unmarshal error such as invalid character ''<'', which made api_base or proxy misconfiguration harder to diagnose.

This change detects HTML-like responses and returns a more actionable error message with a short response preview. A regression test is included.

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactoring

Related Issue

Closes #1068

Testing

go test ./pkg/providers/openai_compat -count=1

[afjcjsbx]

I think this is an improved version of this PR: #1073, LGTM but there is a need to fix the lint please

[qs3c]

Fixed in a305c0a. The lint failure was the predeclared warning for max in responsePreview, which is now renamed to maxLen.

[qs3c]

@afjcjsbx Could you help review this pr, please ~🙏

[afjcjsbx]

If the body contains a very large HTML page or a huge string, converting the whole byte array to string, doing TrimSpace and then ToLower on the whole body allocates a lot of memory unnecessarily, since you only care about the very first few characters. You can optimize by reading only the first N bytes ignoring the initial whitespace.

[qs3c]

Addressed in 9216cd1. looksLikeHTML no longer converts the whole body; it now inspects only a trimmed prefix (leadingTrimmedPrefix, 128 bytes) before lowercase/prefix checks. I also switched responsePreview to bytes.TrimSpace plus bounded string conversion to avoid large allocations.

[afjcjsbx]

Currently, if the server returns a 502 Bad Gateway (typical of nginx proxies) with an HTML page, the code stops there.

This means that if a proxy goes wrong by returning a 502 HTML, your new wrapResponseParseError wrapper is not invoked, because it only kicks in if the status code is 200 OK (which is rarely the case if the endpoint is broken and returns HTML).

How do you want to handle this? If the goal is to intercept HTML and show your error message even when there is an HTTP error (such as 404 Not Found, 502 Bad Gateway, 503 Service Unavailable, often accompanied by HTML), you may want to invoke your HTML check even within the resp.StatusCode != http.StatusOK block.

[qs3c]

Good catch, fixed in 9216cd1. For non-200 responses we now run the same HTML diagnostic path via wrapHTTPResponseError(...), so 404/502/503 HTML pages also return the actionable api_base/proxy hint instead of only raw body output. Added TestProviderChat_HTMLErrorResponseReturnsHelpfulError (502 case).

[afjcjsbx]

here we could simplify the code in this way:

    contentType := resp.Header.Get("Content-Type")

	// check if there is an HTTP error (caused by proxy or gateway) or if the response is HTML 
	if resp.StatusCode != http.StatusOK || strings.Contains(strings.ToLower(contentType), "text/html") {
		body, _ := io.ReadAll(resp.Body)
		return nil, wrapHTTPResponseError(resp.StatusCode, body, contentType, p.apiBase)
	}

	// directly pass the stream (resp.Body) to the JSON parser without loading everything into memory
	out, err := parseResponse(resp.Body)
	if err != nil {
		// Note: if it fails here, we do not have the full body in memory for HTML inspection, 
		// but having already checked the Content-Type above, the error is genuinely related to JSON parsing.
		return nil, fmt.Errorf("failed to parse JSON response: %w", err)
	}

	return out, nil
}

WDYT??

[qs3c]

Thanks a lot for the super helpful suggestions, Professor Hubert!

Updated in 6eaa49f.

I've already tweaked this part of the code for better performance.

For non-200 status codes, I'm using io.LimitReader to read only a small prefix into memory instead of the whole body. For 200 responses, I switched to streaming JSON decoding instead of reading the entire body at once. I also use reader.Peek to inspect a small prefix and check whether the response looks like HTML.

I also tightened the tests to cover:

• non-200 JSON errors not being reported as HTML
• helpful HTML diagnostics for both success and error responses
• a regression case ensuring successful responses are decoded in a streaming way

[qs3c]

Fixed the lint failure in 53cba73. @afjcjsbx