Update the schema

api.capnp

@@ -25,21 +25,28 @@
 using Rust = import "rust.capnp";
 $Rust.parentModule("api");
 
-interface Diflouroborane {
-    # Upon initial connection this is the interface a program is presented with, serving as the
-    # common point to access specific subsystems. Keep in mind that one can use pipelining to make this
-    # just as efficient as direct calls — e.g. access the authentication system and call
-    # `initializeAuthentication` on it in one roundtrip, provided one gets granted access to the
-    # Authentication subsystem (which in all fairness is a reasonable assumption)
-
-    permissions @0 () -> ( perm :Permissions );
+struct FabAccess {
+    permissions @0 :Permissions;
     # Permission subsystem to manage permissions and systems underlying the authorization process
 
-    machines @1 () -> ( mach :Machines );
+    machines @1 :Machines;
     # Diflouroborane stores machine¹ information in an opaque internal database. This interface is
     # the only stable process of modifying that information
+}
 
-    # TODO Capability transfer system, required for machine takeover, session resumption.
+interface Machines {
+    # The interface to the machines subsystem
+
+    listMachines @0 () -> ( machines :List(Machine) );
+    # List all machines that BFFH knows about the user has been granted at least read access on
+
+    getMachine @1 ( uuid :UUID ) -> ( machine :Machine );
+    # Access a particular machine by known UUID. This may fail for two reasons: The user
+    # has not been granted access to know the machine exists or the machine does in fact
+    # not exist. In both cases the `machine` result will be a NULL-pointer
+}
+
+interface Permissions {
 }
 
 struct UUID {
@@ -58,13 +65,6 @@ struct UUID {
     uuid1 @1 :UInt64;
 }
 
-struct Maybe(T) {
-    union {
-        none @0 :Void;
-        some @1 :T;
-    }
-}
-
 enum State {
     free @0;
     inUse @1;
@@ -74,48 +74,77 @@ enum State {
     reserved @5;
 }
 
-interface Machine {
+struct Machine {
+    # A machine struct. This represents a machine as BFFH thinks about it which may mean
+    # several machines or just part of a machine in the real world.
+    # By itself this struct is completely useless since it contains only the information
+    # that the machine exists the user is allowed to know about that fact. For all further
+    # information the user has to call the contained capabilities which depending on the
+    # access level may not be set. For example an admin will have every capability here
+    # set but a simple user may only have `read` and `write` set while some users may not
+    # even have `read` set and are unable to even see if the machine is currently in use.
     struct MInfo {
         state @0 :State;
         name @1 :Text;
         description @2 :Text;
 
-        responsible @3 :Text;
-        # TODO: Make that an user
+        responsible @3 :User; # This field may be NULL if nobody is using the machine
     }
 
-    info @0 () -> ( minfo :MInfo );
-    # Check the state of a machine.
-
-    interface GiveBack {
-        ret @0 () -> ();
+    read @0 :Read;
+    interface Read {
+        info @0 () -> ( minfo :MInfo );
+        # Check the state of a machine.
     }
 
-    use @1 () -> ( ret :Maybe(GiveBack) );
-    # Try to use a machine. Fails if the user doesn't have enough permissions
+    write @1 :Write;
+    interface Write {
+        use @0 () -> ( ret :GiveBack );
+        # Try to use a machine. Returns a NULL-ptr if the user does not have the required
+        # permissions to use this machine
+        interface GiveBack {
+            # If you are using a machine you have the capablity to give it back
 
-    interface Check {
+            ret @0 () -> ();
+            # Calling this function will return the machine and set its state as appropiate
+        }
+    }
+
+
+    manage @2 :Manage;
+    # After a machine has been used by an user with low enough permissions it's
+    # in the 'toCheck' state.  This call then allows more priviledged users to
+    # "check" the machine and move it to the `free` state.
+    interface Manage {
         ok @0 () -> (); # The machine was clean & ok. -> free
         notOk @1 () -> ();
         # The machine was left in an unacceptable state.
         # Most likely marks the machine as `blocked` and somehow informs the previous user.
     }
 
-    check @2 () -> ( chk :Maybe(Check) );
-    # After a machine has been used by an user with low enough permissions it's
-    # in the 'toCheck' state.  This call then allows more priviledged users to
-    # "check" the machine and move it to the `free` state.
-
-    reserve @3 () -> ( rsrv :Maybe(AnyPointer) );
+    admin @3 :Admin;
+    # Administrative overrides. This is only not-NULL if you have the required permissions
+    # to use it.
+    interface Admin{
+        forceSetState @0 ( state :State ) -> (); # Forcefully set a machine state
+        forceSetUser @1 ( user :Text ) -> (); # Set the given user as current responsible
+    }
 }
 
-interface Machines {
-    lookup @0 ( uuid :UUID ) -> ( machine :Maybe(Machine) );
-    # Get a machine interface. Returns `none` if there is no Machine with the given uuid.
+struct User {
+    struct UserInformation {
+        id @0 :Text;
+        name @1 :Text;
+        originatingWorkshop @2 :Text;
+    }
 
-    list @1 () -> ( machines :List(Machine) );
-    # List all machines
-}
+    read @0 :Read;
+    interface Read {
+        info @0 () -> ( uinfo :UserInformation );
+    }
 
-interface Permissions {
+    write @1 :Write;
+    interface Write {
+        setName @0 ( name :Text ) -> ();
+    }
 }

connection.capnp

@@ -39,7 +39,7 @@ struct Message {
         # Start an authenticaion exchange
 
         # TODO: RPC bootstrapping
-        api @3 :Api.Diflouroborane;
+        api @3 :Api.FabAccess;
     }
 }