Skip to content

Commit 5a16e4f

Browse files
Expand body stream lifecycle documentation
Assisted-By: devx/618580b0-d55f-4c2e-95b6-87e648f60543
1 parent 00614ac commit 5a16e4f

5 files changed

Lines changed: 44 additions & 4 deletions

File tree

‎context/message-body.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,23 @@ content = uppercase.join # => "HELLO WORLD"
259259

260260
## Life-cycle
261261

262+
Bodies model application-facing streams. Their close operations describe what the application will do next; protocol implementations are responsible for mapping those operations to the wire protocol safely.
263+
264+
### Directional Closure
265+
266+
Request and response bodies are independent, so a bidirectional {ruby Protocol::HTTP::Body::Stream} can close either direction without implicitly closing the other:
267+
268+
| Operation | Application-level meaning | Typical protocol consequence |
269+
| --- | --- | --- |
270+
| `read` returns `nil` | The peer or producer completed the input normally. | The inbound body has reached end-of-stream. |
271+
| `close_read` before end-of-stream | The application will not consume the remaining input, but may continue writing. | Discard unread data, terminate the exchange, or make the connection non-reusable. |
272+
| `close_write` without an error | The application has finished producing output, but may continue reading. | Preserve previously written data and send a normal end-of-stream. |
273+
| `close` without an error | The application has finished with both directions. | Complete or terminate the exchange without reporting an application error. |
274+
| `close` with an error | The application cannot continue the exchange successfully. | Propagate the error or terminate the exchange using an appropriate protocol error. |
275+
| `discard` | Consume input without processing it. | Prefer preserving the exchange or connection for reuse. |
276+
277+
These operations update local application-facing state. Returning from a close operation does not guarantee that the peer has observed it or that the underlying transport has been closed synchronously. Those details depend on the protocol and may be completed later.
278+
262279
### Initialization
263280

264281
Bodies are typically initialized with the data they need to process. For example:

‎guides/message-body/readme.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,23 @@ content = uppercase.join # => "HELLO WORLD"
259259

260260
## Life-cycle
261261

262+
Bodies model application-facing streams. Their close operations describe what the application will do next; protocol implementations are responsible for mapping those operations to the wire protocol safely.
263+
264+
### Directional Closure
265+
266+
Request and response bodies are independent, so a bidirectional {ruby Protocol::HTTP::Body::Stream} can close either direction without implicitly closing the other:
267+
268+
| Operation | Application-level meaning | Typical protocol consequence |
269+
| --- | --- | --- |
270+
| `read` returns `nil` | The peer or producer completed the input normally. | The inbound body has reached end-of-stream. |
271+
| `close_read` before end-of-stream | The application will not consume the remaining input, but may continue writing. | Discard unread data, terminate the exchange, or make the connection non-reusable. |
272+
| `close_write` without an error | The application has finished producing output, but may continue reading. | Preserve previously written data and send a normal end-of-stream. |
273+
| `close` without an error | The application has finished with both directions. | Complete or terminate the exchange without reporting an application error. |
274+
| `close` with an error | The application cannot continue the exchange successfully. | Propagate the error or terminate the exchange using an appropriate protocol error. |
275+
| `discard` | Consume input without processing it. | Prefer preserving the exchange or connection for reuse. |
276+
277+
These operations update local application-facing state. Returning from a close operation does not guarantee that the peer has observed it or that the underlying transport has been closed synchronously. Those details depend on the protocol and may be completed later.
278+
262279
### Initialization
263280

264281
Bodies are typically initialized with the data they need to process. For example:

‎lib/protocol/http/body/stream.rb‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,8 @@ def flush
353353
#
354354
# Closing without an error represents orderly application-level abandonment, not a protocol failure.
355355
#
356+
# This method is idempotent. After the first call, subsequent calls have no effect.
357+
#
356358
# If, while processing the data that was read from this stream, an error is encountered, it should be passed to this method.
357359
#
358360
# @parameter error [Exception | Nil] The error that was encountered, if any.
@@ -368,7 +370,9 @@ def close_read(error = nil)
368370

369371
# Close the application-facing output body. This does not close the input body, which may continue to be read independently.
370372
#
371-
# Closing without an error indicates that no more output will be produced and should be represented as a normal end-of-stream by the protocol implementation. If an error is provided, the protocol implementation may terminate the exchange instead.
373+
# Closing without an error indicates that no more output will be produced. Previously written data remains part of the output and should be followed by a normal end-of-stream from the protocol implementation. If an error is provided, the protocol implementation may terminate the exchange instead.
374+
#
375+
# This method is idempotent. After the first call, subsequent calls have no effect.
372376
#
373377
# If, while generating the data that is written to this stream, an error is encountered, it should be passed to this method.
374378
#
@@ -385,6 +389,8 @@ def close_write(error = nil)
385389
#
386390
# Closing without an error represents orderly completion or abandonment of both application-facing directions, not cancellation. If the peer has not completed the exchange, the protocol implementation may need to terminate it without reporting an application error.
387391
#
392+
# Repeated calls are safe; each underlying direction will be closed at most once.
393+
#
388394
# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
389395
def close(error = nil)
390396
self.close_read(error)

‎lib/protocol/http/body/streamable.rb‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ module Body
1515
#
1616
# In some cases, it's advantageous to directly read and write to the underlying stream if possible. For example, HTTP/1 upgrade requests, WebSockets, and similar. To handle that case, response bodies can implement {stream?} and return `true`. When {stream?} returns true, the body **should** be consumed by calling `call(stream)`. Server implementations may choose to always invoke `call(stream)` if it's efficient to do so. Bodies that don't support it will fall back to using {each}.
1717
#
18-
# When invoking `call(stream)`, the stream can be read from and written to, and closed. However, the stream is only guaranteed to be open for the duration of the `call(stream)` call. Once the method returns, the stream **should** be closed by the server.
18+
# Invoking `call(stream)` transfers ownership of the stream to the called body. The body may read from and write to the stream, and **must** close it before returning. The caller must consider the stream closed and unusable after `call(stream)` returns.
1919
module Streamable
2020
# Generate a new streaming request body using the given block to generate the body.
2121
#
@@ -113,7 +113,7 @@ def read
113113
@output.read
114114
end
115115

116-
# Invoke the block with the given stream. The block can read and write to the stream, and must close the stream when finishing.
116+
# Invoke the block with the given stream. The block owns the stream for the duration of the call and must close it before returning.
117117
#
118118
# @parameter stream [Stream] The stream to read and write to.
119119
def call(stream)

‎releases.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Unreleased
44

5-
- Clarified the directional semantics of `Protocol::HTTP::Body::Stream#close_read`, `#close_write`, and `#close`, including how premature input closure affects the associated HTTP exchange.
5+
- Clarified body stream lifecycle and ownership, including the directional semantics of `Protocol::HTTP::Body::Stream#close_read`, `#close_write`, and `#close`, how premature input closure affects the associated HTTP exchange, and ownership of streams passed to `Streamable#call`.
66

77
## v0.71.0
88

0 commit comments

Comments
 (0)