Add custom timeout option for requests

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v4.2.0 - 2025-02-25
+
+- Added the `timeout` configuration option.
+
 ## v4.1.0 - 2025-02-08
 
 - Added the `follow_redirects` configuration option.

gleam.toml

@@ -1,5 +1,5 @@
 name = "gleam_httpc"
-version = "4.1.0"
+version = "4.2.0"
 gleam = ">= 1.0.0"
 
 licences = ["Apache-2.0"]

src/gleam/httpc.gleam

@@ -5,12 +5,16 @@ import gleam/http.{type Method}
 import gleam/http/request.{type Request}
 import gleam/http/response.{type Response, Response}
 import gleam/list
+import gleam/option.{type Option, None, Some}
 import gleam/result
 import gleam/uri
 
 pub type HttpError {
   InvalidUtf8Response
   FailedToConnect(ip4: ConnectError, ip6: ConnectError)
+  /// The response body was not received within the configured timeout period
+  /// 
+  RequestTimeout
 }
 
 pub type ConnectError {
@@ -27,6 +31,7 @@ fn normalise_error(error: Dynamic) -> HttpError
 type ErlHttpOption {
   Ssl(List(ErlSslOption))
   Autoredirect(Bool)
+  Timeout(Int)
 }
 
 type BodyFormat {
@@ -106,7 +111,10 @@ pub fn dispatch_bits(
     |> uri.to_string
     |> charlist.from_string
   let erl_headers = prepare_headers(req.headers)
-  let erl_http_options = [Autoredirect(config.follow_redirects)]
+  let erl_http_options = case config.timeout {
+    None -> [Autoredirect(config.follow_redirects)]
+    Some(timeout) -> [Autoredirect(config.follow_redirects), Timeout(timeout)]
+  }
   let erl_http_options = case config.verify_tls {
     True -> erl_http_options
     False -> [Ssl([Verify(VerifyNone)]), ..erl_http_options]
@@ -155,13 +163,18 @@ pub opaque type Configuration {
     /// Whether to follow redirects.
     ///
     follow_redirects: Bool,
+    /// Timeout for the request in milliseconds.
+    /// This defaults to `Infinity`, meaning the request will not raise a timeout error 
+    /// unless you provide a timeout value.
+    ///
+    timeout: Option(Int),
   )
 }
 
 /// Create a new configuration with the default settings.
 ///
 pub fn configure() -> Configuration {
-  Builder(verify_tls: True, follow_redirects: False)
+  Builder(verify_tls: True, follow_redirects: False, timeout: None)
 }
 
 /// Set whether to verify the TLS certificate of the server.
@@ -182,6 +195,12 @@ pub fn follow_redirects(config: Configuration, which: Bool) -> Configuration {
   Builder(..config, follow_redirects: which)
 }
 
+/// Set the timeout for the request in milliseconds.
+/// The default timeout value is `Infinity`, meaning the request will not raise a timeout error unless this is called
+pub fn set_timeout(config: Configuration, timeout: Int) -> Configuration {
+  Builder(..config, timeout: Some(timeout))
+}
+
 /// Send a HTTP request of unicode data.
 ///
 pub fn dispatch(

src/gleam_httpc_ffi.erl

@@ -11,6 +11,8 @@ normalise_error(Error = {failed_connect, Opts}) ->
         _ -> erlang:error({unexpected_httpc_error, Error})
     end,
     {failed_to_connect, normalise_ip_error(Ipv4), normalise_ip_error(Ipv6)};
+normalise_error(timeout) -> 
+    request_timeout;
 normalise_error(Error) ->
     erlang:error({unexpected_httpc_error, Error}).
 

test/gleam_httpc_test.gleam

@@ -1,3 +1,4 @@
+import gleam/erlang/atom
 import gleam/http.{Get, Head, Options}
 import gleam/http/request
 import gleam/http/response
@@ -133,3 +134,31 @@ pub fn custom_user_agent_test() {
     httpc.send(request.set_header(req, "user-agent", "gleam-test"))
   let assert True = string.contains(resp.body, "\"User-Agent\": \"gleam-test")
 }
+
+pub fn timeout_success_test() {
+  let req =
+    request.new()
+    |> request.set_method(Get)
+    |> request.set_host("httpbin.org")
+    |> request.set_path("/delay/1")
+
+  let assert Ok(resp) =
+    httpc.configure()
+    |> httpc.set_timeout(5000)
+    |> httpc.dispatch(req)
+
+  let assert 200 = resp.status
+}
+
+pub fn timeout_error_test() {
+  let req =
+    request.new()
+    |> request.set_method(Get)
+    |> request.set_host("httpbin.org")
+    |> request.set_path("/delay/1")
+
+  let assert Error(httpc.RequestTimeout) =
+    httpc.configure()
+    |> httpc.set_timeout(200)
+    |> httpc.dispatch(req)
+}