httpc(3erl)

📦
version 25.3.2.8 · 7 versions
, in ubuntu noble

💅 NAME 💅

httpc — an HTTP/1.1 client. Yep, that's the whole vibe. (Also, for the record: this is an Erlang Module Definition, bestie — we're in the Erlang docs, not some random man page.)

✨ DESCRIPTION ✨

Okay so like, this module gives you the API to an HTTP/1.1 compatible client built according to RFC 2616. Caching? Not supported. We don't do that here. 🙅‍♀️

📌 Note, bestie, read this one: When you start the Inets application, a manager process for the default profile gets started. Every function in this API that doesn't explicitly name a profile just... goes and talks to the default profile. And a profile is basically the little purse 👜 where the client keeps track of proxy options, cookies, and all the other options that can apply to more than one request.

If the scheme is https, you must start the SSL application. And when https links need to go through a proxy, the CONNECT method — that's the extension to HTTP-1.1 — is used to establish a tunnel, and then the connection gets upgraded to TLS. But heads up: "TLS upgrade" according to RFC 2817 is not supported. So don't come for her with that. 😭

Pipelining? Only used if the pipeline time-out is set. Otherwise you get persistent connections without pipelining — meaning the client always waits for the previous response before it sends the next request. Very "wait for your turn in the group chat" energy. 💀

Some examples are provided in the Inets User's Guide, if you wanna go look. 👀

🎀 HTTP CLIENT SERVICE START/STOP 🎀

An HTTP client can be configured to start when you start the Inets application, or it can be started dynamically at runtime by calling the Inets application API:

inets:start(httpc, ServiceConfig)

or

inets:start(httpc, ServiceConfig, How)

— see inets(3erl). 🫶

The configuration options are as follows:

  • {profile, Profile :: atom() | pid()} — the name of the profile. This option is mandatory. No profile, no service, no vibes. 💅
  • {data_dir, Path :: string()} — the directory where the profile can save persistent data. If you omit it, all cookies get treated as session cookies (so they ghost you when the session ends 🍪👻). Path represents a file path or directory path.

And to stop the client, you use inets:stop(httpc, Pid) or inets:stop(httpc, Profile). Slay, cleanup. ✨

⚠️ Warning — actually important, don't skip: Please note that httpc normalizes input URIs before internal processing, and you need to take special care when the URI has percent ("%") characters. A percent serves as the indicator for percent-encoded octets — and it must be percent-encoded as "%25" for that octet to be used as data within the URI. For example, in order to send an HTTP GET request with the URI http://localhost/foo%25bar, the percent character must be percent-encoded when creating the request: httpc:request("http://localhost/foo%2525bar"). Like yes it looks cursed. That's the point. 😭

🔥 EXPORTS 🔥

🌸 cancel_request(RequestId) -> ok

🌸 cancel_request(RequestId, Profile) -> ok

Types:

RequestId = any()
   A unique identifier as returned by request/4
Profile = atom() | pid()
   When started stand_alone only the pid can be used.
  • RequestId — a unique identifier, as returned by request/4.
  • Profile — an atom() or a pid(). When started stand_alone, only the pid can be used.

Cancels an asynchronous HTTP request. But listen — this does not guarantee that the request response won't be delivered. Because it's asynchronous, the request can already have been completed by the time the cancellation arrives. It's giving "you tried to leave the group chat but the message already sent". 🙈

Types:

Url = uri_string:uri_string()
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
ProfileOrOpts = Profile | Opts
Profile = atom() | pid()
   When started stand_alone only the pid can be used.
Opts = [CookieHeaderOpt]
CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
Reason = term()
  • Url — a uri_string:uri_string().
  • HttpHeader — a tuple of {Field :: [byte()], Value :: binary() | iolist()}.
  • ProfileOrOpts — either a Profile or Opts, your call, main character. ✨
  • Profile — an atom() or a pid(). When started stand_alone, only the pid can be used.
  • Opts — a list of CookieHeaderOpt.
  • CookieHeaderOpt — {ipv6_host_with_brackets, boolean()}.
  • Reason — a term().

