1@0x8f5d14e1c273738d;
2
3$import "/capnp/c++.capnp".namespace("capnp");
4
5interface ByteStream {
6  write @0 (bytes :Data) -> stream;
7  # Write a chunk.
8
9  end @1 ();
10  # Signals clean EOF. (If the ByteStream is dropped without calling this, then the stream was
11  # prematurely canceled and so the body should not be considered complete.)
12
13  getSubstream @2 (callback :SubstreamCallback,
14                   limit :UInt64 = 0xffffffffffffffff) -> (substream :ByteStream);
15  # This method is used to implement path shortening optimization. It is designed in particular
16  # with KJ streams' pumpTo() in mind.
17  #
18  # getSubstream() returns a new stream object that can be used to write to the same destination
19  # as this stream. The substream will operate until it has received `limit` bytes, or its `end()`
20  # method has been called, whichever occurs first. At that time, it invokes one of the methods of
21  # `callback` based on the termination condition.
22  #
23  # While a substream is active, it is an error to call write() on the original stream. Doing so
24  # may throw an exception or may arbitrarily interleave bytes with the substream's writes.
25
26  interface SubstreamCallback {
27    ended @0 (byteCount :UInt64);
28    # `end()` was called on the substream after writing `byteCount` bytes. The `end()` call was
29    # NOT forwarded to the underlying stream, which remains open.
30
31    reachedLimit @1 () -> (next :ByteStream);
32    # The number of bytes specified by the `limit` parameter of `getSubstream()` was reached.
33    # The substream will "resolve itself" to `next`, so that all future calls to the substream
34    # are forwarded to `next`.
35    #
36    # If the `write()` call which reached the limit included bytes past the limit, then the first
37    # `write()` call to `next` will be for those leftover bytes.
38  }
39}
40