Subject: [quicwg/base-drafts] Rename Final Offset to Final Size (#2285)

From: Kazuho Oku <[email-masked]>
Date: Wed, 02 Jan 2019 16:32:53 -0800

Use "final size" instead of "final offset", because the latter is ambiguous. Closes #2262.
You can view, comment on, or merge this pull request online at:

  https://github.com/quicwg/base-drafts/pull/2285

-- Commit Summary --

  * s/final offset/final size/g

-- File Changes --

    M draft-ietf-quic-transport.md (63)

-- Patch Links --

https://github.com/quicwg/base-drafts/pull/2285.patch
https://github.com/quicwg/base-drafts/pull/2285.diff

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285

---

From: Kazuho Oku <[email-masked]>
Date: Wed, 02 Jan 2019 16:42:36 -0800

kazuho commented on this pull request.

-The final offset is the count of the number of bytes that are transmitted on a
-stream.  For a stream that is reset, the final offset is carried explicitly in a
-RESET_STREAM frame.  Otherwise, the final offset is the offset of the end of the
-data carried in a STREAM frame marked with a FIN flag, or 0 in the case of
-incoming unidirectional streams.
+The final size is the amount of data that is transmitted on a stream.  For a
+stream that is reset, the final size is carried explicitly in a RESET_STREAM
+frame.  Otherwise, the final size is the offset plus the length of a STREAM
+frame marked with a FIN flag, or 0 in the case of incoming unidirectional
+streams.

I think that the current draft is incorrectly referring to incoming unidirectional streams; see #2286.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-188877667

---

From: Martin Thomson <[email-masked]>
Date: Wed, 02 Jan 2019 19:04:36 -0800

martinthomson commented on this pull request.

I think that this is fine, but wonder if a better definition would help.  Or maybe "end offset" - the offset of the end of the stream.

"offset" was chosen specifically because that is what matters.  And it allows for gaps.  So a more careful definition is probably needed either way.  I've a suggestion inline that uses "final size", but I think that "end offset" might still be better.

This is the critical piece.  We have to allow for gaps, so I suggest:

```suggestion
The final size is the amount of flow control credit that is consumed by a
stream.  Assuming that every contiguous byte on the stream was sent, the final
size is the number of bytes sent.  More generally, this is one higher than the
largest byte offset sent on the stream.

For a
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-188891346

---

From: Kazuho Oku <[email-masked]>
Date: Wed, 02 Jan 2019 20:46:03 -0800

@kazuho pushed 1 commit.

e2498da8e49df6322c1e4da2f29db9cf13679d03  "flow control credit"

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285/files/2475cc5bc585cc24c9c9acebf62e48e368486d12..e2498da8e49df6322c1e4da2f29db9cf13679d03

---

From: Marten Seemann <[email-masked]>
Date: Wed, 02 Jan 2019 20:50:14 -0800

I don’t really understand what’s wrong with „offset“, and I’d prefer to keep that term. I find that term a lot less confusing then „size“, and then we don’t need any explanation regarding gaps and retransmitted data.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#issuecomment-451055539

---

From: Kazuho Oku <[email-masked]>
Date: Wed, 02 Jan 2019 20:58:12 -0800

I think that "end offset" might be ambiguous the same way as "final offset" is; it could mean the offset of the final octet. Using terms like "size" (or "number of bytes") avoids that confusion. It should also be noted that we refer to the same thing as "amount of data that can be sent" in the definition of MAX_STREAM_DATA; so far I have tried to align the definition of RESET_STREAM to that.

@martinthomson's suggestion to use "flow control credit" as a term sounds good to me. Ideally we should RESET_STERAM.final_offset and MAX_STREAM_DATA.max_stream_data using the same term.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#issuecomment-451056182

---

From: MikkelFJ <[email-masked]>
Date: Thu, 03 Jan 2019 02:34:43 -0800

mikkelfj commented on this pull request.

-The final offset is the count of the number of bytes that are transmitted on a
-stream.  For a stream that is reset, the final offset is carried explicitly in a
-RESET_STREAM frame.  Otherwise, the final offset is the offset of the end of the
-data carried in a STREAM frame marked with a FIN flag, or 0 in the case of
-incoming unidirectional streams.
+The final size is the amount of flow control credit that is consumed by a
+stream.  Assuming that every contiguous byte on the stream was sent, the final

```suggestion
stream.  Assuming that every contiguous byte on the stream was sent once, the final
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-188961329

---

From: janaiyengar <[email-masked]>
Date: Thu, 03 Jan 2019 17:19:47 -0800

I don't think I understand the ambiguity with "offset". @kazuho: can you clarify what the ambiguity is? I find "offset" more accurate because, as @martinthomson notes, there can be gaps in the stream.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#issuecomment-451329791

---

From: janaiyengar <[email-masked]>
Date: Thu, 03 Jan 2019 17:40:00 -0800

janaiyengar commented on this pull request.

-An endpoint will know the final offset for a stream when the receiving part of
-the stream enters the "Size Known" or "Reset Recvd" state ({{stream-states}}).
+For a
+stream that is reset, the final size is carried explicitly in a RESET_STREAM
+frame.  Otherwise, the final size is the offset plus the length of a STREAM

It might be worth adding that for a stream that is reset, the final size might be smaller than the number of bytes sent on the stream.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-189244548

---

From: janaiyengar <[email-masked]>
Date: Thu, 03 Jan 2019 17:40:30 -0800

As I said on the issue, I understand now and think this is a fine change. 

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#issuecomment-451332529

---

From: Kazuho Oku <[email-masked]>
Date: Sun, 06 Jan 2019 10:13:31 -0800

@kazuho pushed 1 commit.

5779ec165e78ace2503496a6099ba1ca8242c320  Update draft-ietf-quic-transport.md

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285/files/e2498da8e49df6322c1e4da2f29db9cf13679d03..5779ec165e78ace2503496a6099ba1ca8242c320

---

From: Kazuho Oku <[email-masked]>
Date: Sun, 06 Jan 2019 10:16:14 -0800

Isn't that a protocol violation triggering FINAL_OFFSET_ERROR (to be renamed to FINAL_SIZE_ERROR)? Quoting from the draft: _an endpoint received a RESET_STREAM frame containing a final offset that was lower than the maximum offset of data that was already received._

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#discussion_r245517266

---

From: Kazuho Oku <[email-masked]>
Date: Sun, 06 Jan 2019 10:22:21 -0800

@kazuho pushed 1 commit.

d0163cadacef8b8a6fc8ff03721af0baa24aa952  Merge branch 'master' into kazuho/final-size

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285/files/5779ec165e78ace2503496a6099ba1ca8242c320..d0163cadacef8b8a6fc8ff03721af0baa24aa952

---

From: Kazuho Oku <[email-masked]>
Date: Sun, 06 Jan 2019 10:23:06 -0800

Thank you for the suggestion, applied in 5779ec1.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#discussion_r245517428

---

From: Kazuho Oku <[email-masked]>
Date: Sun, 06 Jan 2019 10:24:39 -0800

@kazuho pushed 1 commit.

7369a018415fabd6e3295b4e04a102a0531fc06c  "final stream size" is confusing, avoid "stream"

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285/files/d0163cadacef8b8a6fc8ff03721af0baa24aa952..7369a018415fabd6e3295b4e04a102a0531fc06c

---

From: ianswett <[email-masked]>
Date: Sun, 06 Jan 2019 13:08:39 -0800

ianswett commented on this pull request.

```suggestion
stream.  When every contiguous byte on the stream is sent, the final
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-189644361

---

From: Kazuho Oku <[email-masked]>
Date: Sun, 06 Jan 2019 19:16:18 -0800

@kazuho pushed 1 commit.

2d606c0b470d1279c2208460d3734b589bc5d92d  Merge branch 'master' into kazuho/final-size

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285/files/7369a018415fabd6e3295b4e04a102a0531fc06c..2d606c0b470d1279c2208460d3734b589bc5d92d

---

From: janaiyengar <[email-masked]>
Date: Mon, 07 Jan 2019 17:33:41 -0800

Yes, my suggestion was incorrect. Not sure what I was thinking.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#discussion_r245854188

---

From: ianswett <[email-masked]>
Date: Mon, 07 Jan 2019 19:54:56 -0800

ianswett approved this pull request.

I'm not sure if we want to make this change, but I think this is good text overall.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-190084778

---

From: Mike Bishop <[email-masked]>
Date: Tue, 08 Jan 2019 14:31:06 -0800

MikeBishop approved this pull request.

I'm okay with this change.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-190487764

---

From: Martin Thomson <[email-masked]>
Date: Tue, 08 Jan 2019 14:37:40 -0800

Merged #2285 into master.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#event-2061514377

---

From: Martin Thomson <[email-masked]>
Date: Tue, 08 Jan 2019 14:38:24 -0800

I'm not convinced that size > offset, but the other changes are a definite improvement.  Changing back to offset is easy enough.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#issuecomment-452477547

---

From: MikkelFJ <[email-masked]>
Date: Tue, 08 Jan 2019 14:39:52 -0800

-The final offset is the count of the number of bytes that are transmitted on a
-stream.  For a stream that is reset, the final offset is carried explicitly in a
-RESET_STREAM frame.  Otherwise, the final offset is the offset of the end of the
-data carried in a STREAM frame marked with a FIN flag.
+The final size is the amount of flow control credit that is consumed by a
+stream.  Assuming that every contiguous byte on the stream was sent once, the
+final size is the number of bytes sent.  More generally, this is one higher
+than the largest byte offset sent on the stream.

Too late, but there is missing a "if any".

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#pullrequestreview-190492084

---

From: Martin Thomson <[email-masked]>
Date: Tue, 08 Jan 2019 14:53:17 -0800

Never too late.  But I'm not following you.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#discussion_r246188819

---

From: MikkelFJ <[email-masked]>
Date: Wed, 09 Jan 2019 02:36:31 -0800

The final size can be zero. That is not one larger than largest sent.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2285#discussion_r246332747