From b12fa851c572343ef2672d03814f949d06f07e97 Mon Sep 17 00:00:00 2001
From: Nadja Reitzenstein <me@dequbed.space>
Date: Fri, 4 Nov 2022 15:54:15 +0100
Subject: [PATCH] Make Users::addUser fail in a better way

---
 users.capnp | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/users.capnp b/users.capnp
index f1a10bb..5256344 100644
--- a/users.capnp
+++ b/users.capnp
@@ -8,7 +8,29 @@ using import "user.capnp".User;
 interface Users {
     list @0 () -> ( users :List(User) );
 
-    addUser @1 ( username :Text, password :Text ) -> ( user :User );
+    addUser @1 ( username :Text, password :Text ) -> ( user :User, error :Error );
+    # Add a new user.  If adding the user succeeds then the newly created user is returned and
+    # `error` is NULL / set to Error::ok.  If adding the user fails `user` is NULL and `error`
+    # contains the reason for the failure.
 
     removeUser @2 ( user :User );
 }
+
+struct Error {
+    union {
+        ok @0 :Void;
+        # This error is not actually set, i.e. the operation completed successfully.
+        # This field is necessary because a NULL struct pointer may be interpreted as a struct with
+        # default values.  In that case this will appear as an `Error` with the `ok` field set.
+
+        exists @1 :Void;
+        # There is already an user with the requested username
+
+        usernameInvalid @2 :Void;
+        # The provided username is not usable, e.g. contains invalid characters, is too long, or too
+        # short.
+
+        passwordInvalid @3 :Void;
+        # The provided password is not usable, e.g. it's zero-length.
+    }
+}