Expose streaming API by adkelley · Pull Request #50 · gleam-lang/httpc

adkelley · 2025-09-16T21:10:02Z

Expose Streaming API

Motivation

Erlang's inets application provides a set of Internet-related services, including the HTTP client httpc. The httpc module gives users the option to stream the body of a 200 or 206 response either to the calling process or directly to a file.

This pull request exposes that option to gleam_httpc while maintaining full backward compatibility. It supports the stated use case stream:{self, once}, (i.e., streaming chunks) represented by the custom type Stream:

type Destination {
  Self
}

type Mode {
  Once
}

type ErlOption {
  ...
  Stream(#(Destination, Mode))
}

None of the other streaming APIs from the Erlang httpc module is supported (e.g., stream:{filename}).

Implementation Details

Several functions that have synchronous equivalents were added to support streaming, including:

dispatch_stream_bits(config: Configuration, req: Request(BitArray)) - similar to dispatch_bits function, send a HTTP stream request of binary data
dispatch_stream_request(config: Configuration, req: Request(String)) - similar to thedispatch function, send a HTTP stream request of unicode data
send_stream_request(req: Request(String) - similar to the send function, send an HTTP stream request of Unicode data using the default configuration.

The function select_stream_messages configures a selector to receive stream messages. Finally, the function receive_next_stream_message(pid: Pid) triggers the next streaming message to be sent to the calling process designated by pid.

Testing

Added two new unit tests, send_stream_request_test, and dispatch_stream_request_test using the postman streamed response api

Documentation

Updated README.md with a stream:{self, once} example
Added inline documentation to new public functions

Related Issues

Resolves Issue Expose streaming API #31

Erlang's httpc module supports streaming the body of 200 or 206 responses to the calling process or to a file. These changes expose this API.

lpil

Thank you! I've left a bunch of notes inline, let me know if any of it is unclear.

src/gleam/httpc.gleam

Streaming chunks is the stated use case. By limiting support to this API (i.e, stream:self, once} it removes considerable complexity and enables deterministic API responses that can be correctly typed in gleam

lpil

This is looking a lot nicer, thank you!

It still needs to be changed to use selectors rather than a custom non-composable API for receiving messages. Check out Mug's https://hexdocs.pm/mug/mug.html#receive_next_packet_as_message and https://hexdocs.pm/mug/mug.html#select_tcp_messages for how this can be done.

The new message types are not very clear due to using tuples instead of a descriptive custom type, and the use of charlists makes it difficult for the programmer to use as they have to know how to convert them to strings. Make a custom type for the response messages please, one designed with the Gleam programmer in mind rather than being more faithful to the Erlang APIs are we building on top of 🙏

Thanks again!

src/gleam/httpc.gleam

Erlang's httpc module supports streaming the body of 200 or 206 responses to the calling process or to a file. These changes expose the stream:{self, once} API, the stated use case. Resolves Issue Expose streaming API gleam-lang#31

lpil

Lovely work! This is def getting where we want it to be. I've left more notes inline, thank you

src/gleam/httpc.gleam

lpil · 2025-09-23T10:26:50Z

src/gleam/httpc.gleam

+/// If you wish to only handle stream messages from one process, then use one
+/// process per asychronous HTTP request. 
+///
+pub fn initialize_stream_selector() -> process.Selector(StreamMessage) {


Use the same design as found in the other packages please, so take the selector as an argument, take a mapping function as an argument, and use the naming convention they use. The TCP library is a good reference here.

If you cannot use an existing selector then you would not be able to use it with code that already has a selector (so most actor based code).

if you do not have a mapping function then you can't produce selectors of different types, which means you cannot easily select other types of messages with the selector.

And the naming convention is just to be consistent and to make the API easy to approach for people who have learnt about how to use selectors already.

Yes, agreed. Revised.

src/gleam/httpc.gleam

src/gleam_httpc_ffi.erl

README.md

Erlang's httpc module supports streaming the body of 200 or 206 responses to the calling process or to a file. These changes expose the stream:{self, once} API, the stated use case. Resolves Issue Expose streaming API gleam-lang#31

adkelley · 2025-10-07T16:18:38Z

Thanks again for your previous comments and suggestions. Is there anything else you'd like to see before accepting this pull request?

lpil

Thank you! Nearly there, left some API related notes inline

lpil · 2025-11-06T11:27:56Z

src/gleam/httpc.gleam

  VerifyNone
 }

+pub type HttpSocket


Is this used anywhere?

Good catch - removed.

src/gleam/httpc.gleam

lpil · 2025-11-06T11:29:14Z

src/gleam/httpc.gleam

+  RawStreamChunk(RequestIdentifier, BitArray)
+  RawStreamEnd(RequestIdentifier, List(#(Charlist, Charlist)))
+  RawStreamError(RequestIdentifier, HttpError)
+}


This looks like it is an implementation detail and should not be in part of the public interface?

Yes, it's an implementation detail. I've refactored the code to make it private, and, as a consequence, I was able to simplify the configuration of the selector that receives stream messages (See pub fn select_stream_messages() -> process.Selector(StreamMessage))

How come we construct values of this type and then immediately convert to another type? Why not construct that final type and skip this intermediate one?

lpil · 2025-11-06T11:29:29Z

src/gleam/httpc.gleam

+  StreamChunk(RequestIdentifier, BitArray)
+  StreamEnd(RequestIdentifier, List(#(String, String)))
+  StreamError(RequestIdentifier, HttpError)
+}


Could you document this type and add labels please 🙏

lpil · 2025-11-06T11:29:49Z

src/gleam/httpc.gleam

 }

+/// Send a HTTP stream request of binary data
+/// 


Could you finish this documentation please 🙏

lpil · 2025-11-06T11:32:48Z

src/gleam/httpc.gleam

 }

-/// Send a HTTP request of unicode data.
+/// Send a synchronus HTTP request of unicode data.


Remove this please 🙏

lpil · 2025-11-06T11:33:44Z

src/gleam/httpc.gleam

+  configure()
+  |> dispatch_stream_request(req)
+}
+


Let's have just the dispatch function 🙏

Can you explain more about this? Are you suggesting that I remove pub fn send_stream_request(req: Request(String)) -> Result(RequestIdentifier, HttpError), leaving dispatch_stream_request whenever streaming?

lpil · 2025-11-06T11:34:31Z

src/gleam/httpc.gleam

+/// 
+/// With the exception of timeout errors, all other errors will be delivered via:
+/// `StreamError(RequestIdentifier, HttpError)`.
+///


This is a complex API, so folks will need examples to understand how to use it. Could you add these please 🙏

I've added a thorough example to the README

I also added a simpler example to the documentation above dispatch_stream_request and send_stream_request functions.

lpil · 2025-11-06T11:34:50Z

test/gleam_httpc_test.gleam

+    process.selector_receive(selector, 1000)
+  assert request_id_ == request_id
+
+  let _nil = httpc.receive_next_stream_message(pid)


Remove the let nil_ = prefixes please, including from the documentation

test/gleam_httpc_test.gleam

lpil

Oh sorry! I wrote some review comments and then didn't press submit for some reason. Sorry about that

lpil · 2025-12-01T18:08:28Z

README.md


+## Http streaming requests
+
+`httpc` supports `stream:{self, once}` mode, which is a **pull-based** approach for


What's this stream:{self, once} syntax? I don't recognise it

Yes, that's Erlang speak :-) Replaced with `Stream(#(Self, Once))

lpil · 2025-12-01T18:09:01Z

README.md

+
+/// Receive a streamed response from Postman Echo. The number of
+/// stream chunks we receive is 5, as we specfied by the endpoint
+///


Remove the reference to postman please

lpil · 2025-12-01T18:09:25Z

README.md

+  // Configure the selector
+  let selector = httpc.select_stream_messages()
+  let assert Ok(chunks) =
+    loop(request_id, selector, process.self(), bit_array.from_string(""))


Do not use raw looping please, we don't want people to do that when they should be using an actor

Revised to use the Actor model. This required a good deal of thought, but it certainly helped me to better understand your approach to OTP.

lpil · 2025-12-01T18:10:31Z

test/gleam_httpc_test.gleam

+  let selector = httpc.select_stream_messages()
+  let assert Ok(_request_id) = httpc.send_stream_request(req)
+  let assert Ok(httpc.StreamError(_request_id, httpc.SocketClosedRemotely)) =
+    process.selector_receive(selector, 1000)


Use assert process.selector_receive(selector, 1000) == Ok(httpc.StreamError(request_id, httpc.SocketClosedRemotely)) please 🙏

lpil · 2025-12-01T18:11:01Z

src/gleam_httpc_ffi.erl

+coerce_stream_message({http, {ReqId, stream_start, Headers, Pid}}) -> {raw_stream_start, ReqId, Headers, Pid};
+coerce_stream_message({http, {ReqId, stream, BinBodyPart}}) when is_binary(BinBodyPart) -> {raw_stream_chunk, ReqId, BinBodyPart};
+coerce_stream_message({http, {ReqId, stream_end, Headers}}) -> {raw_stream_end, ReqId, Headers};
+coerce_stream_message({http, {ReqId, {error, Reason}}}) -> {raw_stream_error, ReqId, normalise_error(Reason)}. 


Wrap these long lines before 80 columns please

lpil · 2025-12-01T18:23:40Z

src/gleam/httpc.gleam

+/// 
+pub type StreamMessage {
+  /// Sent exactly once when the server response begins. The returned `pid`
+  /// identifies the process and must be passed to `httpc:stream_next`


No Erlang syntax or explaining Erlang APIs in Gleam documentation please.

Revised to refer to the Gleam function

lpil · 2025-12-01T18:24:41Z

src/gleam/httpc.gleam

+  let request = request.map(request, bit_array.from_string)
+  use request_id <- result.try(async_dispatch_bits(config, request))
+  Ok(request_id)
+}


Let's always work with bits and not have a string specialised version, seeing as it is not possible to ensure that the response is a string, as the other string versions do.

lpil · 2025-12-01T18:25:35Z

src/gleam/httpc.gleam

+  )
+  /// Sent for every chunk of response data that the worker emits. Each chunk
+  /// must be explicitly requested by calling `httpc:stream_next/1` with the pid
+  /// supplied in `StreamStart`.


