Add a retryable flag to errors

This flag can simplify deciding if an operation returning an error can
be blindly retried. Some errors might need some intervention to change
the system's state, but another actor might do that, so a bling retry
might still succeed.

Retrying is still largely missing, but it will be solved separately,
see: #52

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/client/microgrid/_exception.py

@@ -11,21 +11,29 @@
 
 
 class ClientError(Exception):
-    """There was an error in the microgrid API client."""
+    """There was an error in the microgrid API client.
+
+    To simplify retrying, errors are classified as
+    [retryable][frequenz.client.microgrid.ClientError.is_retryable], or not. Retryable
+    errors might succeed if retried, while permanent errors won't. When uncertain,
+    errors are assumed to be retryable.
+    """
 
     def __init__(
         self,
         *,
         server_url: str,
         operation: str,
         description: str,
+        retryable: bool,
     ) -> None:
         """Create a new instance.
 
         Args:
             server_url: The URL of the server that returned the error.
             operation: The operation that caused the error.
             description: A human-readable description of the error.
+            retryable: Whether retrying the operation might succeed.
         """
         super().__init__(
             f"Failed calling {operation!r} on {server_url!r}: {description}"
@@ -40,6 +48,9 @@ def __init__(
         self.description = description
         """The human-readable description of the error."""
 
+        self.is_retryable = retryable
+        """Whether retrying the operation might succeed."""
+
     @classmethod
     def from_grpc_error(
         cls,
@@ -55,6 +66,7 @@ def from_grpc_error(
             server_url: The URL of the server that returned the error.
             operation: The operation that caused the error.
             grpc_error: The gRPC error to convert.
+            retryable: Whether retrying the operation might succeed.
 
         Returns:
             An instance of
@@ -97,6 +109,7 @@ def __call__(
             operation=operation,
             description="Got an unrecognized status code",
             grpc_error=grpc_error,
+            retryable=retryable,
         )
 
 
@@ -111,13 +124,14 @@ class GrpcStatusError(ClientError):
            codes](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md)
     """
 
-    def __init__(
+    def __init__(  # pylint: disable=too-many-arguments
         self,
         *,
         server_url: str,
         operation: str,
         description: str,
         grpc_error: grpclib.GRPCError,
+        retryable: bool,
     ) -> None:
         """Create a new instance.
 
@@ -126,13 +140,15 @@ def __init__(
             operation: The operation that caused the error.
             description: A human-readable description of the error.
             grpc_error: The gRPC error originating this exception.
+            retryable: Whether retrying the operation might succeed.
         """
         message = f": {grpc_error.message}" if grpc_error.message else ""
         details = f" ({grpc_error.details})" if grpc_error.details else ""
         super().__init__(
             server_url=server_url,
             operation=operation,
             description=f"{description} <status={grpc_error.status.name}>{message}{details}",
+            retryable=retryable,
         )
         self.description = description
 
@@ -158,6 +174,7 @@ def __init__(
             operation=operation,
             description="The operation was cancelled",
             grpc_error=grpc_error,
+            retryable=True,
         )
 
 
@@ -179,6 +196,7 @@ def __init__(
             operation=operation,
             description="There was an error that can't be described using other statuses",
             grpc_error=grpc_error,
+            retryable=True,  # We don't know so we assume it's retryable
         )
 
 
@@ -206,6 +224,7 @@ def __init__(
             operation=operation,
             description="The client specified an invalid argument",
             grpc_error=grpc_error,
+            retryable=False,
         )
 
 
@@ -233,6 +252,7 @@ def __init__(
             description="The time limit was exceeded while waiting for the operation "
             "to complete",
             grpc_error=grpc_error,
+            retryable=True,
         )
 
 
@@ -259,6 +279,7 @@ def __init__(
             operation=operation,
             description="The requested entity was not found",
             grpc_error=grpc_error,
+            retryable=True,  # If the entity is added later it might succeed
         )
 
 
@@ -280,6 +301,7 @@ def __init__(
             operation=operation,
             description="The entity that we attempted to create already exists",
             grpc_error=grpc_error,
+            retryable=True,  # If the entity is deleted later it might succeed
         )
 
 
@@ -310,6 +332,7 @@ def __init__(
             description="The caller does not have permission to execute the specified "
             "operation",
             grpc_error=grpc_error,
+            retryable=True,  # If the user is granted permission it might succeed
         )
 
 
@@ -332,6 +355,7 @@ def __init__(
             description="Some resource has been exhausted (for example per-user quota, "
             "disk space, etc.)",
             grpc_error=grpc_error,
+            retryable=True,  # If the resource is freed it might succeed
         )
 
 
@@ -359,6 +383,7 @@ def __init__(
             description="The operation was rejected because the system is not in a "
             "required state",
             grpc_error=grpc_error,
+            retryable=True,  # If the system state changes it might succeed
         )
 
 
@@ -383,6 +408,7 @@ def __init__(
             operation=operation,
             description="The operation was aborted",
             grpc_error=grpc_error,
+            retryable=True,
         )
 
 
@@ -413,6 +439,7 @@ def __init__(
             operation=operation,
             description="The operation was attempted past the valid range",
             grpc_error=grpc_error,
+            retryable=True,  # If the system state changes it might succeed
         )
 
 
@@ -435,6 +462,7 @@ def __init__(
             description="The operation is not implemented or not supported/enabled in "
             "this service",
             grpc_error=grpc_error,
+            retryable=False,
         )
 
 
@@ -460,6 +488,7 @@ def __init__(
             description="Some invariants expected by the underlying system have been "
             "broken",
             grpc_error=grpc_error,
+            retryable=True,  # If the system state changes it might succeed
         )
 
 
@@ -485,6 +514,7 @@ def __init__(
             operation=operation,
             description="The service is currently unavailable",
             grpc_error=grpc_error,
+            retryable=True,  # If the service becomes available it might succeed
         )
 
 
@@ -506,6 +536,7 @@ def __init__(
             operation=operation,
             description="Unrecoverable data loss or corruption",
             grpc_error=grpc_error,
+            retryable=False,
         )
 
 
@@ -528,4 +559,5 @@ def __init__(
             description="The request does not have valid authentication credentials "
             "for the operation",
             grpc_error=grpc_error,
+            retryable=False,
         )