# `HTTP.Stream`
[🔗](https://github.com/gsmlg-dev/http_fetch/blob/v0.21.17/apps/http_fetch/lib/http/stream.ex#L1)

Process-backed readable stream used for Fetch-style response and request bodies.

Streamed responses expose this PID in `HTTP.Response.body`. Streaming uploads can
pass a stream PID as `body` when `HTTP.fetch/2` is called with `duplex: "half"`.
Producers write chunks with `chunk/3` and finish with `finish/1`; consumers read
by sending `{:read_chunk, pid}` or `{:read_chunk, pid, :ack}`.

# `chunk`

```elixir
@spec chunk(pid(), binary(), timeout()) :: :ok | {:error, term()}
```

# `error`

```elixir
@spec error(pid(), term()) :: :ok
```

# `finish`

```elixir
@spec finish(pid()) :: :ok
```

# `finish`

```elixir
@spec finish(pid(), HTTP.Headers.t() | HTTP.Headers.headers_list()) ::
  :ok | {:error, term()}
```

Finishes a stream with ordered trailer fields (a list or `HTTP.Headers`).

Validation limits trailers to 128 fields and 65,536 serialized bytes. Invalid
trailers return an error without finishing the stream. For HTTP/1 uploads,
every field must be declared in the request's `Trailer` header and the body
must use chunk framing (no `Content-Length`). HTTP/2 uploads send trailing
HEADERS after acknowledged DATA; fixed content length counts DATA bytes only.
HTTP/3 uploads send ordered trailing HEADERS with FIN after acknowledged DATA;
valid `Trailer` declarations are optional.
Completion is signalled asynchronously, like `finish/1`.

# `from_enumerable`

```elixir
@spec from_enumerable(Enumerable.t(), keyword()) :: {:ok, pid()} | {:error, term()}
```

Creates a stream from an enumerable.

Pass `telemetry: false` in the optional second argument to silence producer
streaming events. The default is `true`.

Each enumerable item is converted to binary and emitted with backpressure. The
returned PID can be passed as a streaming request body:

    {:ok, stream} = HTTP.Stream.from_enumerable(["hello", " ", "world"])
    HTTP.fetch(url, method: :post, body: stream, duplex: "half")

# `start_link`

```elixir
@spec start_link(non_neg_integer()) :: {:ok, pid()}
```

# `trailers`

Sends response trailers to the reader before the terminal stream event.

---

*Consult [api-reference.md](api-reference.md) for complete listing*