diff --git a/api.capnp b/api.capnp index 544c35b..7ad0e9f 100644 --- a/api.capnp +++ b/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 ) -> (); + } } diff --git a/connection.capnp b/connection.capnp index 2d00d64..b24e662 100644 --- a/connection.capnp +++ b/connection.capnp @@ -39,7 +39,7 @@ struct Message { # Start an authenticaion exchange # TODO: RPC bootstrapping - api @3 :Api.Diflouroborane; + api @3 :Api.FabAccess; } }