From 67cbc7cfcf71bfe01ec36fb743167d7f5865b70a Mon Sep 17 00:00:00 2001 From: Mat Trudel Date: Mon, 15 Jan 2024 15:16:25 -0500 Subject: [PATCH] Update adapter docs suggested behaviour regarding `chunk/2` return types (#1204) --- lib/plug/conn/adapter.ex | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/lib/plug/conn/adapter.ex b/lib/plug/conn/adapter.ex index 72aad7f1..3c0c81ce 100644 --- a/lib/plug/conn/adapter.ex +++ b/lib/plug/conn/adapter.ex @@ -84,9 +84,11 @@ defmodule Plug.Conn.Adapter do a chunked response to the client. Webservers are advised to return `nil` as the sent_body, - as the body can no longer be manipulated. However, the - test implementation returns the actual body so it can - be used during testing. + since this function does not actually produce a body. + However, the test implementation returns an empty binary + as the body in order to be consistent with the built-up + body returned by subsequent calls to the test implementation's + `chunk/2` function """ @callback send_chunked(payload, status :: Conn.status(), headers :: Conn.headers()) :: {:ok, sent_body :: binary | nil, payload} @@ -97,13 +99,14 @@ defmodule Plug.Conn.Adapter do If the request has method `"HEAD"`, the adapter should not send the response to the client. - Webservers are advised to return `:ok` and not modify - any further state for each chunk. However, the test - implementation returns the actual body and payload so - it can be used during testing. + Webservers are advised to return `nil` as the sent_body, + since the complete sent body depends on the sum of all + calls to this function. However, the test implementation + tracks the overall body and payload so it can be used + during testing. """ @callback chunk(payload, body :: Conn.body()) :: - :ok | {:ok, sent_body :: binary, payload} | {:error, term} + :ok | {:ok, sent_body :: binary | nil, payload} | {:error, term} @doc """ Reads the request body.