[hybi] Clarify the role of closing handshake

[Takeshi Yoshino <[e-mail]>]

Long time has passed since there was active discussion on closing handshake
design. Closing handshake detail has been gradually changed in -01 and -05
adopting suggestions from tickets and posts on the list, and now there is
some inconsistency between sections. I think now it's good time to discuss
again what closing handshake should realize, how it should be done, and what
_cleanly_ means.

== What closing handshake should realize ==
Now it seems closing handshake in -05 is designed to realize two things.
a) peer B assume that no more data is coming from peer A when B receives
closing initiation from A
b) peer A assume that all the data sent out has been successfully received
by peer B when A receives closing acknowledgement from B

Section 1.4 in -05 states only a), but I thought that b) is also closing
handshake's objective. e.g. this old post
http://www.ietf.org/mail-archive/web/hybi/current/msg01526.html by Hixie
says so.

How many people on this list are supportive for having feature-b) realized
by closing handshake? When I was talking with people offlist, some were
doubtful about the usefulness of this feature. It think most apps would
build their own shutdown protocol and doesn't rely on WebSocket closing
handshake.

== How it should be done for each option ==
1) If we need only a), a) can be simply realized by closing frame without
body.

2) If we need both a) and b), we have to distinguish closing initiation and
acknowledgement since it's possible that both sides initiate closing at the
same time.

Some sentences ("A received close message is deemed to be ..." in Section
4.5.1) were added to -01 to ask each peer to check the body of closing frame
to distinguish if it's acknowledgement or not". This was incomplete as
Gabriel pointed out in http://trac.tools.ietf.org/wg/hybi/trac/ticket/34,
but it's now almost addressed in -05. I think we need to make one more tiny
fix on 4.5.1, but then, I think it's perfect.

== What does _cleanly_ means? ==
By the word _cleanly_ all the information about closing handshake is passed
to the WebSocket API.

If we take 1), _cleanly_ means the user agent has received all data from the
server.

If we take 2),... in -05, _cleanly_ has different meaning depending on
whether client initiated close or server initiated close. If client
initiated close, _cleanly_ means the user agent has received all data from
the server and all the data sent to the server has been received by the
server. If server initiated close, _cleanly_ only means the user agent has
received all data from the server. Since we're going to assure b), the user
agent should initiate closure before sending back acknowledgement (we need
some change in 4.5.1). Then, _cleanly_ means the same for both cases.

====

Let's make decision here to clean-up closing handshake stuff in the spec.

1) keep feature-b)
- Change Section 1.4 to mention that closing handshake is designed to
realize feature-b)
- Fix 4.5.1 so that a peer wait until receiving acknowledgement if it has
initiated closing handshake
2) drop feature-b)
- Drop body comparison procedure added in -01
- Avoid using a word "acknowledgement". It's confusing IMO.