http3 0.0.4 → 0.0.5

data/ext/http3/session.c

@@ -6,6 +6,7 @@
 #include <stdlib.h>
 #include <string.h>
 #include <sys/random.h>
+#include <time.h>
 #include <unistd.h>
 
 /*
@@ -28,7 +29,7 @@
 VALUE rb_cHTTP3Session;
 
 static ID id_on_begin_headers, id_on_header, id_on_end_headers, id_on_data,
-    id_on_end_stream, id_on_fields_too_large, id_on_reset;
+    id_on_end_stream, id_on_fields_too_large, id_on_reset, id_on_stop_sending;
 
 /* What h3_session.field_sizes holds for a request whose header section has
  * gone over max_field_section_size. */
@@ -65,12 +66,19 @@ typedef struct {
   size_t nchunks, cap;
   size_t handed;    /* how many of chunks read_data has handed to nghttp3 */
   uint64_t unsent;  /* bytes queued but not handed to nghttp3 yet */
+  uint64_t queued;  /* bytes ever queued, the pieces read from a file too */
   uint64_t acked;   /* bytes the peer has acknowledged */
   uint64_t shifted; /* bytes of the chunks already dropped */
   int fd;           /* a file body (#attach_file) not read in full yet, or -1 */
   off_t file_off, file_end;
-  bool eof;     /* nothing follows the queued chunks */
-  bool blocked; /* read_data returned NGHTTP3_ERR_WOULDBLOCK */
+  /* When the body began to wait on the peer, or last moved: the peer
+   * acknowledged some of it, or widened the stream's flow control window
+   * (CLOCK_MONOTONIC seconds; #response_stalled_since) */
+  double since;
+  bool fc_blocked; /* the peer's flow control window holds it back */
+  bool eof;        /* nothing follows the queued chunks */
+  bool blocked;    /* read_data returned NGHTTP3_ERR_WOULDBLOCK */
+  bool aborted;    /* #abort_stream stopped it: no more of the body is sent */
 } h3_stream;
 
 typedef struct {
@@ -89,8 +97,18 @@ typedef struct {
   /* stream_id => size of the header section received so far, while the
    * headers of that request come in */
   st_table *field_sizes;
+  /* When the peer last acknowledged some response body, on any stream
+   * (CLOCK_MONOTONIC seconds) */
+  double acked_at;
 } h3_session;
 
+/* CLOCK_MONOTONIC in seconds, as Process.clock_gettime gives it. */
+static double h3_now(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (double)ts.tv_sec + (double)ts.tv_nsec / 1e9;
+}
+
 /* Streams */
 
 static void h3_chunk_release(h3_chunk *chunk) {
@@ -130,9 +148,20 @@ static int h3_stream_push(h3_stream *st, const uint8_t *base, size_t len,
   }
   st->chunks[st->nchunks++] = (h3_chunk){base, len, str};
   st->unsent += len;
+  st->queued += len;
   return 0;
 }
 
+/* Bytes of the body the peer has not acknowledged: queued, the rest of a
+ * file not read yet, or sent; 0 once the stream has been aborted. */
+static uint64_t h3_stream_unacked(const h3_stream *st) {
+  if (st->aborted) {
+    return 0;
+  }
+  uint64_t rest = st->fd >= 0 ? (uint64_t)(st->file_end - st->file_off) : 0;
+  return st->queued - st->acked + rest;
+}
+
 /* The whole file body has been read: let go of its descriptor now rather
  * than when the stream closes, which waits for the peer to acknowledge
  * every byte. */
@@ -142,6 +171,24 @@ static void h3_stream_end_file(h3_stream *st) {
   st->eof = true;
 }
 
+/* The stream has been aborted, and no more of its body will be sent: let go
+ * at once of what nghttp3 has not taken, and of the file's descriptor,
+ * rather than when the stream closes, which waits for the peer to
+ * acknowledge the reset. The chunks nghttp3 has taken stay until then,
+ * since it still points into them. */
+static void h3_stream_abort(h3_stream *st) {
+  for (size_t i = st->handed; i < st->nchunks; i++) {
+    h3_chunk_release(&st->chunks[i]);
+  }
+  st->nchunks = st->handed;
+  st->unsent = 0;
+  if (st->fd >= 0) {
+    close(st->fd);
+    st->fd = -1;
+  }
+  st->aborted = true;
+}
+
 /* Drop the chunks at the front the peer has acknowledged to their end. A
  * chunk acknowledged only in part stays. */
 static void h3_stream_acked(h3_stream *st, uint64_t n) {
@@ -276,7 +323,14 @@ static VALUE h3_end_headers_body(VALUE arg) {
 static int h3_acked_stream_data_cb(nghttp3_conn *conn, int64_t id,
                                    uint64_t datalen, void *user_data,
                                    void *stream_user_data) {
-  h3_stream *st = h3_stream_find(user_data, id);
+  h3_session *s = user_data;
+  h3_stream *st = h3_stream_find(s, id);
+  if (datalen > 0) {
+    s->acked_at = h3_now();
+    if (st != NULL) {
+      st->since = s->acked_at;
+    }
+  }
   if (st != NULL) {
     h3_stream_acked(st, datalen);
   }
@@ -468,7 +522,7 @@ static void h3_raise(h3_session *s, int rv, const char *message) {
   if (nghttp3_err_is_fatal(rv) || rv == NGHTTP3_ERR_QPACK_FATAL) {
     h3_fail(s, rv);
   }
-  nghttp3_rb_raise(rv, message);
+  nghttp3_rb_raise(rv, "%s", message);
 }
 
 /* Make the nghttp3 connection and its three unidirectional streams, as
@@ -579,14 +633,22 @@ static int h3_stream_data_written(void *ud, int64_t id, size_t n) {
   return rv == 0 ? 0 : h3_fail(s, rv);
 }
 
+/* The peer's flow control window for the stream is used up. */
 static int h3_stream_blocked(void *ud, int64_t id) {
   h3_session *s = ud;
+  h3_stream *st = h3_stream_find(s, id);
+  if (st != NULL) {
+    st->fc_blocked = true;
+  }
   if (s->h3 != NULL) {
     nghttp3_conn_block_stream(s->h3, id);
   }
   return 0;
 }
 
+/* quic found our side of the stream shut when next_stream_data offered it:
+ * nghttp3 sends no more of it. recv_stop_sending and #abort_stream tell
+ * nghttp3 first, so this is what is left for a stream shut otherwise. */
 static int h3_stream_shut_write(void *ud, int64_t id) {
   h3_session *s = ud;
   if (s->h3 != NULL) {
@@ -604,8 +666,15 @@ static int h3_acked_stream_data(void *ud, int64_t id, uint64_t n) {
   return rv == 0 ? 0 : h3_fail(s, rv);
 }
 
+/* The peer widened the stream's flow control window: it has read some of
+ * the body. */
 static int h3_extend_max_stream_data(void *ud, int64_t id) {
   h3_session *s = ud;
+  h3_stream *st = h3_stream_find(s, id);
+  if (st != NULL) {
+    st->fc_blocked = false;
+    st->since = h3_now();
+  }
   if (s->h3 == NULL) {
     return 0;
   }
@@ -646,6 +715,51 @@ static int h3_stream_reset(void *ud, int64_t id, uint64_t final_size,
   return h3_call_ruby(s, id_on_reset, id, 0, NULL);
 }
 
+/* The client asked for no more of what goes out on the stream
+ * (STOP_SENDING); ngtcp2 resets our side of it once this returns. Of a
+ * response, what nghttp3 has not taken is let go at once, and nghttp3
+ * sends no more. The rest of the request is not read either: RFC 9114
+ * section 4.1.1 has a cancelled request stopped in every direction still
+ * open. That is done here, as #stop_reading does it, rather than left to
+ * the Ruby part, so that nothing more of the request comes in, from the
+ * packets read after this one too, even on a stream the Ruby part has not
+ * heard of yet, since STOP_SENDING may come before the request. quic sends
+ * nothing if all of the request has arrived. The Ruby part then drops the
+ * request (#on_stop_sending).
+ *
+ * Our unidirectional streams are the control and QPACK streams, which the
+ * client must not ask us to close, and whose closing is a connection error
+ * of type H3_CLOSED_CRITICAL_STREAM (RFC 9114 section 6.2.1, RFC 9204
+ * section 4.2): the connection fails at once, rather than when the stream
+ * has closed. The client's own unidirectional streams never get here:
+ * ngtcp2 refuses STOP_SENDING on a stream we only receive on. */
+static int h3_recv_stop_sending(void *ud, int64_t id, uint64_t app_error_code) {
+  h3_session *s = ud;
+  if (s->h3 == NULL) {
+    return 0;
+  }
+  if (id & 0x2) {
+    return h3_fail_with(s, NGHTTP3_H3_CLOSED_CRITICAL_STREAM);
+  }
+  h3_stream *st = h3_stream_find(s, id);
+  if (st != NULL) {
+    h3_stream_abort(st);
+  }
+  nghttp3_conn_shutdown_stream_write(s->h3, id);
+  int rv = h3_shutdown_stream_read(s, id);
+  if (rv != 0) {
+    return rv;
+  }
+  if (http3_quic_api->shutdown_stream_read(s->qc, id,
+                                           NGHTTP3_H3_REQUEST_CANCELLED) != 0) {
+    return h3_fail_with(s, NGHTTP3_H3_INTERNAL_ERROR);
+  }
+  /* No end_headers will come to drop the count of a section cut short. */
+  st_data_t key = (st_data_t)id;
+  st_delete(s->field_sizes, &key, NULL);
+  return h3_call_ruby(s, id_on_stop_sending, id, 0, NULL);
+}
+
 static int h3_stream_close(void *ud, int64_t id, int has_code,
                            uint64_t app_error_code) {
   h3_session *s = ud;
@@ -660,8 +774,16 @@ static int h3_stream_close(void *ud, int64_t id, int has_code,
   return h3_fail(s, rv);
 }
 
+/* The size of a handler filled in up to member m. The size tells quic.so
+ * which members the handler has (quic/ext.h): those it fills in, whatever
+ * quic/ext.h it is built against. */
+#define H3_HANDLER_SIZE_TO(m)                                                  \
+  (offsetof(quic_ext_stream_handler, m) +                                      \
+   sizeof(((quic_ext_stream_handler *)0)->m))
+
+/* An ABI 1.1 handler: recv_stop_sending came with quic 0.0.6. */
 static const quic_ext_stream_handler h3_handler = {
-    .size = sizeof(quic_ext_stream_handler),
+    .size = H3_HANDLER_SIZE_TO(recv_stop_sending),
     .recv_stream_data = h3_recv_stream_data,
     .next_stream_data = h3_next_stream_data,
     .stream_data_written = h3_stream_data_written,
@@ -674,6 +796,7 @@ static const quic_ext_stream_handler h3_handler = {
     .stream_reset = h3_stream_reset,
     .stream_close = h3_stream_close,
     .handshake_completed = h3_handshake_completed,
+    .recv_stop_sending = h3_recv_stop_sending,
 };
 
 /* The Ruby object */
@@ -703,6 +826,11 @@ static int h3_free_stream_i(st_data_t key, st_data_t value, st_data_t arg) {
   return ST_CONTINUE;
 }
 
+static int h3_abort_stream_i(st_data_t key, st_data_t value, st_data_t arg) {
+  h3_stream_abort((h3_stream *)value);
+  return ST_CONTINUE;
+}
+
 /* Never touches qc: the QUIC connection may be gone already. */
 static void h3_session_free(void *ptr) {
   h3_session *s = ptr;
@@ -783,6 +911,12 @@ static void h3_raise_no_body(VALUE rb_id) {
            "no response body is open on stream %" PRIsVALUE, rb_id);
 }
 
+NORETURN(static void h3_raise_aborted(VALUE rb_id));
+static void h3_raise_aborted(VALUE rb_id) {
+  rb_raise(rb_eNghttp3InvalidStateError,
+           "stream %" PRIsVALUE " has been aborted", rb_id);
+}
+
 /* The body of stream rb_id. Ruby code that runs once it is found may make
  * the connection go on and close the stream, so convert everything else
  * first. */
@@ -974,18 +1108,26 @@ static VALUE rb_http3_session_stop_reading(VALUE self, VALUE rb_id) {
  *   session.push_chunk(stream_id, str) -> self
  *
  * Queue a frozen copy of str as the next piece of the response body.
+ * Raises InvalidStateError once the stream has been aborted.
  */
 static VALUE rb_http3_session_push_chunk(VALUE self, VALUE rb_id, VALUE str) {
   h3_session *s = h3_session_enter(self);
   StringValue(str);
   VALUE copy = rb_str_new_frozen(str);
   h3_stream *st = h3_session_stream(self, rb_id);
+  if (st->aborted) {
+    h3_raise_aborted(rb_id);
+  }
   if (st->eof) {
     rb_raise(rb_eNghttp3InvalidStateError, "the body has ended");
   }
   if (RSTRING_LEN(copy) == 0) {
     return self;
   }
+  if (h3_stream_unacked(st) == 0) {
+    /* The body waits on the peer from now. */
+    st->since = h3_now();
+  }
   if (h3_stream_push(st, (const uint8_t *)RSTRING_PTR(copy),
                      (size_t)RSTRING_LEN(copy), copy) != 0) {
     rb_raise(rb_eNoMemError, "failed to queue a body chunk");
@@ -999,11 +1141,15 @@ static VALUE rb_http3_session_push_chunk(VALUE self, VALUE rb_id, VALUE str) {
  * call-seq:
  *   session.push_eof(stream_id) -> self
  *
- * Mark the end of the response body.
+ * Mark the end of the response body. Raises InvalidStateError once the
+ * stream has been aborted.
  */
 static VALUE rb_http3_session_push_eof(VALUE self, VALUE rb_id) {
   h3_session *s = h3_session_enter(self);
   h3_stream *st = h3_session_stream(self, rb_id);
+  if (st->aborted) {
+    h3_raise_aborted(rb_id);
+  }
   st->eof = true;
   h3_stream_wake(s, st);
   return self;
@@ -1017,7 +1163,8 @@ static VALUE rb_http3_session_push_eof(VALUE self, VALUE rb_id) {
  * descriptor is duplicated, so io may be closed afterwards. The duplicate
  * is close-on-exec, as Ruby's own descriptors are, so that a process the
  * application spawns does not inherit it, and is closed as soon as the
- * whole length has been read.
+ * whole length has been read. Raises InvalidStateError once the stream has
+ * been aborted.
  */
 static VALUE rb_http3_session_attach_file(VALUE self, VALUE rb_id, VALUE io,
                                           VALUE offset, VALUE length) {
@@ -1039,6 +1186,10 @@ static VALUE rb_http3_session_attach_file(VALUE self, VALUE rb_id, VALUE io,
     close(fd);
     h3_raise_no_body(rb_id);
   }
+  if (st->aborted) {
+    close(fd);
+    h3_raise_aborted(rb_id);
+  }
   if (st->fd >= 0 || st->eof || st->nchunks > 0) {
     close(fd);
     rb_raise(rb_eNghttp3InvalidStateError, "the body is already given");
@@ -1046,6 +1197,7 @@ static VALUE rb_http3_session_attach_file(VALUE self, VALUE rb_id, VALUE io,
   st->fd = fd;
   st->file_off = off;
   st->file_end = off + len;
+  st->since = h3_now();
   if (len == 0) {
     h3_stream_end_file(st);
   }
@@ -1065,6 +1217,36 @@ static VALUE rb_http3_session_unsent_bytes(VALUE self, VALUE rb_id) {
   return ULL2NUM(st == NULL ? 0 : st->unsent);
 }
 
+/*
+ * call-seq:
+ *   session.response_stalled_since(stream_id) -> Float or nil
+ *
+ * Since when (CLOCK_MONOTONIC seconds, as Process.clock_gettime gives it)
+ * the response body on stream_id has waited on the client: some of it has
+ * not been acknowledged, and nothing has moved since. nil while none of it
+ * waits, for a stream without a body, and once the stream has been
+ * aborted.
+ *
+ * Moving is the client acknowledging some of the body, or widening the
+ * stream's flow control window. While that window does not hold the body
+ * back, an acknowledgement of any response body on the connection counts
+ * too: nghttp3 sends the responses of one priority one at a time, so a
+ * response waiting its turn behind another the client is reading gets no
+ * acknowledgements of its own.
+ */
+static VALUE rb_http3_session_response_stalled_since(VALUE self, VALUE rb_id) {
+  h3_session *s = h3_session_get(self);
+  h3_stream *st = h3_stream_find(s, NUM2LL(rb_id));
+  if (st == NULL || h3_stream_unacked(st) == 0) {
+    return Qnil;
+  }
+  double since = st->since;
+  if (!st->fc_blocked && s->acked_at > since) {
+    since = s->acked_at;
+  }
+  return DBL2NUM(since);
+}
+
 /*
  * call-seq:
  *   session.take_closed -> Array
@@ -1116,13 +1298,21 @@ static VALUE rb_http3_session_shutdown_notice(VALUE self) {
  *   session.abort_stream(stream_id, app_error_code) -> self
  *
  * Stop the stream in both directions with app_error_code (for instance
- * H3_INTERNAL_ERROR after the response headers went out).
+ * H3_INTERNAL_ERROR after the response headers went out). What of the
+ * response body nghttp3 has not taken is let go at once, so that
+ * #unsent_bytes no longer counts it, and a file body's descriptor is
+ * closed; #push_chunk, #push_eof and #attach_file raise InvalidStateError
+ * from then on.
  */
 static VALUE rb_http3_session_abort_stream(VALUE self, VALUE rb_id,
                                            VALUE rb_code) {
   h3_session *s = h3_session_enter(self);
   int64_t id = NUM2LL(rb_id);
   uint64_t code = NUM2ULL(rb_code);
+  h3_stream *st = h3_stream_find(s, id);
+  if (st != NULL) {
+    h3_stream_abort(st);
+  }
   if (s->h3 != NULL) {
     nghttp3_conn_shutdown_stream_write(s->h3, id);
   }
@@ -1131,6 +1321,36 @@ static VALUE rb_http3_session_abort_stream(VALUE self, VALUE rb_id,
   return self;
 }
 
+/*
+ * call-seq:
+ *   session.release_connection -> self   (private; #release_all calls it)
+ *
+ * Let go of the HTTP/3 connection now, rather than when the Session is
+ * garbage collected: the nghttp3 connection is deleted, and every response
+ * body aborted as #abort_stream aborts one, though no stream is reset, so
+ * that what nghttp3 had not taken of it is let go of and a file body's
+ * descriptor closed. What nghttp3 had taken stays until the Session is
+ * freed, even once the stream closes, since without nghttp3 nothing tells
+ * of that: ngtcp2 may still point into it, to send it again.
+ *
+ * For a QUIC connection that has gone. One still driven goes on as after a
+ * failure (h3_fail_with), with H3_NO_ERROR; without nghttp3, it sends
+ * nothing more of a body let go of, its FIN included. A connection that
+ * failed keeps the error it failed with. From then on #submit_response and
+ * #stop_reading raise InvalidStateError, as on a failed connection, and
+ * #push_chunk, #push_eof and #attach_file as on an aborted stream. Raises
+ * InvalidStateError inside a callback of the Session, where nghttp3 may be
+ * running. Calling it again does nothing.
+ */
+static VALUE rb_http3_session_release_connection(VALUE self) {
+  h3_session *s = h3_session_enter(self);
+  if (!s->failed) {
+    h3_fail_with(s, NGHTTP3_H3_NO_ERROR);
+  }
+  st_foreach(s->streams, h3_abort_stream_i, 0);
+  return self;
+}
+
 void Init_http3_session(VALUE rb_mHTTP3) {
   id_on_begin_headers = rb_intern("on_begin_headers");
   id_on_header = rb_intern("on_header");
@@ -1139,6 +1359,7 @@ void Init_http3_session(VALUE rb_mHTTP3) {
   id_on_end_stream = rb_intern("on_end_stream");
   id_on_fields_too_large = rb_intern("on_fields_too_large");
   id_on_reset = rb_intern("on_reset");
+  id_on_stop_sending = rb_intern("on_stop_sending");
 
   rb_cHTTP3Session = rb_define_class_under(rb_mHTTP3, "Session", rb_cObject);
   rb_undef_alloc_func(rb_cHTTP3Session);
@@ -1155,6 +1376,8 @@ void Init_http3_session(VALUE rb_mHTTP3) {
                    rb_http3_session_attach_file, 4);
   rb_define_method(rb_cHTTP3Session, "unsent_bytes",
                    rb_http3_session_unsent_bytes, 1);
+  rb_define_method(rb_cHTTP3Session, "response_stalled_since",
+                   rb_http3_session_response_stalled_since, 1);
   rb_define_method(rb_cHTTP3Session, "take_closed",
                    rb_http3_session_take_closed, 0);
   rb_define_method(rb_cHTTP3Session, "take_error", rb_http3_session_take_error,
@@ -1163,4 +1386,6 @@ void Init_http3_session(VALUE rb_mHTTP3) {
                    rb_http3_session_shutdown_notice, 0);
   rb_define_method(rb_cHTTP3Session, "abort_stream",
                    rb_http3_session_abort_stream, 2);
+  rb_define_private_method(rb_cHTTP3Session, "release_connection",
+                           rb_http3_session_release_connection, 0);
 }

data/lib/http3/body_pipe.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module HTTP3
+  # The stream a response was being sent on is gone: the client reset it or
+  # asked for no more of it (STOP_SENDING), the connection ended, the server
+  # stopped, or the response was aborted after waiting on its client for
+  # response_timeout. Body::Pipe's write, finish and flush raise it. It is
+  # an IOError, as a write to a closed socket raises one.
+  class StreamClosed < IOError
+  end
+
+  module Body
+    # A response body written by the thread that runs the application and
+    # taken by the server's I/O loop, which sends it. On the writer's side,
+    # #write waits while capacity bytes or more are queued, and #finish ends
+    # the body, #fail ends it with an exception, each waiting until all of
+    # it has been taken. On the I/O loop's side, #take never waits, and
+    # #cancel gives up on the body: from then on the writer's write, finish
+    # and flush raise StreamClosed, those waiting included, and fail
+    # returns false. Since a writer waits for the
+    # end of its body to be taken, the pipes holding chunks are no more than
+    # the writers.
+    #
+    # wake is called, with no lock held, each time the body goes from
+    # having nothing to take to having something: a chunk, its end, or the
+    # exception that ended it.
+    class Pipe
+      def initialize(capacity:, wake:)
+        @capacity = capacity
+        @wake = wake
+        @lock = Thread::Mutex.new
+        @changed = Thread::ConditionVariable.new
+        @chunks = []
+        @bytes = 0
+        @finished = false
+        @end_taken = false
+        @error = nil
+        @cancelled = false
+      end
+
+      # Queue chunk, a String, first waiting while capacity bytes or more are
+      # queued. A String that can still change is copied. Returns its size.
+      def write(chunk)
+        raise TypeError, "chunk must be a String (got #{chunk.class})" unless chunk.is_a?(String)
+
+        chunk = chunk.dup.freeze unless chunk.frozen?
+        woke = @lock.synchronize do
+          @changed.wait(@lock) while @bytes >= @capacity && !@cancelled
+          check_writable
+          next false if chunk.empty?
+
+          was_empty = @chunks.empty?
+          @chunks << chunk
+          @bytes += chunk.bytesize
+          was_empty
+        end
+        @wake.call if woke
+        chunk.bytesize
+      end
+
+      # End the body, and wait until the I/O loop has taken all of it, its
+      # end included.
+      def finish
+        woke = @lock.synchronize do
+          check_writable
+          @finished = true
+          @chunks.empty?
+        end
+        @wake.call if woke
+        @lock.synchronize do
+          wait_for_the_end
+          raise StreamClosed, "stream closed" unless @end_taken
+        end
+        nil
+      end
+
+      # End the body with error, for the I/O loop to abort the stream once
+      # it has taken what is queued, and wait until it has. Returns true
+      # once the I/O loop has taken error, and false when it never will:
+      # the body had ended or been given up on, and fail did nothing, or it
+      # was given up on while fail waited.
+      def fail(error)
+        woke = @lock.synchronize do
+          next nil if @cancelled || @finished || @error
+
+          @error = error
+          @chunks.empty?
+        end
+        return false if woke.nil?
+
+        @wake.call if woke
+        @lock.synchronize do
+          wait_for_the_end
+          @end_taken
+        end
+      end
+
+      # Wait until the I/O loop has taken every chunk queued.
+      def flush
+        @lock.synchronize do
+          @changed.wait(@lock) until @chunks.empty? || @cancelled
+          raise StreamClosed, "stream closed" if @cancelled
+        end
+        self
+      end
+
+      # The next of what the writer queued, without waiting: a chunk; once
+      # they have all been taken, :eof for a body that ended, or the
+      # exception given to #fail; nil while there is nothing yet, and after
+      # #cancel.
+      def take
+        @lock.synchronize do
+          return nil if @cancelled
+
+          if (chunk = @chunks.shift)
+            @bytes -= chunk.bytesize
+            @changed.broadcast
+            return chunk
+          end
+          return nil unless @finished || @error
+
+          @end_taken = true
+          @changed.broadcast
+          @error || :eof
+        end
+      end
+
+      # True when #take has something new to return: a chunk, or the end.
+      def ready?
+        @lock.synchronize do
+          !@cancelled && (!@chunks.empty? || ((@finished || !@error.nil?) && !@end_taken))
+        end
+      end
+
+      # Give up on the body: what is queued is dropped, and the writer's
+      # calls, those waiting included, raise StreamClosed.
+      def cancel
+        @lock.synchronize do
+          @cancelled = true
+          @chunks.clear
+          @bytes = 0
+          @changed.broadcast
+        end
+        nil
+      end
+
+      private
+
+      # With the lock held.
+      def wait_for_the_end
+        @changed.wait(@lock) until @end_taken || @cancelled
+      end
+
+      def check_writable
+        raise StreamClosed, "stream closed" if @cancelled
+        raise IOError, "body already ended" if @finished || @error
+      end
+    end
+  end
+end