HTTP clients

A test server

The HTTP client of the standard library is httpc, and it lives in the inets application. To show it without a dependency on a website, the page starts a tiny server of its own on the loopback address: it accepts one connection at a time and always answers the same page. Save this module as micro_http.erl, and use it in your own tests whenever a client needs a server to talk to.

-module(micro_http). -export([start/0, stop/0]). -define(PORT, 18089). start() -> {ok, Listen} = gen_tcp:listen(?PORT, [binary, {active, false}, {reuseaddr, true}]), Pid = spawn(fun() -> loop(Listen) end), register(micro_http, Pid), ok. stop() -> case whereis(micro_http) of undefined -> ok; Pid -> exit(Pid, shutdown), ok end. loop(Listen) -> case gen_tcp:accept(Listen) of {ok, Socket} -> respond(Socket), loop(Listen); {error, closed} -> ok end. respond(Socket) -> {ok, _Request} = gen_tcp:recv(Socket, 0, 5000), Body = <<"hello from the local server">>, Response = [<<"HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: ">>, integer_to_binary(byte_size(Body)), <<"\r\nConnection: close\r\n\r\n">>, Body], ok = gen_tcp:send(Socket, Response), gen_tcp:close(Socket).

Start inets and send

Nothing in inets runs until the application is started, so the first call of a program is application:ensure_all_started(inets). After that, httpc:request takes a URL and answers the whole exchange in one tuple.

erlc micro_http.erl
erl

1> application:ensure_all_started(inets).
{ok,[inets]}
2> micro_http:start().
ok
3> {ok, {{_, Status, _}, _Headers, Body}} = httpc:request("http://127.0.0.1:18089/hello"), {Status, Body}.
{200,"hello from the local server"}

The answer has three levels: the outer ok says the exchange happened, the triple is the status line with the version, the code and the reason, and the last element is the body. The middle element is the header proplist, which the next section reads.

The answer

The body is a string by default, so length walks the list and an image arrives as a long list of integers. Ask for {body_format, binary} when the content is bytes, and read a single header with proplists:get_value, because the header list is a plain proplist of string pairs.

erl

1> application:ensure_all_started(inets).
{ok,[inets]}
2> micro_http:start().
ok
3> {ok, {{_, _, _}, Headers, Bin}} = httpc:request(get, {"http://127.0.0.1:18089/hello", []}, [], [{body_format, binary}]), {proplists:get_value("content-type", Headers), Bin}.
{"text/plain",<<"hello from the local server">>}
4> micro_http:stop().
ok

A status of 404 or 500 is not an error tuple: the request worked and the server answered, so the answer stays {ok, ...} and the status tells you how it went. The error tuple is for the exchange itself: a refused connection, a timeout, a host that does not resolve.

Options and timeout

The third argument of httpc:request/4 holds the HTTP options and the fourth the request options. The timeout is in the first list and counts milliseconds for the whole exchange; without it the client waits for as long as the server keeps the socket open. The body format is a request option, not an HTTP option, which is why it travels in the fourth list.

For many requests to the same host, let httpc keep its pool: the default session handles several connections per host, and httpc:set_options can raise max_sessions and max_keep_alive_length. Build one profile per host if you need different proxies or certificates. For HTTP/2, gRPC and a connection per stream, the ecosystem reaches for gun or hackney instead; httpc stays the choice when the only dependency should be the language itself.

Next: io:format and output

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which application provides the httpc client?

    Answer

    inets

    httpc ships with inets, so the application must be started before the first request.

  2. Which call starts inets and its dependencies?

    Answer

    application:ensure_all_started(inets)

    The call starts inets and every application it needs, and answers {ok, Started}.

  3. What is the shape of a successful httpc:request/1 answer?

    Answer

    {ok, {{Version, Status, Reason}, Headers, Body}}

    The status line is a triple inside the response tuple, and the response sits inside ok.

  4. What is the type of the body by default?

    Answer

    A string, that is a list of characters

    httpc answers a string unless {body_format, binary} is requested.

  5. How do you get a binary body?

    Answer

    Pass {body_format, binary} in the request options

    It is a request option, the fourth argument of httpc:request/4, not an HTTP option.

  6. Which argument of httpc:request/4 holds the timeout?

    Answer

    The HTTP options list

    The timeout is an HTTP option, so it goes in the third argument.

  7. What does a 404 answer look like?

    Answer

    {ok, {{_, 404, _}, Headers, Body}}

    The HTTP exchange succeeded, so the answer is ok and the status code carries the failure.

  8. What does {error, Reason} mean for a request?

    Answer

    The request never completed

    A refused connection, a timeout or a bad URL ends the exchange with an error tuple.

  9. How do you read one header value?

    Answer

    proplists:get_value/2 on the headers

    The headers are a proplist of string pairs, and proplists:get_value picks one value.

  10. Why does the page start its own server instead of fetching a website?

    Answer

    So the session needs no internet or DNS

    A local server answers the same HTTP shape without depending on a remote site.

The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev