From 352206dee80905b10fa9af97f065ce7bee928d87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 26 Apr 2019 15:59:58 +0200
Subject: Add specs to await functions, document error type better

---
 doc/src/manual/gun.await.asciidoc      | 15 ++++++++-------
 doc/src/manual/gun.await_body.asciidoc |  3 ++-
 doc/src/manual/gun.await_up.asciidoc   |  2 +-
 src/gun.erl                            | 26 +++++++++++++++++++++-----
 4 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/doc/src/manual/gun.await.asciidoc b/doc/src/manual/gun.await.asciidoc
index 21de953..09c244b 100644
--- a/doc/src/manual/gun.await.asciidoc
+++ b/doc/src/manual/gun.await.asciidoc
@@ -65,13 +65,14 @@ may also be returned when a timeout or an error occur.
 [source,erlang]
 ----
 Result :: {inform, Status, Headers}
-          {response, IsFin, Status, Headers}
-          {data, IsFin, Data}
-          {trailers, Trailers}
-          {push, NewStreamRef, Method, URI, Headers}
-          {error, Reason}
-
-Reason :: timeout | any()
+        | {response, IsFin, Status, Headers}
+        | {data, IsFin, Data}
+        | {trailers, Trailers}
+        | {push, NewStreamRef, Method, URI, Headers}
+        | {error, Reason}
+
+Reason :: {stream_error | connection_error | down, any()}
+        | timeout
 ----
 
 Because the messages and returned tuples are equivalent,
diff --git a/doc/src/manual/gun.await_body.asciidoc b/doc/src/manual/gun.await_body.asciidoc
index 9ac26d9..0505112 100644
--- a/doc/src/manual/gun.await_body.asciidoc
+++ b/doc/src/manual/gun.await_body.asciidoc
@@ -26,7 +26,8 @@ MonitorRef :: reference()
 Timeout    :: timeout()
 Body       :: binary()
 Trailers   :: [{binary(), binary()}]
-Reason     :: timeout | any()
+Reason     :: {stream_error | connection_error | down, any()}
+            | timeout
 ----
 
 Wait for the complete response body.
diff --git a/doc/src/manual/gun.await_up.asciidoc b/doc/src/manual/gun.await_up.asciidoc
index 3937665..2639943 100644
--- a/doc/src/manual/gun.await_up.asciidoc
+++ b/doc/src/manual/gun.await_up.asciidoc
@@ -24,7 +24,7 @@ ConnPid    :: pid()
 MonitorRef :: reference()
 Timeout    :: timeout()
 Protocol   :: http | http2
-Reason     :: timeout | any()
+Reason     :: {down, any()} | timeout
 ----
 
 Wait for the connection to be up.
diff --git a/src/gun.erl b/src/gun.erl
index d5a39af..b1f493b 100644
--- a/src/gun.erl
+++ b/src/gun.erl
@@ -488,14 +488,22 @@ connect(ServerPid, Destination, Headers, ReqOpts) ->
 
 %% Awaiting gun messages.
 
-%% @todo spec await await_body
-
+-type resp_headers() :: [{binary(), binary()}].
+-type await_result() :: {inform, 100..199, resp_headers()}
+	| {response, fin | nofin, non_neg_integer(), resp_headers()}
+	| {data, fin | nofin, binary()}
+	| {trailers, resp_headers()}
+	| {push, reference(), binary(), binary(), resp_headers()}
+	| {error, {stream_error | connection_error | down, any()} | timeout}.
+
+-spec await(pid(), reference()) -> await_result().
 await(ServerPid, StreamRef) ->
 	MRef = monitor(process, ServerPid),
 	Res = await(ServerPid, StreamRef, 5000, MRef),
 	demonitor(MRef, [flush]),
 	Res.
 
+-spec await(pid(), reference(), timeout() | reference()) -> await_result().
 await(ServerPid, StreamRef, MRef) when is_reference(MRef) ->
 	await(ServerPid, StreamRef, 5000, MRef);
 await(ServerPid, StreamRef, Timeout) ->
@@ -505,6 +513,7 @@ await(ServerPid, StreamRef, Timeout) ->
 	Res.
 
 %% @todo Add gun_upgrade and gun_ws?
+-spec await(pid(), reference(), timeout(), reference()) -> await_result().
 await(ServerPid, StreamRef, Timeout, MRef) ->
 	receive
 		{gun_inform, ServerPid, StreamRef, Status, Headers} ->
@@ -527,12 +536,18 @@ await(ServerPid, StreamRef, Timeout, MRef) ->
 		{error, timeout}
 	end.
 
+-type await_body_result() :: {ok, binary()}
+	| {ok, binary(), resp_headers()}
+	| {error, {stream_error | connection_error | down, any()} | timeout}.
+
+-spec await_body(pid(), reference()) -> await_body_result().
 await_body(ServerPid, StreamRef) ->
 	MRef = monitor(process, ServerPid),
 	Res = await_body(ServerPid, StreamRef, 5000, MRef, <<>>),
 	demonitor(MRef, [flush]),
 	Res.
 
+-spec await_body(pid(), reference(), timeout() | reference()) -> await_body_result().
 await_body(ServerPid, StreamRef, MRef) when is_reference(MRef) ->
 	await_body(ServerPid, StreamRef, 5000, MRef, <<>>);
 await_body(ServerPid, StreamRef, Timeout) ->
@@ -541,6 +556,7 @@ await_body(ServerPid, StreamRef, Timeout) ->
 	demonitor(MRef, [flush]),
 	Res.
 
+-spec await_body(pid(), reference(), timeout(), reference()) -> await_body_result().
 await_body(ServerPid, StreamRef, Timeout, MRef) ->
 	await_body(ServerPid, StreamRef, Timeout, MRef, <<>>).
 
@@ -565,14 +581,14 @@ await_body(ServerPid, StreamRef, Timeout, MRef, Acc) ->
 		{error, timeout}
 	end.
 
--spec await_up(pid()) -> {ok, http | http2} | {error, atom()}.
+-spec await_up(pid()) -> {ok, http | http2} | {error, {down, any()} | timeout}.
 await_up(ServerPid) ->
 	MRef = monitor(process, ServerPid),
 	Res = await_up(ServerPid, 5000, MRef),
 	demonitor(MRef, [flush]),
 	Res.
 
--spec await_up(pid(), reference() | timeout()) -> {ok, http | http2} | {error, atom()}.
+-spec await_up(pid(), reference() | timeout()) -> {ok, http | http2} | {error, {down, any()} | timeout}.
 await_up(ServerPid, MRef) when is_reference(MRef) ->
 	await_up(ServerPid, 5000, MRef);
 await_up(ServerPid, Timeout) ->
@@ -581,7 +597,7 @@ await_up(ServerPid, Timeout) ->
 	demonitor(MRef, [flush]),
 	Res.
 
--spec await_up(pid(), timeout(), reference()) -> {ok, http | http2} | {error, atom()}.
+-spec await_up(pid(), timeout(), reference()) -> {ok, http | http2} | {error, {down, any()} | timeout}.
 await_up(ServerPid, Timeout, MRef) ->
 	receive
 		{gun_up, ServerPid, Protocol} ->
-- 
cgit v1.2.3