Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update adapter docs suggested behaviour regarding chunk/2 return types #1204

Merged
merged 1 commit into from
Jan 15, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Update adapter docs suggested behaviour regarding chunk/2 return types
  • Loading branch information
mtrudel committed Jan 15, 2024
commit 3ea5b0bc380dd571ef06785a643c387431cd2d0e
19 changes: 11 additions & 8 deletions lib/plug/conn/adapter.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -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.
Expand Down