Returns the cookie header that would have been sent when making a request to Url using profile Profile. If no profile is specified, the default profile is used. It's like a little preview of what your cookies are about to say. 🍪

Option ipv6_host_with_bracket deals with how to parse IPv6 addresses. For details, see argument Options of request/[4,5]. (Yes, the docs said it singular there and plural in the type. We don't editorialize, we just report. 💀)

Types:

Url = uri_string:uri_string()
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
Profile = atom() | pid()
   When started stand_alone only the pid can be used.
Opts = [CookieHeaderOpt]
CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
Reason = term()
  • Url — a uri_string:uri_string().
  • HttpHeader — a tuple of {Field :: [byte()], Value :: binary() | iolist()}.
  • Profile — an atom() or a pid(). When started stand_alone, only the pid can be used.
  • Opts — a list of CookieHeaderOpt.
  • CookieHeaderOpt — {ipv6_host_with_brackets, boolean()}.
  • Reason — a term().

Returns the cookie header that would have been sent when making a request to Url using profile Profile. If no profile is specified, the default profile is used.

Option ipv6_host_with_bracket deals with how to parse IPv6 addresses. For details, see argument Options of request/[4,5]. Same deal as above, icon. 💅

🧚 get_options(OptionItems) -> {ok, Values} | {error, Reason}

🧚 get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}

Types:

OptionItems = all | [OptionItem]
OptionItem =
    proxy | https_proxy | max_sessions | keep_alive_timeout |
    max_keep_alive_length | pipeline_timeout |
    max_pipeline_length | cookies | ipfamily | ip | port |
    socket_opts | verbose | unix_socket
Values = [{OptionItem, term()}]
Profile = atom() | pid()
   When started stand_alone only the pid can be used.
Reason = term()
  • OptionItems — either all or a list of OptionItem.
  • OptionItem — one of: proxy, https_proxy, max_sessions, keep_alive_timeout, max_keep_alive_length, pipeline_timeout, max_pipeline_length, cookies, ipfamily, ip, port, socket_opts, verbose, unix_socket.
  • Values — a list of {OptionItem, term()}.
  • Profile — an atom() or a pid(). When started stand_alone, only the pid can be used.
  • Reason — a term().

Retrieves the options currently used by the client. Peak "what are we even doing right now" introspection. 🔍

⭐ info() -> list() | {error, Reason}

⭐ info(Profile) -> list() | {error, Reason}

Types:

Reason = term()
Profile = atom() | pid()
   When started stand_alone only the pid can be used.
  • Reason — a term().
  • Profile — an atom() or a pid(). When started stand_alone, only the pid can be used.

Produces a list of miscellaneous information. Intended for debugging. If no profile is specified, the default profile is used. It's literally just a little gossip dump about the client. 🫶

🌈 reset_cookies() -> Void

🌈 reset_cookies(Profile) -> Void

Types:

Profile = atom() | pid()
   When started stand_alone only the pid can be used.
Void = term()
  • Profile — an atom() or a pid(). When started stand_alone, only the pid can be used.
  • Void — a term().

Resets (clears) the cookie database for the specified Profile. If no profile is specified, the default profile is used. Fresh start, clean slate, unbothered, moisturized. ✨🧖‍♀️

👑 request(Url :: uri_string:uri_string()) -> {ok, Result} | {error, term()}

👑 request(Url, Profile) -> {ok, Result} | {error, term()}

Types:

Url = uri_string:uri_string()
Profile = atom() | pid()
   When started stand_alone only the pid can be used.
Result =
    {StatusLine, [HttpHeader], HttpBodyResult} |
    {StatusCode, HttpBodyResult} |
    RequestId | saved_to_file
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
HttpBodyResult = uri_string:uri_string() | binary()
StatusLine = {HttpVersion, StatusCode, string()}
HttpVersion = uri_string:uri_string()
StatusCode = integer() >= 0
RequestId = any()
  • Url — a uri_string:uri_string().
  • Profile — an atom() or a pid(). When started stand_alone, only the pid can be used.
  • Result — either {StatusLine, [HttpHeader], HttpBodyResult}, or {StatusCode, HttpBodyResult}, or a RequestId, or saved_to_file.
  • HttpHeader — {Field :: [byte()], Value :: binary() | iolist()}.
  • HttpBodyResult — a uri_string:uri_string() or a binary().
  • StatusLine — {HttpVersion, StatusCode, string()}.
  • HttpVersion — a uri_string:uri_string().
  • StatusCode — an integer() >= 0.
  • RequestId — any().

