Server-protocol: Half-close mailboxes

server-protocol.md

@@ -245,24 +245,6 @@ a mailbox directly without using a nameplate. This is mainly useful for
 reconnecting clients that had a mailbox previously, but may be used by future
 protocols too.
 
-The `close` command accepts an optional "mood" string: this allows clients to
-tell the server (in general terms) about their experiences with the wormhole
-interaction. The server records the mood in its "usage" record, so the server
-operator can get a sense of how many connections are succeeding and failing.
-The moods currently recognized by the Mailbox server are:
-
-* `happy` (default): the PAKE key-establishment worked, and the client saw at
-  least one valid encrypted message from its peer
-* `lonely`: the client gave up without hearing anything from its peer
-* `scary`: the client saw an invalid encrypted message from its peer,
-  indicating that either the wormhole code was typed in wrong, or an attacker
-  tried (and failed) to guess the code
-* `errory`: the client encountered some other error: protocol problem or
-  internal error
-
-The server will also record `pruney` if it deleted the mailbox due to
-inactivity, or `crowded` if more than two sides tried to access the mailbox.
-
 When clients use the `add` command to add a client-to-client message, they
 will put the body (a bytestring) into the command as a hex-encoded string in
 the `body` key. They will also put the message's "phase", as a string, into
@@ -282,6 +264,32 @@ The `message` response will also include `id`, copied from the `id` of the
 The Mailbox server does not de-duplicate messages, nor does it retain
 ordering: clients must do both if they need to.
 
+The `close` command accepts an optional "mood" string: this allows clients to
+tell the server (in general terms) about their experiences with the wormhole
+interaction. The server records the mood in its "usage" record, so the server
+operator can get a sense of how many connections are succeeding and failing.
+The moods currently recognized by the Mailbox server are:
+
+* `happy` (default): the PAKE key-establishment worked, and the client saw at
+  least one valid encrypted message from its peer
+* `lonely`: the client gave up without hearing anything from its peer
+* `scary`: the client saw an invalid encrypted message from its peer,
+  indicating that either the wormhole code was typed in wrong, or an attacker
+  tried (and failed) to guess the code
+* `errory`: the client encountered some other error: protocol problem or
+  internal error
+
+The server will also record `pruney` if it deleted the mailbox due to
+inactivity, or `crowded` if more than two sides tried to access the mailbox.
+
+A client sending a `close` message issues a `closed` message on the other client,
+to notify it about the intended session teardown. The latter client can then
+continue to send messages (so-called "half-closed state") until sending a `close`
+message too, which in turn will send the `closed` command to the first client and
+thus finalize the session teardown. The second client may disconnect directly
+after sending the `close` message, there will be no further confirmation. It is
+an error to send messages after having sent `close`.
+
 ## All Message Types
 
 This lists all message types, along with the type-specific keys for each (if