Remove the documentation of Erlang internals please. This is documentation for users, not maintainers.

lpil · 2025-12-01T18:28:20Z

src/gleam/httpc.gleam

+pub type StreamMessage {
+  /// Sent exactly once when the server response begins. The returned `pid`
+  /// identifies the process and must be passed to `httpc:stream_next`
+  /// whenever you are ready for the next chunk.


What is this process? Is it some internal detail of Erlang's HTTPC? Is it a process the user creates? What happens if we pass a different pid to the stream function?

Good question! According to the API documentation, you're supposed to use this pid in stream_next_message. However, I tested a different pid (process.self()) in an example, and it still worked correctly. I suggest we stick with the documented behavior (See https://www.erlang.org/doc/apps/inets/httpc.html#request/5)

lpil · 2025-12-01T18:29:34Z

src/gleam/httpc.gleam

+  RawStreamChunk(RequestIdentifier, BitArray)
+  RawStreamEnd(RequestIdentifier, List(#(Charlist, Charlist)))
+  RawStreamError(RequestIdentifier, HttpError)
+}


How come we construct values of this type and then immediately convert to another type? Why not construct that final type and skip this intermediate one?

adkelley · 2025-12-17T18:32:55Z

In the latest version, I leave it to the user to either work with RawStreamMessages or convert them to StreamMessages. I've provided a convenience function to perform this transformation. The only difference is Charlist vs. String headers, which are easier to work with in Gleam. If you feel we should always work with StreamMessage then I'll change it.

* Updated README with a streaming example * Added error case to streaming tests * Removed send_stream from httpc and improved function documentation

CrowdHailer · 2026-02-18T19:43:10Z

I think it's possible for a non streaming request to be returned even when streaming.
When I make a request to ollama that results in a 400 I get a match error.

I added this line to the end of coerce_stream_message

coerce_stream_message(Any) ->io:format("X is: ~p~n", [Any]).

And get this output.

X is: {http,{#Ref<0.1590068022.2841640966.62230>,
             {{"HTTP/1.1",400,"Bad Request"},
              [{"connection","close"},
               {"date","Wed, 18 Feb 2026 19:40:44 GMT"},
               {"content-length","136"},
               {"content-type","application/json; charset=utf-8"}],
              <<"{\"error\":\"json: cannot unmarshal string into Go struct field ToolFunction.tools.function.parameters of type api.ToolFunctionParameters\"}">>}}}

Munksgaard · 2026-03-03T19:49:53Z

What's the status on this PR? Streaming seems like something that'd be nice to have :-)

jtdowney · 2026-03-10T03:47:08Z

@adkelley I noticed this PR is still marked as a draft

Expose streaming API

373666a

Erlang's httpc module supports streaming the body of 200 or 206 responses to the calling process or to a file. These changes expose this API.

lpil reviewed Sep 18, 2025

View reviewed changes

Restrict api to stream:{self, once}

6e129ec

Streaming chunks is the stated use case. By limiting support to this API (i.e, stream:self, once} it removes considerable complexity and enables deterministic API responses that can be correctly typed in gleam

lpil reviewed Sep 19, 2025

View reviewed changes

src/gleam/httpc.gleam Outdated Show resolved Hide resolved

Expose streaming API - stream:{self, once}

c0989bf

Erlang's httpc module supports streaming the body of 200 or 206 responses to the calling process or to a file. These changes expose the stream:{self, once} API, the stated use case. Resolves Issue Expose streaming API gleam-lang#31

adkelley force-pushed the main branch 2 times, most recently from 37a29e3 to f7b038a Compare September 22, 2025 23:12

Merge branch 'self_once'

b37ad44

adkelley force-pushed the main branch from f7b038a to b37ad44 Compare September 22, 2025 23:13

lpil reviewed Sep 23, 2025

View reviewed changes

adkelley added 2 commits September 24, 2025 15:54

Expose streaming API - stream:{self, once}

4b1ee6b

Erlang's httpc module supports streaming the body of 200 or 206 responses to the calling process or to a file. These changes expose the stream:{self, once} API, the stated use case. Resolves Issue Expose streaming API gleam-lang#31

Merge branch 'self_once'

b7098b8

adkelley force-pushed the main branch from f1f810e to b7098b8 Compare September 24, 2025 23:27

lpil reviewed Nov 6, 2025

View reviewed changes

lpil reviewed Dec 11, 2025

View reviewed changes

lpil marked this pull request as draft December 11, 2025 18:51

adkelley force-pushed the main branch from 02db59f to 51bc79e Compare January 12, 2026 00:08

Refactor streaming code, tests, and docs

791a7ac

* Updated README with a streaming example * Added error case to streaming tests * Removed send_stream from httpc and improved function documentation

adkelley force-pushed the main branch from 51bc79e to 791a7ac Compare January 12, 2026 00:36


		## Http streaming requests

		`httpc` supports `stream:{self, once}` mode, which is a pull-based approach for

Conversation

adkelley commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Expose Streaming API

Motivation

Implementation Details

Testing

Documentation

Related Issues

Uh oh!

lpil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lpil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lpil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adkelley commented Oct 7, 2025

Uh oh!

lpil left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adkelley Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

adkelley commented Sep 16, 2025 •

edited

Loading

adkelley Nov 8, 2025 •

edited

Loading