Equivalent to httpc:request(get, {Url, []}, [], []). She's the shortcut, the low-effort bop, the "just GET it" of the family. 💅

🔥 request(Method, Request, HttpOptions, Options) -> {ok, Result} | {error, term()}

🔥 request(Method, Request, HttpOptions, Options, Profile) -> {ok, Result} | {error, term()}

Types:

Method =
    head | get | put | patch | post | trace | options | delete
Request =
    {uri_string:uri_string(), [HttpHeader]} |
    {uri_string:uri_string(),
     [HttpHeader],
     ContentType :: uri_string:uri_string(),
     HttpBody}
HttpBody =
    iolist() |
    binary() |
    {fun((Accumulator :: term()) ->
             eof | {ok, iolist(), Accumulator :: term()}),
     Accumulator :: term()} |
    {chunkify,
     fun((Accumulator :: term()) ->
             eof | {ok, iolist(), Accumulator :: term()}),
     Accumulator :: term()}
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
HttpOptions = [HttpOption]
HttpOption =
    {timeout, timeout()} |
    {connect_timeout, timeout()} |
    {ssl, [ssl:tls_option()]} |
    {autoredirect, boolean()} |
    {proxy_auth, {string(), string()}} |
    {version, HttpVersion} |
    {relaxed, boolean()}
Options = [OptionRequest]
OptionRequest =
    {sync, boolean()} |
    {stream, StreamTo} |
    {body_format, BodyFormat} |
    {full_result, boolean()} |
    {headers_as_is, boolean()} |
    {socket_opts, [SocketOpt]} |
    {receiver, Receiver} |
    {ipv6_host_with_brackets, boolean()} |
    {max_header_size, MaxSize} |
    {max_body_size, MaxSize}
StreamTo = none | self | {self, once} | file:name_all()
BodyFormat = string() | binary() | atom()
SocketOpt = term()
Receiver =
    pid() |
    fun((term()) -> term()) |
    {ReceiverModule :: atom(),
     ReceiverFunction :: atom(),
     ReceiverArgs :: list()}
MaxSize = integer() >= 0 | nolimit
Profile = atom() | pid()
   When Profile is stand_alone only the pid can be used.
HttpVersion = uri_string:uri_string()
Result =
    {StatusLine, [HttpHeader], HttpBodyResult} |
    {StatusCode, HttpBodyResult} |
    RequestId | saved_to_file
StatusLine = {HttpVersion, StatusCode, string()}
StatusCode = integer() >= 0
HttpBodyResult = uri_string:uri_string() | binary()
RequestId = any()
  • Method — head, get, put, patch, post, trace, options, or delete. Pick your fighter. 🥊
  • Request — either {uri_string:uri_string(), [HttpHeader]}, or {uri_string:uri_string(), [HttpHeader], ContentType :: uri_string:uri_string(), HttpBody}.
  • HttpBody — an iolist(), a binary(), a {fun/1, Accumulator} pair, or a {chunkify, fun/1, Accumulator} triple. Lots of shapes, all valid, she's flexible. 🦋
  • HttpHeader — {Field :: [byte()], Value :: binary() | iolist()}.
  • HttpOptions — a list of HttpOption.
  • HttpOption — one of {timeout, timeout()}, {connect_timeout, timeout()}, {ssl, [ssl:tls_option()]}, {autoredirect, boolean()}, {proxy_auth, {string(), string()}}, {version, HttpVersion}, {relaxed, boolean()}.
  • Options — a list of OptionRequest.
  • OptionRequest — one of {sync, boolean()}, {stream, StreamTo}, {body_format, BodyFormat}, {full_result, boolean()}, {headers_as_is, boolean()}, {socket_opts, [SocketOpt]}, {receiver, Receiver}, {ipv6_host_with_brackets, boolean()}, {max_header_size, MaxSize}, {max_body_size, MaxSize}.
  • StreamTo — none, self, {self, once}, or a file:name_all().
  • BodyFormat — a string(), a binary(), or an atom().
  • SocketOpt — a term().
  • Receiver — a pid(), a fun((term()) -> term()), or {ReceiverModule :: atom(), ReceiverFunction :: atom(), ReceiverArgs :: list()}.
  • MaxSize — an integer() >= 0 or nolimit.
  • Profile — an atom() or a pid(). When Profile is stand_alone, only the pid can be used.
  • HttpVersion — a uri_string:uri_string().
  • Result — {StatusLine, [HttpHeader], HttpBodyResult}, or {StatusCode, HttpBodyResult}, or a RequestId, or saved_to_file.
  • StatusLine — {HttpVersion, StatusCode, string()}.
  • StatusCode — an integer() >= 0.
  • HttpBodyResult — a uri_string:uri_string() or a binary().
  • RequestId — any().

