Deprecate Plug.Conn's Collectable protocol implementation (elixir-plu…

…g#673)
ddresselhaus · Mar 4, 2018 · 963b1f3 · 963b1f3
1 parent c17ecd2
commit 963b1f3
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 2 deletions.
diff --git a/lib/plug/conn.ex b/lib/plug/conn.ex
@@ -475,6 +475,23 @@ defmodule Plug.Conn do
   It expects a connection with state `:chunked` as set by
   `send_chunked/2`. It returns `{:ok, conn}` in case of success,
   otherwise `{:error, reason}`.
+
+  To stream data use `Enum.reduce_while/3` instead of `Enum.into/2`.
+  `Enum.reduce_while/3` allows aborting the execution if `chunk/2` fails to
+  deliver the chunk of data.
+
+  ## Example
+
+      ~w(each chunk as a word)
+      |> Enum.reduce_while(conn, fn (chunk, conn) ->
+        case Plug.Conn.chunk(conn, chunk) do
+          {:ok, conn} ->
+            {:cont, conn}
+          {:error, :closed} ->
+            {:halt, conn}
+        end
+      end)
+
   """
   @spec chunk(t, body) :: {:ok, t} | {:error, term} | no_return
   def chunk(%Conn{adapter: {adapter, payload}, state: :chunked} = conn, chunk) do
@@ -1356,6 +1373,27 @@ end
 
 defimpl Collectable, for: Plug.Conn do
   def into(conn) do
+    IO.puts(:stderr, """
+    warning: using Enum.into/2 for conn is deprecated, use Enum.reduce_while/3 instead:
+
+    To stream data use `Enum.reduce_while/3` instead of `Enum.into/2`.
+    `Enum.reduce_while/3` allows aborting the execution if `chunk/2` fails to
+    deliver the chunk of data.
+
+    Example
+
+        ~w(each chunk as a word)
+        |> Enum.reduce_while(conn, fn (chunk, conn) ->
+          case Plug.Conn.chunk(conn, chunk) do
+            {:ok, conn} ->
+              {:cont, conn}
+            {:error, :closed} ->
+              {:halt, conn}
+          end
+        end)
+
+    """)
+
     fun = fn
       conn, {:cont, x} ->
         {:ok, conn} = Plug.Conn.chunk(conn, x)

diff --git a/test/plug/conn_test.exs b/test/plug/conn_test.exs
@@ -5,6 +5,8 @@ defmodule Plug.ConnTest do
   alias Plug.Conn
   alias Plug.ProcessStore
 
+  import ExUnit.CaptureIO
+
   test "test adapter builds on connection" do
     conn =
       Plug.Adapters.Test.Conn.conn(%Plug.Conn{private: %{hello: :world}}, :post, "/hello", nil)
@@ -360,8 +362,11 @@ defmodule Plug.ConnTest do
 
   test "send_chunked/3 with collectable" do
     conn = send_chunked(conn(:get, "/foo"), 200)
-    conn = Enum.into(~w(hello world), conn)
-    assert conn.resp_body == "helloworld"
+
+    capture_io(:stderr, fn ->
+      conn = Enum.into(~w(hello world), conn)
+      assert conn.resp_body == "helloworld"
+    end)
   end
 
   test "send_chunked/3 sends self a message" do