RE: Report on Unidirectional Streams in Minq

"Lubashev, Igor" <> Mon, 02 October 2017 16:34 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 3E67213263F for <>; Mon, 2 Oct 2017 09:34:49 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -0.71
X-Spam-Status: No, score=-0.71 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HTML_MESSAGE=0.001, HTTPS_HTTP_MISMATCH=1.989, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: (amavisd-new); dkim=pass (2048-bit key)
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id qcX1rXqn7gta for <>; Mon, 2 Oct 2017 09:34:44 -0700 (PDT)
Received: from ( []) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by (Postfix) with ESMTPS id DC20D1344C6 for <>; Mon, 2 Oct 2017 09:34:43 -0700 (PDT)
Received: from pps.filterd ( []) by ( with SMTP id v92GW4KH027754; Mon, 2 Oct 2017 17:34:40 +0100
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; h=from : to : cc : subject : date : message-id : references : in-reply-to : content-type : mime-version; s=jan2016.eng; bh=+BcJMJ9xig4WXp2Wd64k/QEYdcncpbiZpzK9KTSSamY=; b=kV3lEGhRwZZ//d6mnY0royNw66P1tBh7ZDFFFMHaKkvenda+gQ5JDZdMlVtd9vKIT94B MkfgaXM9mc4oBVMwccFNpyqrM34ZIPK1ghP3Ov+vgMUrtfhNBj60zZ9NVgwPz+oL+yDF BQwRE67/6OOom4Y/xpdd0JvRN/TEIC3OrQEjtyJdgiP3sugT3t9kUvptyrszIHjf7TnE SSfukkII48Cbty/t7bCgiIl2qvhUXI0511lKqQxlk6+RkmNx3Awq0l3VZOVo0tS/Js1Y tA8vKyNpG/HUSN51LViabTvHOwDL1Tv7KWvumRfNFXOH04KDILi1HW+C27s09/qD/MEj Ng==
Received: from prod-mail-ppoint4 ([]) by with ESMTP id 2da3agch4q-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 02 Oct 2017 17:34:39 +0100
Received: from pps.filterd ( []) by ( with SMTP id v92GVCnD004373; Mon, 2 Oct 2017 12:34:38 -0400
Received: from ([]) by with ESMTP id 2da6ku6811-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Mon, 02 Oct 2017 12:34:37 -0400
Received: from ( by ( with Microsoft SMTP Server (TLS) id 15.0.1263.5; Mon, 2 Oct 2017 12:34:36 -0400
Received: from ([]) by ([]) with mapi id 15.00.1263.000; Mon, 2 Oct 2017 12:34:36 -0400
From: "Lubashev, Igor" <>
To: Mike Bishop <>, Eric Rescorla <>
CC: "" <>, "" <>
Subject: RE: Report on Unidirectional Streams in Minq
Thread-Topic: Report on Unidirectional Streams in Minq
Date: Mon, 2 Oct 2017 16:34:35 +0000
Message-ID: <>
References: <> <> <> <> <> <> <> <>
In-Reply-To: <>
Accept-Language: en-US
Content-Language: en-US
x-ms-exchange-transport-fromentityheader: Hosted
x-originating-ip: []
Content-Type: multipart/alternative; boundary="_000_b6ca3e39c94e44c2ad1987d5ea90078eusma1exdag1mb5msgcorpak_"
MIME-Version: 1.0
X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2017-10-02_04:, , signatures=0
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 suspectscore=0 malwarescore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1707230000 definitions=main-1710020241
X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2017-10-02_04:, , signatures=0
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 impostorscore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1707230000 definitions=main-1710020241
Archived-At: <>
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: Main mailing list of the IETF QUIC working group <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Mon, 02 Oct 2017 16:34:49 -0000

Thanks, Mike.  Indeed, I thought the it was proposed for the sender to send RESET_STREAM in the same frame as STREAM(off=0|FIN) (and len>0).  Yes, STREAM(off=0|len=0|FIN) is equivalent to RESET_STREAM, as far as transport state is concerned (but it may have a different API effect – a different callback called).

From: Mike Bishop []
Sent: Monday, October 02, 2017 12:08 PM
To: Eric Rescorla <>om>; Lubashev, Igor <>
Subject: RE: Report on Unidirectional Streams in Minq

I think you’re talking past each other.  Igor, the draft currently says that RST_STREAM applies to the sender’s direction only, so sending a RST_STREAM doesn’t help anything.  The other side could reasonably send RST_STREAM or the STREAM-FIN, and they’re identical for all practical purposes.  The point is that one side is sending all the data, but the other side still has to ack on the stream for it to reach the closed state.  Unidirectional streams don’t require any per-stream action by the receiver to complete the state machine.

From: Eric Rescorla []
Sent: Monday, October 2, 2017 7:52 AM
To: Lubashev, Igor <<>>
Cc: Mike Bishop <<>>;<>;<>
Subject: Re: Report on Unidirectional Streams in Minq

On Mon, Oct 2, 2017 at 4:27 AM, Lubashev, Igor <<>> wrote:
> Nit: Can't you send RESET_STREAM

I do not think this is an option, since RESET_STREAM may prevent data buffered by the transport from being delivered to the application.

Those are also the semantics of STREAM(offset=0, FIN).


I am less concerned about how long connection state has to be kept around -- in a cooperating peer situation, this is one rtt, which is the same amount of time that is required to wait for an ACK. A malicious peer could withhold ACKs for packets with STREAM+FIN. The bidirectional protocol is more chatty, though.

-----Original Message-----
From: Eric Rescorla [<>]
Received: Sunday, 01 Oct 2017, 5:29PM
To: Mike Bishop [<>]
CC: Mikkel Fahnøe Jørgensen [<>]; IETF QUIC WG [<>]
Subject: Re: Report on Unidirectional Streams in Minq

On Sun, Oct 1, 2017 at 2:19 PM, Mike Bishop <<>> wrote:
I think the difference is for the scenario where you don’t expect a peer to respond (or don’t expect them to respond stream-by-stream).  With -05, the receiver still needs to send STREAM(offset=0,FIN) on each stream.

Nit: Can't you send RESET_STREAM?

  With either unidirectional proposal, this pattern is a bit cleaner.  In #656, the sender can essentially say, “Don’t bother” at the time of stream creation.  In #643, there’s no corresponding channel to close.

Yes, I agree that this is cleaner. Note that in #643 you presumably need to have some way of signaling that you don't want a return connection....

In all cases, the only thing that really limits you is the peer’s willingness to increase your MAX_STREAM_ID, it’s just a question of how chatty you have to be – which can matter if these messages are fairly small.



From: QUIC [<>] On Behalf Of Eric Rescorla
Sent: Sunday, October 1, 2017 2:03 PM
To: Mikkel Fahnøe Jørgensen <<>>
Subject: Re: Report on Unidirectional Streams in Minq

I'm not sure I have any useful insights on this, as my implementation handles them more or less the same. Can you explain why you think this would be different with unidirectional versus bidirectional?


On Sun, Oct 1, 2017 at 1:38 PM, Mikkel Fahnøe Jørgensen <<>> wrote:

I only skimmed this superfast, but one the observations appear to not cover one of my key points:

You can create and close uni-streams at at very high rate of many streams per packet, without waiting for peer response, assuming the ACK framework handles retransmission. Any insights on this?

Kind Regards,
Mikkel Fahnøe Jørgensen

On 1 October 2017 at 22.32.02, Eric Rescorla (<>) wrote:
Hi folks,

As promised I spent a bunch of time hacking unidirectional streams
into Minq and I'm here to report back [0]. Specifically, I

  - PR#643 -- Unidirectional Streams
  - PR#720 -- Add bidirectional streams on top of unidirectional
  - A bidirectional stream API that mostly mimics Minq's original API
    for -05.

The following is kind of a wall of text, so you could also skip this
and refer to my slides [1].

Minq's master object is the Connection, which has a list of Streams
indexed by stream ID. Applications register a handler with the
connection to be notified of new events.

   type ConnectionHandler interface {
    // The connection has changed state to state |s|
    StateChanged(s State)

    // A new stream has been created (by receiving a frame
    // from the other side. |s| contains the stream.
    NewStream(s *Stream)

    // Stream |s| is now readable.
    StreamReadable(s *Stream)

Streams get created in two ways:

- Locally via Connection.CreateStream()
- Remotely, in which case the application is notified via a callback to

Streams themselves have the APIs you would expect, namely, Read(),
Write(), Close(), Reset(), etc. You get notified of stream readability
by a callback to ConnectionHandler.StreamReadable(), at which point
you can do Stream.Read(). As expected, Stream.Read() returns
WOULDBLOCK when no data ia available

As noted above, we start with the Connection object (only relevant fields

   type Connection struct {
    handler          ConnectionHandler
    streams          []*Stream
    maxStream        uint32
outputClearQ     []frame // For stream 0
outputProtectedQ []frame // For stream >= 0

As you can see, streams are in an array slice, so they're contiguously
indexed by stream ID. Right now, I have no provision for reclaiming
the unused bottom part of the array, but it would be straightforward
to index by |streamId| - |minStream|, which I think is consistent with
the design implied by the requirement to create streams in sequence.

Because Streams are bidirectional, each stream actually consists of a
pair of half streams.

   type streamHalf struct {
    s             *stream           // pointer to parent
    log           loggingFunction
    dir           direction         // Sending or receiving
    closed        bool              // Is the half-stream closed
    offset        uint64            // The
    chunks        []streamChunk
    maxStreamData uint64

   // Internal object to allow unit testing.
   type stream struct {
    id         uint32
    log        loggingFunction
    state      streamState
    send, recv *streamHalf
  blocked    bool // Have we returned blocked

   // Public API object, which needs access to the Connection
   type Stream struct {
    c *Connection

Outgoing data is enqueued into |stream.chunks|, and then periodically
the connection polls the stream for all the chunks which are permitted
by stream-level flow control and enqueues them into
|Connection.outputClearQ| or |Connection.outputProtectedQ|. At this
point, the connection owns the data and is responsible for
transmitting it, subject to connection-level flow control, and
(presumably) congestion control once I have that implemented [2].

Incoming data gets queued (sorted) into |stream.chunks| for later
reassembly at the time when someone calls I'm not sure
I love this, because it means I don't have a good view of the incoming
queue size (which I'd need to account for separately), but it allowed
me to share data structures between incoming and outgoing, which
seemed kind of natural when I did it (this architecture is replicated
in the unidirectional streams design, but it's probably less natural

With the unidirectional branch, Minq offers two APIs. The first is a
straightforward mapping of PR#720, in which we have two objects:

  SendStream -- used for writing
  RecvStream -- used for reading

As before, we have a handler object, but it's directional now:

   type ConnectionHandler interface {
    // The connection has changed state to state |s|
    StateChanged(s State)

    // A new receiving stream has been created (by receiving a frame
    // from the other side. |s| contains the stream.
    NewRecvStream(s *RecvStream)

    // Stream |s| is now readable.
    StreamReadable(s *RecvStream)

Obviously SendStreams are locally created and RecvStreams are remotely
created. SendStreams can be created using
Connection.CreateSendStream() and you learn about remotely created
RecvStreams by a callback to ConnectionHandler.NewRecvStream().
Second-created streams can be marked as "related" to a single
first-created stream, using Connection.CreateRelatedSendStream() with
the appropriate RecvStream as the argument [3]. Streams have a
Related() API to tell you if they are related to some other stream.

The {Send,Recv}Stream APIs are about what you'd expect. You can
Write() on SendStream and Read() on RecvStream(). Right now, you can
Close() and Reset() SendStreams, but not do anything on RecvStreams()
or than ignore them. Eventually I'll probably offer
RecvStream().Mute() or something to let you send STOP_SENDING.

Minq also includes a bidirectional API that's layered on top of
unidirectional streams. I've created a Connection2 structure that's
intended as a wrapper around Connection [4]:

   type Connection2 struct {
    shim    *connection2ShimHandler
    streams []*Stream // Odd for client originated, even for server.

   type Stream struct {
    id   uint32
    send *SendStream
    recv *RecvStream

Basically, Stream is just a pair of SendStream and RecvStream and
Connection2 does the bookkeeping to keep them connected (I even do the
odd/even ID thing that QUIC-05 has). Connection2 has the same handler
API as Minq for QUIC-05, and the shim is responsible for translating
unidirectional events into bidirectional events.

Internally, what's going on here is that when you call CreateStream()
Minq creates a Stream with a nil RecvStream. When a new remote stream
is detected, we check RecvStream.Related(). If they are related to an
existing SendStream then we will in the relevant |Stream.send| slot.
Otherwise, we create a new SendStream that's related to the incoming
stream and notify the application of the creation of the new
bidirectional stream.

Note that this all works fine if one side does the undirectional API
and one does the bidirectional API. My test programs actually exercise
this. Of course, there's an assumption that the peer conforms to a 1:1
mapping. If we define unidirectional streams, we'll need some protocol
mechanism to know if the other side is exercising this level of
increased flexibility or not. I can imagine a number of options here
(e.g., ALPN).  We could also forbid 1:N mappings but I think that
would be a mistake as it's a cool feature/benefit of doing

The entire bidirectional wrapper shim is < 150 lines of Go code.
Converting my test application to this API was a matter of just
changing class names, e.g., s/Connectionb/Connection2/.

In my implementation, I assume that at the time Minq hears about a
stream, you know if its related to a given existing stream.  That way
you can immediately either associate it with that stream or make a new
local stream. In my implementation, I always send Related Stream Id
and assume that you never get an "unrelated" stream frame before a
"related" one. The spec doesn't really require that right now, and
offline MT suggested just sending related with offset=0 but I think
that's a mistake, because it means that you need to hold stream frames
in some provisional "undetermined" state until you get that frame. I
would suggest instead that we require that you include the field until
one of the frames is ACKed.

Sending and receiving streams still share a lot of common components:

    type baseStream struct {
    state         streamState
    id            uint32
    log           loggingFunction
    offset        uint64
    chunks        []streamChunk
    maxStreamData uint64
    isRelated     bool
    related       uint32

    type sendStream struct {
    blocked bool

    type recvStream struct {

Most of this is the same as with bidirectional streams.  As above,
it's probably possible to make them more asymmetrical.

The connection maintains separate lists of sending and receiving
streams and it's straightforward to create and access them without
worrying about the odd/even stuff.

At the end of the day, I think this shows that these designs aren't
really that disssimilar. I was able to convert Minq to unidirectional
streams in about 16 total hours of work (basically a long plane flight
plus the next morning). While I had to make a bunch of changes to the
internal structures, basically none of them modified anything tricky,
and in particular the flow control mechanics and the like are
basically unchanged, except for a bunch of mechanical-type
transformations like referring to |sendStream.chunks| instead of
|stream.send.chunks|. The only really new protocol machinery is the
new frame format for related streams.

There are a few pros/cons that are worth noting about these designs.

- Without a bidirectional API, having unidirectional streams is more
  work for the programmer. However, with an API shim, the difference
  is trivial.

- Because undirectional streams are inherently more flexible, it's
  possible for the sides to try to use different mappings, e.g., one
  side expects paired and the other expects 1:N. We'll need some way
  of making sure that doesn't happen, maybe ALPN?

- The "Related Stream ID" frame indicator needs fleshing out a bit.
  From the application's perspective, it should never hear about a
  stream without knowing its related status. And as noted above, I
  think it would be best if we required that all "first flight" stream
  frames that are related include the fied

- Undirectional streams kind of sharpen the confusion about exactly
  what kinds of "closure" we want to allow. Specifically, what should
  implementations be able to say about their willingness to receive?
  Right now we have STOP_SENDING, but that doesn't influence the
  sender's state. I don't think undirectional streams make this worse,
  they just require us to think it through some more. They do simplify
  the implementation of the closure state machine: in my QUIC-05 code,
  whenever one side closes I have to have checks to see if I should be
  transitioning to CLOSED or HALF-CLOSED, etc, which is odd because
  the directions are basically independent.  It would probably be
  easier even in QUIC-05 not to reify these states but just to
  determine the state from the composition of the individual

- Unidirectional streams don't need the kind of annoying odd-even
  mechanics, which was easier to code up (just having to create all
  the lower-numbered streams of the same parity is kind of a pain).
  One additional benefit here is that with QUIC-05 there are several
  messages which involve implicit stream creation (e.g.,
  STREAM_MAX_DATA, and RST_STREAM) and so you need to check whether
  the stream is one that should have been created locally or
  remotely. This just doesn't happen with bidirectional streams; I do
  implement odd/even mechanics but because the other side has to have
  its stream ids increment by one, I can make sure that they have the
  right IDs by construction and just check to see if the stream exists
  in these cases.  I'd like to see us get rid of odd/even no matter

- Unidirectional streams also helps avoid some of the corner cases around
  bidirectional streams. Specifically, suppose I am the client and
  I get MAX_STREAM_DATA as the first frame on stream 2. Am I allowed
  to just start sending or not? You can sort of get into this situation
  with unidirectional streams, but because it's explicit, one might
  hope that the application semantics would require clear specification.

- As noted above, bidirectional streams are more flexible because they
  let you have mappings that you can't have with unidirectional
  streams (unpaired, 1:N).

Happy to answer more questions if people have them. Otherwise we can
talk about this in Seattle.


[2] Thanks to Patrick McManus for suggesting this design.
[3] In C++, you would have a single function with a default argument of
    |nullptr| but Go doesn't support that, hence two different arguments.
[4] For implementation reasons, it's actually using Connection as a mixin,
    which means it's simultaneously possible to use the unidirectional
    and bidirectional APIs, but that's going to cause a lot of confusion.
    A real implementation would probably have to either commit to one
    or the other or do a real wrapper, so you could only use one set of
    APIs, at the cost of having to do more forwarded methods.