Sends an HTTP request. 🚀 The function can be both synchronous and asynchronous — she contains multitudes. In the asynchronous case, the function returns {ok, RequestId} and then the information is delivered to the receiver, depending on that value.

When Profile is stand_alone, only the pid can be used. Not the atom. The pid. Only the pid. Okay? 😤

💜 HTTP options 💜

  • timeout — the time-out time for the request.
    • The clock starts ticking when the request is sent. ⏰
    • Time is in milliseconds.
    • Default is infinity.
  • connect_timeout — the connection time-out time, used during the initial request, when the client is connecting to the server. (That's the "hey are you there" phase. 🫶)
    • Time is in milliseconds.
    • Default is the value of option timeout.
  • ssl — this is the SSL/TLS connecting configuration option.
    • Defaults to []. See ssl:connect/[2,3,4] for available options.
  • autoredirect — the client goes and fetches the thing from the new URI itself and hands you that as the result, instead of giving you back a 30X-result code. 💫 But heads up: for some 30X-result codes, automatic redirect is not allowed, and in those cases the 30X-result is always returned. No sneaky workarounds. Default is true.
  • proxy_auth — a proxy-authorization header, given as a tuple where the first element is the username and the second element of the tuple is the password, added to the request. 🎀
  • version — lets you make the client act as an HTTP/1.0 client. By default this is an HTTP/1.1 client. When using HTTP/1.0, persistent connections are not used (sad, but that's the rules). Default is the string "HTTP/1.1".
  • relaxed — if set to true, workarounds for known server deviations from the HTTP-standard are enabled. Basically giving the server some grace 💅. Default is false.

Options details 🎀

  • sync — option for the request to be synchronous or asynchronous. Default is true.
  • stream — streams the body of a 200 or 206 response to the calling process or to a file. 🦋 When streaming to the calling process using option self, the following stream messages are sent to that process:
{http, {RequestId, stream_start, Headers}}
{http, {RequestId, stream, BinBodyPart}}
{http, {RequestId, stream_end, Headers}}

When streaming to the calling processes using option {self, once}, the first message has an extra element, that is, {http, {RequestId, stream_start, Headers, Pid}}. This is the process id to be used as an argument to httpc:stream_next/1 to trigger the next message to be sent to the calling process. 👑

Notice that chunked encoding can add headers so that there are more headers in the stream_end message than in stream_start. When streaming to a file and the request is asynchronous, the message {http, {RequestId, saved_to_file}} is sent. 📁

Default is none.

  • body_format — defines if the body is to be delivered as a string or binary. This option is only valid for the synchronous request, fyi. Default is string.
  • full_result — defines if a "full result" is to be returned to the caller (that is, the body, the headers, and the entire status line) or not (the body and the status code). Default is true.
  • headers_as_is — defines if the headers provided by the user are to be made lower case or to be regarded as case sensitive.

The HTTP standard requires them to be case insensitive. Use this feature only if there is no other way to communicate with the server or for testing purpose. When this option is used, no headers are automatically added. All necessary headers must be provided by the user, bestie. 😭

Default is false.

  • socket_opts — socket options to be used for this request.

See the options used by gen_tcp(3erl) and ssl(3erl)

Overrides any value set by function set_options.

The validity of the options is not checked by the HTTP client — they are assumed to be correct and passed on to the ssl application and inet driver, which may reject them if they are not correct. 🙈

Note: persistent connections are not supported when setting the socket_opts option. When socket_opts is not set, the current implementation assumes the requests to the same host, port combination will use the same socket options.

By default the socket options set by function set_options/[1,2] are used when establishing a connection.

  • receiver — defines how the client delivers the result of an asynchronous request (sync has the value false). ✨
    • pid() — messages are sent to this process in the format {http, ReplyInfo}.
    • function/1 — information is delivered to the receiver through calls to the provided fun Receiver(ReplyInfo).
    • {Module, Function, Args} — information is delivered to the receiver through calls to the callback function apply(Module, Function, [ReplyInfo | Args]).

In all of these cases, ReplyInfo has the following structure:

{RequestId, saved_to_file}
{RequestId, {error, Reason}}
{RequestId, Result}
{RequestId, stream_start, Headers}
{RequestId, stream_start, Headers, HandlerPid}
{RequestId, stream, BinBodyPart}
{RequestId, stream_end, Headers}

Default is the pid of the process calling the request function (self()).

  • ipv6_host_with_brackets — defines when parsing the Host-Port part of an URI with an IPv6 address with brackets, if those brackets are to be retained (true) or stripped (false). Default is false.

set_options(Options) -> ok | {error, Reason}

set_options(Options, Profile) -> ok | {error, Reason}

Types:

Options = [Option]
Option =
    {proxy, {Proxy, NoProxy}} |
    {https_proxy, {Proxy, NoProxy}} |
    {max_sessions, MaxSessions} |
    {max_keep_alive_length, MaxKeepAlive} |
    {keep_alive_timeout, KeepAliveTimeout} |
    {max_pipeline_length, MaxPipeline} |
    {pipeline_timeout, PipelineTimeout} |
    {cookies, CookieMode} |
    {ipfamily, IpFamily} |
    {ip, IpAddress} |
    {port, Port} |
    {socket_opts, [SocketOpt]} |
    {verbose, VerboseMode} |
    {unix_socket, UnixSocket}
Profile = atom() | pid()
SocketOpt = term()
Proxy = {HostName, Port}
Port = integer() >= 0
NoProxy = [DomainDesc | HostName | IpAddressDesc]
MaxSessions = MaxKeepAlive = KeepAliveTimeout = MaxPipeline =
    PipelineTimeout = integer()
CookieMode = enabled | disabled | verify
IpFamily = inet | inet6 | local | inet6fb4
IpAddressDesc = uri_string:uri_string()
IpAddress = inet:ip_address()
VerboseMode = false | verbose | debug | trace
UnixSocket = string()
Reason = term()
DomainDesc = string()
HostName = uri_string:uri_string()

Sets options to be used for subsequent requests. Like, "remember this for next time" vibes. 🫶

  • HostName — example: "localhost" or "foo.bar.se"
  • DomainDesc — example "*.Domain" or "*.ericsson.se"
  • IpAddressDesc — example: "134.138" or "[FEDC:BA98" (all IP addresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP address). proxy defaults to {undefined, []}, that is, no proxy is configured, and https_proxy defaults to the value of proxy.
  • MaxSessions — MaxSessions maximum number of persistent connections to a host. Default is 2.
  • MaxKeepAlive — MaxKeepAlive maximum number of outstanding requests on the same connection to a host. Default is 5.
  • KeepAliveTimeout — KeepAliveTimeout: if a persistent connection is idle longer than the keep_alive_timeout in milliseconds, the client closes the connection. The server can also have such a time-out, but do not take that for granted. Default is 120000 (= 2 min). ⏰
  • MaxPipeline — MaxPipeline maximum number of outstanding requests on a pipelined connection to a host. Default is 2.
  • PipelineTimeout — PipelineTimeout: if a persistent connection is idle longer than the pipeline_timeout in milliseconds, the client closes the connection. Default is 0, which results in pipelining not being used.
  • CookieMode — if cookies are enabled, all valid cookies are automatically saved in the cookie database of the client manager. If option verify is used, function store_cookies/2 has to be called for the cookies to be saved. Default is disabled. 🍪
  • IpFamily — default is inet. With inet6fb4 option, IPv6 will be preferred but if connection fails, an IPv4 fallback connection attempt will be made. best of both worlds fr fr 🌈
  • IpAddress — if the host has several network interfaces, this option specifies which one to use. See gen_tcp:connect/3,4 for details.
  • Port — example: 8080. Local port number to use. See gen_tcp:connect/3,4 for details.
  • SocketOpts — the options are appended to the socket options used by the client. These are the default values when a new request handler is started (for the initial connect). They are passed directly to the underlying transport (gen_tcp or SSL) without verification.

See the options used by gen_tcp(3erl) and ssl(3erl)

  • VerboseMode — default is false. This option is used to switch on (or off) different levels of Erlang trace on the client. It is a debug feature. 🔍
  • Profile — when started stand_alone only the pid can be used.
  • UnixSocket — experimental option for sending HTTP requests over a unix domain socket. The value of unix_socket shall be the full path to a unix domain socket file with read/write permissions for the erlang process. Default is undefined.
Note: if possible, the client keeps its connections alive and uses persistent connections with or without pipeline depending on configuration and current circumstances. The HTTP/1.1 specification does not provide a guideline for how many requests that are ideal to be sent on a persistent connection. This depends much on the application. 💀

Real talk about max_sessions, bestie: a long queue of requests can cause a user-perceived delay, because earlier requests can take a long time to complete. The HTTP/1.1 specification suggests a limit of two persistent connections per server — and that is literally the default value of option max_sessions. Also, the current implementation assumes that requests to the same host, port combination will use the same socket options. ✨

🌈 ssl_verify_host_options(WildcardHostName) -> list()

Types:

WildcardHostName = boolean()

This one returns ssl options you can use to verify the host. It uses public_key:cacerts_get() to read CA certificates, and if WildcardHostName is true, it adds the hostname check from public_key:public_key:pkix_verify_hostname_match_fun(https) to the options. Very “trust but verify” of it. 💅

🍓 store_cookies(SetCookieHeaders, Url) -> ok | {error, Reason} / store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}

Types:

SetCookieHeaders = [HttpHeader]
   Where field = "set-cookie"
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
Url = term()
Profile = atom() | pid()
   When started stand_alone only the pid can be used.
Reason = term()

Saves the cookies defined in SetCookieHeaders in the client profile cookie database. Call this function if option cookies is set to verify. If no profile is specified, the default profile is used. Cookie storage era, no cap. 🍪💖

⭐ stream_next(Pid) -> ok

Types:

Pid = pid()
   As received in the stream_start message

Triggers the next message to be streamed — that is, the same behavior as active ones for sockets. It’s literally the “next bestie please” button. 😭

🎀 which_cookies() -> [CookieStores] / which_cookies(Profile) -> [CookieStores]

Types:

Profile = atom() | pid()
   When started stand_alone only the pid can be used.
CookieStores = {cookies, Cookies} | {session_cookies, Cookies}
Cookies = [term()]

Produces a list of the entire cookie database. Intended for debugging/testing purposes. If no profile is specified, the default profile is used. Detective mode: activated. 🔍🫶

👑 which_sessions() -> SessionInfo / which_sessions(Profile) -> SessionInfo

Types:

Profile = atom() | pid()
   When started stand_alone only the pid can be used.
SessionInfo = {GoodSession, BadSessions, NonSessions}
GoodSession = [Session]
BadSessions = NonSessions = [term()]
Session = term()
   Internal representation of a session.

This function is intended for debugging only. It produces a slightly processed dump of the session database. The first list of the session information tuple will contain session information on an internal format. The last two lists of the session information tuple should always be empty if the code is working as intended. If no profile is specified, the default profile is used. Vibe check on the session DB, fr fr. 🧚💜

👀 SEE ALSO 👀

Footer sign-off, with source/version/date energy: Ericsson AB · inets 8.3.1.2 · httpc(3erl) 🎀✨

📦 where this page comes from