From 6d7a2477f39dd39bb8e7a68ef828e08d7c46b966 Mon Sep 17 00:00:00 2001 From: Dylan Russell Date: Tue, 3 Jun 2025 20:11:00 +0000 Subject: [PATCH 1/6] Minor spec change around UNAVAILABLE / RetryInfo --- docs/specification.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 496ae1a3..2314f838 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -224,18 +224,12 @@ retryable and not-retryable: and cannot be deserialized or processed by the server. The client SHOULD maintain a counter of such dropped data. -The server MUST indicate retryable errors using code -[Unavailable](https://godoc.org/google.golang.org/grpc/codes) and MAY supply -additional -[details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) -using -[RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40) -containing 0 value of RetryDelay. Here is a sample Go code to illustrate: +For retryable errors the server is recommended to use code +[Unavailable](https://godoc.org/google.golang.org/grpc/codes). ```go // Do this on server side. - st, err := status.New(codes.Unavailable, "Server is unavailable"). - WithDetails(&errdetails.RetryInfo{RetryDelay: &duration.Duration{Seconds: 0}}) + st, err := status.New(codes.Unavailable, "Server is unavailable") if err != nil { log.Fatal(err) } From 65c0302d8991ed9cc42f77341c8c70164b03214d Mon Sep 17 00:00:00 2001 From: Dylan Russell Date: Tue, 10 Jun 2025 13:42:21 +0000 Subject: [PATCH 2/6] MUST -> SHOULD return unavailable --- docs/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification.md b/docs/specification.md index 2314f838..7d0bbfc3 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -302,7 +302,7 @@ If the server is unable to keep up with the pace of data it receives from the client then it SHOULD signal that fact to the client. The client MUST then throttle itself to avoid overwhelming the server. -To signal backpressure when using gRPC transport, the server MUST return an +To signal backpressure when using gRPC transport, the server SHOULD return an error with code [Unavailable](https://godoc.org/google.golang.org/grpc/codes) and MAY supply additional [details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) From 7b8277fa23868cfaa045b4493a7e824445a2a0a1 Mon Sep 17 00:00:00 2001 From: DylanRussell Date: Tue, 10 Jun 2025 13:42:53 +0000 Subject: [PATCH 3/6] Update docs/specification.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- docs/specification.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 7d0bbfc3..e93e267a 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -224,8 +224,13 @@ retryable and not-retryable: and cannot be deserialized or processed by the server. The client SHOULD maintain a counter of such dropped data. -For retryable errors the server is recommended to use code -[Unavailable](https://godoc.org/google.golang.org/grpc/codes). +The server SHOULD indicate retryable errors using code +[Unavailable](https://godoc.org/google.golang.org/grpc/codes) and MAY supply +additional +[details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) +using +[RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40). +Here is a sample Go code to illustrate: ```go // Do this on server side. From 0c983156b17a70e6d59fd38a7a63ce827826fff3 Mon Sep 17 00:00:00 2001 From: Dylan Russell Date: Tue, 10 Jun 2025 13:44:03 +0000 Subject: [PATCH 4/6] Change language a bit --- docs/specification.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 7d0bbfc3..e0f07f45 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -224,8 +224,14 @@ retryable and not-retryable: and cannot be deserialized or processed by the server. The client SHOULD maintain a counter of such dropped data. -For retryable errors the server is recommended to use code -[Unavailable](https://godoc.org/google.golang.org/grpc/codes). +The server SHOULD indicate retryable errors using code + [Unavailable](https://godoc.org/google.golang.org/grpc/codes) and MAY supply + additional + [details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) + using + [RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40). + + Here is a sample Go code to illustrate: ```go // Do this on server side. From 40d01b788d1d75fc206e204319b333ffac991a9a Mon Sep 17 00:00:00 2001 From: Dylan Russell Date: Tue, 10 Jun 2025 13:44:25 +0000 Subject: [PATCH 5/6] Tweak language --- docs/specification.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index e0f07f45..7d0bbfc3 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -224,14 +224,8 @@ retryable and not-retryable: and cannot be deserialized or processed by the server. The client SHOULD maintain a counter of such dropped data. -The server SHOULD indicate retryable errors using code - [Unavailable](https://godoc.org/google.golang.org/grpc/codes) and MAY supply - additional - [details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) - using - [RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40). - - Here is a sample Go code to illustrate: +For retryable errors the server is recommended to use code +[Unavailable](https://godoc.org/google.golang.org/grpc/codes). ```go // Do this on server side. From c21f28bb7721a14fe4aae184fbd5366b49e3423c Mon Sep 17 00:00:00 2001 From: Dylan Russell Date: Tue, 10 Jun 2025 13:48:06 +0000 Subject: [PATCH 6/6] Add RetryInfo example back --- docs/specification.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/specification.md b/docs/specification.md index e93e267a..62119588 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -235,6 +235,7 @@ Here is a sample Go code to illustrate: ```go // Do this on server side. st, err := status.New(codes.Unavailable, "Server is unavailable") + WithDetails(&errdetails.RetryInfo{RetryDelay: &duration.Duration{Seconds: 5}}) if err != nil { log.Fatal(err) }