docs(wal): describe gRPC code intent, not future operator behavior

The per-case and helper comments asserted what the operator will do
with each gRPC code ("the operator stops retrying", "the operator
will retry the request", etc.). On the current cloudnative-pg main,
the operator only differentiates ErrWALNotFound; the precise-code
distinctions become meaningful only after the operator-side retry
work lands.

Rewrite the comments to describe what the code emits and why (per
gRPC convention), so they stay accurate regardless of the operator
version on the other end. Also note that barman returns ErrGeneric
(exit 4) for some retryable conditions too — not only ErrConnectivity
(exit 2) — which justifies why both map to codes.Unavailable.

Signed-off-by: Armando Ruocco <armando.ruocco@enterprisedb.com>

internal/cnpgi/common/errors.go

@@ -35,19 +35,18 @@ var ErrEndOfWALStreamReached = status.Errorf(codes.OutOfRange, "end of WAL reach
 var ErrMissingPermissions = status.Errorf(codes.FailedPrecondition,
 	"no permission to download the backup credentials, retrying")
 
-// newWALNotFoundError returns an error indicating that the
+// newWALNotFoundError reports that the requested WAL file is not
-// requested WAL file is not present in the object store.
+// present in the object store. Emits codes.NotFound: this is a
-// It carries a gRPC NotFound status so the operator can
+// terminal condition (the file won't appear on retry).
-// treat it as a terminal condition.
 func newWALNotFoundError(walName string) error {
 	return status.Errorf(codes.NotFound, "wal %q not found", walName)
 }
 
-// newUnavailableError returns an error indicating that
+// newUnavailableError reports that downloading the WAL file failed
-// downloading the given WAL file failed for a transient
+// for a reason expected to be transient (a barman-cloud connectivity
-// reason (e.g. a connectivity blip). It carries a gRPC
+// blip, or a generic exit code that in practice covers retryable
-// Unavailable status so the operator will retry the
+// conditions too). Emits codes.Unavailable: per gRPC conventions,
-// request.
+// the canonical signal for "retry may succeed".
 func newUnavailableError(walName string, err error) error {
 	return status.Errorf(
 		codes.Unavailable,
@@ -57,10 +56,9 @@ func newUnavailableError(walName string, err error) error {
 	)
 }
 
-// newInvalidWALNameError returns an error indicating that
+// newInvalidWALNameError reports that the requested WAL name is
-// the requested WAL name is not valid. It carries a gRPC
+// not a valid name. Emits codes.InvalidArgument: this is a
-// InvalidArgument status so the operator treats it as a
+// terminal condition (the same name won't become valid on retry).
-// terminal condition.
 func newInvalidWALNameError(walName string, err error) error {
 	return status.Errorf(
 		codes.InvalidArgument,
@@ -70,10 +68,10 @@ func newInvalidWALNameError(walName string, err error) error {
 	)
 }
 
-// newInternalWALRestoreError returns an error indicating
+// newInternalWALRestoreError reports that downloading the WAL
-// that downloading the given WAL file failed for an
+// file failed for an unclassified reason. Emits codes.Internal:
-// unclassified reason. It carries a gRPC Internal status
+// we have no positive signal that retry would help, so by gRPC
-// so the operator treats it as a terminal condition.
+// convention this is treated as terminal.
 func newInternalWALRestoreError(walName string, err error) error {
 	return status.Errorf(
 		codes.Internal,

internal/cnpgi/common/wal.go

@@ -369,22 +369,23 @@ func (w WALServiceImplementation) restoreFromBarmanObjectStore(
 		walErr := walStatus[0].Err
 		switch {
 		case errors.Is(walErr, barmanRestorer.ErrWALNotFound):
-			// A missing WAL is a terminal condition: surface it as a
-			// gRPC NotFound so the operator stops retrying.
 			return newWALNotFoundError(walName)
 		case errors.Is(walErr, barmanRestorer.ErrInvalidWalName):
-			// A malformed WAL name will never succeed on retry.
+			// A malformed WAL name will never become valid on retry.
 			return newInvalidWALNameError(walName, walErr)
 		case errors.Is(walErr, barmanRestorer.ErrConnectivity),
 			errors.Is(walErr, barmanRestorer.ErrGeneric):
-			// Connectivity and generic barman-cloud failures are
+			// barman-cloud exit codes 2 (connectivity) and 4
-			// considered transient: surface them as gRPC Unavailable
+			// (generic) both surface conditions that are retryable
-			// so the operator retries the download.
+			// in practice — barman uses the "generic" bucket for
+			// some connection-class failures too, not just exit 2.
+			// Emit codes.Unavailable so the caller retries.
 			return newUnavailableError(walName, walErr)
 		default:
-			// Unrecognized exit codes and unexpected failures (e.g. the
+			// Unrecognized exit codes and unexpected failures
-			// barman-cloud command could not be executed) are surfaced
+			// (e.g. the barman-cloud command could not be
-			// as gRPC Internal so the operator treats them as terminal.
+			// executed). No positive signal that retry would
+			// help; emit codes.Internal.
 			return newInternalWALRestoreError(walName, walErr)
 		}
 	}