varlink: add an operation not ready error

Add a new more catch-all error type to the varlink interface definition
and code. In particular this error should be used by a scope when it
can't perform an operation and needs to return something sensible to
the client rather than just blowing up.

Signed-off-by: John Mulligan <[email protected]>

Author: phlogistonjohn

sambacc/varlink/interfaces/org.samba.containers.keybridge.varlink

@@ -74,3 +74,16 @@ error ReadOnlyScope (name: string)
 # OperationNotSupported may be returned if an entry method is not supported by
 # the given scope.
 error OperationNotSupported (op: string, name: string, scope: string)
+
+
+# OperationFailed may be returned if an entry method is not currently
+# functioning for the given scope. This could indicate the need to retry the
+# operation later. It may provide a scope specific status and message for the
+# reason the operation is not ready.
+error OperationFailed (
+    op: string,
+    name: string,
+    scope: string,
+    status: ?string,
+    reason: ?string
+)

sambacc/varlink/keybridge.py

@@ -100,6 +100,24 @@ class OperationNotSupported(KeyBridgeError):
     _expect = {"op", "name", "scope"}
 
 
+class OperationFailed(KeyBridgeError):
+    """
+    OperationFailed may be returned if an entry method is not currently
+    functioning for the given scope. This could indicate the need to retry the
+    operation later. It may provide a scope specific status and message for the
+    reason the operation is not ready.
+
+    The status value, if provided, should be a short string suitable for
+    logging or parsing and creating conditional logic, but is scope-specific.
+    The reason value, if provided, is a human-readable description of the
+    problem.
+    """
+
+    _name = "OperationFailed"
+    _expect = {"op", "name", "scope"}
+    _optional = {"status", "reason"}
+
+
 class OpKind(str, enum.Enum):
     GET = "Get"
     SET = "Set"