Merge branch 'feature/fallible' into 'main'

User management and related API improvements

See merge request fabinfra/fabaccess/fabaccess-api!20

general.capnp

@@ -33,3 +33,13 @@ struct Optional(T) {
         just @1 :T;
     }
 }
+
+struct Fallible(T, E) {
+    # Some operations can fail in several expected ways.
+    # In those cases returning an `Optional` doesn't transfer information about the way that the
+    # operation failed. `Fallible` contains this information in the generic `E` type.
+    union {
+        failed @0 :E;
+        successful @1 :T;
+    }
+}

usersystem.capnp

@@ -8,6 +8,8 @@ $CSharp.namespace("FabAccessAPI.Schema");
 
 using General = import "general.capnp";
 using User = import "user.capnp".User;
+using Optional = General.Optional;
+using Fallible = General.Fallible;
 
 struct UserSystem
 {
@@ -16,11 +18,34 @@ struct UserSystem
     	getUserSelf @0 ( ) -> User;
 	}
 
+	search @2 :Search;
+	interface Search $CSharp.name("SearchInterface") {
+	    getUserByName @0 (username: Text) -> Optional(User);
+	}
+
 	manage @1 :Manage;
     interface Manage $CSharp.name("ManageInterface") {
     	getUserList @0 () -> ( user_list :List(User) );
 
-    	addUser @1 (username :Text, password: Text) -> User;
+        addUser @1 (username :Text, password: Text) -> User;
+        # DEPRECATED: use `addUserFallible` instead
+
     	removeUser @2 (user: User);
+
+        struct AddUserError {
+            enum AddUserError {
+                alreadyExists @0;
+                # An user with that username already exists
+
+                usernameInvalid @1;
+                # The provided username is unusable, e.g. contains invalid characters,
+                # is too long or too short.
+
+                passwordInvalid @2;
+                # The provided password is unusable, e.g. it's of zero length
+            }
+            error @0 :AddUserError;
+        }
+    	addUserFallible @3 (username :Text, password: Text) -> Fallible(User, AddUserError);
 	}
 }