Document status ordering rules

This documents a rule that's existed in a hard to find internal document
that's existed since Feb 2016 by abhikumar@google.com.

Since that rule is critical to untangling some gRPC C core behavior, we
should document it publically.

2 files changed, 19 insertions, 0 deletions

diff --git a/doc/status_ordering.md b/doc/status_ordering.md
new file mode 100644
index 0000000000..fccfa863a3
--- /dev/null
+++ b/doc/status_ordering.md
@@ -0,0 +1,16 @@
+Ordering Status and Reads in the gRPC API
+-----------------------------------------
+
+Rules for implementors:
+1. Reads and Writes Must not succeed after Status has been delivered.
+2. OK Status is only delivered after all buffered messages are read.
+3. Reads May continue to succeed after a failing write.
+   However, once a write fails, all subsequent writes Must fail,
+   and similarly, once a read fails, all subsequent reads Must fail.
+4. When an error status is known to the library, if the user asks for status,
+   the library Should discard messages received in the library but not delivered
+   to the user and then deliver the status. If the user does not ask for status
+   but continues reading, the library Should deliver buffered messages before
+   delivering status. The library MAY choose to implement the stricter version
+   where errors cause all buffered messages to be dropped, but this is not a
+   requirement.
diff --git a/test/core/end2end/tests/streaming_error_response.c b/test/core/end2end/tests/streaming_error_response.c
index 42055907c8..2b9c404b15 100644
--- a/test/core/end2end/tests/streaming_error_response.c
+++ b/test/core/end2end/tests/streaming_error_response.c
@@ -31,6 +31,9 @@
  *
  */
 
+/** \file Verify that status ordering rules are obeyed.
+    \ref doc/status_ordering.md */
+
 #include "test/core/end2end/end2end_tests.h"
 
 #include <stdio.h>