From 9436a23ca55e8d3eb49bdf58889ee1ab3db5f64c Mon Sep 17 00:00:00 2001
From: Doug Fawley <dfawley@google.com>
Date: Mon, 1 Jul 2024 08:59:26 -0700
Subject: [PATCH] doc: add grpc-status-details-bin to HTTP/2 spec

---
 doc/PROTOCOL-HTTP2.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/doc/PROTOCOL-HTTP2.md b/doc/PROTOCOL-HTTP2.md
index e5d9696575a99..b973139317feb 100644
--- a/doc/PROTOCOL-HTTP2.md
+++ b/doc/PROTOCOL-HTTP2.md
@@ -106,10 +106,11 @@ For requests, **EOS** (end-of-stream) is indicated by the presence of the END_ST
 * **Response** → (Response-Headers \*Length-Prefixed-Message Trailers) / Trailers-Only
 * **Response-Headers** → HTTP-Status [Message-Encoding] [Message-Accept-Encoding] Content-Type \*Custom-Metadata
 * **Trailers-Only** → HTTP-Status Content-Type Trailers
-* **Trailers** → Status [Status-Message] \*Custom-Metadata
+* **Trailers** → Status [Status-Message] [Status-Details] \*Custom-Metadata
 * **HTTP-Status** → ":status 200"
 * **Status** → "grpc-status" 1\*DIGIT ; 0-9
 * **Status-Message** → "grpc-message" Percent-Encoded
+* **Status-Details** → "grpc-status-details-bin" {base64 encoded value} # See notes below.
 * **Percent-Encoded** → 1\*(Percent-Byte-Unencoded / Percent-Byte-Encoded)
 * **Percent-Byte-Unencoded** → 1\*( %x20-%x24 / %x26-%x7E ) ; space and VCHAR, except %
 * **Percent-Byte-Encoded** → "%" 2HEXDIGIT ; 0-9 A-F
@@ -138,6 +139,11 @@ implementation can decode valid portions while leaving broken %-encodings as-is
 or replacing them with a replacement character (e.g., '?' or the Unicode
 replacement character).
 
+**Status-Details** is allowed only if **Status** is not OK. If it is set, it
+contains additional information about the RPC error. If it contains a status
+code field, it MUST NOT contradict the **Status** header. The consumer MUST
+verify this requirement.
+
 #### Example
 
 Sample unary-call showing HTTP2 framing sequence
@@ -257,3 +263,4 @@ to be used.
 * **Service-Name** → ?( {_proto package name_} "." ) {_service name_}
 * **Message-Type** → {_fully qualified proto message name_}
 * **Content-Type** → "application/grpc+proto"
+* **Status-Details** → {_google.rpc.Status proto message_}