ezcurl icon indicating copy to clipboard operation
ezcurl copied to clipboard

Enhance streaming API control for long-running transfers

Open let-def opened this issue 9 months ago • 0 comments

This PR refactors the streaming API to grant users finer control over HTTP transfers, particularly for long-running cases. Key changes include:

  • Early access to response metadata by exposes HTTP response code and headers as soon as they’re received (previously only available after the entire body was transferred).
  • Progress monitoring and cancellation, by adding hooks to track transfer progress and interrupt streams programmatically.

Together, they allow clients to abort transfers early based on metadata (e.g., invalid status code).

Limitations:

  • Malformed headers trigger an immediate failure without giving access to the response code.
  • The on_respond callback may receive an early response, but if the transfer fails, the final return will be an error (e.g., because of network issues or when aborted by user).

Alternatively, revisiting the response type could better represent the different point of failures:

type response = {  
  code: int option; (* None if the request failed *)  
  headers: (header list, string) result; (* The headers or an error message if they failed to parse; we could also provide the raw headers, though this is probably a fringe case *)
  body: ('a, curl_error) result;  
}

However, this would break backward compatibility and is still insufficient for async scenarios, which control flow is actually closer to (response_code * (headers * body io) io) io, though it’s syntactically cumbersome.

While not perfect, this API is strictly more flexible than the current implementation, addressing core pain points for streaming use cases.

let-def avatar Mar 14 '25 10:03 let-def